ClouderaManagerResource Resource

GET /cm/commands

List active global commands.

Request Parameters
name type description default
view query The view of the data to materialize, either "summary" or "full". summary
Response Body
media type data type description
application/json ApiCommandList (JSON) A list of active global commands.

GET /cm/config

Retrieve the Cloudera Manager settings.

Request Parameters
name type description default
view query The view to materialize, either "summary" or "full". summary
Response Body
media type data type description
application/json ApiConfigList (JSON) The current Cloudera Manager settings.

PUT /cm/config

Update the Cloudera Manager settings.

If a value is set in the given configuration, it will be added to the manager's settings, replacing any existing entry. If a value is unset (its value is null), the existing the setting will be erased.

Settings that are not listed in the input will maintain their current values.

Request Body
media type data type description
application/json ApiConfigList (JSON) Settings to update.
Response Body
media type data type description
application/json ApiConfigList (JSON) The updated configuration.

PUT /cm/config

Update the Cloudera Manager settings.

If a value is set in the given configuration, it will be added to the manager's settings, replacing any existing entry. If a value is unset (its value is null), the existing the setting will be erased.

Settings that are not listed in the input will maintain their current values.

Request Parameters
name type description default
message query Optional message describing the changes. n/a
Request Body
media type data type description
application/json ApiConfigList (JSON) Settings to update.
Response Body
media type data type description
application/json ApiConfigList (JSON) The updated configuration.

GET /cm/deployment

Retrieve full description of the entire Cloudera Manager deployment including all hosts, clusters, services, roles, users, settings, etc.

This object can be used to reconstruct your entire deployment

Note: Only users with sufficient privileges are allowed to call this.

  • Full Administrators
  • Cluster Administrators (but Navigator config will be redacted)

Note: starting with v3, the deployment information contains data about Cloudera Manager peers configured for the instance. This data contains plain text authentication information used to connect to the remote peer.

Request Parameters
name type description default
view query May be one of "export" (default) or "export_redacted". The latter replaces configurations that are sensitive with the word "REDACTED". export
Response Body
media type data type description
application/json ApiDeployment (JSON) A complete deployment description

GET /cm/deployment

Retrieve full description of the entire Cloudera Manager deployment including all hosts, clusters, services, roles, users, settings, etc.

This object can be used to reconstruct your entire deployment

Note: Only users with sufficient privileges are allowed to call this.

  • Full Administrators
  • Cluster Administrators (but Navigator config will be redacted)

Note: starting with v19, the deployment information contains a newer version of users ApiUser2 that can hold granular permissions.

Request Parameters
name type description default
view query May be one of "export" (default) or "export_redacted". The latter replaces configurations that are sensitive with the word "REDACTED". Other filter options are not supported. export
Response Body
media type data type description
application/json ApiDeployment2 (JSON) A complete deployment description

PUT /cm/deployment

Apply the supplied deployment description to the system. This will create the clusters, services, hosts and other objects specified in the argument. This call does not allow for any merge conflicts. If an entity already exists in the system, this call will fail. You can request, however, that all entities in the system are deleted before instantiating the new ones.

You may specify a complete or partial deployment, e.g. you can provide host info with no clusters. However, if you request that the current deployment be deleted, you are required to specify at least one admin user or this call will fail. This is to protect you from creating a system that cannot be logged into again.

If there are any errors creating (or optionally deleting) a deployment, all changes will be rolled back leaving the system exactly as it was before calling this method. The system will never be left in a state where part of the deployment is created and other parts are not.

If the submitted deployment contains entities that require Cloudera Enterprise license, then the license should be provided to Cloudera Manager before making this API call.

Request Parameters
name type description default
deleteCurrentDeployment query If true, the current deployment is deleted before the specified deployment is applied false
Request Body
media type data type description
application/json ApiDeployment (JSON) The deployment to create
Response Body
media type data type description
application/json ApiDeployment (JSON) The system deployment info after successfully applying the given deployment.

PUT /cm/deployment

Apply the supplied deployment description to the system. This will create the clusters, services, hosts and other objects specified in the argument. This call does not allow for any merge conflicts. If an entity already exists in the system, this call will fail. You can request, however, that all entities in the system are deleted before instantiating the new ones.

