Package cm_api :: Package endpoints :: Module clusters :: Class ApiCluster
[hide private]
[frames] | no frames]

Class ApiCluster

source code

         object --+        
                  |        
types.BaseApiObject --+    
                      |    
  types.BaseApiResource --+
                          |
                         ApiCluster

Instance Methods [hide private]
 
__init__(self, resource_root, name=None, version=None, fullVersion=None)
Initializes internal state and sets all known writable properties of the object to None.
source code
 
__str__(self)
Default implementation of __str__.
source code
 
_path(self)
Returns the path to the resource.
source code
 
_put_cluster(self, dic, params=None)
Change cluster attributes
source code
 
get_service_types(self)
Get all service types supported by this cluster.
source code
 
get_commands(self, view=None)
Retrieve a list of running commands for this cluster.
source code
 
rename(self, newname)
Rename a cluster.
source code
 
update_cdh_version(self, new_cdh_version)
Manually set the CDH version.
source code
 
create_service(self, name, service_type)
Create a service.
source code
 
delete_service(self, name)
Delete a service by name.
source code
 
get_service(self, name)
Lookup a service by name.
source code
 
get_all_services(self, view=None)
Get all services in this cluster.
source code
 
get_parcel(self, product, version)
Lookup a parcel by product and version.
source code
 
get_all_parcels(self, view=None)
Get all parcels in this cluster.
source code
 
list_hosts(self)
Lists all the hosts that are associated with this cluster.
source code
 
remove_host(self, hostId)
Removes the association of the host with the cluster.
source code
 
remove_all_hosts(self)
Removes the association of all the hosts with the cluster.
source code
 
add_hosts(self, hostIds)
Adds a host to the cluster.
source code
 
start(self)
Start all services in a cluster, respecting dependencies.
source code
 
stop(self)
Stop all services in a cluster, respecting dependencies.
source code
 
restart(self, restart_only_stale_services=None, redeploy_client_configuration=None, restart_service_names=None)
Restart all services in the cluster.
source code
 
deploy_client_config(self)
Deploys Service client configuration to the hosts on the cluster.
source code
 
deploy_cluster_client_config(self, hostIds=[])
Deploys Cluster client configuration (Kerberos configuration) to the hosts on the cluster.
source code
 
upgrade_services(self)
This command is no longer recommended with API v6 onwards.
source code
 
enter_maintenance_mode(self)
Put the cluster in maintenance mode.
source code
 
exit_maintenance_mode(self)
Take the cluster out of maintenance mode.
source code
 
get_all_host_templates(self)
Retrieves all host templates in the cluster.
source code
 
get_host_template(self, name)
Retrieves a host templates by name.
source code
 
create_host_template(self, name)
Creates a host template.
source code
 
delete_host_template(self, name)
Deletes a host template.
source code
 
rolling_restart(self, slave_batch_size=None, slave_fail_count_threshold=None, sleep_seconds=None, stale_configs_only=None, unupgraded_only=None, roles_to_include=None, restart_service_names=None)
Command to do a "best-effort" rolling restart of the given cluster, i.e.
source code
 
rolling_upgrade(self, upgrade_from_cdh_version, upgrade_to_cdh_version, upgrade_service_names, slave_batch_size=None, slave_fail_count_threshold=None, sleep_seconds=None)
Command to do a rolling upgrade of services in the given cluster
source code
 
auto_assign_roles(self)
Automatically assign roles to hosts and create the roles for all the services in a cluster.
source code
 
auto_configure(self)
Automatically configures roles and services in a cluster.
source code
 
first_run(self)
Prepare and start services in a cluster.
source code
 
upgrade_cdh(self, deploy_client_config=True, start_all_services=True, cdh_parcel_version=None, cdh_package_version=None, rolling_restart=False, slave_batch_size=None, sleep_seconds=None, slave_fail_count_threshold=None)
Perform CDH upgrade to the next major version.
source code
 
configure_for_kerberos(self, datanode_transceiver_port=None, datanode_web_port=None)
Command to configure the cluster to use Kerberos for authentication.
source code
 
export(self, export_auto_config=False)
Export the cluster template for the given cluster.
source code
 
pools_refresh(self)
Refresh Dynamic Pools configurations for relevant services..
source code
 
list_dfs_services(self, view=None)
List available DFS (distributed file system) services in a cluster.
source code

Inherited from types.BaseApiObject: __setattr__, to_json_dict

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __sizeof__, __subclasshook__

Class Methods [hide private]

Inherited from types.BaseApiObject: from_json_dict

