# RolesResource Resource

### GET /clusters/{clusterName}/services/{serviceName}/roles

Lists all roles of a given service that match the provided filter.

Request Parameters
name | type | description | default
--- | --- | --- | ---
clusterName | path |  | n/a
serviceName | path |  | n/a

filter

query

Optional query to filter the roles by.

The query specifies the intersection of a list of constraints, joined together with semicolons (without spaces). For example: hostname==host1.abc.com;type==DATANODE

Currently supports filtering by:

- hostname: The hostname of the host the role is running on.
- hostId: The unique identifier of the host the role is running on.
- type: The role's type.

Response Body
media type | data type | description
--- | --- | ---
application/json | ApiRoleList (JSON) | List of roles.

### GET /clusters/{clusterName}/services/{serviceName}/roles

Lists all roles of a given service.

Request Parameters
name | type | description | default
--- | --- | --- | ---
clusterName | path |  | n/a
serviceName | path |  | n/a

Response Body
media type | data type | description
--- | --- | ---
application/json | ApiRoleList (JSON) | List of roles.

### GET /clusters/{clusterName}/services/{serviceName}/roles

Lists all roles of a given service.

Request Parameters
name | type | description | default
--- | --- | --- | ---
clusterName | path |  | n/a
serviceName | path |  | n/a

filter

query

Optional query to filter the roles by.

The query specifies the intersection of a list of constraints, joined together with semicolons (without spaces). For example: hostname==host1.abc.com;type==DATANODE

Currently supports filtering by:

- hostname: The hostname of the host the role is running on.
- hostId: The unique identifier of the host the role is running on.
- type: The role's type.

view | query | DataView for getting roles. Defaults to 'summary'. | summary

Response Body
media type | data type | description
--- | --- | ---
application/json | ApiRoleList (JSON) | List of roles.

### POST /clusters/{clusterName}/services/{serviceName}/roles

Create new roles in a given service.

Service Type | Available Role Types
--- | ---
HDFS (CDH3) | NAMENODE, DATANODE, SECONDARYNAMENODE, BALANCER, GATEWAY
HDFS (CDH4) | NAMENODE, DATANODE, SECONDARYNAMENODE, BALANCER, HTTPFS, FAILOVERCONTROLLER, GATEWAY, JOURNALNODE
HDFS (CDH5) | NAMENODE, DATANODE, SECONDARYNAMENODE, BALANCER, HTTPFS, FAILOVERCONTROLLER, GATEWAY, JOURNALNODE, NFSGATEWAY
MAPREDUCE | JOBTRACKER, TASKTRACKER, GATEWAY, FAILOVERCONTROLLER, | HBASE | MASTER, REGIONSERVER, GATEWAY, HBASETHRIFTSERVER, HBASERESTSERVER
YARN | RESOURCEMANAGER, NODEMANAGER, JOBHISTORY, GATEWAY
OOZIE | OOZIE_SERVER
ZOOKEEPER | SERVER
HUE (CDH3) | HUE_SERVER, BEESWAX_SERVER, KT_RENEWER, JOBSUBD
HUE (CDH4) | HUE_SERVER, BEESWAX_SERVER, KT_RENEWER
HUE (CDH5) | HUE_SERVER, KT_RENEWER
HUE (CDH5 5.5+) | HUE_SERVER, KT_RENEWER, HUE_LOAD_BALANCER
FLUME | AGENT
IMPALA (CDH4) | IMPALAD, STATESTORE, CATALOGSERVER
IMPALA (CDH5) | IMPALAD, STATESTORE, CATALOGSERVER
HIVE | HIVESERVER2, HIVEMETASTORE, WEBHCAT, GATEWAY
SOLR | SOLR_SERVER, GATEWAY
SQOOP | SQOOP_SERVER
SQOOP_CLIENT | GATEWAY
SENTRY | SENTRY_SERVER
ACCUMULO16 | GARBAGE_COLLECTOR, GATEWAY, ACCUMULO16_MASTER, MONITOR, ACCUMULO16_TSERVER, TRACER
KMS | KMS
KS_INDEXER | HBASE_INDEXER
SPARK_ON_YARN | GATEWAY, SPARK_YARN_HISTORY_SERVER

When specifying roles to be created, the names provided for each role must not conflict with the names that CM auto-generates for roles. Specifically, names of the form "<service name>-<role type>-<arbitrary value>" cannot be used unless the <arbitrary value> is the same one CM would use. If CM detects such a conflict, the error message will indicate what <arbitrary value> is safe to use. Alternately, a differently formatted name should be used. Since API v6: The role name can be left blank to allow CM to generate the name.

