Characteristics of User and Access Tags on IBM Cloud

3 min read

Tags on IBM Cloud are a simple and effective tool to logically group resources for development purposes, billing purposes, operational purposes or even access management purposes.

To address multiple scenarios involving different personas, we introduced the idea of tag types.

A tag of type "user" is tailored to address development or billing scenarios where the main actors involved are resource editors and/or billing administrators. These are the tags that get propagated to the usage report. To learn more, see "Viewing your usage."

A tag of type "access" is tailored to address access management scenarios where you can leverage tags to build access management policies — hence, granting access to resources. The main actors, in this case, are the account administrator and the resource administrator.

Let’s have a look at the key characteristics of each tag type.

Tagging rules

Tags are not case-sensitive, and the maximum length of a tag is 128 characters. The permitted characters are A-Z, 0-9, spaces, underscores, hyphens, periods and colons. The use of a colon formats the tag into a string that isolates two logical parts, like a key:value pair.

Access management tags are always in the format key:value pair (e.g., project:myproject), while user tags can be either simple labels (e.g., mytag) or in key:value format. For user tags, you can have multiple occurrences of ":" — building tags like env:test:myproject.

Access management tags and user tags are different objects in IBM Cloud. In the same account, you can have an access management tag and a user tag with the same name. 

Taggable resources

All resources that show up in the Resource List can be tagged with user tags.

On the contrary, access management tags can be used with all IAM-enabled resources you can see in the Resource List except Cloud Foundry and classic infrastructure ones. Cloud Foundry and classic infrastructure resources do not support access tags.

Managing tags

Attaching and detaching tags are the typical operations we can expect during a tag lifecycle. Once a tag is attached to a resource, anybody who has read privileges on the resource can see the tag.

Access management tags can be created independently from attaching and detaching access tags to resources. IAM best practice is to have an administrator of the tagging service create and manage all access tags in the account. Once the access management tags are created, administrators of IAM-enabled resources can attach or detach tags to resources to grant or revoke access.

User tags that don't already exist are created by the system automatically when attached to a resource.

Tags can only be deleted if they are not attached to any resource. Bulk requests are available to delete many unassigned tags in one request.

To perform the aforementioned operations, you need different privileges depending on the tag type. Details on permissions needed can be found here.

Using the IBM Cloud UI, CLI or the API to manage tags

Using tagging operations can be done via UI, CLI and API (and SDK as well). Let’s look at some examples:

Creating an access management tag "project:myproject"

UI: Go To Manage > Account > Tags:

Creating an access management tag "project:myproject"

CLI: ibmcloud resource tag-create —tag-names "project:myproject"

API equivalent:

curl -X POST -H "Authorization: bearer <your IAM token>"   -H "Accept: application/json"   -H "Content-Type: application/json"   -d '{ "tag_names": ["project:myproject"] }'   "https://tags.global-search-tagging.cloud.ibm.com/v3/tags?tag_type=access"

Attaching the tag "project:myproject" to a resource name "myresource"

UI: There are multiple paths that will allow you to attach tags to a resource:

  • When provisioning a resource: https://test.cloud.ibm.com/catalog/services/<service name>
    When provisioning a resource: https://test.cloud.ibm.com/catalog/services/<service name>
  • From the the Resource List:
    From the the Resource List:
    From the the Resource List:
  • From the instance detail page:
    From the instance detail page:

CLI:

  • User tags: ibmcloud resource tag-attach --tag-names "project:myproject" --resource-name my resource Access tags: ibmcloud resource tag-attach --tag-names "project:myproject" --resource-name my resource —tag-type access

Note the difference among the commands above is the –tag-type option. If not specified, it is implicitly assumed "user."

API equivalent: In this case, two API calls are needed — one to find the unique identifier for myresource and the second one to perform the tag attachment action:

curl -v -X POST -k --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: bearer  <your IAM token>' -d '{"query": "name:myresource"}' 'https://api.global-search-tagging.cloud.ibm.com/v3/resources/search'

Extract the value of the crn field from the response and then call:

curl -X POST -H "Authorization: bearer <your IAM token>" -H "Accept: application/json" -H "Content-Type: application/json"  -d "{"tag_names":["project:myproject"],"resources":[{"<the crn of the resource>"}]}" "https://tags.global-search-tagging.cloud.ibm.com/v3/tags/attach?tag_type=user"

If using tag_type=access in the call above, you would have been attaching an access tag. 

Detaching the tag "project:myproject" to a resource name "myresource"

UI: There are multiple paths that will allow you to detach tags to a resource:

  • From the the Resource List:
    From the the Resource List:
  • From the instance detail page:
    From the instance detail page:

CLI:

  • User tags: ibmcloud resource tag-detach --tag-names "project:myproject" —resource-name myresource
  • Access tags: user tag: ibmcloud resource tag-detach --tag-names "project:myproject" —resource-name myresource tag-type access

Note the difference among the commands above is the —tag-type option. If not specified, it is implicitly assumed "user."

API equivalent:

curl -v -X POST -k --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: bearer  <your IAM token>' -d '{"query": "name:myresource"}' 'https://api.global-search-tagging.cloud.ibm.com/v3/resources/search'

Extract the value of the crn field from the response and then call:

curl -X POST -H "Authorization: bearer <your IAM token>" -H "Accept: application/json" -H "Content-Type: application/json" -d '{ "resources": [{ "resource_id": "<the crn of the resource>" }], "tag_names": ["project:myproject"] }' "https://tags.global-search-tagging.cloud.ibm.com/v3/tags/detach?tag_type=user"

If using tag_type=access in the call above you would have been detaching an access tag. 

Listing all tags in the account

UI: Go to Manage > Account > Tags:

IMAGE 8

CLI:

  • User tags: ibmcloud resource tags
  • Access tags: ibmcloud resource tags —tag-type access

API equivalent:

curl -X GET -H "Authorization: bearer <your IAM token>" -H "Accept: application/json" https://tags.global-search-tagging.cloud.ibm.com/v3/tags?tag_type=user

If using tag_type=access in the call above, you would have been listing all access tags.

Searching for all resources with tag "project:myproject" attached

UI: Use the search bar in the header:

Use the search bar in the header:

CLI:

  • User tags: ibmcloud resource search "tags:project\:myproject"
  • Access tags: ibmcloud resource search "access_tags:project\:myproject"
  • Both: ibmcloud resource search "tags:project\:myproject OR access_tags:project\:myproject"

API equivalent:

User tags:

curl -v -X POST -k --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: bearer  <your IAM token>' -d '{"query": "tags:project\\:myproject"}’ 'https://api.global-search-tagging.cloud.ibm.com/v3/resources/search'

Access tags:

curl -v -X POST -k --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: bearer  <your IAM token>' -d '{"query": "access_tags:project\\:myproject"}' 'https://api.global-search-tagging.cloud.ibm.com/v3/resources/search'

Both:

curl -v -X POST -k --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: bearer  <your IAM token>' -d '{"query": "tags:project\\:myproject OR access_tags:project\\:myproject"}' 'https://api.global-search-tagging.cloud.ibm.com/v3/resources/search'

Deleting the tag "project:myproject"

UI: Go to Manage > Account > Tags:

Go to Manage > Account > Tags:

CLI: 

  • User tags: ibmcloud resource tag-delete --tag-name "project:myproject"
  • Access tags: ibmcloud resource tag-delete --tag-name "project:myproject" —tag-type access

API equivalent:

User tags:

curl -X DELETE "https://tags-prestage.us-south.global-search-tagging.test.cloud.ibm.com/v3/tags/project%3Amyproject" -H  "accept: application/json" -H  "Authorization: bearer <your IAM token>"

Access tags:

curl -X DELETE "https://tags-prestage.us-south.global-search-tagging.test.cloud.ibm.com/v3/tags/project%3Amyproject?tag_type=access" -H  "accept: application/json" -H  "Authorization: bearer <your IAM token>"

Deleting all unattached tags

UI: There is no possibility to delete all tags at once via UI

CLI:

  • User tags: ibmcloud resource tag-delete -a
  • Access tags: ibmcloud resource tag-delete -a  —tag-type access

API equivalent:

User tags:

curl -X DELETE "https://tags.global-search-tagging.cloud.ibm.com/v3/tags" --header  "accept: application/json" --header "Authorization: bearer <your IAM token>"

Access tags:

curl -X DELETE "https://tags.global-search-tagging.cloud.ibm.com/v3/tags?tag_type=access" --header  "accept: application/json" --header "Authorization: bearer <your IAM token>"

Notice that the CLI and UI allow bulk deletion.

Note: The examples above do not include classic infrastructure resources with object type:

  • SoftLayer_Hardware (not including bare metal servers)
  • SoftLayer_Network_Application_Delivery_Controller
  • SoftLayer_Network_Subnet_IpAddress
  • SoftLayer_Network_Vlan 

Conclusions

After reading this article you should be familiar with the concepts of user tags and access management tags, the respective scenarios they have been designed for and the existing interfaces (UI, CLI, API) that can be used to manage the lifecycle of tags.

Be the first to hear about news, product updates, and innovation from IBM Cloud