Inherited from types.BaseApiObject (private): _get_attributes

Static Methods [hide private]

Inherited from types.BaseApiObject: init

Class Variables [hide private]
  _ATTRIBUTES = {'clusterUrl': None, 'displayName': None, 'entit...

Inherited from types.BaseApiObject (private): _WHITELIST

Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self, resource_root, name=None, version=None, fullVersion=None)
(Constructor)

source code 

Initializes internal state and sets all known writable properties of the object to None. Then initializes the properties given in the provided attributes dictionary.

Parameters:
  • resource_root - API resource object.
  • attrs - optional dictionary of attributes to set. This should only contain r/w attributes.
Overrides: object.__init__
(inherited documentation)

__str__(self)
(Informal representation operator)

source code 

Default implementation of __str__. Uses the type name and the first attribute retrieved from the attribute map to create the string.

Overrides: object.__str__
(inherited documentation)

_path(self)

source code 

Returns the path to the resource.

e.g., for a service 'foo' in cluster 'bar', this should return '/clusters/bar/services/foo'.

Overrides: types.BaseApiResource._path
(inherited documentation)

get_service_types(self)

source code 

Get all service types supported by this cluster.

Returns:
A list of service types (strings)

get_commands(self, view=None)

source code 

Retrieve a list of running commands for this cluster.

Parameters:
  • view - View to materialize ('full' or 'summary')
Returns:
A list of running commands.

rename(self, newname)

source code 

Rename a cluster.

Parameters:
  • newname - New cluster name
Returns:
An ApiCluster object

Since: API v2

update_cdh_version(self, new_cdh_version)

source code 

Manually set the CDH version.

Parameters:
  • new_cdh_version - New CDH version, e.g. 4.5.1
Returns:
An ApiCluster object

Since: API v6

create_service(self, name, service_type)

source code 

Create a service.

Parameters:
  • name - Service name
  • service_type - Service type
Returns:
An ApiService object

delete_service(self, name)

source code 

Delete a service by name.

Parameters:
  • name - Service name
Returns:
The deleted ApiService object

get_service(self, name)

source code 

Lookup a service by name.

Parameters:
  • name - Service name
Returns:
An ApiService object

get_all_services(self, view=None)

source code 

Get all services in this cluster.

Returns:
A list of ApiService objects.

get_parcel(self, product, version)

source code 

Lookup a parcel by product and version.

Parameters:
  • product - the product name
  • version - the product version
Returns:
An ApiParcel object

get_all_parcels(self, view=None)

source code 

Get all parcels in this cluster.

Returns:
A list of ApiParcel objects.

list_hosts(self)

source code 

Lists all the hosts that are associated with this cluster.

Returns:
A list of ApiHostRef objects of the hosts in the cluster.

Since: API v3

remove_host(self, hostId)

source code 

Removes the association of the host with the cluster.

Returns:
A ApiHostRef of the host that was removed.

Since: API v3

remove_all_hosts(self)

source code 

Removes the association of all the hosts with the cluster.

Returns:
A list of ApiHostRef objects of the hosts that were removed.

Since: API v3

add_hosts(self, hostIds)

source code 

Adds a host to the cluster.

Parameters:
  • hostIds - List of IDs of hosts to add to cluster.
Returns:
A list of ApiHostRef objects of the new hosts that were added to the cluster

Since: API v3

start(self)

source code 

Start all services in a cluster, respecting dependencies.

Returns:
Reference to the submitted command.

stop(self)

source code 

Stop all services in a cluster, respecting dependencies.

Returns:
Reference to the submitted command.

restart(self, restart_only_stale_services=None, redeploy_client_configuration=None, restart_service_names=None)

source code 

Restart all services in the cluster.
Services are restarted in the appropriate order given their dependencies.

@param restart_only_stale_services: Only restart services that have stale
                                    configuration and their dependent
                                    services. Default is False.
@param redeploy_client_configuration: Re-deploy client configuration for
                                      all services in the cluster. Default
                                      is False.
@param restart_service_names: Only restart services that are specified and their dependent services.
                              Available since API v11.
@since API v6

@return: Reference to the submitted command.

deploy_client_config(self)

source code 

Deploys Service client configuration to the hosts on the cluster.

Returns:
Reference to the submitted command.

Since: API v2

deploy_cluster_client_config(self, hostIds=[])

source code 

Deploys Cluster client configuration (Kerberos configuration) to the hosts on the cluster. Any hosts that are decommissioned or have running roles will be skipped.