Request Parameters
name | type | description | default
--- | --- | --- | ---
clusterName | path |  | n/a
serviceName | path |  | n/a

Request Body
media type | data type | description
--- | --- | ---
application/json | ApiRoleList (JSON) | Roles to create.

Response Body
media type | data type | description
--- | --- | ---
application/json | ApiRoleList (JSON) | List of created roles.

### POST /clusters/{clusterName}/services/{serviceName}/roles/bulkDelete

Bulk delete roles in a particular service by name. Fails if any role cannot be found.

Request Parameters
name | type | description | default
--- | --- | --- | ---
clusterName | path |  | n/a
serviceName | path |  | n/a

Request Body
media type | data type | description
--- | --- | ---
application/json | ApiRoleNameList (JSON) | list of role names to be deleted

Response Body
media type | data type | description
--- | --- | ---
application/json | ApiRoleList (JSON) | list of roles deleted, index-aligned with roleNames. Export view.

### GET /clusters/{clusterName}/services/{serviceName}/roles/configs

Retrieves all the roles in the service, including all the configurations for each role. This API does not retrieve the configs for the *service*,only the configs in the *roles* in the service.

Request Parameters
name | type | description | default
--- | --- | --- | ---
clusterName | path |  | n/a
serviceName | path |  | n/a
limit | query | Maximum size of list of roles configuration parameters | 100
offset | query | Index of first role configuration parameters | 0
view | query | The view of the data to materialize, either "summary" or "full". | summary

Response Body
media type | data type | description
--- | --- | ---
application/json | ApiRoleConfigList (JSON) | List of roles configuration parameters

### DELETE /clusters/{clusterName}/services/{serviceName}/roles/{roleName}

Deletes a role from a given service.

Request Parameters
name | type | description | default
--- | --- | --- | ---
clusterName | path |  | n/a
roleName | path | The role name. | n/a
serviceName | path |  | n/a

Response Body
media type | data type | description
--- | --- | ---
application/json | ApiRole (JSON) | The details of the deleted role.

### GET /clusters/{clusterName}/services/{serviceName}/roles/{roleName}

Retrieves detailed information about a role.

Request Parameters
name | type | description | default
--- | --- | --- | ---
clusterName | path |  | n/a
roleName | path | The role name. | n/a
serviceName | path |  | n/a

Response Body
media type | data type | description
--- | --- | ---
application/json | ApiRole (JSON) | The details of the role.

### GET /clusters/{clusterName}/services/{serviceName}/roles/{roleName}

Retrieves detailed information about a role.

Request Parameters
name | type | description | default
--- | --- | --- | ---
clusterName | path |  | n/a
roleName | path | The role name. | n/a
serviceName | path |  | n/a
view | query | The view to materialize. Defaults to 'full'. | full

Response Body
media type | data type | description
--- | --- | ---
application/json | ApiRole (JSON) | The details of the role.

### GET /clusters/{clusterName}/services/{serviceName}/roles/{roleName}/commands

List active role commands.

Request Parameters
name | type | description | default
--- | --- | --- | ---
clusterName | path |  | n/a
roleName | path | The role to start. | n/a
serviceName | path |  | n/a
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 role commands.

### GET /clusters/{clusterName}/services/{serviceName}/roles/{roleName}/commandsByName

Lists all the commands that can be executed by name on the provided role.

Request Parameters
name | type | description | default
--- | --- | --- | ---
clusterName | path |  | n/a
roleName | path | the role name. | n/a
serviceName | path |  | n/a

Response Body
media type | data type | description
--- | --- | ---
application/json | ApiCommandMetadataList (JSON) | a list of command metadata objects.

### GET /clusters/{clusterName}/services/{serviceName}/roles/{roleName}/config

Retrieves the configuration of a specific role. Note that the "full" view performs validation on the configuration, which could take a few seconds on a large cluster (around 500 nodes or more).

Request Parameters
name | type | description | default
--- | --- | --- | ---
clusterName | path |  | n/a
roleName | path | The role to look up. | n/a
serviceName | path |  | n/a
view | query | The view of the data to materialize, either "summary" or "full". | summary

Response Body
media type | data type | description
--- | --- | ---
application/json | ApiConfigList (JSON) | List of role configuration parameters.

