# HostsResource Resource

### DELETE /hosts

Delete all hosts in the system

Response Body
media type | data type | description
--- | --- | ---
application/json | ApiHostList (JSON) | The list of deleted hosts

### GET /hosts

Returns the hostIds for all hosts in the system.

Request Parameters
name | type | description | default
--- | --- | --- | ---
view | query | The view to materialize | summary

Response Body
media type | data type | description
--- | --- | ---
application/json | ApiHostList (JSON) | A list of hostIds

### GET /hosts

Returns hosts in the system filtered by optional host configuration parameters, if specified.

Request Parameters
name | type | description | default
--- | --- | --- | ---
configName | query | Optional host config name to filter hosts by. Available from v40. | n/a
configValue | query | host config value associated with config name. Available from v40. | n/a
view | query | The view to materialize | summary

Response Body
media type | data type | description
--- | --- | ---
application/json | ApiHostList (JSON) | A list of hosts

### POST /hosts

Create one or more hosts.

You must specify at least the hostname and ipAddress in the request objects. If no hostId is specified, it will be set to the hostname. It is an error to try and create host with the same hostId as another host.

Request Body
media type | data type | description
--- | --- | ---
application/json | ApiHostList (JSON) | The list of hosts to create

Response Body
media type | data type | description
--- | --- | ---
application/json | ApiHostList (JSON) | The newly created host objects

### POST /hosts/enterMaintenanceMode

Puts a set of hosts into Maintenance mode

Available since API v49. Since this is a bulk API, the response may contain partial failures. The returned list contains a list of responses indicating the status of the maintenance mode of the hosts.

Request Body
media type | data type | description
--- | --- | ---
application/json | ApiHostNameList (JSON) | The List of Host Names that needs to go into the maintenance mode.

Response Body
media type | data type | description
--- | --- | ---
application/json | ApiHostMaintenanceResponseList (JSON) | Maintenance mode status of the hosts

### POST /hosts/reallocateMemory

Performs memory reallocation on set of hosts

Request Body
media type | data type | description
--- | --- | ---
application/json | ApiHostNameList (JSON) | A list of hosts identified by hostnames to perform reallocation on.

Response Body
media type | data type | description
--- | --- | ---
application/json | ApiGenericResponse (JSON) | success Boolean value denoting success

### POST /hosts/removeHostsFromCluster

Decommissions and deletes all non management roles from the list of hosts and removes the hosts from the cluster. Also additionally delete the hosts if deleteHosts is set to true.

Request Body
media type | data type | description
--- | --- | ---
application/json | ApiHostsToRemoveArgs (JSON) | The list of hosts to remove from cluster or delete from CM

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

### DELETE /hosts/{hostId}

Delete a host from the system

Request Parameters
name | type | description | default
--- | --- | --- | ---
hostId | path | The ID of the host to remove | n/a

Response Body
media type | data type | description
--- | --- | ---
application/json | ApiHost (JSON) | The deleted Host

### GET /hosts/{hostId}

Returns a specific Host in the system

Request Parameters
name | type | description | default
--- | --- | --- | ---
hostId | path | The ID of the host to read | n/a

Response Body
media type | data type | description
--- | --- | ---
application/json | ApiHost (JSON) | The Host object with the specified hostId

### GET /hosts/{hostId}

Returns a specific Host in the system.

Request Parameters
name | type | description | default
--- | --- | --- | ---
hostId | path | The ID of the host to read. | n/a
view | query | The view to materialize. Defaults to 'full'. | full

Response Body
media type | data type | description
--- | --- | ---
application/json | ApiHost (JSON) | The Host object with the specified hostId.

### PUT /hosts/{hostId}

Update an existing host in the system.

Currently, only updating the rackId is supported. All other fields of the host will be ignored.

Request Parameters
name | type | description | default
--- | --- | --- | ---
hostId | path | The hostId to update | n/a

Request Body
media type | data type | description
--- | --- | ---
application/json | ApiHost (JSON) | The updated host object.

Response Body
media type | data type | description
--- | --- | ---
application/json | ApiHost (JSON) | The updated host

### GET /hosts/{hostId}/components

Returns the list of Component details on the requested host.

Request Parameters
name | type | description | default
--- | --- | --- | ---
hostId | path | The ID of the host. | n/a

Response Body
media type | data type | description
--- | --- | ---
application/json | array of ApiComponentInfo (JSON) | List of component details.

### GET /hosts/{hostId}/config

Retrieves the configuration of a specific host.

