AWS ECR Explained: Store and Manage Docker Images in AWS

Quick Answer

Amazon Elastic Container Registry (ECR) is a fully managed, secure Docker container registry that allows developers to store, manage, and deploy container images. To use it, you authenticate your local Docker daemon using the AWS CLI, tag your local container image with your unique ECR repository URI, and execute a standard push command. ECR integrates natively with AWS Identity and Access Management (IAM) for granular access control, Amazon ECS, and Amazon EKS, making it the default destination for cloud-native containerized workloads.

What Is ECR?

Amazon Elastic Container Registry serves as the central bridge linking your local development environments or CI/CD pipelines directly into AWS infrastructure. As a fully managed container registry aws service, ECR removes the operational overhead of setting up, scaling, and patching your own registry infrastructure, such as running a self-hosted Docker Registry on an EC2 instance.

Under the hood, ECR stores your Docker images reliably across multiple Availability Zones within a given AWS region. It handles high availability and storage scaling automatically. Whether you are running containerized microservices on Amazon ECS, orchestrating complex workloads with Amazon EKS, or deploying serverless containers via AWS Fargate, ECR acts as the trusted source of truth for your immutable deployment artifacts.

Create a Repository

Before you can push any images, you must provision an ecr repository within your targeted AWS account and region. Repositories organize your container images logically, often mirroring microservice names such as production/api-service or staging/web-frontend.

You can create a repository using either the AWS Management Console or the AWS CLI. To use the console, navigate to the ECR service dashboard, click "Create repository," choose between a public or private visibility setting, specify a repository name, and configure tag mutability settings.

Alternatively, you can provision a repository instantly via the command line:

aws ecr create-repository \
    --repository-name production/api-service \
    --image-scanning-configuration scanOnPush=true \
    --image-tag-mutability MUTABLE \
    --region us-east-1

Executing this command returns a JSON response containing your unique repository URI, ARN, and configuration timestamps. Always verify that your repository region aligns with your downstream compute clusters to minimize data transfer latency and cross-region costs.

Authenticate Docker

Before pushing or pulling images, your local Docker daemon must prove its identity to AWS ECR. Because ECR relies on AWS IAM for security, you cannot use standard static Docker Hub credentials. Instead, you must generate a temporary authentication token through the AWS CLI.

The standard aws ecr login workflow requires you to retrieve an authorization token and pass it directly to the Docker client. A common and secure way to perform this operation combines both tools into a single command:

aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com

Let's break down what happens here. The aws ecr get-login-password command queries AWS security endpoints using your local AWS CLI credentials (configured via environment variables, IAM user keys, or SSO profiles) to generate an encoded authorization token. This token is piped into docker login, which authenticates your local Docker daemon for a default duration of 12 hours. Never hardcode or expose your AWS access keys within scripts or Dockerfiles.

Push and Pull Images

Once authenticated, moving your images into cloud storage follows a familiar Git-like tagging and pushing workflow. First, build your local image as you normally would:

docker build -t my-local-app:latest .

Next, you must re-tag this local image so the Docker daemon knows which remote registry and repository it belongs to. The target URI format combines your 12-digit AWS account ID, the ECR domain, your region, and your repository name:

docker tag my-local-app:latest 123456789012.dkr.ecr.us-east-1.amazonaws.com/production/api-service:v1.0.0

With the tag correctly applied, you can execute the docker push ecr operation:

docker push 123456789012.dkr.ecr.us-east-1.amazonaws.com/production/api-service:v1.0.0

ECR streams your image layers concurrently. Once the upload finishes, you can pull the image down to verify integrity or deploy it to a test environment:

docker pull 123456789012.dkr.ecr.us-east-1.amazonaws.com/production/api-service:v1.0.0

Tags and Digests

Managing image versions effectively requires understanding how ECR handles tags and cryptographic digests. A tag (such as :latest or :v1.0.0) is a mutable pointer to a specific container image manifest. If you push a new build using an existing tag, ECR updates that pointer to reference the new image layers, while the older image becomes untagged.

For mission-critical production deployments, relying solely on mutable tags introduces risks. To guarantee absolute immutability and reproducibility, reference images by their cryptographic SHA-256 image digest rather than a tag string:

123456789012.dkr.ecr.us-east-1.amazonaws.com/production/api-service@sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890

Configuring your repositories with IMMUTABLE tag settings prevents developers or CI/CD pipelines from accidentally overwriting existing release versions, ensuring that deployed code matches tested artifacts precisely.

Lifecycle and Security

Maintaining a clean container registry requires proactive governance. Over time, continuous integration builds accumulate thousands of unused tags, inflating storage costs and complicating artifact management. ECR lifecycle policies automate this maintenance by defining rules that expire and delete untagged or old images based on age or count criteria.

Security is equally vital. You should enable automated vulnerability scanning on push for every repository. ECR integrates with Amazon Inspector to scan operating system packages and application language dependencies for known Common Vulnerabilities and Exposures (CVEs), surfacing actionable remediation reports directly inside the console.

Docker-to-AWS Workflow

Bringing everything together into a realistic production workflow involves coordinating local developer testing, automated CI/CD pipelines, and secure runtime deployment. In a typical enterprise setup, developers write code locally, run unit tests inside Docker containers, and commit changes to a GitHub or GitLab repository.

A continuous integration server (such as GitHub Actions or GitLab CI) picks up the commit, builds the container image, executes automated security scans, and authenticates with AWS using assumed IAM roles with least-privilege permissions. The pipeline then pushes the verified artifact to ECR and triggers an rolling update on an Amazon ECS service or an ArgoCD deployment manifest targeting an Amazon EKS cluster.

Repository

Repository-level configurations dictate how your artifacts are stored and accessed. You can apply fine-grained resource-based IAM policies directly to individual repositories, allowing specific cross-account access or restricting read operations to distinct deployment roles. When planning multi-region architectures, establish replication rules within ECR to automatically copy images across secondary AWS regions for disaster recovery and low-latency global deployments.

Authentication

Authentication tokens expire strictly after 12 hours for security reasons. In automated CI/CD pipelines, this means your build runner must execute the aws ecr get-login-password command immediately before every push or pull stage. Ensure that your CI/CD runner is provisioned with an IAM role or OpenID Connect (OIDC) provider rather than static long-lived AWS credentials, eliminating the risk of leaked secret keys.

Image URI

Constructing a valid Image URI is a common point of friction for newcomers. The exact anatomy follows this strict pattern: account-id.dkr.ecr.region.amazonaws.com/repository-name:tag. Omitting any component, misspelling the region, or using an incorrect account ID results in authentication failures or DNS resolution errors when your container runtime attempts to fetch the image.

Tags

Tag hygiene is essential for operational sanity. Avoid the widespread anti-pattern of using the :latest tag for production workloads. Because :latest changes dynamically with every push, it destroys deployment traceability and makes rollbacks extremely difficult. Instead, tag production releases with semantic version numbers or Git commit SHAs.

Vulnerability/security controls

Security controls in ECR extend beyond basic vulnerability scanning. You can enforce client-side encryption using AWS Key Management Service (KMS) customer-managed keys, ensuring that your container layers are encrypted at rest. Combine these encryption settings with AWS CloudTrail logging to audit every push, pull, and repository modification event across your organization.