Resource Tag Management

3 Resource Tag Management

Oracle Private Cloud Appliance Tagging enables you to add metadata to resources by applying key/value pairs called defined tags or free-form tags. You can create tag defaults on compartments, which are tags that are automatically applied to all newly created resources in the tagged compartment. Uses for tags include:

Applying access policies to resources. For example, you can change ownership of a resource to a different product group by changing a tag value on the resource rather than changing the resource access policy directly. See Using Defined Tags in Conditions).
Filtering resource lists in the Compute Web UI.

For conceptual information, see the Tagging Overview and "How Policies Work" in the Identity and Access Management Overview in the Oracle Private Cloud Appliance Concepts Guide.

Creating and Managing Tag Namespaces

Tag namespaces enable you to create collections of related tags. After you create a tag namespace, create tag key definitions within that tag namespace. See Creating and Managing Tag Key Definitions. Tag namespaces with tag key definitions must exist in the tenancy before users can apply a defined tag to a resource.

Creating a Tag Namespace

A tenancy can have at most 100 tag namespaces.

Using the Compute Web UI

In the navigation menu, click Governance, and then click Tag Namespaces.
Above the list of tag namespaces, click the Create Namespace Definitions button.
In the Create Namespace Definition window, enter the following information:
- Create in Compartment: The compartment in which you want to create the namespace definition.
- Namespace Definition Name: A name for this tag namespace. Tag namespace names have the following characteristics:
  - Must be unique within the tenancy.
  - Are case insensitive.
  - Cannot be changed later.
  - Can be no more than 100 characters.
  - Cannot contain period (.) or space characters.
- Description: A description for this set of tags. This description can be no more than 256 characters.
- Tagging: (Optional) Add defined or free-form tags for this tag namespace as described in Adding Tags at Resource Creation. Tags can also be applied later.
Click Create Namespace Definition.

The new tag namespace definition is displayed on the Tag Namespaces page.

Using the OCI CLI

Get the OCID of the compartment where you want to create the tag namespace.
```
$ oci iam compartment list --compartment-id-in-subtree true
```
Run the tag namespace create command.

Syntax:
```
oci iam tag-namespace create --compartment-id compartment_OCID --name tag_namespace_name \
--description "text"
```
You can tag the new tag namespace during creation by adding the options described in Adding Tags at Resource Creation.

Example:
```
$ oci iam tag-namespace create --compartment-id ocid1.compartment.unique_ID --name Products \
--description "Identify resources used in product development."
```
This command returns the same output as the tag-namespace get command.

Updating a Tag Namespace

Using the Compute Web UI

In the navigation menu, click Governance, and then click Tag Namespaces.
If the tag namespace that you want to modify is not listed, use the Compartment drop-down menu above the tag namespaces list to select the correct compartment.
For the namespace that you want to modify, click the Actions menu, and click the Edit option.

The Edit dialog is displayed.
Update the tag namespace.

You can modify the description of a tag namespace and add or modify tags on the tag namespace.
Click Update Tag Namespace.

Using the OCI CLI

Get the tag namespace OCID.

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

Run the tag namespace update command.

Syntax:
```
oci iam tag-namespace update --tag-namespace-id tag_namespace_OCID --description "text"
```
To add or modify a tag on the tag namespace, add the options described in Applying Tags to an Existing Resource.

Example:
```
$ oci iam tag-namespace update --tag-namespace-id ocid1.tagnamespace.unique_ID \
--description "Identify resources used to develop different products."
```
This command returns the same output as the tag-namespace get command.

Retiring a Tag Namespace

When you retire a tag namespace, all tag key definitions and tags in that tag namespace are retired, and you cannot create new tag key definitions in that tag namespace. Retired tags cannot be applied to resources. However, retired tags remain applied to any resources where they were already applied and can still be used in operations such as listing, sorting, and filtering.

Using the Compute Web UI

In the navigation menu, click Governance, and then click Tag Namespaces.
If the tag namespace that you want to retire is not listed, use the Compartment drop-down menu above the tag namespaces list to select the correct compartment.
For the tag namespace that you want to retire, click the Actions menu, and click the Retire option.
At the Retire Tag Namespace confirmation prompt, click Confirm.

