Oracle Cloud Infrastructure Documentation

Managing Tags and Tag Namespaces

When you have many resources (for example, instances, VCNs, load balancers, and block volumes) across multiple compartments in your tenancy, it can become difficult to track resources used for specific purposes, or to aggregate them, report on them, or take bulk actions on them. Tagging allows you to define keys and values and associate them with resources. You can then use the tags to help you organize and list resources based on your business needs.

Required IAM Policy

If you're in the Administrators group, then you have the required access for managing tag namespaces and tags. For more policy samples specific to working with tags and tag namespaces, see Required Permissions for Working with Defined Tags.

If you're new to policies, see Getting Started with Policies and Common Policies. If you want to dig deeper into writing policies for groups or other IAM components, see Details for IAM.

Overview of Tags

Oracle Cloud Infrastructure supports two kinds of tags: free-form tags and defined tags.

Tip

Watch a video to introduce you to the concepts and features of tagging: Introduction to Tagging.

Free-form Tags

Free-form tags consist simply of a key and a value, for example:

Environment: Production

where "Environment" is the key and "Production" is the value.

You can apply multiple free-form tags to a single resource (up to the limit).

This image shows two instances with free-form tags

Because free-from tags are limited in functionality, Oracle recommends you only use them when you are first getting started with tagging, to try out the tagging feature in your system. For more information about the features and limitations of free-form tags, see Working with Free-form Tags.

Defined Tags

Defined tags provide more features and control than free-form tags. Before you create a defined tag key, you first set up a tag namespace for it. You can think of the tag namespace as a container for a set of tag keys. Defined tags support policy to allow you to control who can apply your defined tags. The tag namespace is the entity to which you can apply policy.

To apply a defined tag to a resource, a user first selects the tag namespace, then the tag key within the namespace, and then they can assign the value. Administrators can control which groups of users are allowed to use each namespace.

The following diagrams illustrate defined tags. Two tag namespaces are set up: Operations and HumanResources. The tag keys are defined in the namespaces. Within each namespace, the tag keys must be unique, but a tag key name can be repeated across namespaces. In the example, both namespaces include a key named "Environment".

This image shows two namespaces with tag key definitions

The first instance is tagged with two tags from the Operations tag namespace, indicating that it belongs to the Operations production environment and the Operations project "Alpha". The second instance is tagged with tags from both the HumanResources tag namespace and the Operations tag namespace, indicating that it belongs to the HumanResources "Production" environment, the HumanResources cost center "42", and also the Operations project "Beta".

This image shows defined tags applied to instances, highlighting the concept of namespace

Tagging Concepts

Here's a list of the basic tagging concepts:

Tag Namespace
You can think of a tag namespace as a container for your tag keys. It consists of a name, and zero or more tag key definitions. Tag namespaces are not case sensitive, and must be unique across the tenancy. The namespace is also a natural grouping to which administrators can apply policy. One policy on the tag namespace applies to all the tag definitions contained in it.
Key
The name you use to refer to the tag. Tag keys are case insensitive (for example," mytagkey" duplicates "MyTagKey"). Tag keys for defined tags must be created in a namespace. A tag key must be unique within a namespace.
Tag Value Type
The tag value type specifies the data type allowed for the value. Currently the only data type supported is string.
Key Definition
A key definition defines the schema of a tag and includes a namespace, tag key, and tag value type.
Tag Value
The tag value is the value you give to the tag key. In the example:
Operations.CostCenter="42"
Operations is the namespace, CostCenter is the tag key, and 42 is the tag value. A tag value is optional. Tag values only support the string data type.
Tag (or Defined Tag)
A tag is the instance of a key definition that is applied to a resource. It consists of a namespace, a key and a value. "Tag" is used generically to refer to defined tags.
Free-form Tag
A basic metadata association that consists of a key and a value only. Free-form tags have limited functionality. See Working with Free-form Tags.
Cost-tracking
Cost tracking is a feature supported for defined tags. Tags enabled for cost tracking (also called cost-tracking tags) allow you use a tag to filter and subtotal your online statement to track usage and costs. For example, you could tag a group of resources with the “Finance.CostCenter” tag and then see the cost generated by just those resources. You view your online statement in My Services.
Retire
You can't delete a tag key definition or a tag namespace. Instead, you retire them. Retired tag namespaces and key definitions can no longer be applied to resources. However, retired tags are not removed from the resources to which they have already been applied. You can still specify retired tags when searching, filtering, reporting, and so on.
Reactivate
You can reactivate a tag namespace or tag key definition that has been retired to reinstate its usage in your tenancy.