You may specify a complete or partial deployment, e.g. you can provide host info with no clusters. However, if you request that the current deployment be deleted, you are required to specify at least one admin user or this call will fail. This is to protect you from creating a system that cannot be logged into again.

If there are any errors creating (or optionally deleting) a deployment, all changes will be rolled back leaving the system exactly as it was before calling this method. The system will never be left in a state where part of the deployment is created and other parts are not.

If the submitted deployment contains entities that require Cloudera Enterprise license, then the license should be provided to Cloudera Manager before making this API call.

Request Parameters
name type description default
deleteCurrentDeployment query If true, the current deployment is deleted before the specified deployment is applied false
Request Body
media type data type description
application/json ApiDeployment2 (JSON) The deployment to create
Response Body
media type data type description
application/json ApiDeployment2 (JSON) The system deployment info after successfully applying the given deployment.

POST /cm/importClusterTemplate

Create cluster as per the given cluster template

Request Parameters
name type description default
addRepositories query if true the parcels repositories in the cluster template will be added. false
Request Body
media type data type description
application/json ApiClusterTemplate (JSON) cluster template
Response Body
media type data type description
application/json ApiCommand (JSON) The command performing import task

GET /cm/instances

Retrieves all CM server information.

Available since API v41.

Response Body
media type data type description
application/json ApiCmServerList (JSON) Detailed CM server information.

GET /cm/kerberosInfo

Provides Cloudera Manager Kerberos information

Response Body
media type data type description
application/json ApiKerberosInfo (JSON) Cloudera Manager Kerberos information

GET /cm/kerberosPrincipals

Returns the Kerberos principals needed by the services being managed by Cloudera Manager.

Request Parameters
name type description default
missingOnly query Whether to include only those principals which do not already exist in Cloudera Manager's database. n/a
Response Body
media type data type description
application/json ApiPrincipalList (JSON) List of kerberos principals.

GET /cm/krb5conf

Retrieves krb5.conf of the CM server host

Available since API v41.

Response Body
media type data type description
application/octet-stream object krb5.conf file contents or null if not present

GET /cm/license

Retrieve information about the Cloudera Manager license.

Response Body
media type data type description
application/json ApiLicense (JSON) The current license information.

POST /cm/license

Updates the Cloudera Manager license.

After a new license is installed, the Cloudera Manager needs to be restarted for the changes to take effect.

The license file should be uploaded using a request with content type "multipart/form-data", instead of being encoded into a JSON representation.

Request Parameters
name type description default
license multipart The license file to install. n/a
Request Body
media type data type
multipart/form-data (custom)
Response Body
media type data type description
application/json ApiLicense (JSON) The new license information.

GET /cm/licensedFeatureUsage

Retrieve a summary of licensed feature usage.

This command will return information about what Cloudera Enterprise licensed features are in use in the clusters being managed by this Cloudera Manager, as well as totals for usage across all clusters.

The specific features described can vary between different versions of Cloudera Manager.

Available since API v6.

Response Body
media type data type description
application/json ApiLicensedFeatureUsage (JSON)

GET /cm/log

Returns the entire contents of the Cloudera Manager log file

Response Body
media type data type description
text/plain object

POST /cm/retrieveKeytab

Retrieves a keytab for a list of principals. The principals must already exist.

Request Body
media type data type
application/json ApiPrincipalList (JSON)
Response Body
media type data type description
application/octet-stream object bytes of the keytab

GET /cm/scmDbInfo

Provides Cloudera Manager server's database information

Response Body
media type data type description
application/json ApiScmDbInfo (JSON) Cloudera Manager server's database information

GET /cm/shutdownReadiness

Retrieve Cloudera Manager's readiness for shutdown and destroy. Applications that wish to destroy Cloudera Manager and its managed cluster should poll this API, repeatedly if necessary, to respect its readiness.

Request Parameters
name type description default
lastActivityTime query End time of the last known activity/workload against the managed clusters, in ISO 8601 format. n/a
Response Body
media type data type description
application/json ApiShutdownReadiness (JSON) Cloudera Manager readiness for shutdown

GET /cm/version

Provides version information of Cloudera Manager itself.

Response Body
media type data type description
application/json ApiVersionInfo (JSON) Version information

POST /cm/commands/addCustomCerts

Add custom certificates to the Auto-TLS certificate database

Request Body
media type data type
application/json ApiAddCustomCertsArguments (JSON)
Response Body
media type data type description
application/json ApiCommand (JSON) Information about the submitted command.

