Managing Tags and Tag Namespaces

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.

Overview of Tags and Tag Namespaces

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. When you create the tag key definition, you must choose the type of value (which also determines how the user applying the tag adds the value): 

  • You can leave it empty so that a user can fill in the value.
  • You can create a list of values so that the user must choose from those values.

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. If the tag key contains a blank value, the user can type in a value or leave it blank. If the tag key contains a list, the user must select a value from the list.

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. 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

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 needs to use the namespace.

Note

Tag namespaces and tag key definitions beginning with "oci" and "orcl" are reserved for internal use.

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 users can apply a defined tag to a resource.
  • You can create the tag key with either a tag value type of string (for the user to add a value or leave blank) or a list of values (from which the user must choose).
  • When applying a defined tag, users select from the list of tag keys.
  • Users 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.
  • You can use tag variables.
  • You can create a list of predefined variables to associate with a tag key. Users that apply the tag to a resource must select a value from the list you create.

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
Important

To apply tags to a resource when using the Console, a user must have permissions to inspect tag-namespaces in tenancy. If the user does not have this permission, the list of tag namespaces cannot be presented to the user in the dialog menu.

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 allow usage of a specific tag namespace or namespaces, use a where clause with the target.tag-namespace.name variable. For example:

Allow group GroupA to use tag-namespaces in tenancy where target.tag-namespace.name='Operations'

or to specify multiple tag namespaces:

Allow group GroupA to use tag-namespaces in tenancy where any {target.tag-namespace.name='Operations', target.tag-namespace.name='HumanResources'}

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 (and only the Operations tag namespace), add the following statements to the InstanceLaunchers policy:

Allow group InstanceLaunchers to use tag-namespaces in compartment CompartmentA where target.tag-namespace.name='Operations'

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

Retiring Key Definitions and Namespace Definitions

You can retire a tag key definition or a tag namespace definition.

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. 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. You can't update tag key definitions that are in the retired state.

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 create new tag key definitions in that 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.

Moving Tag Namespaces to a Different Compartment

You can move a tag namespace to a different compartment. The tag namespace can be active or retired when you move it. When you move the tag namespace, all its tag key definitions are moved along with it.

This functionality is useful if you need to reorganize your compartment hierarchy, or if you need to delete a compartment that contains a retired tag namespace. Remember that you can't delete a compartment that contains resources. A retired tag namespace, even though it is retired, is still an existing resource. Moving the retired tag namespace to a different compartment can enable you to delete its original containing compartment.

To move a tag namespace, you must be allowed to manage tag-namespaces in both compartments.

See the procedure To move a tag namespace to a different compartment.

Deleting Tag Key Definitions and Namespaces

You can delete tag key definitions and tag namespaces.

When you delete a tag key definition, you begin a process that removes the tag from all resources in your tenancy. These things happen immediately: 

  • If the tag was a cost-tracking tag, it no longer counts against your 10 cost-tracking tags limit, whether you first disabled it or not.
  • If the tag was used with dynamic groups, none of the rules that contain the tag will be evaluated against the tag.

The delete action is asynchronous and initiates a work request. Once you start the delete operation, the state of the tag changes to deleting, and tag removal from resources begins. This process can take up to 48 hours depending on the number of resources that were tagged as well as the regions in which those resources reside. When all tags are removed, the state changes to deleted. You cannot restore a deleted tag. After the tag state changes to Deleted, you can use the same tag name again.

To delete a tag key definition, you must first retire it. To delete a tag namespace, you must first retire the tag namespace. When you retire a tag namespace that contains tag key definitions, all the tag keys in the namespace are retired, allowing you to delete the tag namespace.

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
  1. Open the navigation menu. Under Governance and Administration, go to Governance and click Tag Namespaces.

    A list of the tag namespaces in your current compartment is displayed.

  2. Click Create Namespace Definition.
  3. Enter the following:
    • Create in Compartment: The compartment in which you want to create the namespace definition.
    • Namespace Definition Name: A unique name for this set of tags. The name must be unique within your tenancy. Tag namespace is case insensitive. You cannot change this value later.
    • Description: A friendly description. You can change this value later if you want to.
  4. Click Create Namespace Definition.
To update a tag namespace's description
  1. Open the navigation menu. Under Governance and Administration, go to Governance and click Tag Namespaces.

    A list of the tag namespaces in your tenancy is displayed.

  2. Click the tag namespace you want to update.

    The namespace's details are displayed. The description is displayed under the namespace's name.

  3. Click the pencil next to the description.
  4. Edit the description and save it.
To retire a tag namespace
  1. Open the navigation menu. Under Governance and Administration, go to Governance and click Tag Namespaces.

    A list of the tag namespaces in your current compartment is displayed.

  2. Click the tag namespace you want to retire.

    The namespace's details are displayed.

  3. Click Retire Tag Namespace.
  4. Confirm when prompted.
To reactivate a tag namespace
  1. Open the navigation menu. Under Governance and Administration, go to Governance and click Tag Namespaces.

    A list of the tag namespaces in your current compartment is displayed.

  2. Click the tag namespace you want to reactivate.

    The namespace's details are displayed.

  3. Click Reactivate Tag Namespace.
  4. Confirm when prompted.