Parameters:
  • hostIds - hostIds of hosts to deploy to. If empty, deploys to all hosts in the cluster.
Returns:
Reference to the submitted command.

Since: API v7

upgrade_services(self)

source code 

This command is no longer recommended with API v6 onwards. It simply does not work when parcels are used, and even with packages it may fail due to a race. Use upgrade_cdh instead.

Upgrades the services in the cluster to CDH5 version. This command requires that the CDH packages in the hosts used by the cluster be upgraded to CDH5 before this command is issued. Once issued, this command will stop all running services before proceeding.

If parcels are used instead of CDH system packages then the following steps need to happen in order:

  1. Stop all services manually
  2. Activate parcel
  3. Run this upgrade command

The command will upgrade the services and their configuration to the version available in the CDH5 distribution.

Returns:
Reference to the submitted command.

Deprecated: since API v6

enter_maintenance_mode(self)

source code 

Put the cluster in maintenance mode.

Returns:
Reference to the completed command.

Since: API v2

exit_maintenance_mode(self)

source code 

Take the cluster out of maintenance mode.

Returns:
Reference to the completed command.

Since: API v2

get_all_host_templates(self)

source code 

Retrieves all host templates in the cluster.

Returns:
ApiList of ApiHostTemplate objects.

get_host_template(self, name)

source code 

Retrieves a host templates by name.

Parameters:
  • name - Host template name.
Returns:
An ApiHostTemplate object.

create_host_template(self, name)

source code 

Creates a host template.

Parameters:
  • name - Name of the host template to create.
Returns:
An ApiHostTemplate object.

delete_host_template(self, name)

source code 

Deletes a host template.

Parameters:
  • name - Name of the host template to delete.
Returns:
An ApiHostTemplate object.

rolling_restart(self, slave_batch_size=None, slave_fail_count_threshold=None, sleep_seconds=None, stale_configs_only=None, unupgraded_only=None, roles_to_include=None, restart_service_names=None)

source code 

Command to do a "best-effort" rolling restart of the given cluster, i.e. it does plain restart of services that cannot be rolling restarted, followed by first rolling restarting non-slaves and then rolling restarting the slave roles of services that can be rolling restarted. The slave restarts are done host-by-host.

Parameters:
  • slave_batch_size - Number of hosts with slave roles to restart at a time Must be greater than 0. Default is 1.
  • slave_fail_count_threshold - The threshold for number of slave host batches that are allowed to fail to restart before the entire command is considered failed. Must be >= 0. Default is 0.
  • sleep_seconds - Number of seconds to sleep between restarts of slave host batches. Must be >=0. Default is 0.
  • stale_configs_only - Restart roles with stale configs only. Default is false.
  • unupgraded_only - Restart roles that haven't been upgraded yet. Default is false.
  • roles_to_include - Role types to restart. Default is slave roles only.
  • restart_service_names - List of specific services to restart.
Returns:
Reference to the submitted command.

Since: API v4

rolling_upgrade(self, upgrade_from_cdh_version, upgrade_to_cdh_version, upgrade_service_names, slave_batch_size=None, slave_fail_count_threshold=None, sleep_seconds=None)

source code 

Command to do a rolling upgrade of services in the given cluster

This command does not handle any services that don't support rolling upgrades. The command will throw an error and not start if upgrade of any such service is requested.

This command does not upgrade the full CDH Cluster. You should normally use the upgradeCDH Command for upgrading the cluster. This is primarily helpful if you need to need to recover from an upgrade failure or for advanced users to script an alternative to the upgradeCdhCommand.

This command expects the binaries to be available on hosts and activated. It does not change any binaries on the hosts.

Parameters:
  • upgrade_from_cdh_version - Current CDH Version of the services. Example versions are: "5.1.0", "5.2.2" or "5.4.0"
  • upgrade_to_cdh_version - Target CDH Version for the services. The CDH version should already be present and activated on the nodes. Example versions are: "5.1.0", "5.2.2" or "5.4.0"
  • upgrade_service_names - List of specific services to be upgraded and restarted.
  • slave_batch_size - Number of hosts with slave roles to restart at a time Must be greater than 0. Default is 1.
  • slave_fail_count_threshold - The threshold for number of slave host batches that are allowed to fail to restart before the entire command is considered failed. Must be >= 0. Default is 0.
  • sleep_seconds - Number of seconds to sleep between restarts of slave host batches. Must be >=0. Default is 0.
Returns:
Reference to the submitted command.

Since: API v10

auto_assign_roles(self)