POST /cm/commands/clustersPerfInspector

Run performance diagnostics test against specified clusters in ApiClustersPerfInspectorArgs User must be Full Administrator or Global Cluster Administrator.

Request Body
media type data type description
application/json ApiClustersPerfInspectorArgs (JSON) Required arguments for the command. See ApiClustersPerfInspectorArgs.
Response Body
media type data type description
application/json ApiCommand (JSON) Information about the submitted command.

POST /cm/commands/collectDiagnosticData

Collect diagnostic data from hosts managed by Cloudera Manager.

After the command has completed, the ApiCommand will contain a resultDataUrl from where you can download the result.

Only available with Cloudera Manager Enterprise Edition.

Request Body
media type data type description
application/json ApiCollectDiagnosticDataArguments (JSON) The command arguments.
Response Body
media type data type description
application/json ApiCommand (JSON) Detailed command information.

POST /cm/commands/deleteCredentials

Response Body
media type data type description
application/json ApiCommand (JSON)

POST /cm/commands/deleteCredentials

Delete existing Kerberos credentials.

This command will affect all services that have been configured to use Kerberos, and have existing credentials. In V18 this takes a new paramater to determine whether it needs to delete all credentials or just unused ones.

Request Parameters
name type description default
deleteCredentialsMode query this can be set to "all" or "unused" all
Response Body
media type data type description
application/json ApiCommand (JSON) Information about the submitted command.

POST /cm/commands/generateCmca

Generate a CMCA

Request Body
media type data type
application/json ApiGenerateCmcaArguments (JSON)
Response Body
media type data type description
application/json ApiCommand (JSON) Information about the submitted command.

POST /cm/commands/generateCredentials

Generate missing Kerberos credentials.

This command will affect all services that have been configured to use Kerberos, and haven't had their credentials generated yet.

Response Body
media type data type description
application/json ApiCommand (JSON) Information about the submitted command.

POST /cm/commands/generateCredentialsAdhoc

Generate missing Kerberos credentials, optionally accepting a list of ad-hoc credentials to generate as well.

This command will affect all services that have been configured to use Kerberos, and haven't had their credentials generated yet.

Request Body
media type data type
application/json ApiPrincipalList (JSON)
Response Body
media type data type description
application/json ApiCommand (JSON) Information about the submitted command.

POST /cm/commands/hostInstall

Perform installation on a set of hosts.

This command installs Cloudera Manager Agent on a set of hosts.

Available since API v6.

Request Body
media type data type description
application/json ApiHostInstallArguments (JSON) Hosts to perform installation on
Response Body
media type data type description
application/json ApiCommand (JSON) Information about the submitted command.

POST /cm/commands/hostsDecommission

Decommission the given hosts. All slave roles on the hosts will be decommissioned. All other roles will be stopped.

To offline by Upgrade Domain, use the “upgradeDomains” endpoint from the clusters resource to get the list of host names that belong in each Upgrade Domain. Available since API v40.

Request Body
media type data type
application/json ApiHostNameList (JSON)
Response Body
media type data type description
application/json ApiCommand (JSON) Information about the submitted command.

POST /cm/commands/hostsOfflineOrDecommission

Decommission the given hosts. All slave roles on the hosts will be offlined or decommissioned with preference being offlined if supported by the service.

Currently the offline operation is only supported by HDFS, where the offline operation will put DataNodes into HDFS IN MAINTENANCE state which prevents unnecessary re-replication which could occur if decommissioned.

All other roles on the hosts will be stopped.

The offlineTimeout parameter is used to specify a timeout for offline. For HDFS, when the timeout expires, the DataNode will automatically transition out of HDFS IN MAINTENANCE state, back to HDFS IN SERVICE state.

To offline or decommission by Upgrade Domain, use the “upgradeDomains” endpoint from the clusters resource to get the list of host names that belong in each Upgrade Domain. Available since API v40.

Request Parameters
name type description default
offlineTimeout query offline timeout in seconds. Specify as null to get the default timeout (4 hours). Ignored if service does not support he offline operation. n/a
Request Body
media type data type description
application/json ApiHostNameList (JSON) list of host names to decommission.
Response Body
media type data type description
application/json ApiCommand (JSON) Information about the submitted command.

