Oracle Cloud Infrastructure Documentation

Tagging Overview

Oracle Cloud Infrastructure Tagging enables you to add metadata to resources. This 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.

How Tagging Works

The Tagging service provides two ways for you to approach adding tags to resources. Each approach offers a different type of tag for you to work with:

  • Defined tags - tag administrators manage resource metadata.
  • Free-form tags - unmanaged metadata applied to resources by users.

One approach involves a tag administrator creating and managing all the tags that users will apply to resources. You use IAM policy to limit who can create tags to a few select tag administrators, while granting all others in the tenancy only the ability to apply tags. The benefit to this approach is that you can create and manage the keys and values used to tag resources. This avoids typos that weaken automation based on tags and provides better reporting based on tags.

The other approach is to allow users to add tags to resources. Each tag is edited or applied at the resource by you or a user creating or modifying a resource.

You can use both types of tags throughout your tenancy. Most of the Tagging features require defined-tags. "Tag" is used generically to refer to defined tags. To create metadata that you can trust to manage resources and collect data, use defined tags. With defined tags, the following scenarios become possible: 

  • You can create default tags that are applied to all resources in compartments. See Managing Tag Defaults.
  • Specify that users must apply tags to resources to successfully create resources in compartments.
  • If you make a typo using defined tags, you can correct it by editing or even deleting. When you delete a defined tag, Oracle removes the key (and any value) for that tag from all resources. See Deleting Tag Key Definitions and Namespace.
  • Associate a list of predefined values for a defined tag. See Using Predefined Values.
  • Use system variables to automatically generate values for defined tags or tag defaults. See Using Tag Variables.
  • Track costs based on defined tags. See Using Cost-Tracking Tags.

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.
Tag 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 two data types are supported: string and a list of strings.
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 the user applying the tag adds to the tag key. Tag values support two data types: strings and lists of strings. You can define a list of values for the user to select from when you define the tag key, or you can allow the user to enter any value when the tag is applied to the resource. If you select a string tag value when you create the key, the user can leave the value blank when they apply the key.
In the example:
Operations is the namespace, CostCenter is the tag key, and 42 is the tag value.
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 Understanding Free-form Tags.
Cost tracking
Cost tracking is a feature supported for defined tags. Tags enabled for cost tracking (also called cost-tracking tags) help you to manage costs in your tenancy. You can use cost-tracking tags to track projected costs and set budgets and receive alerts when your costs reach a particular threshold. See Using Cost-Tracking Tags.
Tag Default
Tag defaults let you specify tags to be applied automatically to all resources, in a specific compartment, at the time of creation, regardless of the permissions of the user who creates the resource. See Managing Tag Defaults.
You can retire a tag key definition or a tag namespace. 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.
You can reactivate a tag namespace or tag key definition that has been retired to reinstate its usage in your tenancy.
Tag Variable
You can use a variable to set the value of a tag. When you add or update a tag on a resource, the variable resolves to the data it represents. See Using Tag Variables.
Predefined values
You can use a variable to set the value of a tag. When you add or update a tag on a resource, the variable resolves to the data it represents. See Using Predefined Values.

Authentication and Authorization

Each service in Oracle Cloud Infrastructure integrates with IAM for authentication and authorization, for all interfaces (the Console, SDK or CLI, and REST API).

An administrator in your organization needs to set up groups , compartments , and policies  that control which users can access which services, which resources, and the type of access. For example, the policies control who can create new users, create and manage the cloud network, launch instances, create buckets, download objects, etc. For more information, see Getting Started with Policies. For specific details about writing policies for each of the different services, see Policy Reference.

If you’re a regular user (not an administrator) who needs to use the Oracle Cloud Infrastructure resources that your company owns, contact your administrator to set up a user ID for you. The administrator can confirm which compartment or compartments you should be using.

For administrators: Use the following topics to find example of IAM policy for Tagging

Region Availability

Tagging is currently available in all regions.

Ways to Access Oracle Cloud Infrastructure

You can access Oracle Cloud Infrastructure using the Console (a browser-based interface) or the REST API. Instructions for the Console and API are included in topics throughout this guide. For a list of available SDKs, see Software Development Kits and Command Line Interface.

To access the Console, you must use a supported browser. You can use the Console link at the top of this page to go to the sign-in page. You will be prompted to enter your cloud tenant, your user name, and your password.

Limits on Tags

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

  • Tag namespaces: 100 tag namespaces per tenancy
  • Tags per Tag namespace: 100 tags per tag namespace
  • 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: 5 K (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