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, external_accounts, 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 = 17 
 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                 ssl_context=None): 
 60      """ 
 61      Creates a Resource object that provides API endpoints. 
 62   
 63      @param server_host: The hostname of the Cloudera Manager server. 
 64      @param server_port: The port of the server. Defaults to 7180 (http) or 
 65        7183 (https). 
 66      @param username: Login name. 
 67      @param password: Login password. 
 68      @param use_tls: Whether to use tls (https). 
 69      @param version: API version. 
 70      @param ssl_context: A custom SSL context to use for HTTPS (Python 2.7.9+) 
 71      @return: Resource object referring to the root. 
 72      """ 
 73      self._version = version 
 74      protocol = use_tls and "https" or "http" 
 75      if server_port is None: 
 76        server_port = use_tls and 7183 or 7180 
 77      base_url = "%s://%s:%s/api/v%s" % \ 
 78          (protocol, server_host, server_port, version) 
 79   
 80      client = HttpClient(base_url, exc_class=ApiException, 
 81                          ssl_context=ssl_context) 
 82      client.set_basic_auth(username, password, API_AUTH_REALM) 
 83      client.set_headers( { "Content-Type" : "application/json" } ) 
 84      Resource.__init__(self, client) 
 85   
 86    @property 
 87 -  def version(self): 
 88      """ 
 89      Returns the API version (integer) being used. 
 90      """ 
 91      return self._version 
 92   
 93    # CMS ops. 
 94   
 95 -  def get_cloudera_manager(self): 
 96      """ 
 97      Returns a Cloudera Manager object. 
 98      """ 
 99      return cms.ClouderaManager(self) 
