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