### PUT /clusters/{clusterName}/services/{serviceName}/roles/{roleName}/config

Updates the role configuration with the given values.

If a value is set in the given configuration, it will be added to the role's configuration, replacing any existing entries. If a value is unset (its value is null), the existing configuration for the attribute will be erased, if any.

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

Request Parameters
name | type | description | default
--- | --- | --- | ---
clusterName | path |  | n/a
roleName | path | The role to modify. | n/a
serviceName | path |  | n/a
message | query | Optional message describing the changes. | n/a

Request Body
media type | data type | description
--- | --- | ---
application/json | ApiConfigList (JSON) | Configuration changes.

Response Body
media type | data type | description
--- | --- | ---
application/json | ApiConfigList (JSON) | The new service configuration.

### DELETE /clusters/{clusterName}/services/{serviceName}/roles/{roleName}/forceDelete

Force deletes a role from a given service.

Request Parameters
name | type | description | default
--- | --- | --- | ---
clusterName | path |  | n/a
roleName | path | The role name. | n/a
serviceName | path |  | n/a

Response Body
media type | data type | description
--- | --- | ---
application/json | ApiRole (JSON) | The details of the deleted role.

### GET /clusters/{clusterName}/services/{serviceName}/roles/{roleName}/metrics

This method has been deprecated. This endpoint is not supported as of v6. Use the timeseries API instead. To get all metrics for a role with the timeseries API use the query:
'select * where roleName = $ROLE_NAME'.
To get specific metrics for a role use the query:
'select $METRIC_NAME1, $METRIC_NAME2 where roleName = $ROLE_NAME'.
For more information see the tsquery language documentation.

Fetch metric readings for a particular role.

By default, this call will look up all metrics available for the role. If only specific metrics are desired, use the metrics parameter.

By default, the returned results correspond to a 5 minute window based on the provided end time (which defaults to the current server time). The from and to parameters can be used to control the window being queried. A maximum window of 3 hours is enforced.

When requesting a "full" view, aside from the extended properties of the returned metric data, the collection will also contain information about all metrics available for the role, even if no readings are available in the requested window.

Request Parameters
name | type | description | default
--- | --- | --- | ---
clusterName | path |  | n/a
roleName | path | The name of the role. | n/a
serviceName | path |  | n/a
from | query | Start of the period to query. | n/a
metrics | query | Filter for which metrics to query. | n/a
to | query | End of the period to query. | now
view | query | The view of the data to materialize, either "summary" or "full". | summary

Response Body
media type | data type | description
--- | --- | ---
application/json | ApiMetricList (JSON) | List of readings from the monitors.

### DELETE /clusters/{clusterName}/services/{serviceName}/roles/{roleName}/tags

Remove the tags associated with the role. Tag names beginning with the prefix _cldr_ (case insensitive) are reserved for internal use by Cloudera.

Request Parameters
name | type | description | default
--- | --- | --- | ---
clusterName | path |  | n/a
roleName | path | Name of the role to remove tags from | n/a
serviceName | path |  | n/a

Request Body
media type | data type | description
--- | --- | ---
application/json | array of ApiEntityTag (JSON) | A list of tags to remove from the role

Response Body
media type | data type | description
--- | --- | ---
application/json | array of ApiEntityTag (JSON) | A list of tags that were removed from the role

### GET /clusters/{clusterName}/services/{serviceName}/roles/{roleName}/tags

Returns the tags associated with this role. Tag names beginning with the prefix _cldr_ (case insensitive) are reserved for internal use by Cloudera.

Request Parameters
name | type | description | default
--- | --- | --- | ---
clusterName | path |  | n/a
roleName | path | The name of the role | n/a
serviceName | path |  | n/a
limit | query | Number of tags | 10
offset | query | Index of the first tag to retrieve | 0

Response Body
media type | data type | description
--- | --- | ---
application/json | array of ApiEntityTag (JSON) | A list of tags associated with the role

### PUT /clusters/{clusterName}/services/{serviceName}/roles/{roleName}/tags

Attach tags to the role. Tag names beginning with the prefix _cldr_ (case insensitive) are reserved for internal use by Cloudera.

Request Parameters
name | type | description | default
--- | --- | --- | ---
clusterName | path |  | n/a
roleName | path | Name of the role | n/a
serviceName | path |  | n/a

Request Body
media type | data type | description
--- | --- | ---
application/json | array of ApiEntityTag (JSON) | List of tags to add to the role