source code 

Automatically assign roles to hosts and create the roles for all the services in a cluster.

Assignments are done based on services in the cluster and hardware specifications. Existing roles will be taken into account and their assignments will be not be modified.

Since: API v6

auto_configure(self)

source code 

Automatically configures roles and services in a cluster.

Overwrites some existing configurations. Might create new role config groups. Only default role config groups must exist before calling this endpoint. Other role config groups must not exist. If they do, an exception will be thrown preventing any configuration. Ignores the Cloudera Management Service even if colocated with roles of this cluster. To avoid over-committing the heap on hosts, assign hosts to this cluster that are not being used by the Cloudera Management Service.

Since: API v6

first_run(self)

source code 

Prepare and start services in a cluster. Perform all the steps needed to prepare each service in a cluster and start the services in order.

Returns:
Reference to the submitted command.

Since: API v7

upgrade_cdh(self, deploy_client_config=True, start_all_services=True, cdh_parcel_version=None, cdh_package_version=None, rolling_restart=False, slave_batch_size=None, sleep_seconds=None, slave_fail_count_threshold=None)

source code 

Perform CDH upgrade to the next major version. In v9+, also supports minor CDH 5 upgrades (5.a.b to 5.x.y where x > a) and supports maintenance release changes (a.b.x to a.b.y).

If using packages, CDH packages on all hosts of the cluster must be manually upgraded before this command is issued.

The command will upgrade the services and their configuration to the requested version. All running services will be stopped before proceeding, unless rolling restart is requested and is available.

Parameters:
  • deploy_client_config - Whether to deploy client configurations after the upgrade. Default is True. Has no effect in v9+; client configurations are always deployed.
  • start_all_services - Whether to start all services after the upgrade. Default is True. Has no effect in v9+; services are always restarted.
  • cdh_parcel_version - If upgrading to parcels, the full version of an already distributed parcel for the next CDH version. Default is None. Example versions are: '5.0.0-1.cdh5.0.0.p0.11' or '5.0.2-1.cdh5.0.2.p0.32'.
  • cdh_package_version - If upgrading to packages, the full version of an already installed package for the next CDH version. Default is None. Example versions are: '5.2.0' or '4.5.0'. Only available since v9.
  • rolling_restart - If you'd like to do a rolling restart, set this to True. Default is False. Only available since v9.
  • slave_batch_size - Controls the rolling restart slave batch size. Only applicable when rolling_restart is True.
  • sleep_seconds - Controls how many seconds to sleep betweein rolling restart batches. Only applicable when rolling_restart is True.
  • slave_fail_count_threshold - Controls how many slave restart failures are tolerated in a rolling restart. Only applicable when rolling_restart is True.
Returns:
Reference to the submitted command.

Since: API v6 for major upgrades only, v9 for maintenance and CDH 5 minor releases.

configure_for_kerberos(self, datanode_transceiver_port=None, datanode_web_port=None)

source code 

Command to configure the cluster to use Kerberos for authentication.

This command will configure all relevant services on a cluster for Kerberos usage. This command will trigger a GenerateCredentials command to create Kerberos keytabs for all roles in the cluster.

Parameters:
  • datanode_transceiver_port - The HDFS DataNode transceiver port to use. This will be applied to all DataNode role configuration groups. If not specified, this will default to 1004.
  • datanode_web_port - The HDFS DataNode web port to use. This will be applied to all DataNode role configuration groups. If not specified, this will default to 1006.
Returns:
Reference to the submitted command.

Since: API v11

export(self, export_auto_config=False)

source code 

Export the cluster template for the given cluster. ccluster must have host templates defined. It cluster does not have host templates defined it will export host templates based on roles assignment.

Parameters:
  • export_auto_config - Also export auto configured configs
Returns:
Return cluster template

Since: API v12

pools_refresh(self)

source code 

Refresh Dynamic Pools configurations for relevant services..

Returns:
Reference to the submitted command.

Since: API v6

list_dfs_services(self, view=None)

source code 

List available DFS (distributed file system) services in a cluster.

Parameters:
  • view - View to materialize
Returns:
List of available distributed file system services in the cluster.

Since: API v12


Class Variable Details [hide private]

_ATTRIBUTES

Value:
{'name': None, 'displayName': None, 'clusterUrl': None, 'version': Non\
e, 'fullVersion': None, 'hostsUrl': ROAttr(), 'maintenanceMode': ROAtt\
r(), 'maintenanceOwners': ROAttr(), 'entityStatus': ROAttr(),}