Terraform AWS ECR Module

The terraform-aws-ecr module provides a flexible interface for managing Amazon Elastic Container Registry resources in AWS. The module is highly customizable through many input variables and is intended to cover both basic repository provisioning and advanced registry-level configuration. This article maps the module’s behavior, usage patterns, and practical examples as described in the reference material.

Introduction

Managing ECR repositories with Terraform reduces manual console work and enables consistent, repeatable configuration for private and public container registries. The terraform-aws-ecr module from terraform-aws-modules centralizes repository creation, lifecycle policies, scanning configuration, replication, pull-through cache rules, and registry policies into reusable module instantiations. For users already working with raw awsecrrepository resources, the module offers a standardized interface that can be reused across environments with minor adjustments. The guide provides essential instructions for setting up and using the terraform-aws-ecr module to manage Amazon Elastic Container Registry resources. For more advanced features like pull-through cache configuration or replication settings, see Advanced Features.

Getting Started and Prerequisites

Before using the terraform-aws-ecr module, ensure you have the prerequisites required to run Terraform against AWS. To use the module in your Terraform configuration, add the following block:

hcl module "ecr" { source = "terraform-aws-modules/ecr/aws" }

The module creates one or more Elastic Container Registry repositories. All repositories created will share the same configuration. Use this module multiple times to create repositories with different configurations.

Module Interface and Core Behavior

The terraform-aws-ecr module provides a flexible interface for managing ECR resources in AWS.

Repository naming behavior is controlled by input variables:

• If you provide 1 or more names in image_names then one repository will be created for each of the names you provide. Those names can include "namespaces", which are just prefixes ending with a slash (/).
• If you do not provide any names in imagenames, the module will create a single ECR repo named namespace-stage-name or just name depending on the value of usefullname.

This diagram illustrates the configuration flow from Terraform variables to AWS ECR resources.

Access Control and Principals

Access to the repositories is granted to via the principalsfullaccess and principalsreadonlyaccess lists, which are lists of strings that can designate any valid AWS Principal.

This module only creates the Repository Policy allowing those Principals access. The Principals will still separately need IAM policies allowing them permission to execute ECR actions against the repository.

For the cloudposse variant, the module creates one or more Elastic Container Registry repositories and access is controlled through principalsfullaccess and principalsreadonlyaccess lists. The module creates the Repository Policy allowing those Principals access.

Repository Creation Patterns

This example shows how to create a private ECR repository with a lifecycle policy and access control:

hcl module "ecr" { source = "terraform-aws-modules/ecr/aws" repository_name = "private-example" repository_read_write_access_arns = ["arn:aws:iam::012345678901:role/terraform"] repository_lifecycle_policy = jsonencode({ rules = [ { rulePriority = 1, description = "Keep last 30 images", selection = { tagStatus = "tagged", tagPrefixList = ["v"], countType = "imageCountMoreThan", countNumber = 30 }, action = { type = "expire" } } ] }) tags = { Terraform = "true" Environment = "dev" } }

For a public repository, use the following configuration:

hcl module "public_ecr" { source = "terraform-aws-modules/ecr/aws" repository_name = "public-example" repository_type = "public" repository_read_write_access_arns = ["arn:aws:iam::012345678901:role/terraform"] public_repository_catalog_data = { description = "Docker container for some things" about_text = file("${path.module}/files/ABOUT.md") usage_text = file("${path.module}/files/USAGE.md") operating_systems = ["Linux"] architectures = ["x86"] logo_image_blob = filebase64("${path.module}/files/clowd.png") } tags = { Terraform = "true" Environment = "dev" } }

Registry-Level Settings and Advanced Features

The module supports registry-level configuration beyond individual repositories.

The Complete Example demonstrates comprehensive usage of the terraform-aws-ecr module, showcasing how to create and configure both private and public ECR repositories along with registry-level settings.

The example creates the following resources:

The Complete Example demonstrates several module instantiations:

• module.ecr: Creates a private ECR repository with repository policy and other configurations
• module.public_ecr: Creates a public ECR repository
• module.ecr_registry: Configures registry-level settings including policies and features
• module.ecr_disabled: Demonstrates how to conditionally disable resource creation
• module.secretsmanagerdockerhub_credentials: Manages DockerHub credentials for pull-through cache authentication

