Considerations for using pull through cache Required IAM permissions Creating a pull through cache rule Working with pull through cache images Deleting a pull through cache rule

Using pull through cache rules

Amazon ECR supports caching repositories in remote public registries in your private Amazon ECR registry. Amazon ECR currently supports creating pull through cache rules for Amazon ECR Public and Quay. Once a pull through cache is created for an external public registry, simply pull an image from that external public registry using your Amazon ECR private registry URI and then Amazon ECR creates a repository and caches that image. When a cached image is pulled using the Amazon ECR private registry URI, Amazon ECR checks the remote registry to see if there is a new version of the image and will update your private registry up to one time every 24 hours.

Considerations for using pull through cache

The following should be considered when using Amazon ECR pull through cache.

Creating pull through cache rules isn't supported in the following Regions:
- China (Beijing) (cn-north-1)
- China (Ningxia) (cn-northwest-1)
- AWS GovCloud (US-East) (us-gov-east-1)
- AWS GovCloud (US-West) (us-gov-west-1)
When pulling images using pull through cache, the Amazon ECR FIPS service endpoints aren't supported the first time an image is pulled. Using the Amazon ECR FIPS service endpoints work on subsequent pulls though.
You can create a maximum of 10 pull through cache rules for your private registry.
When cached images are pulled through the Amazon ECR private registry URI, the image pulls are initiated by AWS IP addresses. This ensures that the image pull doesn't count against any pull rate quotas the public registry has.
When a cached image is pulled through the Amazon ECR private registry URI, Amazon ECR checks the remote repository up to once per 24 hours to verify whether the cached image is the latest version. This timer is based off the last pull of the cached image.
When a multi-architecture image is pulled using a pull through cache rule, the manifest list and each image referenced in the manifest list are pulled to the Amazon ECR repository. If you only want to pull a specific architecture, you can pull the image using the image digest or tag associated with the architecture rather than the tag associated with the manifest list.
Amazon ECR uses a service-linked IAM role, which provides the permissions needed for Amazon ECR to create the repository for and push the cached image on your behalf. The service-linked IAM role is created automatically when a pull through cache rule is created. For more information, see Amazon ECR service-linked role for pull through cache.
By default, the user,, group, or role pulling the cached image has the permissions granted to them through their IAM policy. You may use the Amazon ECR private registry permissions policy to further scope the permissions of an IAM entity. For more information, see Using registry permissions.
Amazon ECR repositories created using the pull through cache workflow are treated like any other Amazon ECR repository. All repository features, such as replication and image scanning are supported.
When a new repository is created using a pull through cache rule, tag immutability is disabled by default. If you manually turn on tag immutability on the repository, Amazon ECR may not be able to update the cached images.
When a new repository is created using a pull through cache rule, AWS KMS encryption is disabled by default. If you want to use AWS KMS encryption, you can create the repository manually prior to the first image pull.
When an image is pulled using a pull through cache rule for the first time, if you've configured Amazon ECR to use an interface VPC endpoint using AWS PrivateLink then you need to create a public subnet in the same VPC, with a NAT gateway, and then route all outbound traffic to the internet from their private subnet to the NAT gateway in order for the pull to work. Subsequent image pulls don't require this. For more information, see Scenario: Access the internet from a private subnet in the Amazon Virtual Private Cloud User Guide.

Required IAM permissions

In addition to the Amazon ECR API permissions needed to authenticate to a private registry and to push and pull images, the following additional permissions are needed to use pull through cache rules.

ecr:CreatePullThroughCacheRule – Grants permission to create a pull through cache rule. This permission must be granted via an identity-based IAM policy.
ecr:BatchImportUpstreamImage – Grants permission to retrieve the external image and import it to your private registry. This permission can be granted by using the private registry permissions policy, an identity-based IAM policy, or by using the resource-based repository permissions policy. For more information about using repository permissions, see Private repository policies.
ecr:CreateRepository – Grants permission to create a repository in a private registry. This permission is required if the repository storing the cached images doesn't already exist. This permission can be granted by either an identity-based IAM policy or the private registry permissions policy.

Using registry permissions

Amazon ECR private registry permissions may be used to scope the permissions of individual IAM entities to use pull through cache. If an IAM entity has more permissions granted by an IAM policy than the registry permissions policy is granting, the IAM policy takes precedence. For example, if user has ecr:* permissions granted, no additional permissions are needed at the registry level.

Open the Amazon ECR console at https://console.aws.amazon.com/ecr/.
From the navigation bar, choose the Region to configure your private registry permissions statement in.
In the navigation pane, choose Private registry, Registry permissions.
On the Registry permissions page, choose Generate statement.
For each pull through cache permissions policy statement you want to create, do the following.
1. For Policy type, choose Pull through cache policy.
2. For Statement id, provide a name for the pull through cache statement policy.
3. For IAM entities, specify the users, groups, or roles to include in the policy.
4. For Repository namespace, select the pull through cache rule to associate the policy with.
5. For Repository names, specify the repository base name to apply the rule for. For example, if you want to specify the Amazon Linux repository on Amazon ECR Public, the repository name would be amazonlinux.