The state of the tag namespace changes to Inactive. On the details page for the tag namespace, the tag key definitions are also in state Inactive.

Using the OCI CLI

Get the tag namespace OCID.

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

Run the tag namespace retire command.

Syntax:
```
oci iam tag-namespace retire --tag-namespace-id tag_namespace_OCID
```
This command returns the same output as the tag-namespace get command.

Reactivating a Tag Namespace

You can reactivate a tag namespace that is retired. When you reactivate a tag namespace, you can create new tag key definitions in that tag namespace.

When you reactivate a retired tag namespace, the tag key definitions and tags are not reactivated. To use tag key definitions that were retired with the namespace, you must explicitly reactivate each tag key definition.

Using the Compute Web UI

In the navigation menu, click Governance, and then click Tag Namespaces.
If the tag namespace that you want to reactivate is not listed, use the Compartment drop-down menu above the tag namespaces list to select the correct compartment.
For the tag namespace that you want to reactivate, click the Actions menu, and click the Reactivate option.
At the Reactivate Tag Namespace confirmation prompt, click Confirm.

The state of the tag namespace changes to Active. On the details page for the tag namespace, the tag key definitions are still shown as Inactive.

Using the OCI CLI

Get the tag namespace OCID.

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

Run the tag namespace reactivate command.

Syntax:
```
oci iam tag-namespace reactivate --tag-namespace-id tag_namespace_OCID
```
This command returns the same output as the tag-namespace get command.

Moving a Tag Namespace to a Different Compartment

You can move an active or retired tag namespace and its tag key definitions to a different compartment within the same tenancy.

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

To move a tag namespace, you must use the OCI CLI.

Using the OCI CLI

Get the following information:
- The OCID of the compartment where you want to move the tag namespace.
```
$ oci iam compartment list --compartment-id-in-subtree true
```
- The tag namespace OCID.
```
$ oci iam tag-namespace list --compartment-id compartment_OCID
```

Run the tag namespace move command.

Syntax:

oci iam tag-namespace change-compartment --compartment-id destination_compartment_OCID \
--tag-namespace-id tag_namespace_OCID

Use the tag-namespace get command to verify the new compartment-id.

Deleting a Tag Namespace

A tag namespace must be retired before it can be deleted. See Retiring a Tag Namespace.

To delete a tag namespace, all tag key definitions in that namespace must be deleted. See Deleting a Tag Key Definition.

Using the Compute Web UI

In the navigation menu, click Governance, and then click Tag Namespaces.
If the tag namespace that you want to delete is not listed, use the Compartment drop-down menu above the tag namespaces list to select the correct compartment.
Ensure that the tag namespace that you want to delete is retired (in state Inactive).
Click the name of the tag namespace that you want to delete.
In the Resources box on the tag namespace details page, click Tag Key Definitions.
Ensure that all tag key definitions are deleted.
On the Controls menu at the top of the details page, click the Delete option.
At the Delete Tag Namespace confirmation prompt, click Confirm.

The tag namespace is removed from the Tag Namespace list, and tags in that tag namespace are removed from resources.

Using the OCI CLI

Get the tag namespace OCID.

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

Ensure that the tag namespace that you want to delete is retired (in state Inactive).
```
$ oci iam tag-namespace get --tag-namespace-id tag_namespace_OCID
```
Ensure that all tag key definitions for this tag namespace are deleted.
```
$ oci iam tag list --tag-namespace-id tag_namespace_OCID
```

Run the tag namespace delete command.

Syntax:

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

Example:

$ oci iam tag-namespace delete --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 namespace delete:

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

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

Creating and Managing Tag Key Definitions

A tag namespace contains tag key definitions. Instances of tag key definitions that are applied to resources are called defined tags.

A tag key definition includes a tag key name and tag value type. A tag key definition might include a value, depending on the tag value type. The tag value type specifies whether the tag user enters a value or selects a predefined value when applying a tag to a resource.

