Amazon ECR Cheat Sheet - Complete Container Registry Guide 2025

Amazon ECR (Elastic Container Registry) is a fully-managed container image registry that allows you to store, manage, and deploy Docker container images.

Repository Types

Amazon ECR offers two types of repositories to meet different use cases:

• Private ECR: Store images only accessible to your AWS account
• Public ECR: Share images publicly in the Amazon ECR public gallery

Key Features

Components of Amazon ECR

Registry

Each AWS account is provided with a private Amazon ECR registry. This registry serves as a centralized container image storage space where you can create and manage multiple repositories. It helps organize your images by application, project, or environment, ensuring better isolation and easier image management.

Repository

A repository in Amazon ECR is a logical grouping where you can store Docker and OCI-compliant images. You can create separate repositories for different microservices, teams, or deployment stages (e.g., dev, staging, production). Images within a repository can be versioned using tags like v1.0 or latest, making it easier to track changes and roll back if needed.

Image

A container image contains everything needed to run an application: the code, dependencies, libraries, and runtime. These images can be built locally and pushed to a repository in ECR, from where they can be pulled and run in environments like Amazon ECS or EKS. Each image is identified by tags or digests for version control and traceability.

Authorization Token

Before interacting with a private ECR registry (pushing or pulling images), your Docker client must be authenticated using an authorization token. This token can be generated via the AWS CLI and is valid for 12 hours. It ensures that only trusted users or services have access to your container repositories.

Repository Policy

Repository policies allow you to define who can access and perform actions on a specific ECR repository. These JSON-based policies work alongside IAM and can grant permissions such as read-only access (pull), write access (push), or full administrative control over repository settings. This adds a strong layer of access control.

Lifecycle Policy

Amazon ECR supports lifecycle policies that let you automatically remove outdated, unused, or untagged images. You can configure rules like "keep only the latest 10 images" or "delete untagged images older than 30 days." This helps reduce storage costs and keeps your repositories clean and efficient.

Image Scanning

ECR offers built-in image scanning to detect known software vulnerabilities (CVEs) in your container images. Scanning is integrated with Amazon Inspector, helping you catch security issues early before deploying images into production. It's a crucial feature for teams focused on secure DevOps practices.

Access Control with IAM

Amazon ECR integrates tightly with AWS Identity and Access Management (IAM), allowing you to control access to registries and repositories. You can assign fine-grained permissions to users, groups, or roles, defining exactly who can push images, pull images, or modify repository settings.

Cross-Account & Cross-Region Replication

For multi-team or global deployments, ECR supports automatic image replication across AWS accounts and regions. This increases availability, improves performance for geographically distributed teams, and ensures consistent deployment experiences across environments.

Encryption (KMS)

Amazon ECR automatically encrypts images at rest using AWS Key Management Service (KMS). You can use the AWS-managed key by default or bring your own custom KMS key for enhanced security and compliance. Encryption helps protect sensitive container data throughout its lifecycle.

Amazon ECR Security

Security is a Top Priority at AWS

As a customer, you benefit from a secure, global infrastructure built to meet the strict requirements of the most security-sensitive organizations. This includes physical security of data centers, secure network design, and continuous monitoring.

Shared Responsibility Model

AWS uses the Shared Responsibility Model, which divides security roles between AWS and the customer. Understanding this model is critical to securing your applications and infrastructure in the cloud.

Security of the Cloud - AWS's Responsibility

AWS is responsible for protecting the cloud infrastructure, which includes the physical facilities, hardware, software, networking, and operations of AWS services. This means AWS ensures that the platform hosting Amazon ECR is secure and compliant. Third-party audits and certifications are regularly conducted to maintain high standards of security.

Security in the Cloud - Your Responsibility

As an AWS customer, you are responsible for managing the security of your Amazon ECR usage. This includes setting up permissions, managing access control, encrypting data when needed. The level of responsibility depends on how you configure and use the service.

Applying the Shared Responsibility Model to ECR

When using Amazon ECR, it's important to configure the service to align with your organization's security and compliance needs. This includes defining IAM policies, enabling image scanning, managing repository access, and applying lifecycle rules to prevent the accumulation of outdated images.

Leverage AWS Security Services with ECR

AWS provides several additional services that you can integrate with Amazon ECR to enhance its security:

• AWS Identity and Access Management (IAM): Define who can access your ECR repositories and what actions they can perform
• Amazon Inspector: Automatically scan container images in ECR for known vulnerabilities
• AWS CloudTrail: Log all API actions taken on your ECR resources for auditing and compliance
• Amazon CloudWatch: Monitor usage metrics and set alarms for unusual or unauthorized activity
• AWS Key Management Service (KMS): Encrypt container images stored in ECR at rest using managed or custom encryption keys

Achieve Compliance Using AWS Best Practices

By combining proper ECR configuration with AWS security tools and compliance programs, you can meet a wide range of regulatory and internal requirements whether it's SOC, HIPAA, ISO 27001, or others.

Amazon ECR Pricing

Best Practices

Repository Management

• Organize by Purpose: Create separate repositories for different applications, environments, or teams
• Use Meaningful Tags: Implement consistent tagging strategies (e.g., semantic versioning, environment tags)
• Implement Lifecycle Policies: Automatically clean up old or unused images to manage costs

Security Best Practices

• Enable Image Scanning: Regularly scan images for vulnerabilities before deployment
• Use IAM Policies: Implement least-privilege access controls
• Enable Encryption: Use KMS encryption for sensitive container images
• Monitor Access: Use CloudTrail to audit repository access and actions

Cost Optimization

• Leverage Free Tier: Take advantage of the 500MB free tier for private repositories
• Use Public Repositories: For open-source projects, consider public repositories to avoid storage costs
• Implement Lifecycle Policies: Automatically remove outdated images to reduce storage costs
• Monitor Data Transfer: Be aware of data transfer costs when pulling images across regions

Integration Tips

• ECS/EKS Integration: Use ECR with Amazon ECS or EKS for seamless container deployment
• CI/CD Integration: Integrate ECR with your CI/CD pipelines for automated image builds and deployments
• Cross-Region Replication: Set up replication for global deployments and disaster recovery

Common Use Cases

Development Workflows

• Store different versions of application images
• Maintain separate repositories for different microservices
• Implement blue-green deployment strategies

Security and Compliance

• Scan images for vulnerabilities before production deployment
• Maintain audit trails of image access and modifications
• Encrypt sensitive application images

Multi-Environment Deployments

• Replicate images across regions for global applications
• Share images across AWS accounts for multi-team environments
• Implement staging and production image promotion workflows

Getting Started Commands

Authentication

# Get login token and authenticate Docker client
aws ecr get-login-password --region <region> | docker login --username AWS --password-stdin <account-id>.dkr.ecr.<region>.amazonaws.com

Repository Management

# Create repository
aws ecr create-repository --repository-name <repo-name>

# List repositories
aws ecr describe-repositories

Image Operations

# Tag image for ECR
docker tag <local-image> <account-id>.dkr.ecr.<region>.amazonaws.com/<repo-name>:<tag>

# Push image to ECR
docker push <account-id>.dkr.ecr.<region>.amazonaws.com/<repo-name>:<tag>

# Pull image from ECR
docker pull <account-id>.dkr.ecr.<region>.amazonaws.com/<repo-name>:<tag>

References

• Components of Amazon ECR
• Shared Responsibility Model
• ECR Pricing