Taggable Resources

The following table lists resources that support tagging. This table will be updated as tagging support is added for more resources.

Service Taggable Resource Types
Block Volume

volumes

volume_backups

volume_groups

volume_group_backups

Compute

instance

instance-image

instanceconsoleconnections

Database

db-systems

databases

File Storage

filesystem

mount-targets

snapshots

IAM

groups

users

compartments

tenancy (root compartment)

policies

tag-namespaces

tag-definitions (API only)

identity-providers

Load Balancing load-balancers
Networking

vcns

route-tables

security-lists

dhcp-options

subnets

vnics

private-ips

public-ips

internet-gateways

local-peering-gateways

nat-gateways

service-gateways

drgs

cpes

ipsec-connections

Object Storage and Archive Storage buckets

Working with Free-form Tags

Free-form tags consist simply of a key-value pair. Free-form tags have limited features. To experience the full feature set of tagging, use defined tags.

Features of free-form tags include:

  • Consist of a key and a value. Free-form tags do not belong to a namespace.
  • You can apply free-form tags during resource creation or to an existing resource.
  • Free-form tag keys are case sensitive. For example, "Project" and "project" are distinct keys.
  • Free-form tag values are case sensitive. For example, "alpha" and "Alpha" are distinct values.

Limitations of free-form tags include:

  • When applying a free-form tag, you can't see a list of existing free-form tags, so you don't know what tags and values have already been used.
  • You can't see a list of existing free-form tags in your tenancy.
  • You can't use free-form tags to control access to resources (that is, you can't include free-form tags in IAM policies).

Required Permissions for Working with Free-form Tags

To apply, update, or remove free-form tags for a resource, you must have the update permission on the resource. For many resources, the update permission is granted with the use verb. For example, users who can use instances in CompartmentA, can also apply, update, or remove free-form tags for instances in CompartmentA.

Some resources don't include the update permission with the use verb. To allow a group to apply, update, or remove free-form tags for these resources without granting the full permissions of manage, you can add a policy statement to grant only the <RESOURCE>_UPDATE permission from the manage verb. For example, to allow a group NetworkUsers to work with free-from tags with VCNs in CompartmentA, you could write a policy like:

Allow group NetworkUsers to use vcns in compartment CompartmentA

Allow group NetworkUsers to manage vcns in compartment CompartmentA where request.permission='VCN_UDPATE'

The inspect verb for a resource grants permissions to view free-form tags for that resource. So users who can inspect instances in CompartmentA can also view any free-form tags applied to the instance.

For information about resource permissions, see Policy Reference.

Working with Defined Tags

You must set up the tag namespace and tag keys in your tenancy before users can apply a defined tag to a resource. As part of the set up process, you must also grant permissions to the user groups that will need to use the namespace.

Features of defined tags include:

  • Consist of a tag namespace, a key, and a value.
  • The tag namespace and tag key definition must be set up in your tenancy before you can apply a defined tag to a resource.
  • When applying a defined tag, you select from the list of defined tag keys.
  • You can apply a defined tag during resource creation or to an existing resource.
  • Defined tag keys are case insensitive.
  • Defined tag values are case sensitive. For example, "alpha" and "Alpha" are distinct values.

Required Permissions for Working with Defined Tags

To apply, update, or remove defined tags for a resource, a user must be granted permissions on the resource and permissions to use the tag namespace.