For more information about tag key definitions, including required permissions, see the Tagging Overview in the Oracle Private Cloud Appliance Concepts Guide.

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.

Configuring Tag Defaults

A tag default is a defined tag that is automatically applied to resources that are created in the specified compartment.

Tag defaults have the following characteristics:

The tag default is applied to all new resources that are created in that compartment, including in child compartments.
The tag default is not applied to resources that already existed before the tag default was created.
Tag defaults cannot be changed by creating or editing resources. With permission to use the tag namespace, you can change the value of the tag when you create or modify a resource. To change the tag default that will be applied to all new resources in the compartment, you must update the tag default on the compartment.
If you change the default value of the tag default, existing occurrences of that tag default on resources are not updated.
If you change a value of a tag key definition whose value is a defined list, or if you delete a tag key definition, existing occurrences of a tag default that is based on that tag key definition are not updated. Tag default values must be separately updated.

See Creating and Managing Tag Key Definitions for information about the effect on tag defaults of retiring or deleting tag key definitions. For more information about tag defaults, see "Tag Defaults" in the Tagging Overview in the Oracle Private Cloud Appliance Concepts Guide.

Creating a Tag Default

To create a tag default, specify a compartment, a tag key definition, and a value. If the value of the selected tag key definition is Static Value, then you can select User-Defined Value for the value of the tag default.

A compartment can have at most five tag defaults.

Using the Compute Web UI

In the navigation menu, click Identity, and then click Compartments.
If the compartment where you want to add a tag default is not listed, navigate to the correct compartment.

Click the name of the top-level parent compartment and, on the compartment details page, scroll to the Child Compartments box. If necessary, click on the name of another compartment to view those child compartments.
Click the name of the compartment to which you want to add a tag default.
In the Resources section on the compartment details page, click Tag Defaults.

Ensure that no more than four tag defaults already exist in this compartment.
Click the Create Tag Default button.
In the Tag Default dialog, select the Tag Namespace and the Tag Key.
For Required Tag Value Options, choose one of the following value types:
- Default Value: Enter the value for this tag default. If the selected tag key has a defined list of values, then this Default Value must be a member of that list.
- User-Defined Value: Users are required to enter the value when a resource is created. Selecting User-Defined Value is invalid if the selected tag key definition has a predefined list of values.
Click Submit.

The new tag default is displayed on the compartment details page.

Using the OCI CLI

Get the following information:
- The OCID of the compartment on which you want to create the tag default.
```
$ oci iam compartment list --compartment-id-in-subtree true
```
- The OCID of the tag key definition.
```
$ oci iam tag list --tag-namespace-id tag_namespace_OCID
```
Ensure that no more than four tag defaults already exist in this compartment.
```
oci iam tag-default list --compartment-id compartment_OCID
```

Run the tag default create command.

Syntax:

oci iam tag-default create --compartment-id compartment_OCID \
--tag-definition-id tag_definition_OCID --value text

Example:

$ oci iam tag-default create --compartment-id ocid1.compartment.unique_ID \
--tag-definition-id ocid1.tag.unique_ID --value 789

Depending on your shell, you might need to escape the dollar symbol to specify a variable value:

$ oci iam tag-default create --compartment-id ocid1.compartment.unique_ID \
--tag-definition-id ocid1.tag.unique_ID --value "Assigned by: \${iam.principal.name}"

This command returns the same output as the tag-default get command.

Example: Creating Oracle-Tags Tag Defaults

On Oracle Cloud Infrastructure, all resources are tagged with the name of the user that created the resource and the time the resource was created. This example shows you how to achieve the same result on Private Cloud Appliance.

This task can be done using either the Compute Web UI or the OCI CLI. Only the OCI CLI is shown.

Using the OCI CLI

Create the Oracle-Tags tag namespace.

Get the OCID of the compartment in which you want to create the tag namespace. Because the goal of this example is for these tag defaults to be applied to every resource in every compartment, create the tag namespace in the tenancy. Use the following command to find the OCID of the tenancy:

$ oci iam compartment list --include-root

Create the tag namespace.

