# Sync an upstream registry with an Amazon ECR private registry
Using pull through cache rules, you can sync the contents of an upstream registry with your Amazon ECR private registry.
Amazon ECR currently supports creating pull through cache rules for the following upstream registries:
+ Amazon ECR Public, Kubernetes container image registry, and Quay (doesn't require authentication)
+ Docker Hub, Microsoft Azure Container Registry, GitHub Container Registry, GitLab Container Registry and Chainguard Registry (requires authentication with AWS Secrets Manager secret)
+ Amazon ECR (requires authentication with AWS IAM role)
For GitLab Container Registry, Amazon ECR supports pull through cache only with GitLab's Software as a Service (SaaS) offering. For more information about using GitLab's SaaS offering, see [GitLab.com](https://docs.gitlab.com/17.5/subscriptions/choosing_subscription/).
For upstream registries that require authentication with secrets (such as Docker Hub), you must store your credentials in an AWS Secrets Manager secret. You can use the Amazon ECR console to create Secrets Manager secrets for each authenticated upstream registry. For more information about creating a Secrets Manager secret using the Secrets Manager console, see [Storing your upstream repository credentials in an AWS Secrets Manager secret](pull-through-cache-creating-secret.md).
For Amazon ECR, you must create an IAM role if the upstream and downstream Amazon ECR registries belong to different AWS account. For more information about creating an IAM role, see [IAM policies required for cross-account ECR to ECR pull through cache](pull-through-cache-private.md#pull-through-cache-private-permissions).
After you've created a pull through cache rule for the upstream registry, pull an image from that upstream registry using your Amazon ECR private registry URI. Amazon ECR then creates a repository and caches that image in your private registry. For subsequent pull requests of the cached image with a given tag, Amazon ECR checks the upstream registry for a new version of the image with that specific tag and attempts to update the image in your private registry at least once every 24 hours.
## Repository creation templates
Amazon ECR has added support for repository creation templates, which gives you the control to specify initial configurations for new repositories created by Amazon ECR on your behalf using pull through cache rules. Each template contains a repository namespace prefix which is used to match new repositories to a specific template. Templates can specify the configuration for all repository settings including resource-based access policies, tag immutability, encryption, and lifecycle policies. 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. For more information, see [Templates to control repositories created during a pull through cache, create on push, or replication action](repository-creation-templates.md).
## Considerations for using pull through cache rules
Consider the following when using Amazon ECR pull through cache rules.
+ 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`)
+ AWS Lambda doesn't support pulling container images from Amazon ECR using a pull through cache rule.
+ 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.
+ For upstream repositories that require authentication, when an image is pulled through the Amazon ECR private registry URI for the first time or to update the cache, the image pulls are initiated by the user associated to the credentials configured in the pull through cache rule. Subsequent pulls will return the image directly from the cache in the customer's private registry.
+ For upstream repositories that do not require authentication, when an image is pulled through the Amazon ECR private registry URI, the image pulls are initiated by AWS IP addresses.
+ When a customer pulls a cached image through the Amazon ECR private registry URI, Amazon ECR checks whether it has validated the image against the upstream registry within the last 24 hours. If the 24-hour window has expired, Amazon ECR sends a request upstream to check for a newer version and updates the cache if one exists. If the window has not expired, Amazon ECR serves the cached image without contacting the upstream.
+ If Amazon ECR is unable to update the image from the upstream registry for any reason and the image is pulled, the last cached image will still be pulled.
+ When creating the Secrets Manager secret that contains the upstream registry credentials, the secret name must use the `ecr-pullthroughcache/` prefix. The secret must also be in the same account and Region that the pull through cache rule is created in.
+ 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, retrieve the Secrets Manager secret value for authentication, 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](slr-pullthroughcache.md).
+ By default, the IAM principal 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](pull-through-cache-iam.md#pull-through-cache-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 Amazon ECR creates a new repository on your behalf using a pull through cache action, the following default settings are applied to the repository unless there is a matching repository creation template. You can use a repository creation template to define the settings applied to repositories created by Amazon ECR on your behalf. For more information, see [Templates to control repositories created during a pull through cache, create on push, or replication action](repository-creation-templates.md).
+ Tag immutability – Tag immutability specifies whether image tags can be overwritten. By default, image tags are mutable (can be overwritten). You can modify tag behavior by configuring tag exclusion filters in either the **Mutable tag exclusion** text box when **Mutable** is selected, or the **Immutable tag exclusion** text box when **Immutable** is selected.
+ Encryption – The default `AES256` encryption is used.
+ Repository permissions – Omitted, no repository permissions policy is applied.
+ Lifecycle policy – Omitted, no lifecycle policy is applied.
+ Resource tags – Omitted, no resource tags are applied.
+ Turning on image tag immutability for repositories using a pull through cache rule will prevent Amazon ECR from updating images using the same tag.
+ When an image is pulled using the pull through cache rule for the first time a route to the internet may be required. There are certain circumstances in which a route to the internet is required so it's best to set up a route to avoid any failures. Thus, if you've configured Amazon ECR to use an interface VPC endpoint using AWS PrivateLink then you need to ensure the first pull has a route to the internet. One way to do this is to create a public subnet in the same VPC, with an internet gateway, and then route all outbound traffic to the internet from their private subnet to the public subnet. Subsequent image pulls using the pull through cache rule don't require this. For more information, see [Example routing options](https://docs.aws.amazon.com/vpc/latest/userguide/route-table-options.html) in the *Amazon Virtual Private Cloud User Guide*.
# IAM permissions required to sync an upstream registry with an Amazon ECR private registry
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 effectively.
+ `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 in Amazon ECR](repository-policies.md).
+ `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.
### To create a private registry permissions policy (AWS Management Console)
1. Open the Amazon ECR console at [https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/).
1. From the navigation bar, choose the Region to configure your private registry permissions statement in.
1. In the navigation pane, choose **Private registry**, **Registry permissions**.
1. On the **Registry permissions** page, choose **Generate statement**.
1. For each pull through cache permissions policy statement you want to create, do the following.
1. For **Policy type**, choose **Pull through cache policy**.
1. For **Statement id**, provide a name for the pull through cache statement policy.
1. For **IAM entities**, specify the users, groups, or roles to include in the policy.
1. For **Repository namespace**, select the pull through cache rule to associate the policy with.
1. 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`.
### To create a private registry permissions policy (AWS CLI)
Use the following AWS CLI command to specify the private registry permissions using the AWS CLI.
1. 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.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"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.
1. Use the [put-registry-policy](https://docs.aws.amazon.com/cli/latest/reference/ecr/put-registry-policy.html) command to set the registry policy.
```
aws ecr put-registry-policy \
--policy-text file://ptc-registry.policy.json
```
## Next steps
Once you are ready to start using pull through cache rules, the following are the next steps.
+ Create a pull through cache rule. For more information, see [Creating a pull through cache rule in Amazon ECR](pull-through-cache-creating-rule.md).
+ Create a repository creation template. A repository creation template gives you control to define the settings to use for new repositories created by Amazon ECR on your behalf during a pull through cache action. For more information, see [Templates to control repositories created during a pull through cache, create on push, or replication action](repository-creation-templates.md).
# Setting up permissions for cross-account ECR to ECR PTC
The Amazon ECR to Amazon ECR (ECR to ECR) pull through cache feature enables automatic synchronization of images between Regions, AWS accounts, or both. With ECR to ECR PTC, you can push images to your primary Amazon ECR registry and configure a pull through cache rule to cache images in downstream Amazon ECR registries.
## IAM policies required for cross-account ECR to ECR pull through cache
To cache images between Amazon ECR registries across different AWS accounts, create an IAM role in the downstream account and configure the policies in this section to provide the following permissions:
+ Amazon ECR needs permissions to pull images from the upstream Amazon ECR registry on your behalf. You can grant these permissions by creating an IAM role and then specifying it in your pull through cache rule.
+ The upstream registry owner must also grant the cache registry owner with the required permissions to pull the images in to the resource policies.
**Topics**
+ [
### Creating an IAM role to define the pull through cache permissions
](#ecr-policies-for-cross-account-ecr-to-ecr-pull-through-cache)
+ [
### Creating a Trust policy for the IAM role
](#ecr-creating-a-trust-policy-for-the-iam-role)
+ [
### Creating a resource policy in the upstream Amazon ECR registry
](#ecr-creating-registry-permissions-policy-in-upstream-registry)
### Creating an IAM role to define the pull through cache permissions
The following example shows a permissions policy that grants an IAM role permission to pull images from the upstream Amazon ECR registry on your behalf. When Amazon ECR assumes the role, it receives the permissions specified in this policy.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"ecr:GetDownloadUrlForLayer",
"ecr:GetAuthorizationToken",
"ecr:BatchImportUpstreamImage",
"ecr:BatchGetImage",
"ecr:GetImageCopyStatus",
"ecr:InitiateLayerUpload",
"ecr:UploadLayerPart",
"ecr:CompleteLayerUpload",
"ecr:PutImage"
],
"Resource": "*"
}
]
}
```
------
### Creating a Trust policy for the IAM role
The following example shows a trust policy that identifies Amazon ECR pull through cache as the AWS service principal that can assume the role.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "pullthroughcache.ecr.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
### Creating a resource policy in the upstream Amazon ECR registry
The upstream Amazon ECR registry owner must also add a registry policy or a repository policy to grant the downstream registry owner the required permissions to perform the following actions.
**Note**
The following resource policy is required only for **cross-account** ECR to ECR pull through cache configurations. For **same-account, cross-region** pull through cache, you only need the IAM role policy and trust policy shown in the previous sections. The root account principal permission is not required when the upstream and downstream registries are in the same AWS account.
```
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::444455556666:root"
},
"Action": [
"ecr:BatchGetImage",
"ecr:GetDownloadUrlForLayer",
"ecr:BatchImportUpstreamImage",
"ecr:GetImageCopyStatus"
],
"Resource": "arn:aws:ecr:region:111122223333:repository/*"
}
```
# Creating a pull through cache rule in Amazon ECR
For each upstream registry containing images that you want to cache in your Amazon ECR private registry, you must create a pull through cache rule.
For upstream registries that require authentication with secrets, you must store the credentials in a Secrets Manager secret. You can use an existing secret or create a new secret. You can create the Secrets Manager secret in either the Amazon ECR console or the Secrets Manager console. To create a Secrets Manager secret using the Secrets Manager console instead of the Amazon ECR console, see [Storing your upstream repository credentials in an AWS Secrets Manager secret](pull-through-cache-creating-secret.md).
## Prerequisites
+ Verify that you have the proper IAM permissions to create pull through cache rules. For information, see [IAM permissions required to sync an upstream registry with an Amazon ECR private registry](pull-through-cache-iam.md).
+ For upstream registries that require authentication with secrets: If you want to use an existing secret, verify that the Secrets Manager secret meets the following requirements:
+ The name of the secret begins with `ecr-pullthroughcache/`. The AWS Management Console only displays Secrets Manager secrets with the `ecr-pullthroughcache/` prefix.
+ The account and Region that the secret is in must match the account and Region that the pull through cache rule is in.
## To create a pull through cache rule (AWS Management Console)
The following steps show how to create a pull through cache rule and a Secrets Manager secret using the Amazon ECR console. To create a secret using the Secrets Manager console, see [Storing your upstream repository credentials in an AWS Secrets Manager secret](pull-through-cache-creating-secret.md).
### For Amazon ECR Public, Kubernetes container registry, or Quay
1. Open the Amazon ECR console at [https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/).
1. From the navigation bar, choose the Region to configure your private registry settings in.
1. In the navigation pane, choose **Private registry**, **Pull through cache**.
1. On the **Pull through cache configuration** page, choose **Add rule**.
1. On the **Step 1: Specify a source** page, for **Registry**, choose either Amazon ECR Public, Kubernetes, or Quay from the list of upstream registries and then choose **Next**.
1. On the **Step 2: Specify a destination** page, for **Amazon ECR repository prefix**, specify the repository namespace prefix to use when caching images pulled from the source public registry and then choose **Next**. By default, a namespace is populated but a custom namespace can be specified as well.
1. On the **Step 3: Review and create** page, review the pull through cache rule configuration and then choose **Create**.
1. Repeat the previous step for each pull through cache you want to create. The pull through cache rules are created separately for each Region.
### For Docker Hub
1. Open the Amazon ECR console at [https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/).
1. From the navigation bar, choose the Region to configure your private registry settings in.
1. In the navigation pane, choose **Private registry**, **Pull through cache**.
1. On the **Pull through cache configuration** page, choose **Add rule**.
1. On the **Step 1: Specify a source** page, for **Registry**, choose **Docker Hub**, **Next**.
1. On the **Step 2: Configure authentication** page, for **Upstream credentials**, you must store your authentication credentials for Docker Hub in an AWS Secrets Manager secret. You can specify an existing secret or use the Amazon ECR console to create a new secret.
1. To use an existing secret, choose **Use an existing AWS secret**. For **Secret name** use the drop down to select your existing secret, and then choose **Next**.
**Note**
The AWS Management Console only displays Secrets Manager secrets with names using the `ecr-pullthroughcache/` prefix. The secret must also be in the same account and Region that the pull through cache rule is created in.
1. To create a new secret, choose **Create an AWS secret**, do the following, then choose **Next**.
1. For **Secret name**, specify a descriptive name for the secret. Secret names must contain 1-512 Unicode characters.
1. For **Docker Hub email**, specify your Docker Hub email.
1. For **Docker Hub access token**, specify your Docker Hub access token. For more information on creating a Docker Hub access token, see [Create and manage access tokens](https://docs.docker.com/security/for-developers/access-tokens/) in the Docker documentation.
1. On the **Step 3: Specify a destination** page, for **Amazon ECR repository prefix**, specify the repository namespace to use when caching images pulled from the source public registry and then choose **Next**.
By default, a namespace is populated but a custom namespace can be specified as well.
1. On the **Step 4: Review and create** page, review the pull through cache rule configuration and then choose **Create**.
1. Repeat the previous step for each pull through cache you want to create. The pull through cache rules are created separately for each Region.
### For GitHub Container Registry
1. Open the Amazon ECR console at [https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/).
1. From the navigation bar, choose the Region to configure your private registry settings in.
1. In the navigation pane, choose **Private registry**, **Pull through cache**.
1. On the **Pull through cache configuration** page, choose **Add rule**.
1. On the **Step 1: Specify a source** page, for **Registry**, choose **GitHub Container Registry**, **Next**.
1. On the **Step 2: Configure authentication** page, for **Upstream credentials**, you must store your authentication credentials for GitHub Container Registry in an AWS Secrets Manager secret. You can specify an existing secret or use the Amazon ECR console to create a new secret.
1. To use an existing secret, choose **Use an existing AWS secret**. For **Secret name** use the drop down to select your existing secret, and then choose **Next**.
**Note**
The AWS Management Console only displays Secrets Manager secrets with names using the `ecr-pullthroughcache/` prefix. The secret must also be in the same account and Region that the pull through cache rule is created in.
1. To create a new secret, choose **Create an AWS secret**, do the following, then choose **Next**.
1. For **Secret name**, specify a descriptive name for the secret. Secret names must contain 1-512 Unicode characters.
1. For **GitHub Container Registry username**, specify your GitHub Container Registry username.
1. For **GitHub Container Registry access token**, specify your GitHub Container Registry access token. For more information on creating a GitHub access token, see [Managing your personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) in the GitHub documentation.
1. On the **Step 3: Specify a destination** page, for **Amazon ECR repository prefix**, specify the repository namespace to use when caching images pulled from the source public registry and then choose **Next**.
By default, a namespace is populated but a custom namespace can be specified as well.
1. On the **Step 4: Review and create** page, review the pull through cache rule configuration and then choose **Create**.
1. Repeat the previous step for each pull through cache you want to create. The pull through cache rules are created separately for each Region.
### For Microsoft Azure Container Registry
1. Open the Amazon ECR console at [https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/).
1. From the navigation bar, choose the Region to configure your private registry settings in.
1. In the navigation pane, choose **Private registry**, **Pull through cache**.
1. On the **Pull through cache configuration** page, choose **Add rule**.
1. On the **Step 1: Specify a source** page, do the following.
1. For **Registry**, choose **Microsoft Azure Container Registry**
1. For **Source registry URL**, specify the name of your Microsoft Azure container registry and then choose **Next**.
**Important**
You only need to specify the prefix, as the `.azurecr.io` suffix is populated on your behalf.
1. On the **Step 2: Configure authentication** page, for **Upstream credentials**, you must store your authentication credentials for Microsoft Azure Container Registry in an AWS Secrets Manager secret. You can specify an existing secret or use the Amazon ECR console to create a new secret.
1. To use an existing secret, choose **Use an existing AWS secret**. For **Secret name** use the drop down to select your existing secret, and then choose **Next**.
**Note**
The AWS Management Console only displays Secrets Manager secrets with names using the `ecr-pullthroughcache/` prefix. The secret must also be in the same account and Region that the pull through cache rule is created in.
1. To create a new secret, choose **Create an AWS secret**, do the following, then choose **Next**.
1. For **Secret name**, specify a descriptive name for the secret. Secret names must contain 1-512 Unicode characters.
1. For **Microsoft Azure Container Registry username**, specify your Microsoft Azure Container Registry username.
1. For **Microsoft Azure Container Registry access token**, specify your Microsoft Azure Container Registry access token. For more information on creating an Microsoft Azure Container Registry access token, see [Create token - portal](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-repository-scoped-permissions#create-token---portal) in the Microsoft Azure documentation.
1. On the **Step 3: Specify a destination** page, for **Amazon ECR repository prefix**, specify the repository namespace to use when caching images pulled from the source public registry and then choose **Next**.
By default, a namespace is populated but a custom namespace can be specified as well.
1. On the **Step 4: Review and create** page, review the pull through cache rule configuration and then choose **Create**.
1. Repeat the previous step for each pull through cache you want to create. The pull through cache rules are created separately for each Region.
### For GitLab Container Registry
1. Open the Amazon ECR console at [https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/).
1. From the navigation bar, choose the Region to configure your private registry settings in.
1. In the navigation pane, choose **Private registry**, **Pull through cache**.
1. On the **Pull through cache configuration** page, choose **Add rule**.
1. On the **Step 1: Specify a source** page, for Registry, choose GitLab Container Registry, Next.
1. On the **Step 2: Configure authentication** page, for **Upstream credentials**, you must store your authentication credentials for GitLab Container Registry in an AWS Secrets Manager secret. You can specify an existing secret or use the Amazon ECR console to create a new secret.
1. To use an existing secret, choose **Use an existing AWS secret**. For **Secret name** use the drop down to select your existing secret, and then choose **Next**. For more information on creating a Secrets Manager secret using the Secrets Manager console, see [Storing your upstream repository credentials in an AWS Secrets Manager secret](pull-through-cache-creating-secret.md).
**Note**
The AWS Management Console only displays Secrets Manager secrets with names using the `ecr-pullthroughcache/` prefix. The secret must also be in the same account and Region that the pull through cache rule is created in.
1. To create a new secret, choose **Create an AWS secret**, do the following, then choose **Next**.
1. For **Secret name**, specify a descriptive name for the secret. Secret names must contain 1-512 Unicode characters.
1. For **GitLab Container Registry username**, specify your GitLab Container Registry username.
1. For **GitLab Container Registry access token**, specify your GitLab Container Registry access token. For more information on creating a GitLab Container Registry access token, see [Personal access tokens](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html), [Group access tokens](https://docs.gitlab.com/ee/user/group/settings/group_access_tokens.html), or [Project access tokens](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html), in the GitLab documentation.
1. On the **Step 3: Specify a destination** page, for **Amazon ECR repository prefix**, specify the repository namespace to use when caching images pulled from the source public registry and then choose **Next**.
By default, a namespace is populated but a custom namespace can be specified as well.
1. On the **Step 4: Review and create** page, review the pull through cache rule configuration and then choose **Create**.
1. Repeat the previous step for each pull through cache you want to create. The pull through cache rules are created separately for each Region.
### For Amazon ECR private registry within your AWS account
1. Open the Amazon ECR console at [https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/).
1. From the navigation bar, choose the Region in which you want to configure your private registry settings.
1. In the navigation pane, choose **Private registry**, **Pull through cache**.
1. On the **Pull through cache configuration** page, choose **Add rule**.
1. On the **Step 1: Specify upstream** page, for **Registry**, choose **Amazon ECR Private** and **This account**. For **Region**, select the Region for the upstream Amazon ECR registry, and then choose **Next**.
1. On the **Step 2: Specify namespaces** page, for **Cache namespace**, choose whether to create pull through cache repositories with **A specific prefix** or **no prefix**. If you select **A specific prefix**, you must specify a prefix name to be used as part of the namespace for caching images from the upstream registry.
1. For **Upstream namespace**, choose whether to pull from **A specific prefix** that exists in the upstream registry. If you select **no prefix**, you can pull from any repository in the upstream registry. Specify the upstream repository prefix if prompted, and then choose **Next**.
**Note**
To learn more about customizing cache and upstream namespaces, see [Customizing repository prefixes for ECR to ECR pull through cache](pull-through-cache-private-wildcards.md).
1. On the **Step 3: Review and create** page, review the pull through cache rule configuration and then choose **Create**.
1. Repeat these steps for each pull through cache you want to create. The pull through cache rules are created separately for each Region.
### For Amazon ECR private registry from another AWS account
1. Open the Amazon ECR console at [https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/).
1. From the navigation bar, choose the Region to configure your private registry settings in.
1. In the navigation pane, choose **Private registry**, **Pull through cache**.
1. On the **Pull through cache configuration** page, choose **Add rule**.
1. On the **Step 1: Specify upstream** page, for **Registry**, choose **Amazon ECR Private** and **Cross account**. For **Region**, select the Region for the upstream Amazon ECR registry. For **Account**, specify the AWS account ID for the upstream Amazon ECR registry, and then choose **Next**.
1. On the **Step 2: Specify permissions** page, for **IAM role**, select a role to be used for cross account pull through cache access and then choose **Create**.
**Note**
Make sure that you select the IAM role which uses the permissions created in [IAM policies required for cross-account ECR to ECR pull through cache](pull-through-cache-private.md#pull-through-cache-private-permissions).
1. On the **Step 3: Specify namespaces** page, for **Cache namespace**, choose whether to create pull through cache repositories with **A specific prefix** or **no prefix**. If you select **A specific prefix**, you must specify a prefix name to be used as part of the namespace for caching images from the upstream registry.
1. For **Upstream namespace**, choose whether to pull from **A specific prefix** that exists in the upstream registry. If you select **no prefix**, you can pull from any repository in the upstream registry. Specify the upstream repository prefix if prompted, and then choose **Next**.
**Note**
To learn more about customizing cache and upstream namespaces, see [Customizing repository prefixes for ECR to ECR pull through cache](pull-through-cache-private-wildcards.md).
1. On the **Step 4: Review and create** page, review the pull through cache rule configuration and then choose **Create**.
1. Repeat these steps for each pull through cache you want to create. The pull through cache rules are created separately for each Region.
### For Chainguard Registry
1. Open the Amazon ECR console at [https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/).
1. From the navigation bar, choose the Region to configure your private registry settings in.
1. In the navigation pane, choose **Private registry**, **Pull through cache**.
1. On the **Pull through cache configuration** page, choose **Add rule**.
1. On the **Step 1: Specify a source** page, for Registry, choose Chainguard Registry, Next.
1. On the **Step 2: Configure authentication** page, for **Upstream credentials**, you must store your authentication credentials for Chainguard Registry in an AWS Secrets Manager secret. You can specify an existing secret or use the Amazon ECR console to create a new secret.
1. To use an existing secret, choose **Use an existing AWS secret**. For **Secret name** use the drop down to select your existing secret, and then choose **Next**. For more information on creating a Secrets Manager secret using the Secrets Manager console, see [Storing your upstream repository credentials in an AWS Secrets Manager secret](pull-through-cache-creating-secret.md).
**Note**
The AWS Management Console only displays Secrets Manager secrets with names using the `ecr-pullthroughcache/` prefix. The secret must also be in the same account and Region that the pull through cache rule is created in.
1. To create a new secret, choose **Create an AWS secret**, do the following, then choose **Next**.
1. For **Secret name**, specify a descriptive name for the secret. Secret names must contain 1-512 Unicode characters.
1. For **Chainguard Registry username**, specify your Chainguard Registry username.
1. For **Chainguard Registry pull token**, specify your Chainguard Registry pull token. For more information on creating a Chainguard Registry pull token, see [Authenticating with a Pull Token](https://edu.chainguard.dev/chainguard/chainguard-images/chainguard-registry/authenticating/#authenticating-with-a-pull-token) in the Chainguard documentation.
1. On the **Step 3: Specify a destination** page, for **Amazon ECR repository prefix**, specify the repository namespace to use when caching images pulled from the source registry and then choose **Next**.
By default, a namespace is populated but a custom namespace can be specified as well.
1. On the **Step 4: Review and create** page, review the pull through cache rule configuration and then choose **Create**.
1. Repeat the previous step for each pull through cache you want to create. The pull through cache rules are created separately for each Region.
## To create a pull through cache rule (AWS CLI)
Use the [create-pull-through-cache-rule](https://docs.aws.amazon.com/cli/latest/reference/ecr/create-pull-through-cache-rule.html) AWS CLI command to create a pull through cache rule for an Amazon ECR private registry. For upstream registries that require authentication with secrets, you must store the credentials in an Secrets Manager secret. To create a secret using the Secrets Manager console, see [Storing your upstream repository credentials in an AWS Secrets Manager secret](pull-through-cache-creating-secret.md).
The following examples are provided for each supported upstream registry.
### For Amazon ECR Public
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
```
### For Kubernetes Container Registry
The following example creates a pull through cache rule for the Kubernetes public registry. It specifies a repository prefix of `kubernetes`, which results in each repository created using the pull through cache rule to have the naming scheme of `kubernetes/upstream-repository-name`.
```
aws ecr create-pull-through-cache-rule \
--ecr-repository-prefix kubernetes \
--upstream-registry-url registry.k8s.io \
--region us-east-2
```
### For Quay
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
```
### For Docker Hub
The following example creates a pull through cache rule for the Docker Hub registry. It specifies a repository prefix of `docker-hub`, which results in each repository created using the pull through cache rule to have the naming scheme of `docker-hub/upstream-repository-name`. You must specify the full Amazon Resource Name (ARN) of the secret containing your Docker Hub credentials.
```
aws ecr create-pull-through-cache-rule \
--ecr-repository-prefix docker-hub \
--upstream-registry-url registry-1.docker.io \
--credential-arn arn:aws:secretsmanager:us-east-2:111122223333:secret:ecr-pullthroughcache/example1234 \
--region us-east-2
```
### For GitHub Container Registry
The following example creates a pull through cache rule for the GitHub Container Registry. It specifies a repository prefix of `github`, which results in each repository created using the pull through cache rule to have the naming scheme of `github/upstream-repository-name`. You must specify the full Amazon Resource Name (ARN) of the secret containing your GitHub Container Registry credentials.
```
aws ecr create-pull-through-cache-rule \
--ecr-repository-prefix github \
--upstream-registry-url ghcr.io \
--credential-arn arn:aws:secretsmanager:us-east-2:111122223333:secret:ecr-pullthroughcache/example1234 \
--region us-east-2
```
### For Microsoft Azure Container Registry
The following example creates a pull through cache rule for the Microsoft Azure Container Registry. It specifies a repository prefix of `azure`, which results in each repository created using the pull through cache rule to have the naming scheme of `azure/upstream-repository-name`. You must specify the full Amazon Resource Name (ARN) of the secret containing your Microsoft Azure Container Registry credentials.
```
aws ecr create-pull-through-cache-rule \
--ecr-repository-prefix azure \
--upstream-registry-url myregistry.azurecr.io \
--credential-arn arn:aws:secretsmanager:us-east-2:111122223333:secret:ecr-pullthroughcache/example1234 \
--region us-east-2
```
### For GitLab Container Registry
The following example creates a pull through cache rule for the GitLab Container Registry. It specifies a repository prefix of `gitlab`, which results in each repository created using the pull through cache rule to have the naming scheme of `gitlab/upstream-repository-name`. You must specify the full Amazon Resource Name (ARN) of the secret containing your GitLab Container Registry credentials.
```
aws ecr create-pull-through-cache-rule \
--ecr-repository-prefix gitlab \
--upstream-registry-url registry.gitlab.com \
--credential-arn arn:aws:secretsmanager:us-east-2:111122223333:secret:ecr-pullthroughcache/example1234 \
--region us-east-2
```
### For Amazon ECR private registry within your AWS account
The following example creates a pull through cache rule for the Amazon ECR private registry for cross-Region within the same AWS account. It specifies a repository prefix of `ecr`, which results in each repository created using the pull through cache rule to have the naming scheme of `ecr/upstream-repository-name`.
```
aws ecr create-pull-through-cache-rule \
--ecr-repository-prefix ecr \
--upstream-registry-url aws_account_id.dkr.ecr.region.amazonaws.com \
--region us-east-2
```
### For Amazon ECR private registry from another AWS account
The following example creates a pull through cache rule for the Amazon ECR private registry for cross-Region within the same AWS account. It specifies a repository prefix of `ecr`, which results in each repository created using the pull through cache rule to have the naming scheme of `ecr/upstream-repository-name`. You must specify the full Amazon Resource Name (ARN) of the IAM role with the permissions created in [Creating a pull through cache rule in Amazon ECR](#pull-through-cache-creating-rule).
```
aws ecr create-pull-through-cache-rule \
--ecr-repository-prefix ecr \
--upstream-registry-url aws_account_id.dkr.ecr.region.amazonaws.com \
--custom-role-arn arn:aws:iam::aws_account_id:role/example-role \
--region us-east-2
```
### For Chainguard Registry
The following example creates a pull through cache rule for the Chainguard Registry. It specifies a repository prefix of `chainguard`, which results in each repository created using the pull through cache rule to have the naming scheme of `chainguard/upstream-repository-name`. You must specify the full Amazon Resource Name (ARN) of the secret containing your Chainguard Registry credentials.
```
aws ecr create-pull-through-cache-rule \
--ecr-repository-prefix chainguard \
--upstream-registry-url cgr.dev \
--credential-arn arn:aws:secretsmanager:us-east-2:111122223333:secret:ecr-pullthroughcache/example1234 \
--region us-east-2
```
## Next steps
After you create your pull through cache rules, the following are the next steps:
+ Create a repository creation template. A repository creation template gives you control to define the settings to use for new repositories created by Amazon ECR on your behalf during a pull through cache action. For more information, see [Templates to control repositories created during a pull through cache, create on push, or replication action](repository-creation-templates.md).
+ Validate your pull through cache rules. When validating a pull through cache rule, Amazon ECR makes a network connection with the upstream registry, verifies that it can access the Secrets Manager secret containing the credentials for the upstream registry, and that authentication was successful. For more information, see [Validating pull through cache rules in Amazon ECR](pull-through-cache-working-validating.md).
+ Start using your pull through cache rules. For more information, see [Pulling an image with a pull through cache rule in Amazon ECR](pull-through-cache-working-pulling.md).
# Validating pull through cache rules in Amazon ECR
After you create a pull through cache rule, for upstream registries that require authentication you can validate that the rule works properly. When validating a pull through cache rule, Amazon ECR makes a network connection with the upstream registry, verifies that it can access the Secrets Manager secret containing the credentials for the upstream registry, and verifies that authentication was successful.
Before you start working with your pull through cache rules, verify that you have the proper IAM permissions. For more information, see [IAM permissions required to sync an upstream registry with an Amazon ECR private registry](pull-through-cache-iam.md).
## To validate a pull through cache rule (AWS Management Console)
The following steps show how to validate a pull through cache rule using the Amazon ECR console.
1. Open the Amazon ECR console at [https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/).
1. From the navigation bar, choose the Region containing the pull through cache rule to validate.
1. In the navigation pane, choose **Private registry**, **Pull through cache**.
1. On the **Pull through cache configuration** page, select the pull through cache rule to validate. Then, use the **Actions** drop down menu and choose **View details**.
1. On the pull through cache rule detail page, use the **Actions** drop down menu and choose **Verify authentication**. Amazon ECR will display a banner with the result.
1. Repeat these steps for each pull through cache rule you want to validate.
## To validate a pull through cache rule (AWS CLI)
The [validate-pull-through-cache-rule](https://docs.aws.amazon.com/cli/latest/reference/ecr/validate-pull-through-cache-rule.html) AWS CLI command is used to validate a pull through cache rule for an Amazon ECR private registry. The following example uses the `ecr-public` namespace prefix. Replace that value with the prefix value for the pull through cache rule to validate.
```
aws ecr validate-pull-through-cache-rule \
--ecr-repository-prefix ecr-public \
--region us-east-2
```
In the response, the `isValid` parameter indicates whether the validation was successful or not. If `true`, Amazon ECR was able to reach the upstream registry and authentication was successful. If `false`, there was an issue and validation failed. The `failure` parameter indicates the cause.
# Pulling an image with a pull through cache rule in Amazon ECR
The following examples show the command syntax to use when pulling an image using a pull through cache rule. If you receive an error pulling an upstream image using a pull through cache rule, see [Troubleshooting pull through cache issues in Amazon ECR](error-pullthroughcache.md) for the most common errors and how to resolve them.
Before you start working with your pull through cache rules, verify that you have the proper IAM permissions. For more information, see [IAM permissions required to sync an upstream registry with an Amazon ECR private registry](pull-through-cache-iam.md).
**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.
## For Amazon ECR Public
```
docker pull aws_account_id.dkr.ecr.region.amazonaws.com/ecr-public/repository_name/image_name:tag
```
## Kubernetes container registry
```
docker pull aws_account_id.dkr.ecr.region.amazonaws.com/kubernetes/repository_name/image_name:tag
```
## Quay
```
docker pull aws_account_id.dkr.ecr.region.amazonaws.com/quay/repository_name/image_name:tag
```
## Docker Hub
For Docker Hub official images:
```
docker pull aws_account_id.dkr.ecr.region.amazonaws.com/docker-hub/library/image_name:tag
```
**Note**
For Docker Hub official images, the `/library` prefix must be included. For all other Docker Hub repositories, you should omit the `/library` prefix.
For all other Docker Hub images:
```
docker pull aws_account_id.dkr.ecr.region.amazonaws.com/docker-hub/repository_name/image_name:tag
```
## GitHub Container Registry
```
docker pull aws_account_id.dkr.ecr.region.amazonaws.com/github/repository_name/image_name:tag
```
## Microsoft Azure Container Registry
```
docker pull aws_account_id.dkr.ecr.region.amazonaws.com/azure/repository_name/image_name:tag
```
## GitLab Container Registry
```
docker pull aws_account_id.dkr.ecr.region.amazonaws.com/gitlab/repository_name/image_name:tag
```
## Chainguard Registry
```
docker pull aws_account_id.dkr.ecr.region.amazonaws.com/chainguard/repository_name/image_name:tag
```
# Storing your upstream repository credentials in an AWS Secrets Manager secret
When creating a pull through cache rule for an upstream repository that requires authentication, you must store the credentials in a Secrets Manager secret. There may be a cost for using an Secrets Manager secret. For more information, see [AWS Secrets Manager pricing](https://aws.amazon.com/secrets-manager/pricing/).
The following procedures walk you through how to create an Secrets Manager secret for each supported upstream repository. You can optionally use the create pull through cache rule workflow in the Amazon ECR console to create the secret instead of creating the secret using the Secrets Manager console. For more information, see [Creating a pull through cache rule in Amazon ECR](pull-through-cache-creating-rule.md).
------
#### [ Docker Hub ]
**To create a Secrets Manager secret for your Docker Hub credentials (AWS Management Console)**To create a Secrets Manager secret (AWS Management Console)
1. Open the Secrets Manager console at [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/).
1. Choose **Store a new secret**.
1. On the **Choose secret type** page, do the following.
1. For **Secret type**, choose **Other type of secret**.
1. In **Key/value pairs**, create two rows for your Docker Hub credentials. You can store up to 65536 bytes in the secret.
1. For the first key/value pair, specify `username` as the key and your Docker Hub username as the value.
1. For the second key/value pair, specify `accessToken` as the key and your Docker Hub access token as the value. For more information on creating a Docker Hub access token, see [Create and manage access tokens](https://docs.docker.com/security/for-developers/access-tokens/) in the Docker documentation.
1. For **Encryption key**, keep the default **aws/secretsmanager** AWS KMS key value and then choose **Next**. There is no cost for using this key. For more information, see [Secret encryption and decryption in Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/security-encryption.html) in the *AWS Secrets Manager User Guide*.
**Important**
You must use the default `aws/secretsmanager` encryption key to encrypt your secret. Amazon ECR doesn't support using a customer managed key (CMK) for this.
1. On the **Configure secret** page, do the following.
1. Enter a descriptive **Secret name** and **Description**. Secret names must contain 1-512 Unicode characters and be prefixed with `ecr-pullthroughcache/`.
**Important**
The Amazon ECR AWS Management Console only displays Secrets Manager secrets with names using the `ecr-pullthroughcache/` prefix.
1. (Optional) In the **Tags** section, add tags to your secret. For tagging strategies, see [Tag Secrets Manager secrets](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets_tagging.html) in the *AWS Secrets Manager User Guide*. Don't store sensitive information in tags because they aren't encrypted.
1. (Optional) In **Resource permissions**, to add a resource policy to your secret, choose **Edit permissions**. For more information, see [Attach a permissions policy to an Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_resource-policies.html) in the *AWS Secrets Manager User Guide*.
1. (Optional) In **Replicate secret**, to replicate your secret to another AWS Region, choose **Replicate secret**. You can replicate your secret now or come back and replicate it later. For more information, see [Replicate a secret to other Regions](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create-manage-multi-region-secrets.html) in the *AWS Secrets Manager User Guide*.
1. Choose **Next**.
1. (Optional) On the **Configure rotation** page, you can turn on automatic rotation. You can also keep rotation off for now and then turn it on later. For more information, see [Rotate Secrets Manager secrets](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html) in the *AWS Secrets Manager User Guide*. Choose **Next**.
1. On the **Review** page, review your secret details, and then choose **Store**.
Secrets Manager returns to the list of secrets. If your new secret doesn't appear, choose the refresh button.
------
#### [ GitHub Container Registry ]
**To create an Secrets Manager secret for your GitHub Container Registry credentials (AWS Management Console)**To create an Secrets Manager secret (AWS Management Console)
1. Open the Secrets Manager console at [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/).
1. Choose **Store a new secret**.
1. On the **Choose secret type** page, do the following.
1. For **Secret type**, choose **Other type of secret**.
1. In **Key/value pairs**, create two rows for your GitHub credentials. You can store up to 65536 bytes in the secret.
1. For the first key/value pair, specify `username` as the key and your GitHub username as the value.
1. For the second key/value pair, specify `accessToken` as the key and your GitHub access token as the value. For more information on creating a GitHub access token, see [Managing your personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) in the GitHub documentation.
1. For **Encryption key**, keep the default **aws/secretsmanager** AWS KMS key value and then choose **Next**. There is no cost for using this key. For more information, see [Secret encryption and decryption in Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/security-encryption.html) in the *AWS Secrets Manager User Guide*.
**Important**
You must use the default `aws/secretsmanager` encryption key to encrypt your secret. Amazon ECR doesn't support using a customer managed key (CMK) for this.
1. On the **Configure secret** page, do the following:
1. Enter a descriptive **Secret name** and **Description**. Secret names must contain 1-512 Unicode characters and be prefixed with `ecr-pullthroughcache/`.
**Important**
The Amazon ECR AWS Management Console only displays Secrets Manager secrets with names using the `ecr-pullthroughcache/` prefix.
1. (Optional) In the **Tags** section, add tags to your secret. For tagging strategies, see [Tag Secrets Manager secrets](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets_tagging.html) in the *AWS Secrets Manager User Guide*. Don't store sensitive information in tags because they aren't encrypted.
1. (Optional) In **Resource permissions**, to add a resource policy to your secret, choose **Edit permissions**. For more information, see [Attach a permissions policy to an Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_resource-policies.html) in the *AWS Secrets Manager User Guide*.
1. (Optional) In **Replicate secret**, to replicate your secret to another AWS Region, choose **Replicate secret**. You can replicate your secret now or come back and replicate it later. For more information, see [Replicate a secret to other Regions](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create-manage-multi-region-secrets.html) in the *AWS Secrets Manager User Guide*.
1. Choose **Next**.
1. (Optional) On the **Configure rotation** page, you can turn on automatic rotation. You can also keep rotation off for now and then turn it on later. For more information, see [Rotate Secrets Manager secrets](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html) in the *AWS Secrets Manager User Guide*. Choose **Next**.
1. On the **Review** page, review your secret details, and then choose **Store**.
Secrets Manager returns to the list of secrets. If your new secret doesn't appear, choose the refresh button.
------
#### [ Microsoft Azure Container Registry ]
**To create an Secrets Manager secret for your Microsoft Azure Container Registry credentials (AWS Management Console)**To create an Secrets Manager secret (AWS Management Console)
1. Open the Secrets Manager console at [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/).
1. Choose **Store a new secret**.
1. On the **Choose secret type** page, do the following.
1. For **Secret type**, choose **Other type of secret**.
1. In **Key/value pairs**, create two rows for your Microsoft Azure credentials. You can store up to 65536 bytes in the secret.
1. For the first key/value pair, specify `username` as the key and your Microsoft Azure Container Registry username as the value.
1. For the second key/value pair, specify `accessToken` as the key and your Microsoft Azure Container Registry access token as the value. For more information on creating an Microsoft Azure access token, see [Create token - portal](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-repository-scoped-permissions#create-token---portal) in the Microsoft Azure documentation.
1. For **Encryption key**, keep the default **aws/secretsmanager** AWS KMS key value and then choose **Next**. There is no cost for using this key. For more information, see [Secret encryption and decryption in Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/security-encryption.html) in the *AWS Secrets Manager User Guide*.
**Important**
You must use the default `aws/secretsmanager` encryption key to encrypt your secret. Amazon ECR doesn't support using a customer managed key (CMK) for this.
1. On the **Configure secret** page, do the following:
1. Enter a descriptive **Secret name** and **Description**. Secret names must contain 1-512 Unicode characters and be prefixed with `ecr-pullthroughcache/`.
**Important**
The Amazon ECR AWS Management Console only displays Secrets Manager secrets with names using the `ecr-pullthroughcache/` prefix.
1. (Optional) In the **Tags** section, add tags to your secret. For tagging strategies, see [Tag Secrets Manager secrets](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets_tagging.html) in the *AWS Secrets Manager User Guide*. Don't store sensitive information in tags because they aren't encrypted.
1. (Optional) In **Resource permissions**, to add a resource policy to your secret, choose **Edit permissions**. For more information, see [Attach a permissions policy to an Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_resource-policies.html) in the *AWS Secrets Manager User Guide*.
1. (Optional) In **Replicate secret**, to replicate your secret to another AWS Region, choose **Replicate secret**. You can replicate your secret now or come back and replicate it later. For more information, see [Replicate a secret to other Regions](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create-manage-multi-region-secrets.html) in the *AWS Secrets Manager User Guide*.
1. Choose **Next**.
1. (Optional) On the **Configure rotation** page, you can turn on automatic rotation. You can also keep rotation off for now and then turn it on later. For more information, see [Rotate Secrets Manager secrets](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html) in the *AWS Secrets Manager User Guide*. Choose **Next**.
1. On the **Review** page, review your secret details, and then choose **Store**.
Secrets Manager returns to the list of secrets. If your new secret doesn't appear, choose the refresh button.
------
#### [ GitLab Container Registry ]
**To create an Secrets Manager secret for your GitLab Container Registry credentials (AWS Management Console)**To create an Secrets Manager secret (AWS Management Console)
1. Open the Secrets Manager console at [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/).
1. Choose **Store a new secret**.
1. On the **Choose secret type** page, do the following.
1. For **Secret type**, choose **Other type of secret**.
1. In **Key/value pairs**, create two rows for your GitLab credentials. You can store up to 65536 bytes in the secret.
1. For the first key/value pair, specify `username` as the key and your GitLab Container Registry username as the value.
1. For the second key/value pair, specify `accessToken` as the key and your GitLab Container Registry access token as the value. For more information on creating a GitLab Container Registry access token, see [Personal access tokens](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html), [Group access tokens](https://docs.gitlab.com/ee/user/group/settings/group_access_tokens.html), or [Project access tokens](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html), in the GitLab documentation.
1. For **Encryption key**, keep the default **aws/secretsmanager** AWS KMS key value and then choose **Next**. There is no cost for using this key. For more information, see [Secret encryption and decryption in Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/security-encryption.html) in the *AWS Secrets Manager User Guide*.
**Important**
You must use the default `aws/secretsmanager` encryption key to encrypt your secret. Amazon ECR doesn't support using a customer managed key (CMK) for this.
1. On the **Configure secret** page, do the following:
1. Enter a descriptive **Secret name** and **Description**. Secret names must contain 1-512 Unicode characters and be prefixed with `ecr-pullthroughcache/`.
**Important**
The Amazon ECR AWS Management Console only displays Secrets Manager secrets with names using the `ecr-pullthroughcache/` prefix.
1. (Optional) In the **Tags** section, add tags to your secret. For tagging strategies, see [Tag Secrets Manager secrets](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets_tagging.html) in the *AWS Secrets Manager User Guide*. Don't store sensitive information in tags because they aren't encrypted.
1. (Optional) In **Resource permissions**, to add a resource policy to your secret, choose **Edit permissions**. For more information, see [Attach a permissions policy to an Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_resource-policies.html) in the *AWS Secrets Manager User Guide*.
1. (Optional) In **Replicate secret**, to replicate your secret to another AWS Region, choose **Replicate secret**. You can replicate your secret now or come back and replicate it later. For more information, see [Replicate a secret to other Regions](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create-manage-multi-region-secrets.html) in the *AWS Secrets Manager User Guide*.
1. Choose **Next**.
1. (Optional) On the **Configure rotation** page, you can turn on automatic rotation. You can also keep rotation off for now and then turn it on later. For more information, see [Rotate Secrets Manager secrets](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html) in the *AWS Secrets Manager User Guide*. Choose **Next**.
1. On the **Review** page, review your secret details, and then choose **Store**.
Secrets Manager returns to the list of secrets. If your new secret doesn't appear, choose the refresh button.
------
#### [ Chainguard Registry ]
**To create an Secrets Manager secret for your Chainguard credentials (AWS Management Console)**To create an Secrets Manager secret (AWS Management Console)
1. Open the Secrets Manager console at [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/).
1. Choose **Store a new secret**.
1. On the **Choose secret type** page, do the following.
1. For **Secret type**, choose **Other type of secret**.
1. In **Key/value pairs**, create two rows for your Chainguard credentials. You can store up to 65536 bytes in the secret.
1. For the first key/value pair, specify `username` as the key and your Chainguard Registry username as the value.
1. For the second key/value pair, specify `accessToken` as the key and your Chainguard Registry access token as the value. For more information on creating a Chainguard Registry pull token, see [Authenticating with a Pull Token ](https://edu.chainguard.dev/chainguard/chainguard-images/chainguard-registry/authenticating/#authenticating-with-a-pull-token) in the Chainguard documentation.
1. For **Encryption key**, keep the default **aws/secretsmanager** AWS KMS key value and then choose **Next**. There is no cost for using this key. For more information, see [Secret encryption and decryption in Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/security-encryption.html) in the *AWS Secrets Manager User Guide*.
**Important**
You must use the default `aws/secretsmanager` encryption key to encrypt your secret. Amazon ECR doesn't support using a customer managed key (CMK) for this.
1. On the **Configure secret** page, do the following:
1. Enter a descriptive **Secret name** and **Description**. Secret names must contain 1-512 Unicode characters and be prefixed with `ecr-pullthroughcache/`.
**Important**
The Amazon ECR AWS Management Console only displays Secrets Manager secrets with names using the `ecr-pullthroughcache/` prefix.
1. (Optional) In the **Tags** section, add tags to your secret. For tagging strategies, see [Tag Secrets Manager secrets](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets_tagging.html) in the *AWS Secrets Manager User Guide*. Don't store sensitive information in tags because they aren't encrypted.
1. (Optional) In **Resource permissions**, to add a resource policy to your secret, choose **Edit permissions**. For more information, see [Attach a permissions policy to an Secrets Manager secret](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_resource-policies.html) in the *AWS Secrets Manager User Guide*.
1. (Optional) In **Replicate secret**, to replicate your secret to another AWS Region, choose **Replicate secret**. You can replicate your secret now or come back and replicate it later. For more information, see [Replicate a secret to other Regions](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create-manage-multi-region-secrets.html) in the *AWS Secrets Manager User Guide*.
1. Choose **Next**.
1. (Optional) On the **Configure rotation** page, you can turn on automatic rotation. You can also keep rotation off for now and then turn it on later. For more information, see [Rotate Secrets Manager secrets](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html) in the *AWS Secrets Manager User Guide*. Choose **Next**.
1. On the **Review** page, review your secret details, and then choose **Store**.
Secrets Manager returns to the list of secrets. If your new secret doesn't appear, choose the refresh button.
------
# Customizing repository prefixes for ECR to ECR pull through cache
Pull through cache rules support both the **ecr repository prefix** and the **upstream repository prefix**. The **ecr repository prefix** is the repository namespace prefix in Amazon ECR cache registry that's associated with the rule. All repositories using this prefix become pull through cache-enabled repositories for the upstream registry defined in the rule. For example, a prefix of `prod` applies to all repositories beginning with `prod/`. To apply a template to all repositories in your registry that don't have an associated pull through cache rule, 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/`.
The **upstream repository prefix** matches the upstream repository name. By default, it's set to `ROOT`, which allows matching with any upstream repository. You can set the **upstream repository prefix** only when the Amazon ECR repository prefix has a non-`ROOT` value.
The following table shows the mapping between cache repository names and upstream repository names based on their prefix configurations in pull through cache rules.
| Cache namespace | Upstream namespace | Mapping relationship (cache repository → upstream repository) |
| --- | --- | --- |
| ecr-public | ROOT (default) | `ecr-public/my-app/image1` → `my-app/image1` `ecr-public/my-app/image2` → `my-app/image2` |
| ROOT | ROOT | `my-app/image1` → `my-app/image1` |
| team-a | team-a | `team-a/myapp/image1` → `team-a/myapp/image1` |
| my-app | upstream-app | `my-app/image1` → `upstream-app/image1` |
# Troubleshooting pull through cache issues in Amazon ECR
When pulling an upstream image using a pull through cache rule, the following are the most common errors you may receive.
**Repository does not exist**
An error indicating that the repository doesn't exist is most often caused by either the repository not existing in your Amazon ECR private registry or the `ecr:CreateRepository` permission not being granted to the IAM principal pulling the upstream image. To resolve this error, you should verify that the repository URI in your pull command is correct, the required IAM permissions are granted to the IAM principal pulling the upstream image, or that the repository for the upstream image to be pushed to is created in your Amazon ECR private registry before doing the upstream image pull. For more information about the required IAM permissions, see [IAM permissions required to sync an upstream registry with an Amazon ECR private registry](pull-through-cache-iam.md)
The following is an example of this error.
```
Error response from daemon: repository 111122223333.dkr.ecr.us-east-1.amazonaws.com/ecr-public/amazonlinux/amazonlinux not found: name unknown: The repository with name 'ecr-public/amazonlinux/amazonlinux' does not exist in the registry with id '111122223333'
```
**Requested image not found**
An error indicating that the image can't be found is most often caused by either the image not existing in the upstream registry or the `ecr:BatchImportUpstreamImage` permission not being granted to the IAM principal pulling the upstream image but the repository already being created in your Amazon ECR private registry. To resolve this error, you should verify the upstream image and image tag name is correct and that it exists and the required IAM permissions are granted to the IAM principal pulling the upstream image. For more information about the required IAM permissions, see [IAM permissions required to sync an upstream registry with an Amazon ECR private registry](pull-through-cache-iam.md).
The following is an example of this error.
```
Error response from daemon: manifest for 111122223333.dkr.ecr.us-east-1.amazonaws.com/ecr-public/amazonlinux/amazonlinux:latest not found: manifest unknown: Requested image not found
```
**403 Forbidden when pulling from a Docker Hub repository**
When pulling from a Docker Hub repository that is tagged as a **Docker Official Image**, you must include the `/library/` in the URI you use. For example, `aws_account_id.dkr.ecr.region.amazonaws.com/docker-hub/library/image_name:tag`. If you omit the `/library/` for Docker Hub Official images, a `403 Forbidden` error will be returned when you attempt to pull the image using a pull through cache rule. For more information, see [Pulling an image with a pull through cache rule in Amazon ECR](pull-through-cache-working-pulling.md).
The following is an example of this error.
```
Error response from daemon: failed to resolve reference "111122223333.dkr.ecr.us-west-2.amazonaws.com/docker-hub/amazonlinux:2023": pulling from host 111122223333.dkr.ecr.us-west-2.amazonaws.com failed with status code [manifests 2023]: 403 Forbidden
```