Users must be granted use access on the tag namespace to apply, update, or remove a defined tag for a resource.

Some example policies for tag namespaces:

To allow a group to simply view the tag namespaces in the tenancy (or in a compartment) requires inspect access:

Allow group GroupA to inspect tag-namespaces in tenancy

To allow a group to read the tag definitions contained in tag namespaces requires read access:

Allow group GroupA to read tag-namespaces in tenancy

To allow a group to apply, update, or remove a defined tag for a resource requires the use access on the tag namespace:

Allow group GroupA to use tag-namespaces in tenancy

To manage tag namespaces and the tag definitions in them, requires manage access:

Allow group GroupA to manage tag-namespaces in tenancy

In addition to the permissions to work with the tag namespace, to apply or remove defined tags on a resource you must have the update permission for the resource. For many resources, the update permission is granted with the use verb. For example, users who can use instances in CompartmentA, can also apply, update, or remove defined tags for instances in CompartmentA.

Some resources don't include the update permission with the use verb. To allow a group to apply, update, or remove defined tags for these resources without granting the full permissions of manage, you can add a policy statement to grant only the <RESOURCE>_UPDATE permission from the manage verb. For example, to allow a group NetworkUsers to work with defined tags with VCNs in CompartmentA, you could write a policy like:

Allow group NetworkUsers to use vcns in compartment CompartmentA
Allow group NetworkUsers to manage vcns in compartment CompartmentA where request.permission='VCN_UDPATE'

The inspect permission for a resource grants permissions to view defined tags for that resource. For example, users who can inspect instances can also view any defined tags applied to the instance.

For information about resource permissions, see Policy Reference.

Example Scenario

Your company has an Operations department. Within the Operations department are several cost centers. You want to be able to tag resources that belong to the Operations department with the appropriate cost center.

  1. Create a tag namespace definition called Operations.
  2. In the Operations namespace, create a tag key definition called CostCenter.

Alice already belongs to the group InstanceLaunchers. Alice can manage instances in CompartmentA. You want Alice and other members of the InstanceLaunchers group to be able to apply the Operations.CostCenter tag to instances in CompartmentA.

To grant the InstanceLaunchers group access to the Operations tag namespace, add the following statements to the InstanceLaunchers policy:

Allow group InstanceLaunchers to use tag-namespaces in compartment CompartmentA 

Alice can now apply the Operations.CostCenter tag to resources in CompartmentA.

Using Cost-Tracking Tags

Cost-tracking tags are displayed in your online billing statement and allow you to filter and subtotal your costs for those resources tagged with a cost-tracking tag. Cost tracking is a feature you can enable for defined tags.

For example, suppose you have a defined tag key definition called CostCenter.Finance. You enable this tag definition for cost tracking. You apply the tag with a value of "W1" (CostCenter.Finance="W1") to some resources, and you apply the tag with a value of "C2" (CostCenter.Finance="C2") to some other resources. When you view your Account Balance and Usage Summary in My Services, you can filter the usage information to show you only the costs generated by the resources tagged with "CostCenter.Finance=W1" . You can then filter your usage summary by "CostCenter.Finance=C2". Using cost-tracking tags, you can compare and track resource usage based on tags.

Enabling Tags for Cost-Tracking

You can enable cost-tracking when you create a tag key definition, or you can update an existing tag key definition to enable cost tracking.

Viewing Usage by Cost-Tracking Tags

Important

After you apply a cost-tracking tag to a resource, allow 5 hours for the usage data to be available on your tenancy's Account Balance and Usage Summary.

Usage tracking by tag begins in the next metering cycle after the tag was applied (or enabled as a cost-tracking tag, if the tag already existed).

To view usage by cost-tracking tags:

  1. Navigate to My Services: Open the navigation menu, go to Administration and click My Services Dashboard.
  2. On the My Services dashboard, Account Management.
  3. On the Usage page, click the Filter by tags text box to select one or more tags. Usage summary is filtered based on all the tags you select.