$ oci iam tag-namespace create -c ocid1.tenancy.unique_ID --name "Oracle-Tags" \
--description "OCI compatibility: add creator and create date of resource"
{
  "data": {
    "compartment-id": "ocid1.tenancy.unique_ID",
    "defined-tags": {},
    "description": "OCI compatibility: add creator and create date of resource",
    "freeform-tags": {},
    "id": "ocid1.tag_namespace.unique_ID",
    "is-retired": false,
    "lifecycle-state": "ACTIVE",
    "name": "Oracle-Tags",
    "time-created": "2022-06-07T14:51:23.256790+00:00"
  },
  "etag": "a000d250-3aea-4faf-b0e6-b6db486ffb42"
}

Create a CreatedBy tag in the Oracle-Tags tag namespace.

Use the value of the id property from the tag-namespace create command for the tag namespace ID. The --validator option is not required.

$ oci iam tag create --tag-namespace-id ocid1.tag_namespace.unique_ID \
--name CreatedBy --description "user that created this resource" \
--validator '{"validator-type":"ENUM","values":["${iam.principal.name}"]}'
{
  "data": {
    "compartment-id": "ocid1.tenancy.unique_ID",
    "defined-tags": {},
    "description": "user that created this resource",
    "freeform-tags": {},
    "id": "ocid1.tag.unique_ID",
    "is-cost-tracking": false,
    "is-retired": false,
    "lifecycle-state": "ACTIVE",
    "name": "CreatedBy",
    "tag-namespace-id": "ocid1.tag_namespace.unique_ID",
    "tag-namespace-name": "Oracle-Tags",
    "time-created": "2022-06-07T15:32:22.226554+00:00",
    "validator": {
      "validator-type": "ENUM",
      "values": [
        "${iam.principal.name}"
      ]
    }
  },
  "etag": "fa18d128-fc7b-420d-87d6-c44a574e522a"
}

Create a CreatedOn tag in the Oracle-Tags tag namespace.

$ oci iam tag create --tag-namespace-id ocid1.tag_namespace.unique_ID \
--name CreatedOn --description "date this resource was created" \
--validator '{"validator-type":"ENUM","values":["${oci.datetime}"]}'

Create a CreatedBy tag default.

To apply this tag default to every new resource created in any compartment, create the tag default in the tenancy.

Use the value of the id property from Step 2 for the tag definition ID. The --value option is required.

$ oci iam tag-default create -c ocid1.tenancy.unique_ID 
--tag-definition-id ocid1.tag.unique_ID --value "\${iam.principal.name}"
{
  "data": {
    "compartment-id": "ocid1.tenancy.unique_ID",
    "id": "ocid1.tag_default.unique_ID",
    "is-required": null,
    "lifecycle-state": "ACTIVE",
    "tag-definition-id": "ocid1.tag.unique_ID",
    "tag-definition-name": "CreatedBy",
    "tag-namespace-id": "ocid1.tag_namespace.unique_ID",
    "time-created": null,
    "value": "${iam.principal.name}"
  },
  "etag": "None"
}

Create a CreatedOn tag default.

Use the value of the id property from Step 3 for the tag definition ID.

$ oci iam tag-default create -c ocid1.tenancy.unique_ID 
--tag-definition-id ocid1.tag.unique_ID --value "\${oci.datetime}"

Whenever a new resource is created in the tenancy or any subcompartment of the tenancy, the following tags are applied, even if no tags are specified when the resource is created:

"defined-tags": {
  "Oracle-Tags": {
    "CreatedBy": "flast",
    "CreatedOn": "2022-06-07T16:09:47.01Z"
  }
}

Updating the Value of a Tag Default

Using the Compute Web UI

In the navigation menu, click Identity, and then click Compartments.
If the compartment where you want to update a tag default is not listed, navigate to the correct compartment.

