Manage your repository creation templates - Amazon ECR
How it worksRequired IAM permissionsCreating a repository creation templateDeleting a repository creation template
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).

Manage your repository creation templates

The repository creation template feature is in preview release for Amazon ECR and is subject to change. During this public preview, only the Amazon Web Services Management Console can be used to manage your repository creation templates.

Amazon ECR repository creation templates give you control to define the settings to use for new repositories created by Amazon ECR on your behalf during a pull through cache action. The settings in a repository creation template are only applied during repository creation and don't have any effect on existing repositories or repositories created using any other method.

Repository creation templates aren't supported in the following Regions.

  • China (Beijing) (cn-north-1)

  • China (Ningxia) (cn-northwest-1)

  • Amazon GovCloud (US-East) (us-gov-east-1)

  • Amazon GovCloud (US-West) (us-gov-west-1)

How repository creation templates work

There are times when Amazon ECR needs to create a new private repository on your behalf. For example, the first time you use a pull through cache rule to retrieve the contents of an upstream repository and store it in your Amazon ECR private registry. When there isn't a repository creation template that matches your pull through cache rule, Amazon ECR uses the default settings for the new repository. These default settings include turning off tag immutability, using AES-256 encryption, and not applying any repository or lifecycle policies.

Using a repository creation template with a prefix that matches a pull through cache rule gives you the ability to define the settings Amazon ECR applies to new repositories created through the pull through cache action. You can define the tag immutability, encryption configuration, repository permissions, lifecycle policy, and resource tags for the new repositories.

The following diagram shows the workflow that Amazon ECR uses when a repository creation template is used.

A display of how repository creation templates are applied to new repositories.

The following describes each parameter in a repository creation template in detail.

Prefix

The Prefix is the repository namespace prefix to associate with the template. All repositories created using this prefix will have the settings applied that are defined in this template. For example, a prefix of prod would apply to all repositories beginning with prod/. Similarly, a prefix of prod/team would apply to all repositories beginning with prod/team/.

To apply a template to all repositories in your registry that don't have an associated creation template, you can use ROOT as the prefix.

Important

There is always an assumed / applied to the end of the prefix. If you specify ecr-public as the prefix, Amazon ECR treats that as ecr-public/. When using a pull through cache rule, the repository prefix you specify during rule creation is what you should specify as your repository creation template prefix as well.

Description

This template description fis optional and is used to describe the purpose for the repository creation template.

Template version

The repository creation template version to use. Currently, only the TV1 template version is supported.

Configuration version

The repository configuration version the template to use. Each template must include a repository configuration. The default configuration version is CV1 and consists of the image tag mutability, repository policy, and lifecycle policy settings.

Image tag mutability

The tag mutability setting to use for repositories created using the template. If this parameter is omitted, the default setting of MUTABLE will be used which will allow image tags to be overwritten. This is the recommended setting to use for templates used for repositories created by pull through cache actions. This ensures that Amazon ECR can update the cached images when the tags are the same.

If IMMUTABLE is specified, all image tags within the repository will be immutable which will prevent them from being overwritten.

Encryption configuration

The encryption configuration to use for repositories created using the template.

If you use the KMS encryption type, the contents of the repository will be encrypted using server-side encryption with an Amazon Key Management Service key stored in Amazon KMS. When you use Amazon KMS to encrypt your data, you can either use the default Amazon managed Amazon KMS key for Amazon ECR, or specify your own Amazon KMS key, which you already created. For more information, see Protecting data using server-side encryption with an Amazon Key Management Service key stored in Amazon Key Management Service (SSE-KMS) in the Amazon Simple Storage Service User Guide.

If you use the AES256 encryption type, Amazon ECR uses server-side encryption with Amazon S3-managed encryption keys which encrypts the images in the repository using an AES-256 encryption algorithm. For more information, see Protecting data using server-side encryption with Amazon S3-managed encryption keys (SSE-S3) in the Amazon Simple Storage Service User Guide.

Repository permissions

The repository policy to apply to repositories created using the template. A repository policy uses resource-based permissions to control access to a repository. Resource-based permissions let you specify which IAM users or roles have access to a repository and what actions they can perform on it. By default, only the Amazon account that created the repository has access to a repository. You can apply a policy document that grant or deny additional permissions to your repository. For more information, see .

Repository lifecycle policy

The lifecycle policy to use for repositories created using the template. A lifecycle policy provides more control over the lifecycle management of images in a private repository. A lifecycle policy contains one or more rules, where each rule defines an action for Amazon ECR. This provides a way to automate the cleaning up of your container images by expiring images based on age or count. For more information, see Lifecycle policies.

Resource tags

