Source Code for Module cm_api.api_client

  1  # Licensed to Cloudera, Inc. under one 
  2  # or more contributor license agreements.  See the NOTICE file 
  3  # distributed with this work for additional information 
  4  # regarding copyright ownership.  Cloudera, Inc. licenses this file 
  5  # to you under the Apache License, Version 2.0 (the 
  6  # "License"); you may not use this file except in compliance 
  7  # with the License.  You may obtain a copy of the License at 
  8  # 
  9  #     http://www.apache.org/licenses/LICENSE-2.0 
 10  # 
 11  # Unless required by applicable law or agreed to in writing, software 
 12  # distributed under the License is distributed on an "AS IS" BASIS, 
 13  # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
 14  # See the License for the specific language governing permissions and 
 15  # limitations under the License. 
 16   
 17  import logging 
 18  try: 
 19    import json 
 20  except ImportError: 
 21    import simplejson as json 
 22   
 23  from cm_api.http_client import HttpClient, RestException 
 24  from cm_api.endpoints import batch, cms, clusters, events, hosts, tools 
 25  from cm_api.endpoints import types, users, timeseries 
 26  from cm_api.resource import Resource 
 27   
 28  __docformat__ = "epytext" 
 29   
 30  LOG = logging.getLogger(__name__) 
 31   
 32  API_AUTH_REALM = "Cloudera Manager" 
 33  API_CURRENT_VERSION = 6 
 34   
 35 -class ApiException(RestException): 
 36    """ 
 37    Any error result from the API is converted into this exception type. 
 38    This handles errors from the HTTP level as well as the API level. 
 39    """ 
 40 -  def __init__(self, error): 
 41      # The parent class will set up _code and _message 
 42      RestException.__init__(self, error) 
 43      try: 
 44        # See if the body is json 
 45        json_body = json.loads(self._message) 
 46        self._message = json_body['message'] 
 47      except (ValueError, KeyError): 
 48        pass    # Ignore json parsing error 
 49   
 50   
 51 -class ApiResource(Resource): 
 52    """ 
 53    Resource object that provides methods for managing the top-level API resources. 
 54    """ 
 55   
 56 -  def __init__(self, server_host, server_port=None, 
 57                 username="admin", password="admin", 
 58                 use_tls=False, version=API_CURRENT_VERSION): 
 59      """ 
 60      Creates a Resource object that provides API endpoints. 
 61   
 62      @param server_host: The hostname of the Cloudera Manager server. 
 63      @param server_port: The port of the server. Defaults to 7180 (http) or 
 64        7183 (https). 
 65      @param username: Login name. 
 66      @param password: Login password. 
 67      @param use_tls: Whether to use tls (https). 
 68      @param version: API version. 
 69      @return: Resource object referring to the root. 
 70      """ 
 71      self._version = version 
 72      protocol = use_tls and "https" or "http" 
 73      if server_port is None: 
 74        server_port = use_tls and 7183 or 7180 
 75      base_url = "%s://%s:%s/api/v%s" % \ 
 76          (protocol, server_host, server_port, version) 
 77   
 78      client = HttpClient(base_url, exc_class=ApiException) 
 79      client.set_basic_auth(username, password, API_AUTH_REALM) 
 80      client.set_headers( { "Content-Type" : "application/json" } ) 
 81      Resource.__init__(self, client) 
 82   
 83    @property 
 84 -  def version(self): 
 85      """ 
 86      Returns the API version (integer) being used. 
 87      """ 
 88      return self._version 
 89   
 90    # CMS ops. 
 91   
 92 -  def get_cloudera_manager(self): 
 93      """ 
 94      Returns a Cloudera Manager object. 
 95      """ 
 96      return cms.ClouderaManager(self) 
 97   
 98    # Cluster ops. 
 99   
