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