To move a tag namespace to a different compartment
  1. Open the navigation menu. Under Governance and Administration, go to Governance and click Tag Namespaces.

    A list of the tag namespaces in your current compartment is displayed.

  2. Click the tag namespace you want to move.

    The namespace's details are displayed.

  3. Click Move Tag Namespace.
  4. Select the Target Compartment that you want to move the tag namespace to.
  5. Click Move Tag Namespace.
To delete a tag namespace

To delete a tag namespace, you must first retire it.

  1. Open the navigation menu. Under Governance and Administration, go to Governance and click Tag Namespaces.

    A list of the tag namespaces in your current compartment is displayed.

  2. Click the tag namespace that you want to delete.

    The namespace's details are displayed.

  3. Click Delete Tag Namespace.

    Tip

    If the Delete Tag Namespace option is unavailable, first retire your tag namespace.
  4. Confirm when prompted.

Managing Key Definitions

To create a key definition
  1. Open the navigation menu. Under Governance and Administration, go to Governance and click Tag Namespaces.

    A list of the tag namespaces in your current compartment is displayed.

  2. Click the tag namespace you want to add the tag key definition to.

    A list of the tag key definitions that belong to the namespace is displayed.

  3. Click Create Tag Key Definition.
  4. Enter the following:
    • Tag Key: Enter the key. The key can be up to 100 characters in length. Tag keys are case insensitive and must be unique within the tag namespace.
    • Description: Enter a friendly description.
    • Cost-tracking: Select the check box to enable this tag for cost tracking. You have a limit of 10 Using Cost-Tracking Tags in your tenancy.
  5. Under Tag Value Type, choose one of the following:
    • Static Value: Specifies that the user applying the tag can specify any value for this key.
    • A List of Values: Specifies that the user must apply a value from a list you create. When you select this option, the Values box appears. Type the values from which the user can select. Separate multiple values with new lines. You must have at least one value. You can't have blank lines or duplicate values.
  6. Click Create Tag Key Definition.
To update a tag key definition
  1. Open the navigation menu. Under Governance and Administration, go to Governance and click Tag Namespaces.

    A list of the tag namespaces in your current compartment is displayed.

  2. Click the tag namespace that includes the tag key definition you want to update.

    A list of the tag key definitions is displayed.

  3. Click the tag key definition you want to update.

    The key definition's details are displayed.

  4. Click Edit Tag Key Definition.

    The edit dialog appears.

    You can change the description, the tag value type, and enable or disable cost tracking.

    If you chose a list of values, the Values box appears, and you must add at least one value. You can't have blank lines or duplicate values in the Values box.

    You have a limit of 10 Using Cost-Tracking Tags in your tenancy.

  5. Make your changes and save it.

To retire a tag key definition
  1. Open the navigation menu. Under Governance and Administration, go to Governance and click Tag Namespaces.

    A list of the tag namespaces in your current compartment is displayed.

  2. Click the tag namespace that includes the tag key definition you want to retire.

    A list of the tag key definitions is displayed.

  3. Select the tag key definition you want to retire. To retire multiple tag key definitions at the same time, select all of the tag key definitions that you want to retire.

    Important

    If the tag is a cost-tracking tag, disable the cost-tracking flag. If you don't disable cost-tracking, this tag will still count against your tenancy maximum of 10 cost-tracking tags, even after it is retired. For more information, see Using Cost-Tracking Tags.
  4. Click Retire.
  5. Confirm when prompted.
To reactivate a tag key definition
  1. Open the navigation menu. Under Governance and Administration, go to Governance and click Tag Namespaces.

    A list of the tag namespaces in your current compartment is displayed.

  2. Click the tag namespace that includes the tag key definition you want to reactivate.

    A list of the tag key definitions is displayed.

  3. Select the tag key definition you want to reactivate. To reactivate multiple tag key definitions at the same time, select all of the tag key definitions that you want to reactivate.

  4. Click Reactivate.
  5. Confirm when prompted.
To delete a tag key definition

To delete a tag key definition, you must first retire it.

  1. Open the navigation menu. Under Governance and Administration, go to Governance and click Tag Namespaces.

    A list of the tag namespaces in your current compartment is displayed.

  2. Click the tag namespace that includes the tag key definition you want to delete.

    A list of the tag key definitions is displayed.

  3. Select the retired tag key definition you want to delete. To delete multiple tag key definitions at the same time, select all of the tag key definitions that you want to delete. You can delete up to five tag key definitions at the same time.

  4. Click Delete.

    Tip

    If the Delete option is unavailable, first retire your tag key definition.
  5. Confirm when prompted.

    After you confirm, the state changes to Deleting. Track the progress of the operation using the work request.

    To track the progress of the delete operation
    1. Open the navigation menu. Under Governance and Administration, go to Governance and click Tag Namespaces.

      A list of the tag namespaces in your current compartment is displayed.

    2. Click the tag namespace that includes the tag key definition you deleted.

      A list of the tag key definitions is displayed.

    3. Click Work Requests.

      The work requests for deleted tag definitions are displayed.

To monitor a work request for a deleted tag
  1. Open the navigation menu. Under Governance and Administration, go to Governance and click Tag Namespaces.

    A list of the tag namespaces in your current compartment is displayed.

  2. Click the tag namespace that includes the tag key definition you deleted.

    A list of the tag key definitions is displayed.

  3. Click Work Requests.

    The work requests for deleted tag definitions are displayed.

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)
  • DeleteTag - deletes the tag key definition
  • BulkDeleteTags - deletes multiple tag key definitions

Use these API operations to manage work requests spawned by the DeleteTag operation: