IBM Cloud Docs
Working with tags

Working with tags

Use tags to organize, track usage costs, and even manage access to your resources and service IDs. You can tag related resources and view them throughout your account by filtering by tags from your resource list.

To see a full list of tags in your account, go to Manage > Account in the IBM Cloud® console, and select Tags.

You can apply user tags to organize your resources and service IDs and easily find them later. User tags can also help you with identifying specific team usage or cost allocation. By creating access management tags, you can control access to your resources and service IDs without requiring updates to your IAM policies.

Tag types

There are three types of tags: service, user, and access management.

User tags
User tags are added to resources or service IDs by an authorized user in the account. Add user tags to your resources to organize, track, and manage costs for related resources. When you use a consistent tagging schema to identify which resources are tied to specific teams, you can group and filter by those tags when you analyze costs within your exported usage report.

Consider using a project to organize and track resources across accounts. Resources that are created by deploying a project automatically have service tags attached with the project ID and configuration ID. This way, you don't have to manage tagging related resources maually.

Service tags
Service tags are attached by services. No users are authorized to attach or detach service tags on a resource, even if they have access to manage tags on the resource.

Resources that are created by deploying a project are automatically tagged with the project ID and configuration ID, which is available on your usage report. Use projects to help you track spending for projects. For more information, see Tracking usage and spend for projects.

Access management tags
Access management tags are used to manage access to resources. They can be created in advance for use in access policies, which grant access to the resources where access management tags are attached. Only the account administrator can create access management tags, and they can delete them only when the tags aren't attached to any resources in the account. Only the resource administrator can attach and detach access management tags on the resource itself.

Tagging rules

Tags are not case-sensitive, any uppercase characters are converted to lowercase, and the maximum length of a tag is 128 characters. The permitted characters are A-Z, 0-9, spaces, underscore, hyphen, period, and colon. The only supported format for access management tags is key:value. The use of a colon formats the tag into a string that isolates two logical parts, like a env:dev pair. A comma separates multiple tags and can't be used within the tag name itself.

Tags are visible account-wide and can be replicated across geographic regions. Since tags are not regulated information, avoid creating tags that use personal information, such as your name, address, phone number, email address, or other identifying or proprietary information.

Sample tags and syntax

You can apply tags to help you organize and manage your resources, service IDs, and access policies. Consider writing tags as key:value pairs to help coordinate your development environments, projects, compliance, and optimization throughout your organization. See the following table for some examples of tags that you might want to use.

Table 1. Tag syntax
Tag Description
env:dev, env:test, env:stage, env:prod Use to identify or even manage access to your development environment
project:lw-wizard, app:poc-app Use to identify or even manage access to a project
dataresidency:germany, compliance:hipaa, compliance:pii Use to define compliance requirements
schedule:24x7, maxruntime:12days Use to help you automate optimization

Creating tags

Creating user tags

You don't need to create user tags to attach them to resources or service IDs. For more information, see Attaching and detaching tags.

Creating access management tags in the console

Before you can attach your access management tags to individual resources or service IDs, you need to create them first. To create access management tags, you must have the administrator role on either the Tagging Service or on All Account management services.

IBM Cloud® allows up to 250 access management tags per account.

  1. Go to Manage > Account in the IBM Cloud® console, and select Tags.
  2. Click Access management tags.
  3. Type the names of your tags, and click Create Tags. These tags are now ready to be attached to resources or service IDs, and to scope access policies.

Next, see Attaching and detaching tags. For a full tutorial, see Controlling access to resources by using tags.

Creating access management tags by using the CLI

Before you can attach your access management tags to individual resources or service IDs, you need to create them first. To create access management tags, you need to have administrator role on either the Tagging Service that is listed under the Account management services or on all Account management services.

IBM Cloud® allows up to 250 access management tags per account.

  1. Log in to IBM Cloud CLI. If you have multiple accounts, you are prompted to select which account to use. If you do not specify a region with the -r flag, you must also select a region.

    ibmcloud login
    

    If your credentials are rejected, you might be using a federated ID. To log in with a federated ID, use the --sso flag. See Logging in with a federated ID for more details.

    If it's your first time using the IBM Cloud CLI, check out the getting started tutorial.

  2. Enter the ibmcloud resource tag-create command to create an access management tag in your account. This example creates a tag that is called project:myproject:

    ibmcloud resource tag-create --tag-names project:myproject
    

For more information, see the ibmcloud resource command reference.

Next, see Attaching and detaching tags.

Creating access management tags by using the API

Before you can attach your access management tags to individual resources or service IDs, you need to create them first. To create access management tags, you need to have administrator role on either the Tagging Service that is listed under the Account management services or on all Account management services.

IBM Cloud® allows up to 250 access management tags per account.

You can programmatically create access management tags by calling the Global Search and Tagging - Tagging API as shown in the following sample request. The example creates a tag that is called project:myproject.

curl -X POST -H "Authorization: {iam_token}" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{ "tag_names": ["project:myproject"] }' \
"tags.global-search-tagging.cloud.ibm.com/v3/tags?tag_type=access"
CreateTagOptions createTagOptions = new CreateTagOptions.Builder()
    .addTagNames("project:myproject")
    .tagType("access")
    .build();

Response<CreateTagResults> response = service.createTag(createTagOptions).execute();
CreateTagResults createTagResults = response.getResult();
System.out.println(createTagResults);
const params = {
  tagNames: ['project:myproject'],
  tagType: 'access',
};

globalTaggingService.createTag(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err)
  });
create_tag_results = global_tagging_service.create_tag(
  tag_names=['project:myproject'],
  tag_type='access').get_result()

print(json.dumps(create_tag_results, indent=2))
createTagOptions := globalTaggingService.NewCreateTagOptions(
  []string{"project:myproject"},
)
createTagOptions.SetTagType("access")

createTagResults, response, err := globalTaggingService.CreateTag(createTagOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(createTagResults, "", "  ")
fmt.Println(string(b))

Next, see Attaching and detaching tags.

Creating access management tags by using Terraform

Before you can create access management tags by using Terraform, make sure that you have completed the following:

  • Install the Terraform CLI and configure the IBM Cloud Provider plug-in for Terraform. For more information, see the tutorial for Getting started with Terraform on IBM Cloud®. The plug-in abstracts the IBM Cloud APIs that are used to complete this task.
  • Create a Terraform configuration file that is named main.tf. In this file, you define resources by using HashiCorp Configuration Language. For more information, see the Terraform documentation.
  • Before you can attach your access management tags to individual resources or service IDs, you need to create them first. To create access management tags, you need to have administrator role on either the Tagging Service that is listed under the Account management services or on all Account management services.

IBM Cloud® allows up to 250 access management tags per account.

Use the following steps to create access management tags by using Terraform:

  1. Create an argument in your main.tf file. The following example creates the access management tag ibm_tag to the ibm resource for the resource ID ibm_satellite_location.location.crn.

    resource "ibm_resource" "ibm" {
    resource_id = ibm_satellite_location.location.crn
    tags        = [ "ibm_tag" ]
    }
    
  2. After you finish building your configuration file, initialize the Terraform CLI. For more information, see Initializing Working Directories.

    terraform init
    
  3. Provision the resources from the main.tf file. For more information, see Provisioning Infrastructure with Terraform.

    1. Run terraform plan to generate a Terraform execution plan to preview the proposed actions.

      terraform plan
      
    2. Run terraform apply to create the resources that are defined in the plan.

      terraform apply
      

Searching for tags in the console

You can search for tags and tag related resources by using any of the following methods:

  • Try the search bar that is located in the IBM Cloud® console menu bar.
  • You can filter your resource list by the tag you are searching for.
  • From the application detail page, you can locate the tags that are associated with that resource.

The same tag can be attached to multiple resources and service IDs by different users in the same billing account, and not all users have visibility on all resources on the account.

Tagging for resellers

All tags are visible to all members of an account. To view the policy of an access management tag, the user must be assigned at least a viewer role on the tagged resource. If your account is associated with different organizations, if you're a reseller for example, you might want to recommend your customers not to store sensitive information in tags.

To control tag visibility, circulate tagging guidelines and let users know that tags are visible account-wide.

Use codes rather than names for clients and accounts and avoid placing sensitive information in tags.