POST /cm/commands/hostsPerfInspector

Run performance diagnostics test against specified hosts in ApiHostsPerfInspectorArgs User must be Full Administrator or Global Cluster Administrator.

Request Body
media type data type description
application/json ApiHostsPerfInspectorArgs (JSON) Required arguments for the command. See ApiHostsPerfInspectorArgs.
Response Body
media type data type description
application/json ApiCommand (JSON) Information about the submitted command.

POST /cm/commands/hostsRecommission

Recommission the given hosts. All slave roles on the hosts will be recommissioned. Roles are not started after this command. Use hostsStartRoles command for that.

Request Body
media type data type
application/json ApiHostNameList (JSON)
Response Body
media type data type description
application/json ApiCommand (JSON) Information about the submitted command.

POST /cm/commands/hostsRecommissionAndExitMaintenanceMode

Recommission and exit maintenance on the given hosts. The recommission step may optionally start roles as well.

Request Parameters
name type description default
recommissionType query recommission
Request Body
media type data type
application/json ApiHostNameList (JSON)
Response Body
media type data type description
application/json ApiCommand (JSON) Information about the submitted command.

POST /cm/commands/hostsRecommissionWithStart

Recommission the given hosts. If slave roles support start when decommissioned, start those roles before recommission. All slave roles on the hosts will be recommissioned. Warning: Evolving. This method may change in the future and does not offer standard compatibility guarantees. Recommission the given hosts. If possible, start those roles before recommission. All slave roles on the hosts will be recommissioned. Do not use without guidance from Cloudera. Currently, only HDFS DataNodes will be started by this command.

Request Body
media type data type
application/json ApiHostNameList (JSON)
Response Body
media type data type description
application/json ApiCommand (JSON) Information about the submitted command.

POST /cm/commands/hostsStartRoles

Start all the roles on the given hosts.

Request Body
media type data type
application/json ApiHostNameList (JSON)
Response Body
media type data type description
application/json ApiCommand (JSON) Information about the submitted command.

POST /cm/commands/importAdminCredentials

Imports the KDC Account Manager credentials needed by Cloudera Manager to create kerberos principals needed by CDH services.

Request Parameters
name type description default
password query Password for the Account Manager. return Information about the submitted command. n/a
username query Username of the Account Manager. Full name including the Kerberos realm must be specified. n/a
Response Body
media type data type description
application/json ApiCommand (JSON)

POST /cm/commands/importKerberosPrincipal

Imports the Kerberos credentials for the specified principal which can then be used to add to a role's keytab by running Generate Credentials command.

Request Parameters
name type description default
kvno query Key-version number of the password. return Information about the submitted command. n/a
password query Password for the Kerberos principal. Cloudera Manager will encrypt the principal and password and use it when needed for a daemon. n/a
principal query Name of the principal. Full name including the Kerberos realm must be specified. If it already exists, it will be overwritten. n/a
Response Body
media type data type description
application/json ApiCommand (JSON)

POST /cm/commands/inspectHosts

Runs the host inspector on the configured hosts.

Response Body
media type data type description
application/json ApiCommand (JSON) Information about the submitted command.

POST /cm/commands/migrateCmcaToDb

Migrate CMCA to the DB

Response Body
media type data type description
application/json ApiCommand (JSON) Information about the submitted command.

POST /cm/commands/refreshParcelRepos

Submit a command to refresh parcels information.

This API could be used following two scenarios.
- User updated Cloudera Manager's local parcel repository.
- User updated remote parcel locations.

User wants to invoke this API to make sure that Cloudera Manager gets latest parcels information. User can then monitor the returned command before proceeding to the next step.

Response Body
media type data type description
application/json ApiCommand (JSON) Information about the submitted command.

POST /cm/commands/testExternalAuthentication

Launches a command to test the currently configured external authentication

Request Body
media type data type
application/json ApiTestCmExternalAuthArguments (JSON)
Response Body
media type data type description
application/json ApiCommand (JSON) the command to test external authentication

GET /cm/instances/{cmServerId}

Retrieves the CM server information.

Available since API v41.

Request Parameters
name type description default
cmServerId path The CM server ID. n/a
Response Body
media type data type description
application/json ApiCmServer (JSON) Detailed CM server information.

POST /cm/trial/begin

Begin trial license.

POST /cm/trial/end

End trial license.