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

Private cloud use cases: 6 ways private cloud brings value to enterprise business

7 min read - As cloud computing continues to transform the enterprise workplace, private cloud infrastructure is evolving in lockstep, helping organizations in industries like healthcare, government and finance customize control over their data to meet compliance, privacy, security and other business needs.  According to a report from Future Market Insights (link resides outside ibm.com), the global private cloud services market is forecast to grow to USD 405.30 billion by 2033, up from USD 92.64 billion in 2023.  What is a private cloud? A private cloud is…

Hyperscale vs. colocation: Go big or go rent?

9 min read - Here’s the situation: You’re the CIO or similarly empowered representative of an organization. Different voices within your business are calling attention to the awesome scalability and power of hyperscale computing, which you’ve also noticed with increasing interest. Now the word comes down from on high that you’ve been tasked with designing and implementing your company’s hyperscale computing solution—whatever that should be. Your organization already has an ambitious agenda in mind for whatever IT infrastructure you wind up choosing. The company…

IBM Tech Now: March 25, 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 95 On this episode, we're covering the IBM X-Force Threat Intelligence Index 2024: IBM X-Force Cyber Range Combating deepfakes Stay plugged in You can check out the IBM Blog Announcements for a full rundown…

IBM Newsletters

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