A registry-level example with create_repository disabled is:

hcl module "ecr_registry" { source = "terraform-aws-modules/ecr/aws" repository_name = "registry-example" create_repository = false create_registry_policy = true registry_policy = jsonencode({ Version = "2012-10-17", Statement = [ { Sid = "testpolicy", Effect = "Allow", Principal = { "AWS" : } } ] }) }

Examples and Usage Patterns

These examples demonstrate the practical implementation and usage patterns of the module's features for creating and managing Amazon Elastic Container Registry resources.

The terraform-aws-ecr module includes two comprehensive examples to help users understand and implement the module:

• The Complete Example demonstrates comprehensive usage of the terraform-aws-ecr module, showcasing how to create and configure both private and public ECR repositories along with registry-level settings.

If you plan to create multiple ECR repositories with similar configurations, you should consider using Terraform modules for reusability best practice.

Modules allow you to define the ECR repository configuration once and reuse it for multiple repositories with minor adjustments. Centralizing configuration in a module makes it easier to manage and update the code for all ECR repositories. Modules also promote code organization and separation between core infrastructure and specific resource configurations.

You can use a public or private module for this. Public modules offer a quick starting point, while private modules provide greater control and customization.

Alternative Modules and Private Module Development

A popular alternative is cloudposse/ecr/aws, which uses a different input convention (namespace, stage, name, principalsfullaccess) if you prefer that style.

If you prefer to develop a private module:

• Create a separate directory for your module code (e.g., modules/ecr).
• Inside the directory, create a file named main.tf containing the awsecrrepository resource definition with desired configuration options.
• Optionally, create a variables.tf file to define variables that can be customized when using the module
• Create an outputs.tf file (also optional) to expose module outputs, such as the ECR repository URI.

Example: Using the Public ECR module in Terraform

Here’s an example using the terraform-aws-modules/ecr/aws module, which also lets you define the lifecycle policy inline.

Follow the steps listed previously and replace the code in Step 3 with the following to use the module rather than the resource directly.

Terraform will show the resource being adopted into state with no changes if your configuration matches the live resource, or a diff if it doesn’t.

Run terraform apply to perform the import. Once the apply succeeds, you can remove the import block from your configuration — it’s only needed for the initial import.

Compliance and Controls

Terraform AWS ECR

ECR repositories with image scanning, immutable tags, KMS encryption, lifecycle policies, repository policies, replication, and controlled push and pull access.

Controls enforced

These compliance controls are checked at terraform plan time.

Quick start

Migration from upstream

Already using terraform-aws-modules? Change only the source URL:

Same arguments. Same outputs. Controls are checked at terraform plan. See the Migration Guide for step-by-step instructions.

Reversibility

No lock-in. Switch back by reverting the source URL:

Run terraform init -upgrade. Terraform state is unchanged — same resource addresses, same provider, no compliance.tf-specific resources. Controls you already applied remain in AWS.

Mapped compliance frameworks

Framework coverage

Which controls from this module are active under each framework endpoint.

● enforced by default · ○ not activated by this endpoint

Conclusion

The terraform-aws-ecr module consolidates ECR repository provisioning, policy, lifecycle, scanning, replication, and registry-level settings into reusable Terraform code. The module supports private repositories with lifecycle policies and access control, public repositories with catalog data, and registry-wide configuration for pull-through cache, replication, and registry policies. Instantiation patterns include single repository creation, multiple repositories via image_names, and separate module calls for registry settings versus repositories. Access control is expressed through principal lists and repository policies, with the understanding that IAM permissions remain a separate requirement. For teams managing many repositories, the module encourages centralization and reuse, while compliance-focused variants add plan-time controls for image scanning and tag immutability. Migration is reversible by changing the source URL without altering state, enabling adoption with minimal risk.

Sources

1. DeepWiki Getting Started
2. CloudPosse Terraform AWS ECR
3. Spacelift Terraform ECR Blog
4. DeepWiki Examples
5. Terraform AWS Modules ECR GitHub
6. Compliance.tf Terraform AWS ECR