Tagging Overview

Tag Types

Private Cloud Appliance supports two kinds of tags:

Free-form tags are created and applied to resources by users. They contain unmanaged metadata.
Defined tags offer a structured approach to tagging. Administrators create and manage the metadata, while users only have the ability to apply a tag to a resource, and in some cases add a value.

Most of the tagging features require defined tags. They ensure that the applied metadata is reliable for managing resources, collecting accurate information and automating certain operations. With defined tags, the following scenarios become possible:

Creating default tags that are applied to all resources in compartments.
Specifying that users must apply tags to resources to successfully create resources in compartments.
If you make a typo using defined tags, correct it by editing or even deleting the tag. When you delete a defined tag, the key and any value for that tag are removed from all resources.
Associating a list of predefined values with a defined tag.
Using system variables to generate values for defined tags or tag defaults automatically.

Both free-form tags and defined tags can be used simultaneously within a tenancy. The table below shows a feature comparison of the two types.

Feature	Free-form Tags	Defined Tags
Hierarchy	Free-form tags consist of a key and a value, but do not belong to a namespace.	Defined tags consist of a tag namespace, a key, and a value.
Creation and application	Free-form tags can be applied during resource creation or to an existing resource.	The tag namespace and tag key definition must be set up in advance by an administrator. Defined tags can be applied during resource creation or to an existing resource.
Predefined keys and values	Not supported.	When applying a defined tag, users select from the list of tag keys. Administrators can also create a list of predefined values to associate with a tag key. When applying a tag to a resource, users must select a value from that list.
Variables	Not supported.	Variables are used to set the value of a defined tag. When a user applies the tag, the variable is resolved and replaced with the data it represents.
Case sensitivity	Free-form tag keys and values are both case sensitive.	In defined tags, the key is not case sensitive; only the tag values are case sensitive.

Free-form tags allow users to quickly and conveniently include relevant information in the metadata of a resource. However, you should be aware of their limitations:

When applying a free-form tag, you cannot see a list of existing free-form tags, so you do not know what tags and values have already been used. It is not possible to list the free-form tags used in your tenancy. The OCI CLI does allow you to list a set of resources and view the free-form tags applied to them.
You cannot control access to resources based on free-form tags. They cannot be used in IAM policy statements.
You cannot use predefined tag values or tag variables in free-form tags.

Categorization with Defined Tags

This section describes how defined tags work and which permissions are required.

Tag Namespaces and Keys

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. Within each namespace, the tag keys must be unique, but a tag key name can be repeated across namespaces. 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.

Permissions for Working with Defined Tags

Setting up and managing tag namespaces and key definitions is an administrator responsibility. Full management permissions for tag namespaces are required.

To apply, update, or remove defined tags for a resource, users must be granted use access for the tag namespaces they need to work with. Users must also have the permission to update the resource to which they apply a tag. 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 those instances. For resources that do not include the update permission with the use verb, you can create a policy statement to grant only the update permission from the manage verb.

Here are a few examples of policy statements related to tagging:

Administrators must be allowed to define tag namespaces and keys.
```
Allow group TagAdmins to manage tag-namespaces in tenancy
```

Users are granted permission to apply tags from all namespaces in the tenancy, or a subset.

Allow group GroupA to use tag-namespaces in tenancy

or

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

or

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

Users are granted permission to update resources in order to apply tags.

Allow group GroupA to use instance-family in compartment CompartmentA

or

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

Tag Management Features

This section describes the operations available to an administrator who sets up and manages tag namespaces and key definitions.

Retiring and Reactivating Tag 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 searching, listing, sorting, or reporting.

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

When you reactivate a tag key, it is again available for users 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

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

Deleting Tag Definitions

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. 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 several hours depending on the number of resources that were tagged. When all tags have been 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 keys. The tag namespace can be deleted only after all its tag key definitions have been deleted.

Using Predefined Values

You can create a list of values and associate that list with a tag key definition. When users then apply the tag to a resource, they must select a value from the list of predefined values. Use lists of predefined values to impose limits on the values that users can apply to tags.

In the OCI CLI and Compute API, predefined values are specified through what is known as a validator. The validator is a parameter of a defined tag, used to supply the predefined values in JSON format. The Compute Web UI does not mention the term "validator", though it follows the same principle.

