Infrastructure as code has become the default way to treat Amazon Elastic Container Registry as a managed asset rather than a console click-through. In a cloud computing and microservice world, the involvement of infrastructure resources must be concentrated and repeatable. Terraform, an open source IaC tool that is widely used for provisioning and managing cloud resources across many cloud service providers such as AWS, has become the de-facto standard, not surprising that people have started noticing its advantages over other available options. Among the workable services of AWS is Amazon Elastic Container Registry which is a well-managed Docker container registry that gives the chance to images to store, manage, and deploy.
Terraform replies to the difficulty of creating and handling ECR repositories by providing a hot approach to IT architecture preservation. In Terraform, you may define your desired state of an ECR repository and other associated resources in a software configuration file. Terraform will consequently handle the creation, updating, and maintenance procedures for your infrastructure.
Terraform and AWS ECR Fundamentals
Terraform is an open-source resource infrastructure tool manufactured by HashiCorp. It provides the independence of its declaration and configuration to the developers and operations teams to define, provision, and manage cloud infrastructure resources across multiple cloud providers and off-premises environments in a consistent manner.
The basic structure of terraform is based on a human-friendly language that is called HashiCorp Configuration Language or HCL which implies the desired state of infrastructure resources. These resources can include things like virtual machines, networks, databases, and container registries provided by big top cloud providers such as Amazon Web Services, Microsoft Azure, Google Cloud Platform, and the rest.
Amazon Elastic Container Registry is a fully managed Docker container offering provided by Amazon Web Services as it is prevalently called, abbreviated as AWS, which is a cloud computing subsidiary of Amazon.
Repositories of ECR may be differentiating for the libraries, each of which contains multiple Docker Images, designated by different tags such as versions and configurations.
Terraform is an Infrastructure as Code tool used to automate and manage all cloud resources.
- Defines, provisions, and destroys infrastructure consistently across environments.
- Enables full automation of the VPC, ECS, ALB, CloudFront, S3, CloudWatch, and SNS setup.
- Makes your deployments repeatable, version-controlled, and easy to maintain.
Prerequisites and Provider Configuration
Before using the terraform-aws-ecr module, ensure you have the prerequisites in place.
The workflow for creating an ECR repository with Terraform is commonly described as:
- Install Terraform
- Configure Terraform AWS provider
- Create an ECR repository
- Run terraform init
- Run terraform plan
- Apply your configuration
- Verify the deployment in the AWS console
- Run terraform destroy
Step 1 — Install Terraform
Make sure you have Terraform installed on your machine.
Step 2 — Configure Terraform AWS provider
Once you have Terraform installed, it is time to add some configuration files.
Create a new Terraform configuration file, let's call it main.tf. In this file, you need to define the AWS provider and specify your AWS credentials.
A minimal provider block follows the HCL pattern used by Terraform:
provider "aws" {
region = "us-east-1"
}
Step 1: Install Terraform
If you haven't already, install Terraform on your machine. You can download by referring to Terraform Install.
Step 2: Configure AWS Provider
Create a new Terraform configuration file, let's call it main.tf. In this file, you need to define the AWS provider and specify your AWS credentials.
Step-by-Step ECR Creation with Terraform
Create ECR repository in AWS using Terraform: Practical Step-by-Step Guide.
Step 1: Initialize Terraform
Set up Terraform in your working directory.
terraform init
Step 2: Format the Terraform Code
Clean up the Terraform files, optional but recommended:
terraform fmt
Step 3: Prepare the Docker Image and Push to ECR
If you haven't pushed your app image to ECR yet, check for ecr_push.sh in scripts folder and run the commands.
This script will:
- Build the Docker image
- Tag it with your ECR repo URL
- Push the image to ECR
Already have an image in ECR? You can skip this step.
Final Checks Before You Deploy
The step list above is typical for a beginner ECS ECR project.
Terraform AWS ECR Module Usage
This 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.
To use the module in your Terraform configuration, add the following block:
module "ecr" {
source = "terraform-aws-modules/ecr/aws"
}
The terraform-aws-ecr module provides a flexible interface for managing ECR resources in AWS.
This example shows how to create a private ECR repository with a lifecycle policy and access control:
The module is highly customizable through many input variables.
This diagram illustrates the configuration flow from Terraform variables to AWS ECR resources.
The module is highly customizable through many input variables.
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. Here is a good example of a public one.
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.
Private Versus Public Repository Configuration
The terraform-aws-ecr module supports both private and public repository patterns.
For a public repository, use the following configuration:
The module documentation shows a private repository example with lifecycle policy and access control, and a separate configuration for a public repository.
A comparison of repository types can be summarized:
| Attribute | Private Repository | Public Repository |
|---|---|---|
| Visibility | Restricted to AWS account | Accessible publicly |
| Access Control | IAM policies, resource policies | Public pull |
| Use Case | Internal services, ECS, EKS | Open source images |
Lifecycle Policy, Access Control and Replication
ECR also supports Cross-Region and Cross-Account Replication to replicate images where needed easily.
Cost: ECR offers a pay-as-you-go pricing model, meaning you only pay for the amount of storage used and the data transferred without upfront costs.
Is ECR backed by S3?
ECR uses S3 as the underlying storage layer, which provides durability, availability, and lifecycle management for the images.
What is an ECR used for?
ECR is used to store, manage, and deploy Docker container images in AWS. It integrates with services like ECS, EKS, and CodeBuild, allowing secure, scalable image storage without managing your own registry.
Frequently asked questions
Is ECR the same as Docker?
Amazon Elastic Container Registry is a managed container image registry service provided by AWS, used to store, manage, and deploy Docker container images.
Workflow Integration and Deployment Validation
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.
Automate Terraform Deployments with Spacelift
Automate your infrastructure provisioning, build more complex workflows based on Terraform using policy as code, programmatic configuration, context sharing, drift detection, resource visualization, and many more.
OpenTofu is an open-source version of Terraform that expands on Terraform's existing concepts and offerings. It is a viable alternative to HashiCorp's Terraform, being forked from Terraform version 1.5.6.
Conclusion
Terraform provides a declarative, version-controlled path to provision Amazon Elastic Container Registry repositories and related controls. The AWS provider configuration establishes credentials and region context, while the awsecrrepository resource or the terraform-aws-ecr module expresses the desired state of private or public repositories, lifecycle policies, access control, and replication. Because ECR uses S3 as the underlying storage layer, durability and lifecycle management are inherited without additional design.
Module reuse, private module development under modules/ecr with main.tf and variables.tf, and integration with ECS, EKS, and CodeBuild make the pattern repeatable across environments. Pay-as-you-go pricing aligns cost with actual storage and data transfer, and cross-region and cross-account replication extends the model to multi-region delivery. The standard Terraform workflow of init, fmt, plan, apply, verify in the AWS console, and destroy ensures safe adoption and ongoing drift management.