Tagging your Amazon EMR on EKS resources
To help you manage your Amazon EMR on EKS resources, you can assign your own metadata to each resource using tags. This topic provides an overview of the tags function and shows you how to create tags.
Topics
Tag basics
A tag is a label that you assign to an Amazon resource. Each tag consists of a key and an optional value, both of which you define.
Tags enable you to categorize your Amazon resources by attributes such as purpose, owner, or environment. When you have many resources of the same type, you can quickly identify a specific resource based on the tags you've assigned to it. For example, you can define a set of tags for your Amazon EMR on EKS clusters to help you track each cluster's owner and stack level. We recommend that you devise a consistent set of tag keys for each resource type. You can then search and filter the resources based on the tags that you add.
Tags are not automatically assigned to your resources. After you add a tag, you can edit tag keys and values or remove tags from a resource at any time. If you delete a resource, any tags for the resource are also deleted.
Tags don't have any semantic meaning to Amazon EMR on EKS and are interpreted strictly as a string of characters.
A tag value can be an empty string, but not null. A tag key cannot be an empty string. If you add a tag that has the same key as an existing tag on that resource, the new value overwrites the earlier value.
If you use Amazon Identity and Access Management (IAM), you can control which users in your Amazon account have permission to manage tags.
For tag-based access control policy examples, see Policies for tag-based access control.
Tag your resources
You can tag new or existing virtual clusters and job runs that are in active states. The
active states for job runs include: PENDING, SUBMITTED,
RUNNING, and CANCEL_PENDING. The active states for virtual clusters
include: RUNNING, TERMINATING and ARRESTED. For more
information, see Job run states and
Virtual cluster states.
When a virtual cluster is terminated, tags are cleaned and no longer accessible.
If you're using the Amazon EMR on EKS API, the Amazon CLI, or an Amazon SDK, you can apply tags to new
resources using the tags parameter on the relevant API action. You can apply tags to existing
resources using the TagResource API action.
You can use some resource-creating actions to specify tags for a resource when the resource is created. In this case, if tags cannot be applied while the resource is being created, the resource fails to be created. This mechanism ensures that resources you intended to tag on creation are either created with specified tags or not created at all. If you tag resources at the time of creation, you don't need to run custom tagging scripts after creating a resource.
The following table describes the Amazon EMR on EKS resources that can be tagged.
| Resource | Supports tags | Supports tag propagation | Supports tagging on creation (Amazon EMR on EKS API, Amazon CLI, and Amazon SDK) | API for creation (tags can be added during creation) |
|---|---|---|---|---|
| Virtual cluster | Yes | No. Tags associated with a virtual cluster do not propagate to job runs submitted to that virtual cluster. | Yes | CreateVirtualCluster |
| Job runs | Yes | No | Yes | StartJobRun |
Tag restrictions
The following basic restrictions apply to tags:
-
Maximum number of tags per resource – 50
-
For each resource, each tag key must be unique, and each tag key can have only one value.
-
Maximum key length – 128 Unicode characters in UTF-8
-
Maximum value length – 256 Unicode characters in UTF-8
-
If your tagging schema is used across multiple Amazon services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are letters, numbers, spaces representable in UTF-8, and the following characters: + - = . _ : / @.
-
Tag keys and values are case sensitive.
-
A tag value can be an empty string, but not null. A tag key cannot be an empty string.
-
Don't use
aws:,AWS:, or any upper or lowercase combination of such as a prefix for either keys or values. These are reserved only for Amazon use.
Work with tags using the Amazon CLI and the Amazon EMR on EKS API
Use the following Amazon CLI commands or Amazon EMR on EKS API operations to add, update, list, and delete the tags for your resources.
| Task | Amazon CLI | API action |
|---|---|---|
| Add or overwrite one or more tags | tag-resource | TagResource |
| List tags for a resource | list-tags-for-resource | ListTagsForResource |
| Delete one or more tags | untag-resource | UntagResource |
The following examples show how to tag or untag resources using the Amazon CLI.
Example 1: Tag an existing virtual cluster
The following command tags an existing virtual cluster.
aws emr-containers tag-resource --resource-arnresource_ARN--tagsteam=devs
Example 2: Untag an existing virtual cluster
The following command deletes a tag from an existing virtual cluster.
aws emr-containers untag-resource --resource-arnresource_ARN--tag-keystag_key
Example 3: List tags for a resource
The following command lists the tags associated with an existing resource.
aws emr-containers list-tags-for-resource --resource-arnresource_ARN