March 9, 2021 By Rossella De Gaetano 6 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:

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>
  • From the the Resource List:
  • 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 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:

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:

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:

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.

Was this article helpful?
YesNo

More from Cloud

Attention new clients: exciting financial incentives for VMware Cloud Foundation on IBM Cloud

4 min read - New client specials: Get up to 50% off when you commit to a 1- or 3-year term contract on new VCF-as-a-Service offerings, plus an additional value of up to USD 200K in credits through 30 June 2025 when you migrate your VMware workloads to IBM Cloud®.1 Low starting prices: On-demand VCF-as-a-Service deployments begin under USD 200 per month.2 The IBM Cloud benefit: See the potential for a 201%3 return on investment (ROI) over 3 years with reduced downtime, cost and…

24 IBM offerings winning TrustRadius 2024 Top Rated Awards

2 min read - TrustRadius is a buyer intelligence platform for business technology. Comprehensive product information, in-depth customer insights and peer conversations enable buyers to make confident decisions. “Earning a Top Rated Award means the vendor has excellent customer satisfaction and proven credibility. It’s based entirely on reviews and customer sentiment,” said Becky Susko, TrustRadius, Marketing Program Manager of Awards. Top Rated Awards have to be earned: Gain 10+ new reviews in the past 12 months Earn a trScore of 7.5 or higher from…

IBM Tech Now: April 8, 2024

< 1 min read - ​Welcome IBM Tech Now, our video web series featuring the latest and greatest news and announcements in the world of technology. Make sure you subscribe to our YouTube channel to be notified every time a new IBM Tech Now video is published. IBM Tech Now: Episode 96 On this episode, we're covering the following topics: IBM Cloud Logs A collaboration with IBM watsonx.ai and Anaconda IBM offerings in the G2 Spring Reports Stay plugged in You can check out the…

IBM Newsletters

Get our newsletters and topic updates that deliver the latest thought leadership and insights on emerging trends.
Subscribe now More newsletters