Creating and Managing Tag Key Definitions

Creating a Tag Key Definition

Create a tag key definition within a tag namespace. A tag namespace can have at most 100 tag key definitions.

Using the Compute Web UI

In the navigation menu, click Governance, and then click Tag Namespaces.
If the tag namespace where you want to add the tag key definition is not listed, use the Compartment drop-down menu above the tag namespaces list to select the correct compartment.
Click the name of the tag namespace where you want to add a tag key definition.
In the Resources box on the tag namespace details page, click Tag Key Definitions.
In the Tag Key Definitions area, click the Create Tag Key Definition button.
In the Create Tag Key Definition window, enter the following information:
- Name: The key name. Tag key names have the following characteristics:
  - Must be unique within the namespace.
    
    The same tag key name can be used in different tag namespaces.
  - Are case insensitive.
  - Cannot be changed later.
  - Can be no more than 100 characters.
  - Cannot contain period (.) or space characters.
- Description: A description for the tag key definition. This description can be no more than 256 characters.
Select the Tag Value Type.
- Static Value: Not populated. The user must enter a value when the tag is applied to a resource. This is the default selection.
- A List of Values: A predefined list of values. Enter at least one value. The user must select one of these predefined values to apply to a resource.
  
  Separate multiple values with new lines. Duplicate values and blank lines are invalid. Values are case sensitive and can be no more than 256 characters.
  
  A value can include one of the following variables:
  
  ${iam.principal.name}
  
  The name of the user that tagged the resource.
  
  ${iam.principal.type}
  
  The type of principal that tagged the resource. One of: root user, IAM user, or Instance principal.
  
  ${oci.datetime}
  
  The date and time that the tag was created.
Click Create Tag Key Definition.

The new tag key definition is displayed on the details page for the tag namespace.

Using the OCI CLI

Get the tag namespace OCID.

$ oci iam tag-namespace list --compartment-id compartment_OCID

Run the tag key definition create command.

The following command creates a tag key definition in which the user must enter a tag value when the tag is applied to a resource. Omitting the --validator option is comparable to selecting the Static Value value type in the Compute Web UI.

Syntax:
```
oci iam tag create --tag-namespace-id tag_namespace_OCID --name text --description "text"
```
Example:
```
$ oci iam tag create --tag-namespace-id ocid1.tagnamespace.unique_ID --name VolumeType \
--description "Identify volumes by type"
```
The following command creates a tag key definition with a list of values from which the user must select when applying the tag.

Syntax:
```
oci iam tag create --tag-namespace-id tag_namespace_OCID --name text --description "text" \
--validator values
```
The value of the --validator option argument is a JSON definition of the tag values. This JSON definition can be provided as a string on the command line or in a file.

You can generate a template of the correct JSON to provide by using the --generate-param-json-input option with the base command that you will use to tag the resource. The argument for the --generate-param-json-input option is the name of the option that you will use to specify the tag values (--validator) without the option indicator (--), as shown in the following example:
```
$ oci iam tag create --generate-param-json-input validator > volume_types.json
```
The following is the content of the output volume_types.json file:
```
{
  "validatorType": "ENUM",
  "values": [
    "string",
    "string"
  ]
}
```
Edit this template to provide new tag values. The value of values is a single string or an array of strings. The validator-type must be ENUM. Specify the result to the --validator option in the final command.

In the following example, the tag values are provided in an inline JSON string.
```
$ oci iam tag create --tag-namespace-id ocid1.tagnamespace.unique_ID --name VolumeType \
--description "Identify volumes by type" \
--validator '{"validator-type": "ENUM", "values": ["typeA","typeB","typeC"]}'
```
The following example includes a variable value:
```
$ oci iam tag create --tag-namespace-id ocid1.tagnamespace.unique_ID --name Product-XYZ \
--description "Identify resources assigned to XYZ development." \
--validator '{"validator-type": "ENUM", "values": ["Assigned by: ${iam.principal.name}"]}'
```
In the following example, the tag values are provided in a JSON file. Use the file:// syntax to specify a file as the option argument.
```
$ oci iam tag create  --tag-namespace-id ocid1.tagnamespace.unique_ID --name VolumeType \
--validator file://volume_types.json
```
This command returns the same output as the tag get command.

Updating a Tag Key Definition

You can update the description of a tag key definition and change the tag value type and value. You cannot update a tag key definition that is retired.

If the value of the tag key definition that you are updating is a predefined list, you cannot remove or change any value that is the value of a tag default. To remove or change a tag key definition value that is the value of a tag default, first update the tag default to use a different value. See Configuring Tag Defaults.

Using the Compute Web UI

In the navigation menu, click Governance, and then click Tag Namespaces.
If the tag namespace where you want to update a tag key definition is not listed, use the Compartment drop-down menu above the tag namespaces list to select the correct compartment.
Click the name of the tag namespace where you want to update a tag key definition.
In the Resources box on the tag namespace details page, click Tag Key Definitions.
For the tag key definition that you want to update, click the Actions menu, and click the Edit option.
In the Edit Tag Key Definition dialog, you can modify the description or change the tag value type. If you choose A List of Values for the type, you must add at least one value in the Value box. Separate multiple values with new lines. Duplicate values and blank lines are invalid. Values are case sensitive and can be no more than 256 characters.
Click Save Changes.

Using the OCI CLI

Get the following information:

The tag namespace OCID.

$ oci iam tag-namespace list --compartment-id compartment_OCID

The name of the tag key.

$ oci iam tag list --tag-namespace-id tag_namespace_OCID