Use the following AWS CLI command to specify the private registry permissions using the AWS CLI.

Create a local file named ptc-registry-policy.json with the contents of your registry policy. The following example grants the ecr-pull-through-cache-user permission to create a repository and pull an image from Amazon ECR Public, which is the upstream source associated with the previously created pull through cache rule.
```
{
  "Sid": "PullThroughCacheFromReadOnlyRole",
  "Effect": "Allow",
  "Principal": {
    "AWS": "arn:aws:iam::111122223333:user/ecr-pull-through-cache-user"
  },
  "Action": [
    "ecr:CreateRepository",
    "ecr:BatchImportUpstreamImage"
  ],
  "Resource": "arn:aws:ecr:us-east-1:111122223333:repository/ecr-public/*"
}
```
Important
The ecr-CreateRepository permission is only required if the repository storing the cached images doesn't already exist. For example, if the repository creation action and the image pull actions are being done by separate IAM principals such as an administrator and a developer.
Use the put-registry-policy command to set the registry policy.
```
aws ecr put-registry-policy \
     --policy-text file://ptc-registry.policy.json
```

Creating a pull through cache rule

You create a pull through cache rule for each external public registry containing images you want to cache in your Amazon ECR private registry.

To create a pull through cache rule (AWS Management Console)

Open the Amazon ECR console at https://console.aws.amazon.com/ecr/.
From the navigation bar, choose the Region to configure your private registry settings in.
In the navigation pane, choose Private registry, Pull through cache.
On the Pull through cache configuration page, choose Add rule.
On the Create pull through cache rule page, do the following.
1. For Public registry, choose one of the preconfigured public registries.
2. For Amazon ECR repository namespace, specify the repository namespace to use when caching images pulled from the source public registry. By default, a namespace is populated but a custom namespace can be specified as well.
3. Choose Save to save the pull through cache rule to your registry settings.
Repeat the previous step for each pull through cache you want to create. The pull through cache rules are created separately for each Region.

Use the following AWS CLI commands to create a pull through cache rule for private registry using the AWS CLI.

create-pull-through-cache-rule (AWS CLI)

The following example creates a pull through cache rule for the Amazon ECR Public registry. It specifies a repository prefix of ecr-public, which results in each repository created using the pull through cache rule to have the naming scheme of ecr-public/upstream-repository-name.
```
aws ecr create-pull-through-cache-rule \
     --ecr-repository-prefix ecr-public \
     --upstream-registry-url public.ecr.aws \
     --region us-east-2
```
The following example creates a pull through cache rule for the Quay public registry. It specifies a repository prefix of quay, which results in each repository created using the pull through cache rule to have the naming scheme of quay/upstream-repository-name.
```
aws ecr create-pull-through-cache-rule \
     --ecr-repository-prefix quay \
     --upstream-registry-url quay.io \
     --region us-east-2
```

Working with pull through cache images

After a pull through cache rule is created for an external public registry, simply pull the remote images using your Amazon ECR repository URI and the images are cached locally. The following are the formats for the supported public registries. If you receive an error pulling an upstream image using a pull through cache rule, see Errors when pulling using a pull through cache rule for the most common errors and how to resolve them.

Note

The following examples use the default Amazon ECR repository namespace values that the AWS Management Console uses. Ensure that you use the Amazon ECR private repository URI that you've configured.

Amazon ECR Public


docker pull aws_account_id.dkr.ecr.region.amazonaws.com/ecr-public/repository_name/image_name:tag

Quay


docker pull aws_account_id.dkr.ecr.region.amazonaws.com/quay/repository_name/image_name:tag

Deleting a pull through cache rule

You can delete a pull through cache rule to stop the caching behavior. Deleting a pull through cache rule doesn't have any effect on the repositories or images that were cached, it only stops future caching behavior.

To delete a pull through cache rule (AWS Management Console)

Open the Amazon ECR console at https://console.aws.amazon.com/ecr/.
From the navigation bar, choose the Region to configure your private registry settings in.
In the navigation pane, choose Private registry, Pull through cache.
On the Pull through cache configuration page, select the pull through cache rules to delete, and then choose Delete rule.
In the navigation pane, choose Private registry, Registry permissions.
(Optional) On the Registry permissions page, review the existing registry permissions policy statements. You may delete any registry permissions policy statements associated with the repository namespace for the deleted pull through cache rule.

Use the following AWS CLI commands to delete a pull through cache rule using the AWS CLI.

delete-pull-through-cache-rule (AWS CLI)

The following example deletes a pull through cache rule that uses the ecr-public repository prefix..
```
aws ecr delete-pull-through-cache-rule \
     --ecr-repository-prefix ecr-public \
     --region us-east-2
```

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Pulling an image

Deleting an image