Request Parameters
name | type | description | default
--- | --- | --- | ---
hostId | path | The ID of the host. | 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 host configuration parameters.

### PUT /hosts/{hostId}/config

Updates the host configuration with the given values.

If a value is set in the given configuration, it will be added to the host'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
--- | --- | --- | ---
hostId | path | The ID of the host. | 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 host configuration.

### GET /hosts/{hostId}/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 host with the timeseries API use the query:
'select * where hostId = $HOST_ID'.
To get specific metrics for a host use a comma-separated list of the metric names as follows:
'select $METRIC_NAME1, $METRIC_NAME2 where hostId = $HOST_ID'.
For more information see the tsquery language documentation.

Fetch metric readings for a host.

By default, this call will look up all metrics available for the host. 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.

Host metrics also include per-network interface and per-storage device metrics. Since collecting this data incurs in more overhead, query parameters can be used to choose which network interfaces and storage devices to query, or to these metrics altogether.

Storage metrics are collected at different levels; for example, per-disk and per-partition metrics are available. The "storageIds" parameter can be used to filter specific storage IDs.

In the returned data, the network interfaces and storage IDs can be identified by looking at the "context" property of the metric objects.

Request Parameters
name | type | description | default
--- | --- | --- | ---
hostId | path | The host's ID. | n/a
from | query | Start of the period to query. | n/a
ifs | query | Network interfaces to query for metrics (default = all). | n/a
metrics | query | Filter for which metrics to query. | n/a
queryNw | query | Whether to query for network interface metrics. | true
queryStorage | query | Whether to query for storage metrics. | true
storageIds | query | Storage context IDs to query for metrics (default = all). | 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 /hosts/{hostname}/tags

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

Request Parameters
name | type | description | default
--- | --- | --- | ---
hostname | path | Name of the host to remove tags from | n/a

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

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

### GET /hosts/{hostname}/tags

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

Request Parameters
name | type | description | default
--- | --- | --- | ---
hostname | path | The name of the host | 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 host

### PUT /hosts/{hostname}/tags

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

Request Parameters
name | type | description | default
--- | --- | --- | ---
hostname | path | Name of the host | n/a

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

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

### POST /hosts/{hostId}/commands/enterMaintenanceMode

Put the host 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
--- | --- | --- | ---
hostId | path | The ID of the host | n/a

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

### POST /hosts/{hostId}/commands/exitMaintenanceMode

Take the host 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
--- | --- | --- | ---
hostId | path | The ID of the host | n/a

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

### POST /hosts/{hostId}/commands/generateHostCerts

Generates (or regenerates) a key and certificate for this host if Auto-TLS is enabled.

Request Parameters
name | type | description | default
--- | --- | --- | ---
hostId | path | The ID of the host to generate a certificate for. | n/a

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

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

### POST /hosts/{hostId}/commands/migrateRoles

Migrate roles to a different host.

This command applies only to HDFS NameNode, JournalNode, and Failover Controller roles. In order to migrate these roles:

- HDFS High Availability must be enabled, using quorum-based storage.
- HDFS must not be configured to use a federated nameservice.

Migrating a NameNode or JournalNode role requires cluster downtime. HDFS, along with all of its dependent services, will be stopped at the beginning of the migration process, and restarted at its conclusion.

If the active NameNode is selected for migration, a manual failover will be performed before the role is migrated. The role will remain in standby mode after the migration is complete.

When migrating a NameNode role, the co-located Failover Controller role must be migrated as well if automatic failover is enabled. The Failover Controller role name must be included in the list of role names to migrate specified in the arguments to this command (it will not be included implicitly). This command does not allow a Failover Controller role to be moved by itself, although it is possible to move a JournalNode independently.

Available since API v10.

Request Parameters
name | type | description | default
--- | --- | --- | ---
hostId | path | The ID of the host on which the roles to migrate currently reside | n/a

Request Body
media type | data type | description
--- | --- | ---
application/json | ApiMigrateRolesArguments (JSON) | Arguments for the command.

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

### POST /hosts/{hostId}/commands/resetHostId

Forces agent on specified host to switch to reporting a different host id.

Request Parameters
name | type | description | default
--- | --- | --- | ---
hostId | path | The ID of the host that should be affected. | n/a
newHostId | query | New ID the the host should report. | n/a

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

### POST /hosts/{hostname}/commands/stopAllRolesGracefully

Gracefully stops all roles that support it; otherwise, performs a simple stop on the provided host.

Request Parameters
name | type | description | default
--- | --- | --- | ---
hostname | path | The name of the host on which all the roles needs to be stopped. | n/a

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