The Wayback Machine - https://web.archive.org/web/20231208205031/https://docs.aws.amazon.com/AmazonECR/latest/userguide/pull-through-cache-creating-rule.html
Creating a pull through cache rule - Amazon ECR
Using the AWS Management ConsoleUsing the AWS CLINext steps

Creating a pull through cache rule

For each upstream registry containing images you want to cache in your Amazon ECR private registry, you must create a pull through cache rule. For upstream registries that require authentication, you must store the credentials in an Secrets Manager secret. You can create the Secrets Manager secret in either the Amazon ECR or Secrets Manager consoles.

Before you start creating your pull through cache rules, ensure you have the proper IAM permissions. For more information, see Required IAM permissions.

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. For more information on creating a secret using the Secrets Manager console, see Storing your upstream repository credentials in an AWS Secrets Manager secret.

  1. Open the Amazon ECR console at https://console.aws.amazon.com/ecr/.

  2. From the navigation bar, choose the Region to configure your private registry settings in.

  3. In the navigation pane, choose Private registry, Pull through cache.

  4. On the Pull through cache configuration page, choose Add rule.

  5. 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.

  6. 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.

  7. On the Step 3: Review and create page, review the pull through cache rule configuration and then choose Create.

  8. Repeat the previous step for each pull through cache you want to create. The pull through cache rules are created separately for each Region.

  1. Open the Amazon ECR console at https://console.aws.amazon.com/ecr/.

  2. From the navigation bar, choose the Region to configure your private registry settings in.

  3. In the navigation pane, choose Private registry, Pull through cache.

  4. On the Pull through cache configuration page, choose Add rule.

  5. On the Step 1: Specify a source page, for Registry, choose Docker Hub, Next.

  6. 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. 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.

      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.

    2. 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.

      2. For Docker Hub username, specify your Docker Hub username.

      3. 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 in the Docker documentation.

  7. 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.

  8. On the Step 4: Review and create page, review the pull through cache rule configuration and then choose Create.

  9. Repeat the previous step for each pull through cache you want to create. The pull through cache rules are created separately for each Region.

  1. Open the Amazon ECR console at https://console.aws.amazon.com/ecr/.

  2. From the navigation bar, choose the Region to configure your private registry settings in.

  3. In the navigation pane, choose Private registry, Pull through cache.

  4. On the Pull through cache configuration page, choose Add rule.

  5. On the Step 1: Specify a source page, for Registry, choose GitHub Container Registry, Next.

  6. 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. 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.

      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.

    2. 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.

      2. For GitHub Container Registry username, specify your GitHub Container Registry username.

      3. 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 in the GitHub documentation.

  7. 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.

  8. On the Step 4: Review and create page, review the pull through cache rule configuration and then choose Create.

  9. Repeat the previous step for each pull through cache you want to create. The pull through cache rules are created separately for each Region.

  1. Open the Amazon ECR console at https://console.aws.amazon.com/ecr/.

  2. From the navigation bar, choose the Region to configure your private registry settings in.

  3. In the navigation pane, choose Private registry, Pull through cache.

  4. On the Pull through cache configuration page, choose Add rule.

  5. On the Step 1: Specify a source page, do the following.

    1. For Registry, choose Microsoft Azure Container Registry

    2. 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.

  6. 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. 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.

      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.

    2. 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.

      2. For Microsoft Azure Container Registry username, specify your Microsoft Azure Container Registry username.

      3. 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 in the Microsoft Azure documentation.

  7. 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.

  8. On the Step 4: Review and create page, review the pull through cache rule configuration and then choose Create.

  9. 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 AWS CLI command to create a pull through cache rule for an Amazon ECR private registry. For upstream registries that require authentication, you must store the credentials in an Secrets Manager secret. For more information on creating a secret using the Secrets Manager console, see Storing your upstream repository credentials in an AWS Secrets Manager secret.

The following examples are provided for each supported upstream registry.

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 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

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

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

The following example creates a pull through cache rule for the GitHub Container Registry 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 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

The following example creates a pull through cache rule for the Microsoft Azure Container Registry 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

Next steps

After you have created 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 Manage your repository creation templates.

  • 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 your pull through cache rule.

  • Start using your pull through cache rules. For more information, see Pulling an image with a pull through cache rule.