Run the tag key definition update command.

The following command updates only the tag key description. Values settings remain the same.

Syntax:
```
oci iam tag update --tag-namespace-id tag_namespace_OCID --tag-name text --description "text"
```
Example:
```
$ oci iam tag update --tag-namespace-id ocid1.tagnamespace.unique_ID --tag-name VolumeType \
--description "Identify the type of the volume."
```
The following command updates only the values.
```
$ oci iam tag update --tag-namespace-id ocid1.tagnamespace.unique_ID --tag-name VolumeType \
--validator file://volume_types.json
WARNING: Updates to freeform-tags and defined-tags and validator will replace any existing 
values.
Are you sure you want to continue? [y/N]: y
```
See Creating a Tag Key Definition for the content of the volume_types.json file. Values that you provide to the --validator option replace any existing values. To add values or to change only some of the values, provide the complete list in this update.

The following command updates the value type to allow the user to enter a value rather than select from a predefined list of values.
```
$ oci iam tag update --tag-namespace-id ocid1.tagnamespace.unique_ID --tag-name VolumeType \
--validator '{}'
```
This command returns the same output as the tag get command.

Retiring a Tag Key Definition

When you retire a tag key definition, you cannot apply tags that are based on this tag key definition to resources. Existing tag defaults that are based on this tag key definition will not be automatically applied to newly created resources. However, the tag is not removed from resources where it was already applied. The tag still exists as metadata on those resources and you can still use the retired tag in operations such as listing, sorting, and reporting.

Using the Compute Web UI

In the navigation menu, click Governance, and then click Tag Namespaces.
If the tag namespace where you want to retire a tag key definition is not listed, use the Compartment drop-down menu above the tag namespaces list to select the correct compartment.
Click the name of the tag namespace where you want to retire a tag key definition.
In the Resources box on the tag namespace details page, click Tag Key Definitions.
For the tag key definition that you want to retire, click the Actions menu, and click the Retire option.
At the Retire Tag Key Definition confirmation prompt, click Confirm.

Using the OCI CLI

Get the following information:

The tag namespace OCID.

$ oci iam tag-namespace list --compartment-id compartment_OCID

The name of the tag key.

$ oci iam tag list --tag-namespace-id tag_namespace_OCID

Run the tag key definition retire command.

Syntax:

oci iam tag retire --tag-name text --tag-namespace-id tag_namespace_OCID

Reactivating a Tag Key Definition

When you reactivate a tag key definition, it is again available for you to apply to resources. You cannot reactivate a tag key definition if the parent tag namespace is retired.

Using the Compute Web UI

In the navigation menu, click Governance, and then click Tag Namespaces.
If the tag namespace where you want to reactivate a tag key definition is not listed, use the Compartment drop-down menu above the tag namespaces list to select the correct compartment.
Click the name of the tag namespace where you want to reactivate a tag key definition.
In the Resources box on the tag namespace details page, click Tag Key Definitions.
For the tag key definition that you want to reactivate, click the Actions menu, and click the Reactivate option.
At the Reactivate Tag Namespace confirmation prompt, click Confirm.

Using the OCI CLI

Get the following information:

The tag namespace OCID.

$ oci iam tag-namespace list --compartment-id compartment_OCID

The name of the tag key.

$ oci iam tag list --tag-namespace-id tag_namespace_OCID

Run the tag key definition reactivate command.

Syntax:

oci iam tag reactivate --tag-name text --tag-namespace-id tag_namespace_OCID

Deleting a Tag Key Definition

A tag key definition must be retired before it can be deleted. See Retiring a Tag Key Definition.

When you delete a tag key definition, tags that are based on this tag key definition are removed from all resources. Tag defaults that are based on this tag key definition are not removed from compartments.

Using the Compute Web UI

In the navigation menu, click Governance, and then click Tag Namespaces.
If the tag namespace where you want to delete a tag key definition is not listed, use the Compartment drop-down menu above the tag namespaces list to select the correct compartment.
Click the name of the tag namespace where you want to delete a tag key definition.
In the Resources box on the tag namespace details page, click Tag Key Definitions.
Ensure that the tag key definition that you want to delete is retired (in state Inactive).
For the tag key definition that you want to delete, click the Actions menu, and click the Delete option.

You cannot restore a deleted tag key definition.
At the Delete Tag Key Definition prompt, click Confirm.

The tag key definition status changes to Deleting, and all tags that are based on this tag key definition are removed from resources.

When the tag removal process is finished, the tag key definition status changes to Deleted. You can create a new tag key definition with the same name as the deleted tag key definition.

Using the OCI CLI

Get the following information:

The tag namespace OCID.

$ oci iam tag-namespace list --compartment-id compartment_OCID

The name of the tag key.

$ oci iam tag list --tag-namespace-id tag_namespace_OCID

Ensure that the tag key definition that you want to delete is retired (in state Inactive).
```
$ oci iam tag get --tag-namespace-id tag_namespace_OCID
```

Run the tag key definition delete command.

Syntax:

oci iam tag delete --tag-name text --tag-namespace-id tag_namespace_OCID

Example:

$ oci iam tag delete --tag-name volume-types --tag-namespace-id ocid1.tagnamespace.unique_ID
Are you sure you want to delete this resource? [y/N]: y
{
  "opc-work-request-id": "ocid1.workrequest.unique_ID"
}

Use the following command to check the status of the tag delete:

$ oci iam tagging-work-request get --work-request-id ocid1.workrequest.unique_ID

To delete a tag key definition without confirmation, use the --force option.