Templates to control repositories created during a pull through cache action - Amazon ECR
How it works
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).

Templates to control repositories created during a pull through cache action

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.

Use Amazon ECR repository creation templates to define the settings for 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 Private repository policies in Amazon ECR.

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 Automate the cleanup of images by using lifecycle policies in Amazon ECR.

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.