Using Tags in Cloudera Manager

Tags provide a way to add information to clusters, hosts, services, and roles using the Cloudera Manager API.

A tag in the context of Cloudera Manager is a name-value pair that is attached to a cluster, service, role, or host. Tags allow information to be added to an entity in a very open-ended fashion. A single entity may have any number of tags, as long as each tag name is unique, and tags may be added or removed at any time. All tags appear in diagnostic bundles.

Tags may be created by various cluster components, using the following naming convention: _cldr_{component_specific_prefix}_tagname. You can also use the Cloudera Manager API to create, update, delete, and retrieve tags.

Setting and Retrieving Tags using the Cloudera Manager API

A TagsResource endpoint for retrieving tags globally is available in versions 41 and higher of the Cloudera Manager API. Endpoints to read, delete, and add or modify tags on clusters, services, hosts and roles are also available. For complete documentation, open the Cloudera Manager Admin Console and go to Support > API Explorer.

You can manage tags for services, roles, and hosts using the following endpoints:

Clusters: /clusters/{clusterName}/tags
Hosts: /hosts/{hostname}/tags
Services: /clusters/{clusterName}/services/<service-name>/tags
Roles: /clusters/{clusterName}/services/{serviceName}/roles/{roleName}/tags
Retrieve all tags:: /tags

API Examples

The following examples show how to add, modify, or delete tags for a cluster:

Add or update a tag on a cluster

This example adds a tag with the name example_name and value example_value to Cluster1. if a tag with the name example_name is already attached to Cluster1, the value of that tag will be updated to example_value.

curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' -d '[
  {
    "name": "example_name",
    "value": "example_value"
  }
]' 'http://username:password@<Cloudera Manager_URL>:7180/api/v49/clusters/<cluster-name>/tags'

Delete a tag on a cluster

This example deletes the tag named example_name from Cluster1, if the tag exists.

curl -X DELETE --header 'Content-Type: application/json' --header 'Accept: application/json' -d '[
  {
    "name": "example_name"
  }
]' 'http://username:password@<Cloudera Manager_URL>l:7180/api/v49/clusters/<cluster-name>/tags'

Retrieve all tags

This example returns a serialized JSON list of all tags, including which entities each is attached to, with a maximum of 10 tags and beginning with the most recently created tag.

curl -X GET --header 'Accept: application/json' http://username:password@<Cloudera Manager_URL>:7180/api/v49/tags?limit=10&offset=0'

Setting Tags using ImportClusterTemplate (Example)

You can set tags on clusters, services, and hosts (but not roles) using a cluster template provided to /cm/importClusterTemplate in the Cloudera Manager API versions 41 and higher.

The following is an example of a template using tags:

 
{
  "cdhVersion" : "7.0.2",
  "displayName" : "Cluster 2",
  "cmVersion" : "7.0.2",
  "tags" : [ {
	"name" : "_cldr_cm_clustertag",
	"value" : "example1"
  }],
  "services" : [ {
    "refName" : "hdfs",
    "serviceType" : "HDFS",
    "tags" : [ {
	  "name" : "_cldr_cm_servicetag",
	  "value" : "example2"
    }],
    "roleConfigGroups" : [ {
      "refName" : "hdfs-NAMENODE-BASE",
      "roleType" : "NAMENODE",
      "base" : true
    },
{
      "refName" : "hdfs-DATANODE-BASE",
      "roleType" : "DATANODE",
      "base" : true
  } ]
} ],
  "hostTemplates" : [ {
    "refName" : "HostTemplate1",
    "cardinality" : 1,
    "roleConfigGroupsRefNames" : [ "hdfs-NAMENODE-BASE" ]
    "tags" : [ {
	  "name" : "_cldr_cm_hosttag",
	  "value" : "example3"
  }],
  } ,{
    "refName" : "HostTemplate2",
    "cardinality" : 1,
    "roleConfigGroupsRefNames" : [ "hdfs-DATANODE-BASE" ]
  } ],
  "instantiator" : {
    "clusterName" : "Cluster 2",
    "hosts" : [ {
      "hostName" : "host00003",
      "hostTemplateRefName" : "HostTemplate1"
    }, 
 {
      "hostName" : "host00004",
      "hostTemplateRefName" : "HostTemplate2"
    }],
    "lenient" : false
  }
}

This adds the _cldr_cm_clustertag to the cluster that is being created, the _cldr_cm_servicetag to the HDFS service on that cluster, and the _cldr_cm_hosttag to host00003. Note that even if the host templates are persisted (which is optional during cluster template import), the _cldr_cm_hosttag will no longer be associated with HostTemplate1, only with host00003 itself.

For more information about cluster templates, see: Creating a Runtime Cluster Using a Cloudera Manager Template.