You can update existing tags to use predefined values. Every list of predefined values that you create must contain at least one value. Lists cannot contain duplicate values or blank entries. With predefined values, users applying tags cannot set the value of a tag to null.

You can use predefined values with defined tags and default tags. In combination with a default tag, users are required to select a tag value from the predefined list for each resource they create in the compartment where the default tag is used. This ensures that new resources contain metadata with values that you expect and can trust.

Using Tag Variables

You can use a variable to set the value of a defined tag. When users add the tag to a resource, the variable resolves to the data it represents. You can use tag variables in defined tags and default tags.

Consider the following example:

Operations.CostCenter="${iam.principal.name} at ${oci.datetime}"

Operations is the namespace, CostCenter is the tag key, and the tag value contains two tag variables ${iam.principal.name} and ${oci.datetime}. When you add this tag to a resource, the variables resolve to your user name – the name of the principal who applied the tag – and a time stamp for when you added the tag.

user-name at 2021-04-18T14:32:57.604Z

The variable is replaced with data at the moment the tag is applied to a given resource. If you later edit the tag, the variable is gone and only the data remains. You can edit the tag value in all the ways you would edit any other tag value.

To create a tag variable, you must use a specific format. The following tag variables are supported:

Variable	Description
`${iam.principal.name}`	The name of the principal applying the tag to the resource.
`${iam.principal.type}`	The type of principal applying the tag to the resource.
`${oci.datetime}`	The date and time when the tag was created.

Tag Defaults

Tag defaults let you specify tags that are applied automatically to all resources at the time of creation in a specific compartment. This feature allows you to ensure that appropriate tags are applied at resource creation without requiring the user creating the resource to have access to the tag namespaces.

Tag defaults allow tenancy administrators to create secure permissions boundaries between users concerned with governance and users who need to create and manage resources. Tag defaults are defined for a specific compartment. A default tag is also applied to child compartments and the resources created within them. In the Compute Web UI, you manage tag defaults on the Compartment Details page.

To create or edit a tag default for a compartment, you must be granted the following combination of permissions:

manage tag-defaults access for the compartment where you are adding the tag default
use tag-namespaces access for the compartment where the tag namespace resides
inspect tag-namespaces access for the tenancy

Tag defaults must include a tag value. If you use a default value, then you must create it as part of the tag default. This value is applied to all resources. Using a tag variable is allowed. If you specify that a user-applied value is required, then the user creating the resource must enter the value for the tag at the time of resource creation. Users cannot create resources without entering a value for the tag.

Tag defaults can be overridden at the time of resource creation by users who have the appropriate permissions to both create the resource and to use the tag namespace. Users with these permissions can also modify the default tags that were applied at resource creation at any later time.

You can define up to 5 tag defaults per compartment. After a tag default is created in a compartment, the default tag is applied to any new resources created in that compartment. Previously existing resources in the compartment are not tagged retro-actively. If you change the default value of the tag default, existing occurrences are not updated.

If you delete the tag default from the compartment, existing occurrences of the tag are not removed from resources. When you delete a tag key definition, existing tag defaults based on that tag key definition are not removed from the compartment. Until you delete the tag default in the compartment, it continues to count against your limit of 5 tag defaults per compartment.

Retired tags cannot be applied to new resources. Therefore, if the tag namespace or tag key specified in a tag default is retired, when new resources are created, the retired tag is not applied. As a best practice, you should delete the tag default that specifies the retired tag.

Tag-Based Access Control

Using conditions and a set of tag variables, you can write policy to scope access based on the tags that have been applied to a resource. Access can be controlled based on a tag that exists on the requesting resource or on the target resource or compartment of the request. Tag-based access control provides additional flexibility to your policies by allowing you to define access policies with tags that span compartments, groups, and resources.

Caution:

If your organization chooses to create policies that use tags to manage access, then ensure that you have appropriate controls in place to govern who can apply tags. Also, after policies are in place, keep in mind that applying tags to a group, user, or resource has the potential to confer access to resources.

Before you create such a policy, ensure that you are aware of all the potential requestors and target resources that carry the tag.

Before you apply a tag to a resource, ensure that you are aware of any policies in place that include the tag and could impact who has access to the resource.