The resource tags are metadata to apply to the repository to help you categorize and organize them. Each tag consists of a key and an optional value, both of which you define.

Required IAM permissions for creating repository creation templates

The following permissions are needed for an IAM principal to manage repository creation templates. These permission must be granted using an identity-based IAM policy.

  • ecr:CreateRepositoryCreationTemplate – Grants permission to create a repository creation template.

  • ecr:DeleteRepositoryCreationTemplate – Grants permission to delete a repository creation template.

  • ecr:PutLifecyclePolicy – Grants permission to create a lifecycle policy and apply it to a repository. This permission is only required if the repository creation template includes a lifecycle policy.

  • ecr:SetRepositoryPolicy – Grants permission to create a permissions policy for a repository. This permission is only required if the repository creation template includes a repository policy.

  • ecr:TagResource – Grants permission to add metadata tags to a resource. This permission is only required if the repository creation template includes resource tags.

Creating a repository creation template

You can create a repository creation template to define the settings to use for repositories created by Amazon ECR on your behalf during pull through cache actions. Once the repository creation template is created, all new repositories created will have the settings applied. This doesn't have any effect on any previously created repositories.

To create a repository creation template (Amazon Web Services Management Console)

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

  2. From the navigation bar, choose the Region to create the repository creation template in.

  3. In the navigation pane, choose Private registry, Repository creation templates.

  4. On the Repository creation templates page, choose Create template.

  5. On the Step 1: Define template page, for Template details, choose A specific prefix to apply the template to a specific repository namespace prefix or choose Any prefix in your ECR registry to apply the template to all repositories that don't match any other template in the Region.

    1. If you choose A specific prefix, for Prefix specify the repository namespace prefix to apply the template to. There is always an assumed / applied to the end of the prefix. For example, a prefix of prod would apply to all repositories beginning with prod/. Similarly, a prefix of prod/team would apply to all repositories beginning with prod/team/.

    2. If you choose Any prefix in your ECR registry, the Prefix will be set to ROOT.

  6. For Template description, specify an optional description for the template and then choose Next.

  7. On the Step 2: Add repository creation configuration page, specify the repository setting configuration to apply to repositories created using the template.

    1. For Image tag mutability, choose the tag mutability setting to use. For more information, see Image tag mutability.

      When Mutable is selected, image tags can be overwritten. This is the recommended setting to use for templates used for repositories created by pull through cache actions. This ensures that Amazon ECR can update the cached images when the tags are the same.

      When Immutable is selected, image tags are prevented from being overwritten. After the repository is configured for immutable tags, an ImageTagAlreadyExistsException error is returned if there is an attempt to push an image with a tag that is already in the repository. When tag immutability is turned on for a repository, this affects all tags and you cannot make some tags immutable while others aren't.

    2. For Encryption configuration, choose the encryption setting to use. For more information, see Encryption at rest.

      When AES-256 is selected, Amazon ECR uses server-side encryption with Amazon Simple Storage Service-managed encryption keys which encrypts your data at rest using an industry standard AES-256 encryption algorithm. This is offered at no additional cost.

      When Amazon KMS is selected, Amazon ECR uses server-side encryption with keys stored in Amazon Key Management Service (Amazon KMS). When you use Amazon KMS to encrypt your data, you can either use the default Amazon managed key, which is managed by Amazon ECR, or specify your own Amazon KMS key, which is referred to as a customer managed key.

      Note

      The encryption settings for a repository can't be changed once the repository is created.

    3. For Repository permissions, specify the repository permissions policy to apply to repositories created using this template. You can optionally use the drop down to select one of the JSON samples for the most common use cases. For more information, see Private repository policies.

    4. For Repository lifecycle policy, specify the repository lifecycle policy to apply to repositories created using this template. You can optionally use the drop down to select one of the JSON samples for the most common use cases. For more information, see Lifecycle policies.

    5. For Repository Amazon tags, specify the metadata, in the form of key-value pairs, to associate with the repositories created using this template and then choose Next. For more information, see Tagging a private repository.

  8. On the Step 3: Review and create page, review the settings you specified for the repository creation template. Choose the Edit option to make changes. Choose Create once you're done.

Deleting a repository creation template

You can delete a repository creation template if you are finished using it. Once the repository creation template is deleted, any new repositories created during a pull through cache action will have default settings applied.

To delete a repository creation template (Amazon Web Services Management Console)

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

  2. From the navigation bar, choose the Region the repository creation template to delete is in.

  3. In the navigation pane, choose Private registry, Repository creation templates.

  4. On the Repository creation templates page, select the repository creation template to delete.

  5. From the Actions dropdown menu, choose Delete.