100   
101    # Cluster ops. 
102   
103 -  def create_cluster(self, name, version=None, fullVersion=None): 
104      """ 
105      Create a new cluster. 
106   
107      @param name: Cluster name. 
108      @param version: Cluster major CDH version, e.g. 'CDH5'. Ignored if 
109        fullVersion is specified. 
110      @param fullVersion: Complete CDH version, e.g. '5.1.2'. Overrides major 
111        version if both specified. 
112      @return: The created cluster. 
113      """ 
114      return clusters.create_cluster(self, name, version, fullVersion) 
115   
116 -  def delete_cluster(self, name): 
117      """ 
118      Delete a cluster by name. 
119   
120      @param name: Cluster name 
121      @return: The deleted ApiCluster object 
122      """ 
123      return clusters.delete_cluster(self, name) 
124   
125 -  def get_all_clusters(self, view = None): 
126      """ 
127      Retrieve a list of all clusters. 
128      @param view: View to materialize ('full' or 'summary'). 
129      @return: A list of ApiCluster objects. 
130      """ 
131      return clusters.get_all_clusters(self, view) 
132   
133 -  def get_cluster(self, name): 
134      """ 
135      Look up a cluster by name. 
136   
137      @param name: Cluster name. 
138      @return: An ApiCluster object. 
139      """ 
140      return clusters.get_cluster(self, name) 
141   
142    # Host ops. 
143   
144 -  def create_host(self, host_id, name, ipaddr, rack_id = None): 
145      """ 
146      Create a host. 
147   
148      @param host_id:  The host id. 
149      @param name:     Host name 
150      @param ipaddr:   IP address 
151      @param rack_id:  Rack id. Default None. 
152      @return: An ApiHost object 
153      """ 
154      return hosts.create_host(self, host_id, name, ipaddr, rack_id) 
155   
156 -  def delete_host(self, host_id): 
157      """ 
158      Delete a host by id. 
159   
160      @param host_id: Host id 
161      @return: The deleted ApiHost object 
162      """ 
163      return hosts.delete_host(self, host_id) 
164   
165 -  def get_all_hosts(self, view = None): 
166      """ 
167      Get all hosts 
168   
169      @param view: View to materialize ('full' or 'summary'). 
170      @return: A list of ApiHost objects. 
171      """ 
172      return hosts.get_all_hosts(self, view) 
173   
174 -  def get_host(self, host_id): 
175      """ 
176      Look up a host by id. 
177   
178      @param host_id: Host id 
179      @return: An ApiHost object 
180      """ 
181      return hosts.get_host(self, host_id) 
182   
183    # Users 
184   
185 -  def get_all_users(self, view = None): 
186      """ 
187      Get all users. 
188   
189      @param view: View to materialize ('full' or 'summary'). 
190      @return: A list of ApiUser objects. 
191      """ 
192      return users.get_all_users(self, view) 
193   
194 -  def get_user(self, username): 
195      """ 
196      Look up a user by username. 
197   
198      @param username: Username to look up 
199      @return: An ApiUser object 
200      """ 
201      return users.get_user(self, username) 
202   
203 -  def create_user(self, username, password, roles): 
204      """ 
205      Create a user. 
206   
207      @param username: Username 
208      @param password: Password 
209      @param roles: List of roles for the user. This should be [] for a 
210                    regular user, or ['ROLE_ADMIN'] for an admin. 
211      @return: An ApiUser object 
212      """ 
213      return users.create_user(self, username, password, roles) 
214   
215 -  def delete_user(self, username): 
216      """ 
217      Delete user by username. 
218   
219      @param username: Username 
220      @return: An ApiUser object 
221      """ 
222      return users.delete_user(self, username) 
223   
224 -  def update_user(self, user): 
225      """ 
226      Update user with the supplied new user object. 
227   
228      @param user: ApiUser object to be applied 
229      @return: An ApiUser object 
230      """ 
231      return users.update_user(self, user) 
232   
233    # Events 
234   
235 -  def query_events(self, query_str = None): 
236      """ 
237      Query events. 
238      @param query_str: Query string. 
239      @return: A list of ApiEvent. 
240      """ 
241      return events.query_events(self, query_str) 
242   
243 -  def get_event(self, event_id): 
244      """ 
245      Retrieve a particular event by ID. 
246      @param event_id: The event ID. 
247      @return: An ApiEvent. 
248      """ 
249      return events.get_event(self, event_id) 
250   
251    # Tools 
252   
253 -  def echo(self, message): 
254      """Have the server echo a message back.""" 
255      return tools.echo(self, message) 
256   
257 -  def echo_error(self, message): 
258      """Generate an error, but we get to set the error message.""" 
259      return tools.echo_error(self, message) 
260   
261    # Metrics 
262   
263 -  def get_metrics(self, path, from_time, to_time, metrics, view, params=None): 
264      """ 
265      Generic function for querying metrics. 
266   
267      @param from_time: A datetime; start of the period to query (optional). 
268      @param to_time: A datetime; end of the period to query (default = now). 
269      @param metrics: List of metrics to query (default = all). 
270      @param view: View to materialize ('full' or 'summary') 
271      @param params: Other query parameters. 
272      @return: List of metrics and their readings. 
273      """ 
274      if not params: 
275        params = { } 
276      if from_time: 
277        params['from'] = from_time.isoformat() 
278      if to_time: 
279        params['to'] = to_time.isoformat() 
280      if metrics: 
281        params['metrics'] = metrics 
282      if view: 
283        params['view'] = view 
284      resp = self.get(path, params=params) 
285      return types.ApiList.from_json_dict(resp, self, types.ApiMetric) 
286   
287 -  def query_timeseries(self, query, from_time=None, to_time=None, by_post=False): 
288      """ 
289      Query time series. 
290      @param query: Query string. 
291      @param from_time: Start of the period to query (optional). 
292      @param to_time: End of the period to query (default = now). 
293      @return: A list of ApiTimeSeriesResponse. 
294      """ 
295      return timeseries.query_timeseries(self, query, from_time, to_time, by_post=by_post) 
296   
297 -  def get_metric_schema(self): 
298      """ 
299      Get the schema for all of the metrics. 
300      @return: A list of ApiMetricSchema. 
301      """ 
302      return timeseries.get_metric_schema(self) 
303   
304    # Batch 
305   
306 -  def do_batch(self, elements): 
307      """ 
308      Execute a batch request with one or more elements. If any element fails, 
309      the entire request is rolled back and subsequent elements are ignored. 
310      @param elements: A list of ApiBatchRequestElements 
311      @return: 2-tuple (overall success, list of ApiBatchResponseElements). 
312      """ 
313      return batch.do_batch(self, elements) 
314   
315 -  def get_supported_external_account_categories(self): 
316      """ 
317      Lookup all supported categories. 
318      @return: An ApiExternalAcccountCategory list 
319      """ 
320      return external_accounts.get_supported_categories(self) 
321   
322 -  def get_supported_external_account_types(self, category_name): 
323      """ 
324      Lookup all supported types in a category. 
325      @param category_name: The category name 
326      @return: An ApiExternalAcccountType list 
327      """ 
328      return external_accounts.get_supported_types(self, category_name) 
329   
330 -  def create_external_account(self, name, display_name, type_name, 
331                                account_configs=None): 
332      """ 
333      Create an external account 
334      @param name: Immutable external account name 
335      @param display_name: Display name 
336      @param type_name: Account type 
337      @param account_configs: Optional account configuration 
338      @return: An ApiExternalAccount object 
339      """ 
340      return external_accounts.create_external_account( 
341        self, name, display_name, type_name, account_configs) 
342   
343   
344 -  def get_external_account(self, name, view=None): 
345      """ 
346      Lookup an external account by name 
347      @param name: Account name 
348      @param view: View 
349      @return: An ApiExternalAccount object 
350      """ 
351      return external_accounts.get_external_account( 
352        self, name, view) 
353   
354   
355 -  def get_external_account_by_display_name( 
356      self, display_name, view=None): 
357      """ 
358      Lookup an external account by display name 
359      @param display_name: Account display name 
360      @param view: View 
361      @return: An ApiExternalAccount object 
362      """ 
363      return external_accounts.get_external_account_by_display_name( 
364        self, display_name, view) 
365   
366 -  def get_all_external_accounts(self, type_name, view=None): 
367      """ 
368      Lookup all external accounts of a particular type, by type name. 
369      @param type_name: Type name 
370      @param view: View 
371      @return: A list of ApiExternalAccount objects. 
372      """ 
373      return external_accounts.get_all_external_accounts( 
374        self, type_name, view) 
375   
376 -  def update_external_account(self, account): 
377      """ 
378      Update an external account 
379      @param account: Account to update, account name must be specified. 
380      @return: An ApiExternalAccount object 
381      """ 
382      return external_accounts.update_external_account(self, account) 
383   
384 -  def delete_external_account(self, name): 
385      """ 
386      Delete an external account by name 
387      @param name: Account name 
388      @return: An ApiExternalAccount object 
389      """ 
390      return external_accounts.delete_external_account(self, name) 
391   
392 -  def list_external_account_commands_by_name(self, type_name): 
393      """ 
394      Lists all the commands that can be executed by name 
395      on the provided external account type. 
396      @param type_name: Account type 
397      @return: A list of ApiCommandMetadata objects 
398      @since: API v16 
399      """ 
400      return external_accounts.list_commands_by_name(self, type_name) 
401   
402 -def get_root_resource(server_host, server_port=None, 
403                        username="admin", password="admin", 
404                        use_tls=False, version=API_CURRENT_VERSION): 
405    """ 
406    See ApiResource. 
407    """ 
408    return ApiResource(server_host, server_port, username, password, use_tls, 
409        version) 
410