You can control access based on the value of a tag applied to a requesting resource. More specifically, you can write policy statements to grant a user access based on the value of a tag that is assigned to the group to which the requesting user belongs.

You can also control access based on the value of a tag applied to a target resource, or a compartment that the target resource resides in.

By using tags in your policy statements to scope access, you can define access for multiple groups through a single policy statement. You can also confer access and revoke access for groups by applying or removing tags, without changing the original policies.

The Oracle Private Cloud Appliance User Guide provides a detailed description and examples of how to use tag variables and operators in your policy syntax. Refer to the section "Writing Policy Statements" in the chapter Identity and Access Management.

Important Notes and Limitations

This section describes a number of items to take into account when you start writing policies to control permissions based on resource tags.

Item	Description
Permissions to list resources must be granted separately	Policies that scope access based on the tag applied to the target resource cannot allow the permissions that enable you to return a list of resources. Therefore, permissions to allow listing a resource must be granted through an additional policy statement. This approach improves the tag-based policy because it allows users to see the resource they want to manage, but still limits the permissions to only inspect. Another approach you can use to avoid this limitation is to tag the compartments that contains the resources you want to grant access to.
Policies requiring a tag on the target resource cannot grant create permissions	When you write a policy to scope access based on the value of a tag on the resource, keep in mind that the policy cannot grant create permissions. For example, a request to create an instance would fail because the target resource has not been created yet and therefore does not have the appropriate tag to be evaluated. Using and deleting instances with that tag would be allowed, but not creating instances.
Limitations on characters in tag namespaces and tag key definitions used in policy variables	Tag namespaces and tag key definitions support a broader set of characters than are allowed in policy variables. Therefore, to you use tag namespaces and tag key definitions in variables, ensure that they only include the characters also supported by policy variables. Supported characters are: `a-z, A-Z, 0-9, _, @, -, :` If your tag namespaces or tag keys have characters other than these, you cannot use them in policy variables. Tag namespaces and tag keys cannot be renamed, so you will have to create new tag namespaces and tag key definitions.
Considerations for case	When working with tags in policies, be aware that tag values are case insensitive.
Compartment hierarchies	When you write a condition to allow access based on the tag applied to a target compartment, remember that this policy also allows access to all compartments nested inside the tagged compartment. All subcompartments in the tagged compartment are resources in the tagged compartment, and therefore the policy grants access.
Supported services	All services support the `request.principal.group`, and `target.resource.compartment.tag` policy variables. Not all services support the `target.resource.tag` policy variable. The supported services are: Compute, Networking, IAM, DNS, File Storage, Block Storage.

Example Using Tags Applied to a Group

Following is an example that demonstrates how you can use tags applied to user groups to manage access to resources in a compartment.

Assume you have three compartments: ProjectA, ProjectB, and ProjectC. For each compartment, there is an admin group set up: A-Admins, B-Admins, and C-Admins. Each admin group has full access over their compartment through the following policies:

allow group A-Admins to manage all-resources in compartment ProjectA
allow group B-Admins to manage all-resources in compartment ProjectB
allow group C-Admins to manage all-resources in compartment ProjectC

Your organization has set up the following tag namespace and key to tag each group by its role: EmployeeGroup.Role. Some values for this tag are 'Admin', 'Developer', 'Test-Engineer'. All your admin groups are tagged with EmployeeGroup.Role='Admin'.

Now you want to set up a Test compartment for members of the three projects to share. You want to give Admin access to all three of your existing admin groups. To accomplish this, you can write a policy like:

allow any-group to manage all-resources in compartment Test where
request.principal.group.tag.EmployeeGroup.Role='Admin'

With this policy, all of your existing admin groups with the tag will have access to the Test compartment. Also, any new or existing groups that you tag with EmployeeGroup.Role='Admin' in the future will have access to the Test compartment without having to update the policy statements.

Example Using Tags Applied to a Target Resource's Compartment

In this example, each of your organization's project compartments contains two child compartments: Test and Prod. You want to give your test engineers access to the test compartments across all three projects. To accomplish this, you create a tag, ResourceGroup.Role='Test', and apply this to the Test compartments in each of your project compartments.

To allow your group Testers to access the resources across all three test compartments, you can then use a policy like:

allow group Testers to use all-resources in tenancy where
target.resource.compartment.tag.ResourceGroup.Role='Test'