100 -  def create_cluster(self, name, version): 
101      """ 
102      Create a new cluster. 
103   
104      @param name: Cluster name. 
105      @param version: Cluster CDH version. 
106      @return: The created cluster. 
107      """ 
108      return clusters.create_cluster(self, name, version) 
109   
110 -  def delete_cluster(self, name): 
111      """ 
112      Delete a cluster by name. 
113   
114      @param name: Cluster name 
115      @return: The deleted ApiCluster object 
116      """ 
117      return clusters.delete_cluster(self, name) 
118   
119 -  def get_all_clusters(self, view = None): 
120      """ 
121      Retrieve a list of all clusters. 
122      @param view: View to materialize ('full' or 'summary'). 
123      @return: A list of ApiCluster objects. 
124      """ 
125      return clusters.get_all_clusters(self, view) 
126   
127 -  def get_cluster(self, name): 
128      """ 
129      Look up a cluster by name. 
130   
131      @param name: Cluster name. 
132      @return: An ApiCluster object. 
133      """ 
134      return clusters.get_cluster(self, name) 
135   
136    # Host ops. 
137   
138 -  def create_host(self, host_id, name, ipaddr, rack_id = None): 
139      """ 
140      Create a host. 
141   
142      @param host_id:  The host id. 
143      @param name:     Host name 
144      @param ipaddr:   IP address 
145      @param rack_id:  Rack id. Default None. 
146      @return: An ApiHost object 
147      """ 
148      return hosts.create_host(self, host_id, name, ipaddr, rack_id) 
149   
150 -  def delete_host(self, host_id): 
151      """ 
152      Delete a host by id. 
153   
154      @param host_id: Host id 
155      @return: The deleted ApiHost object 
156      """ 
157      return hosts.delete_host(self, host_id) 
158   
159 -  def get_all_hosts(self, view = None): 
160      """ 
161      Get all hosts 
162   
163      @param view: View to materialize ('full' or 'summary'). 
164      @return: A list of ApiHost objects. 
165      """ 
166      return hosts.get_all_hosts(self, view) 
167   
168 -  def get_host(self, host_id): 
169      """ 
170      Look up a host by id. 
171   
172      @param host_id: Host id 
173      @return: An ApiHost object 
174      """ 
175      return hosts.get_host(self, host_id) 
176   
177    # Users 
178   
179 -  def get_all_users(self, view = None): 
180      """ 
181      Get all users. 
182   
183      @param view: View to materialize ('full' or 'summary'). 
184      @return: A list of ApiUser objects. 
185      """ 
186      return users.get_all_users(self, view) 
187   
188 -  def get_user(self, username): 
189      """ 
190      Look up a user by username. 
191   
192      @param username: Username to look up 
193      @return: An ApiUser object 
194      """ 
195      return users.get_user(self, username) 
196   
197 -  def create_user(self, username, password, roles): 
198      """ 
199      Create a user. 
200   
201      @param username: Username 
202      @param password: Password 
203      @param roles: List of roles for the user. This should be [] for a 
204                    regular user, or ['ROLE_ADMIN'] for an admin. 
205      @return: An ApiUser object 
206      """ 
207      return users.create_user(self, username, password, roles) 
208   
209 -  def delete_user(self, username): 
210      """ 
211      Delete user by username. 
212   
213      @param username: Username 
214      @return: An ApiUser object 
215      """ 
216      return users.delete_user(self, username) 
217   
218    # Events 
219   
220 -  def query_events(self, query_str = None): 
221      """ 
222      Query events. 
223      @param query_str: Query string. 
224      @return: A list of ApiEvent. 
225      """ 
226      return events.query_events(self, query_str) 
227   
228 -  def get_event(self, event_id): 
229      """ 
230      Retrieve a particular event by ID. 
231      @param event_id: The event ID. 
232      @return: An ApiEvent. 
233      """ 
234      return events.get_event(self, event_id) 
235   
236    # Tools 
237   
238 -  def echo(self, message): 
239      """Have the server echo a message back.""" 
240      return tools.echo(self, message) 
241   
242 -  def echo_error(self, message): 
243      """Generate an error, but we get to set the error message.""" 
244      return tools.echo_error(self, message) 
245   
246    # Metrics 
247   
248 -  def get_metrics(self, path, from_time, to_time, metrics, view, params=None): 
249      """ 
250      Generic function for querying metrics. 
251   
252      @param from_time: A datetime; start of the period to query (optional). 
253      @param to_time: A datetime; end of the period to query (default = now). 
254      @param metrics: List of metrics to query (default = all). 
255      @param view: View to materialize ('full' or 'summary') 
256      @param params: Other query parameters. 
257      @return: List of metrics and their readings. 
258      """ 
259      if not params: 
260        params = { } 
261      if from_time: 
262        params['from'] = from_time.isoformat() 
263      if to_time: 
264        params['to'] = to_time.isoformat() 
265      if metrics: 
266        params['metrics'] = metrics 
267      if view: 
268        params['view'] = view 
269      resp = self.get(path, params=params) 
270      return types.ApiList.from_json_dict(resp, self, types.ApiMetric) 
271   
272 -  def query_timeseries(self, query, from_time=None, to_time=None): 
273      """ 
274      Query time series. 
275      @param query: Query string. 
276      @param from_time: Start of the period to query (optional). 
277      @param to_time: End of the period to query (default = now). 
278      @return: A list of ApiTimeSeriesResponse. 
279      """ 
280      return timeseries.query_timeseries(self, query, from_time, to_time) 
281   
282 -  def get_metric_schema(self): 
283      """ 
284      Get the schema for all of the metrics. 
285      @return: A list of ApiMetricSchema. 
286      """ 
287      return timeseries.get_metric_schema(self) 
288   
289    # Batch 
290   
291 -  def do_batch(self, elements): 
292      """ 
293      Execute a batch request with one or more elements. If any element fails, 
294      the entire request is rolled back and subsequent elements are ignored. 
295      @param elements: A list of ApiBatchRequestElements 
296      @return: 2-tuple (overall success, list of ApiBatchResponseElements). 
297      """ 
298      return batch.do_batch(self, elements) 
299   
300 -def get_root_resource(server_host, server_port=None, 
301                        username="admin", password="admin", 
302                        use_tls=False, version=API_CURRENT_VERSION): 
303    """ 
304    See ApiResource. 
305    """ 
306    return ApiResource(server_host, server_port, username, password, use_tls, 
307        version) 
308