Creating a repository creation template in Amazon ECR

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

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

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

On the Repository creation templates page, choose Create template.

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.

For Applied for, specify which Amazon ECR workflows this template will apply to. The options are PULL_THROUGH_CACHE and REPLICATION.

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

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 Preventing image tags from being overwritten in Amazon ECR.

   • Mutable – Choose this option if you want image tags to be overwritten. Recommended for repositories using pull through cache actions to ensure Amazon ECR can update cached images. Additionally, to disable tag updates for a few mutable tags, enter tag names or use wildcards (*) to match multiple similar tags in the Mutable tag exclusion text box.

   • Immutable – Choose this option if you want to prevent image tags from being overwritten, and it applies to all tags and exclusions in the repository when pushing an image with existing tag. Amazon ECR returns an ImageTagAlreadyExistsException if you attempt to push an image with an existing tag. Additionally, to enable tag updates for a few immutable tags, enter tag names or use wildcards (*) to match multiple similar tags in the Immutable tag exclusion text box.

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 in Amazon ECR.

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

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 in Amazon ECR.

6. For Repository creation role, select a custom IAM role from the drop-down menu to be used for repository creation templates when using repository tags or KMS in the template (see Create an IAM role for repository creation templates for details).Then choose Next.

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.

Use the Amazon CLI to generate a skeleton for the create-repository-creation-template command.

aws ecr create-repository-creation-template \
    --generate-cli-skeleton

The output of the command displays the full syntax of the repository creation template.

{
"appliedFor":[""], // string array, but valid are PULL_THROUGH_CACHE and REPLICATION
"prefix": "string",
    "description": "string",
    "imageTagMutability": "MUTABLE"|"IMMUTABLE"|"IMMUTABLE_WITH_EXCLUSION"|"MUTABLE_WITH_EXCLUSION",
    "imageTagMutabilityExclusionFilters": [
        "filterType": "WILDCARD",
        "filter": "string"
    ],
    "repositoryPolicy": "string",
    "lifecyclePolicy": "string"
"encryptionConfiguration": {
"encryptionType": "AES256"|"KMS",
        "kmsKey": "string"
    },
    "resourceTags": [
        {
"Key": "string",
            "Value": "string"
        }
    ],
    "customRoleArn": "string", // must be a valid IAM Role ARN
}

Create a file named repository-creation-template.json with the output of the previous step. This template sets a KMS encryption key for any repository created under prod/* with a repository policy that enables pushing and pulling images to future repositories, sets a lifecycle policy that will expire images older than two weeks and sets a custom role that will let ECR access the KMS key and assign the resource tag examplekey to future repositories.

{
"prefix": "prod",
    "description": "For repositories cached from my PTC rule and in my replication configuration that start with 'prod/'",
    "appliedFor": ["PULL_THROUGH_CACHE","REPLICATION"],
    "encryptionConfiguration": {
"encryptionType": "KMS",
        "kmsKey": "arn:aws:kms:us-west-2:111122223333:key/a1b2c3d4-5678-90ab-cdef-example11111"
    },
    "resourceTags": [
        {
"Key": "examplekey",
            "Value": "examplevalue"
        }
    ],
    "imageTagMutability": "IMMUTABLE_WITH_EXCLUSION",
    "imageTagMutabilityExclusionFilters": [
      {
      "filterType": "WILDCARD",
      "filter": "latest"
      },
      {
      "filterType": "WILDCARD",
      "filter": "beta*"
      }
    ]
    "repositoryPolicy": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Sid\":\"AllowPushPullIAMRole\",\"Effect\":\"Allow\",\"Principal\":{\"AWS\":\"arn:aws:iam::111122223333:user\/IAMusername\"},\"Action\":[\"ecr:BatchGetImage\",\"ecr:BatchCheckLayerAvailability\",\"ecr:CompleteLayerUpload\",\"ecr:GetDownloadUrlForLayer\",\"ecr:InitiateLayerUpload\",\"ecr:PutImage\",\"ecr:UploadLayerPart\"]}]}", 
    "lifecyclePolicy": "{\"rules\":[{\"rulePriority\":1,\"description\":\"Expire images older than 14 days\",\"selection\":{\"tagStatus\":\"any\",\"countType\":\"sinceImagePushed\",\"countUnit\":\"days\",\"countNumber\":14},\"action\":{\"type\":\"expire\"}}]}",
    "customRoleArn": "arn:aws:iam::111122223333:role/myRole"
}

Use the following command to create a repository creation template. Ensure that you specify the name of the configuration file created in the previous step in place of the repository-creation-template.json in the following example.

aws ecr create-repository-creation-template \
    --cli-input-json file://repository-creation-template.json