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 = 10 
 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    # Events 
222   
223 -  def query_events(self, query_str = None): 
224      """ 
225      Query events. 
226      @param query_str: Query string. 
227      @return: A list of ApiEvent. 
228      """ 
229      return events.query_events(self, query_str) 
230   
231 -  def get_event(self, event_id): 
232      """ 
233      Retrieve a particular event by ID. 
234      @param event_id: The event ID. 
235      @return: An ApiEvent. 
236      """ 
237      return events.get_event(self, event_id) 
238   
239    # Tools 
240   
241 -  def echo(self, message): 
242      """Have the server echo a message back.""" 
243      return tools.echo(self, message) 
244   
245 -  def echo_error(self, message): 
246      """Generate an error, but we get to set the error message.""" 
247      return tools.echo_error(self, message) 
248   
249    # Metrics 
250   
251 -  def get_metrics(self, path, from_time, to_time, metrics, view, params=None): 
252      """ 
253      Generic function for querying metrics. 
254   
255      @param from_time: A datetime; start of the period to query (optional). 
256      @param to_time: A datetime; end of the period to query (default = now). 
257      @param metrics: List of metrics to query (default = all). 
258      @param view: View to materialize ('full' or 'summary') 
259      @param params: Other query parameters. 
260      @return: List of metrics and their readings. 
261      """ 
262      if not params: 
263        params = { } 
264      if from_time: 
265        params['from'] = from_time.isoformat() 
266      if to_time: 
267        params['to'] = to_time.isoformat() 
268      if metrics: 
269        params['metrics'] = metrics 
270      if view: 
271        params['view'] = view 
272      resp = self.get(path, params=params) 
273      return types.ApiList.from_json_dict(resp, self, types.ApiMetric) 
274   
275 -  def query_timeseries(self, query, from_time=None, to_time=None): 
276      """ 
277      Query time series. 
278      @param query: Query string. 
279      @param from_time: Start of the period to query (optional). 
280      @param to_time: End of the period to query (default = now). 
281      @return: A list of ApiTimeSeriesResponse. 
282      """ 
283      return timeseries.query_timeseries(self, query, from_time, to_time) 
284   
285 -  def get_metric_schema(self): 
286      """ 
287      Get the schema for all of the metrics. 
288      @return: A list of ApiMetricSchema. 
289      """ 
290      return timeseries.get_metric_schema(self) 
291   
292    # Batch 
293   
294 -  def do_batch(self, elements): 
295      """ 
296      Execute a batch request with one or more elements. If any element fails, 
297      the entire request is rolled back and subsequent elements are ignored. 
298      @param elements: A list of ApiBatchRequestElements 
299      @return: 2-tuple (overall success, list of ApiBatchResponseElements). 
300      """ 
301      return batch.do_batch(self, elements) 
302   
303 -def get_root_resource(server_host, server_port=None, 
304                        username="admin", password="admin", 
305                        use_tls=False, version=API_CURRENT_VERSION): 
306    """ 
307    See ApiResource. 
308    """ 
309    return ApiResource(server_host, server_port, username, password, use_tls, 
310        version) 
311