Click the name of the top-level parent compartment and, on the compartment details page, scroll to the Child Compartments box. If necessary, click on the name of another compartment to view those child compartments.
Click the name of the compartment that has the tag default whose value you want to change.
In the Resources section of the compartment details page, click Tag Defaults.
For the tag default that you want to change, click the Actions menu, and click the Edit option.
In the Tag Defaults dialog, specify the type of value you want the tag default to have:
- Default Value: Enter the value for this tag default. If the selected tag key has a defined list of values, then this Default Value must be a member of that list.
- User-Defined Value: Users are required to enter the value when a resource is created. Selecting User-Defined Value is invalid if the selected tag key definition has a predefined list of values.
Click Submit.

The updated tag default is displayed on the compartment's details page.

Using the OCI CLI

Get the OCID of the tag default that you want to modify.

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

Run the tag default update command.

Syntax:
```
oci iam tag-default update --tag-default-id tag_default_OCID --value text
```
This command returns the same output as the tag-default get command.

Deleting a Tag Default

When you delete a tag default from a compartment, existing occurrences of the tag are not removed from resources.

Using the Compute Web UI

In the navigation menu, click Identity, and then click Compartments.
If the compartment where you want to delete a tag default is not listed, navigate to the correct compartment.

Click the name of the top-level parent compartment and, on the compartment details page, scroll to the Child Compartments box. If necessary, click on the name of another compartment to view those child compartments.
Click the name of the compartment that has the tag default that you want to delete.
In the Resources section of the compartment details page, click Tag Defaults.
For the tag default that you want to delete, click the Actions menu, and click the Delete option.
At the Delete Default Tag confirmation prompt, click Confirm.

On the compartment details page, the state of the tag default is Deleting.

Using the OCI CLI

Get the OCID of the tag default that you want to delete.

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

Run the tag default delete command.

Syntax:

oci iam tag-default delete --tag-default-id tag_default_OCID

Example:

$ oci iam tag-default delete --tag-default-id ocid1.tag-default.unique_ID
Are you sure you want to delete this resource? [y/N]: y

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

Working with Resource Tags

Tagging resources enables you to identify characteristics of resources and apply the same policies to a group of resources. For more information about policies, see Using Defined Tags in Conditions.

Note the following requirements:

To apply, modify, or delete a tag on a resource, you must have permission to update the resource.
To apply, modify, or delete a defined tag on a resource, you must also have use access on the tag namespace.
A resource can have at most 64 defined tags and ten free-form tags.

Adding Tags at Resource Creation

Any tag defaults that are defined on a compartment are automatically added to all resources that are created in that compartment, or any child compartment of that compartment, after the tag default was defined. A tag default might require you to enter a value for the tag in order to create the resource. See Configuring Tag Defaults.

Using the Compute Web UI

In the Create dialog for the resource, scroll to the Tagging section.
Select the Tag Namespace or select None (apply a free-form tag).
- If you selected a Tag Namespace, then select the Tag Key, and enter a value or select a value from the list.
- If you selected None (apply a free-form tag), then enter a Tag Key and enter a value.
To apply another tag, click the Additional Tag button.

You cannot specify more than one tag with the same tag namespace and the same tag key for a defined tag, or more than one tag with the same tag key for a free-form tag.
To review the tags on the resource, to go the details page for the new resource.

On the resource details page, click the Tags tab to display the tags that are applied to this resource.

Using the OCI CLI

To add a tag to a resource when you create the resource, use the resource create or launch command.

Get the information for each tag that you want to add to the resource.
- Get the namespace, key, and value for each defined tag that you want to add to the resource.
  
  Construct an argument for the --defined-tags option. Specify each tag namespace and tag key pair only one time.
- Get the key and value for each free-form tag that you want to add to the resource.
  
  Construct an argument for the --freeform-tags option. Specify each tag key only one time.
The value of the --defined-tags option argument and the --freeform-tags option argument is a JSON definition of the tags. 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 tags (--defined-tags in this example) without the option indicator (--), as shown in the following example:
```
$ oci service resource create \
--generate-param-json-input defined-tags > defined_tags.json
```
The content of the output defined_tags.json file is:
```
{
  "tagNamespace1": {
    "tagKey1": "tagValue1",
    "tagKey2": "tagValue2"
  },
  "tagNamespace2": {
    "tagKey1": "tagValue1",
    "tagKey2": "tagValue2"
  }
}
```
If you specify freeform-tags instead of defined-tags in the preceding command, you get the following output:
```
{
  "tagKey1": "tagValue1",
  "tagKey2": "tagValue2"
}
```
Edit these templates to provide the desired tags. Specify the result in the final command as shown in the following step.
Run the resource create or launch command.

