Package cm_api :: Module api_client
[hide private]
[frames] | no frames]

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
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