AWS ECR Pull Through cache module

This module creates an ECR (Elastic Container Registry) pull through cache role resource and the IAM policy to use it.

The pull through cache allows you to cache images from an upstream registry in your ECR repository. This is useful for:

• Reducing the number of requests to the upstream registry
• Improving the performance of image pulls
• Avoiding rate limits

Note: This module DOES NOT manage the secret in AWS Secrets Manager, the secret must be created and updated manually.

Prerequisites

• AWS Secrets Manager secret containing upstream registry credentials

Quick Start

module "ecr_pull_through_cache" {
  source = "github.com/terraform-aws-ecr-pull-through-cache?ref=0.3.0"

  aws_region             = "eu-west-1"
  upstream_registry_name = "docker-hub"
  upstream_registry_url  = "registry-1.docker.io"
}

Upstream credentials

The upstream repository credentials must be created (and managed) manually in AWS Secrets Manager. According to the AWS documentation:

• The secret must be created in the same AWS account and region as the ECR pull through cache
• The secret name must follow the AWS required naming convention

IAM Policy

An IAM policy, with the minimum permissions to pull images, is created by the module. You need to attach this IAM policy to the resources that will use the pull through cache.

Usage Examples

In the following examples you can see how to pull Docker images using the pull through cache using the right image format for the URL:

• for Docker Hub official images: docker pull AWS_ACCOUNT_ID.dkr.ecr.AWS_REGION.amazonaws.com/docker-hub/library/image_name:tag.
• For all other Docker Hub images: docker pull AWS_ACCOUNT_ID.dkr.ecr.AWS_REGION.amazonaws.com/docker-hub/repository_name/image_name:tag.

For details about other upstream repositories (like Kubernetes, Quay, GitHub, GitLab, etc.), see the AWS references.

Fallback strategy

This module gives you the option to use a fallback strategy, the upstream credentials (stored in AWS Secret Manager) could be used to populate secrets in the needed namespaces, so you can use it in the ImagePullSecrets of your Kubernetes resources.

Providers

Name	Version
aws	>= 5.0
kubernetes	>= 2.23

Requirements

Name	Version
terraform	>= 1.5
aws	>= 5.0
kubernetes	>= 2.23

Inputs

Name	Description	Type	Default	Required
aws_region	The AWS region to deploy the ECR pull through cache	string	"eu-west-1"	no
fallback_namespaces	The list of namespaces to create the regcred secret in	list(string)	[]	no
fallback_secret_name	The name of the secrets to create	string	"regcred"	no
upstream_registry_name	The upstream registry name	string	"docker-hub"	no
upstream_registry_url	The upstream registry URL	string	"registry-1.docker.io"	no

Outputs

Name	Description
ecr_pullthroughcache_policy_arn	The ARN of the ECR pull-through cache policy.
ecr_pullthroughcache_policy_name	The name of the ECR pull-through cache policy.
ecr_pullthroughcache_repository_uri	The URI of the ECR pull throught cache repository URI.

Resources

Name	Type
aws_ecr_pull_through_cache_rule.ecr_pullthroughcache	resource
aws_iam_policy.ecr_pullthroughcache	resource
kubernetes_secret_v1.secret	resource
aws_caller_identity.current	data source
aws_secretsmanager_secret.ecr_pullthroughcache	data source
aws_secretsmanager_secret_version.ecr_pullthroughcache	data source

Modules

No modules.