If you want to add one or more defined tags, use the --defined-tags option. If you want to add one or more free-form tags, use the --freeform-tags option.

Syntax:
```
oci service resource create --compartment-id compartment_OCID \
--defined-tags defined_tags_json --freeform-tags freeform_tags_json \
other_resource_create_options
```
Example:

In the following example, one or more defined tags is added using a file, and a free-form tag is added using a string argument. Use the file:// syntax to specify a file as the option argument.
```
$ oci service resource create --compartment-id ocid1.compartment.unique_ID \
--defined-tags file://defined_tags.json --freeform-tags '{"MyTag":"val-u"}' \
other_resource_create_options
```
The output of the resource create or launch command is the same as the output of the resource get command. The output shows the defined and free-form tags.

Applying Tags to an Existing Resource

Using the Compute Web UI

In the resource Edit dialog, scroll to the Tagging section.

You can add tags, and you can modify or delete any tags that already exist.
To add tags, click the Additional Tag button if necessary, and select the Tag Namespace or select None (apply a free-form tag).
- If you selected a Tag Namespace, then select a Tag Key, and enter a value or select a value from the list.
- If you selected None (apply a free-form tag), then enter a Tag Key and enter a value.
You cannot specify more than one tag with the same tag namespace and the same tag key for a defined tag, or more than one tag with the same tag key for a free-form tag.
To modify existing tags, change the selections or enter different values.
To delete a tag, click the trash can.
When you are finished adding and modifying tags, click Save Changes.
To review the tags on the resource, go to the details page for the resource.

On the resource details page, click the Tags tab to display the list of tags that are applied to this resource.

Using the OCI CLI

To add tags to an existing resource, and modify or delete any tags that already exist, use the resource update command.

Get the namespace, key, and value information for each tag that you want to add to the resource.
Create a JSON definition of the tags that you want to apply. See Adding Tags at Resource Creation for information about how to create correct JSON.

Note:

Any defined tags that already exist on this resource will be replaced by the --defined-tags argument. Any free-form tags that already exist on this resource will be replaced by the --freeform-tags argument. Be sure to include any existing tags that you want to keep in the new arguments for these options.

Use the resource get command to show the current defined and free-form tags.
Run the resource update command.

If you want to apply one or more defined tags, use the --defined-tags option. If you want to apply one or more free-form tags, use the --freeform-tags option.

The output of the resource update command is the same as the output of the resource get command. The output shows the defined and free-form tags.

Filtering a List of Resources by Tag

Using the Compute Web UI

Display a list of resources.
Under Filter by Tag(s), click Select Tag(s).
Do the following in the Filter by Tag dialog:
1. Select either Defined Tag or Free-Form Tag.
  - If you select Defined Tag, then select a Tag Namespace and a Tag Key.
  - If you selected Free-Form Tag, then enter a Tag Key.
2. Optionally enter values in the Select Values (optional) field.
  - Leave the Select Values (optional) field blank. This option returns all resources that are tagged with the selected namespace and key (for defined tags) or returns all resources that are tagged with the specified key (for free-form tags), regardless of the tag value.
  - Enter values in the Select Values (optional) field. This option returns all resources that are tagged with any of the tag value(s) that you enter. Select a value or enter a single value in the text box. To specify multiple values for the same namespace and key, enter Enter or Return, and then enter a new value. Each value is displayed below the text box.
3. Click Filter by Tag.
  
  The filter that is currently applied is displayed on the Select Tag(s) button.
To filter by multiple tags, click the + on the Select Tag(s) button, and repeat the previous step.
To remove a filter, click the filter definition on the Select Tag(s) button.

Using the OCI CLI

Use the list command for the resource to show each resource in the specified compartment.

The information for each resource shows the existing defined tags and free-form tags.
Use tools for your operating system to filter the list.