Response Body
media type | data type | description
--- | --- | ---
application/json | array of ApiEntityTag (JSON) | A list of tags that were added to the role

### POST /clusters/{clusterName}/services/{serviceName}/roles/{roleName}/commands/enterMaintenanceMode

Put the role into maintenance mode. This is a synchronous command. The result is known immediately upon return.

Available since API v2.

Request Parameters
name | type | description | default
--- | --- | --- | ---
clusterName | path |  | n/a
roleName | path | The role name. | n/a
serviceName | path |  | n/a

Response Body
media type | data type | description
--- | --- | ---
application/json | ApiCommand (JSON) | Synchronous command result.

### POST /clusters/{clusterName}/services/{serviceName}/roles/{roleName}/commands/exitMaintenanceMode

Take the role out of maintenance mode. This is a synchronous command. The result is known immediately upon return.

Available since API v2.

Request Parameters
name | type | description | default
--- | --- | --- | ---
clusterName | path |  | n/a
roleName | path | The role name. | n/a
serviceName | path |  | n/a

Response Body
media type | data type | description
--- | --- | ---
application/json | ApiCommand (JSON) | Synchronous command result.

### POST /clusters/{clusterName}/services/{serviceName}/roles/{roleName}/commands/impalaDiagnostics

Collects diagnostics data for an Impala role.

Available since API v31.

Request Parameters
name | type | description | default
--- | --- | --- | ---
clusterName | path |  | n/a
roleName | path | The role name. | n/a
serviceName | path |  | n/a

Request Body
media type | data type
--- | ---
application/json | ApiImpalaRoleDiagnosticsArgs (JSON)

Response Body
media type | data type | description
--- | --- | ---
application/json | ApiCommand (JSON) | Synchronous command result.

### GET /clusters/{clusterName}/services/{serviceName}/roles/{roleName}/logs/full

Retrieves the log file for the role's main process.

If the role is not started, this will be the log file associated with the last time the role was run.

Log files are returned as plain text (type "text/plain").

Request Parameters
name | type | description | default
--- | --- | --- | ---
clusterName | path |  | n/a
roleName | path | The role to fetch logs from. | n/a
serviceName | path |  | n/a

Response Body
media type | data type | description
--- | --- | ---
text/plain | object | Contents of the role's log file.

### GET /clusters/{clusterName}/services/{serviceName}/roles/{roleName}/logs/stacks

Retrieves the stacks log file, if any, for the role's main process. Note that not all roles support periodic stacks collection. The log files are returned as plain text (type "text/plain").

Request Parameters
name | type | description | default
--- | --- | --- | ---
clusterName | path |  | n/a
roleName | path | The role to fetch stacks logs from. | n/a
serviceName | path |  | n/a

Response Body
media type | data type | description
--- | --- | ---
text/plain | object | Contents of the role's log file.

### GET /clusters/{clusterName}/services/{serviceName}/roles/{roleName}/logs/stacksBundle

Download a zip-compressed archive of role stacks logs. Note that not all roles support periodic stacks collection.

Request Parameters
name | type | description | default
--- | --- | --- | ---
clusterName | path |  | n/a
roleName | path | The role to fetch the stacks logs bundle from. | n/a
serviceName | path |  | n/a

Response Body
media type | data type | description
--- | --- | ---
application/octet-stream | object | The archive data.

### GET /clusters/{clusterName}/services/{serviceName}/roles/{roleName}/logs/stderr

Retrieves the role's standard error output.

If the role is not started, this will be the output associated with the last time the role was run.

Log files are returned as plain text (type "text/plain").

Request Parameters
name | type | description | default
--- | --- | --- | ---
clusterName | path |  | n/a
roleName | path | The role to fetch stderr from. | n/a
serviceName | path |  | n/a

Response Body
media type | data type | description
--- | --- | ---
text/plain | object | Contents of the role's standard error output.

### GET /clusters/{clusterName}/services/{serviceName}/roles/{roleName}/logs/stdout

Retrieves the role's standard output.

If the role is not started, this will be the output associated with the last time the role was run.

Log files are returned as plain text (type "text/plain").

Request Parameters
name | type | description | default
--- | --- | --- | ---
clusterName | path |  | n/a
roleName | path | The role to fetch stdout from. | n/a
serviceName | path |  | n/a

Response Body
media type | data type | description
--- | --- | ---
text/plain | object | Contents of the role's standard output.