Tagging a private repository - Amazon ECR
Tag basicsTagging your resourcesTag restrictionsTagging your resources for billingWorking with tags using the consoleWorking with tags using the Amazon CLI or API
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Tagging a private repository

To help you manage your Amazon ECR repositories, you can optionally assign your own metadata to each repository in the form of Amazon resource tags. This topic describes Amazon resource tags and shows you how to create them.

Tag basics

A tag is a label that you assign to an Amazon resource. Each tag consists of a key and a value, both of which you define.

Tags enable you to categorize your Amazon resources in different ways, for example, by purpose, owner, or environment. This is useful 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 could define a set of tags for your account's Amazon ECR repositories that helps you track the owner of each repository.

We recommend that you devise a set of tag keys that meets your needs. Using a consistent set of tag keys makes it easier for you to manage your resources. You can search and filter the resources based on the tags you add.

Tags don't have any semantic meaning to Amazon ECR and are interpreted strictly as a string of characters. Also, tags are not automatically assigned to your resources. You can edit tag keys and values, and you can remove tags from a resource at any time. You can set the value of a tag to an empty string, but you can't set the value of a tag to null. If you add a tag that has the same key as an existing tag on that resource, the new value overwrites the old value. If you delete a resource, any tags for the resource are also deleted.

You can work with tags using the Amazon Web Services Management Console, the Amazon CLI, and the Amazon ECR API.

If you're using Amazon Identity and Access Management (IAM), you can control which users in your Amazon account have permission to create, edit, or delete tags.

Tagging your resources

You can tag new or existing Amazon ECR repositories.

If you're using the Amazon ECR console, you can apply tags to new resources when they are created or existing resources by using the Tags option on the navigation pane at any time.

If you're using the Amazon ECR API, the Amazon CLI, or an Amazon SDK, you can apply tags to new repositories using the tags parameter on the CreateRepository API action or use the TagResource API action to apply tags to existing resources. For more information, see TagResource.

Additionally, if tags cannot be applied during repository creation, we roll back the repository creation process. This ensures that repositories are either created with tags or not created at all, and that no repositories are left untagged at any time. By tagging repositories at the time of creation, you can eliminate the need to run custom tagging scripts after repository creation.

Tag restrictions

The following basic restrictions apply to tags:

  • Maximum number of tags per repository – 50

  • For each repository, 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 services and resources, remember that other services may have restrictions on allowed characters. Generally allowed characters are: letters, numbers, and spaces representable in UTF-8, and the following characters: + - = . _ : / @.

  • Tag keys and values are case-sensitive.

  • Don't use the aws: prefix for either keys or values; it's reserved for Amazon use. You can't edit or delete tag keys or values with this prefix. Tags with this prefix do not count against your tags per resource limit.

Tagging your resources for billing

The tags you add to your Amazon ECR repositories are helpful when reviewing cost allocation after enabling them in your Cost & Usage Report. For more information, see Amazon ECR usage reports.

To see the cost of your combined resources, you can organize your billing information based on resources that have the same tag key values. For example, you can tag several resources with a specific application name, and then organize your billing information to see the total cost of that application across several services. For more information about setting up a cost allocation report with tags, see The Monthly Cost Allocation Report in the Amazon Billing User Guide.

Note

If you've just enabled reporting, data for the current month is available for viewing after 24 hours.

Working with tags using the console

Using the Amazon ECR console, you can manage the tags associated with new or existing repositories.

When you select a specific repository in the Amazon ECR console, you can view the tags by selecting Tags in the navigation pane.

To add a tag to a repository (Amazon Web Services Management Console)

  1. Open the Amazon ECR console at https://console.amazonaws.cn/ecr/.

  2. From the navigation bar, select the region to use.

  3. In the navigation pane, choose Repositories.

  4. On the Repositories page, select the check box next to the repository you want to tag.

  5. From the Action menu, select Repository tags.

  6. On the Repository tags page, select Add tags, Add tag.

  7. On the Edit repository tags page, specify the key and value for each tag, and then choose Save.

To delete a tag from an individual resource (Amazon Web Services Management Console)

  1. Open the Amazon ECR console at https://console.amazonaws.cn/ecr/.

  2. From the navigation bar, select the region to use.

  3. On the Repositories page, select the check box next to the repository you want to remove a tag from.

  4. From the Action menu, select Repository tags.

  5. On the Repository tags page, select Edit.

  6. On the Edit repository tags page, select Remove for each tag you want to delete, and choose Save.

Working with tags using the Amazon CLI or API

Use the following to add, update, list, and delete the tags for your resources. The corresponding documentation provides examples.

Tagging support for Amazon ECR resources
Task Amazon CLI API action

Add or overwrite one or more tags.

tag-resource

TagResource

Delete one or more tags.

untag-resource

UntagResource

The following examples show how to manage tags using the Amazon CLI.

Example 1: Tag an existing repository

The following command tags an existing repository.

aws ecr tag-resource \
     --resource-arn arn:aws:ecr:region:account_id:repository/repository_name \
     --tags Key=stack,Value=dev
Example 2: Tag an existing repository with multiple tags

The following command tags an existing repository.

aws ecr tag-resource \
     --resource-arn arn:aws:ecr:region:account_id:repository/repository_name \
     --tags Key=key1,Value=value1 Key=key2,Value=value2 Key=key3,Value=value3
Example 3: Untag an existing repository

The following command deletes a tag from an existing repository.

aws ecr untag-resource \
     --resource-arn arn:aws:ecr:region:account_id:repository/repository_name \
     --tag-keys tag_key
Example 4: List tags for a repository

The following command lists the tags associated with an existing repository.

aws ecr list-tags-for-resource \
     --resource-arn arn:aws:ecr:region:account_id:repository/repository_name
Example 5: Create a repository and apply a tag

The following command creates a repository named test-repo and adds a tag with key team and value devs.

aws ecr create-repository \
     --repository-name test-repo \
     --tags Key=team,Value=devs