For more information about this page, see Managing and Monitoring Oracle Cloud.

Limits on Cost-Tracking Tags

  • You can have a maximum of 10 tags enabled for cost-tracking in your tenancy at a time. This includes both active and retired tags.
  • There may be a delay of up to 5 hours between when a cost-tracking tag is applied to a resource and when the tag information is available in My Services.

Billable Resources That Support Cost-Tracking Tags

You can apply a tag that you have enabled for cost-tracking to any resource that supports tagging. However, not all taggable resources provide cost information to My Services that can be filtered by tag. Currently, the following resources support cost-tracking by tag:

  • Compute instances
  • Block Volumes
  • Object Storage buckets
  • Database instances, including Autonomous Data Warehouse and Autonomous Transaction Processing instances

Check back for support for more resources.

For resources that do not yet support cost-tracking by tag, you can still tag the resource with a cost-tracking tag, however, the usage for that resource is not included with the calculations for the tag.

Retiring Key Definitions and Namespace Definitions

You can't delete a tag key definition or a tag namespace definition. Instead, you can retire them.

When you retire a tag key definition, you can no longer apply it to resources. However, the tag is not removed from the resources that it was applied to. The tag still exists as metadata on those resources and you can still call the retired tag in operations (such as listing, sorting, or reporting).

Important

Retiring a tag stops cost tracking for the tag, but if you do not disable the cost-tracking option on the tag key definition, the retired tag continues to count against your maximum of 10 cost-tracking tags for your tenancy. Ensure that you disable cost tracking before you retire the tag key definition. To disable cost-tracking after a tag is retired, you must reactivate the tag key definition to update it. You can't update tag key definitions that are in the retired state.

When you retire a tag namespace, all the tag keys in the tag namespace are retired. As described above, this means that all tags in the tag namespace can no longer be applied to resources, though existing tags are not removed. No new keys can be created in the retired tag namespace.

Reactivating Tag Key Definitions and Namespace Definitions

You can reactivate retired tag key definitions and tag namespace definitions.

When you reactivate a tag key, it is again available for you to apply to resources.

When you reactivate a tag namespace, you can once again create tag key definitions in the namespace. However, if you want to use any of the tag key definitions that were retired with the namespace, you must explicitly reactivate each tag key definition.

Limits on Tags

See Service Limits for a list of applicable limits and instructions for requesting a limit increase.

Tags per resource: 10 free-form tags and 64 defined tags

Tags enabled for cost-tracking: 10 per tenancy (includes both active and retired tags)

Total tag data size: 5K (JSON). The total tag data size includes all tag data for a single resource (all applied tags and tag values). Sizing is per UTF-8.

Resource Supported Characters Max Length
Tag namespace Printable ASCII, excluding periods (.) and spaces 100 characters

Tag key name

(free-form and defined)

Printable ASCII, excluding periods (.) and spaces 100 characters

Tag value

(free-form and defined)

Unicode characters 256 characters

Using the Console

Warning

Avoid entering confidential information when assigning descriptions, tags, or friendly names to your cloud resources through the Oracle Cloud Infrastructure Console, API, or CLI.

Managing Tag Namespaces

To create a tag namespace
To retire a tag namespace
To reactivate a tag namespace
To delete a tag namespace

Managing Key Definitions

To create a key definition
To update a tag key definition's description
To enable or disable a tag key definition for cost-tracking
To retire a tag key definition
To reactivate a tag key definition
To delete a tag key definition

Using the API

For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.

Use these API operations to manage tag namespaces:

Use these API operations to manage tag key definitions:

  • GetTag - gets the tag key definition
  • ListTags - lists tag key definitions
  • ListCostTrackingTags - lists the tags that have been enabled for cost-tracking (can be performed in the root compartment only)
  • CreateTag - creates a tag key definition
  • UpdateTag - updates the tag key definition (use this operation to retire or reactivate a tag key)