Amazon ECR Technical Reference

Configuration Requirements

Authentication Setup

• Command: aws ecr get-login-password --region us-west-2 | docker login --username AWS --password-stdin 123456789.dkr.ecr.us-west-2.amazonaws.com
• Failure Point: Docker Desktop 4.15.0+ breaks ECR credential helper randomly
• Error Symptom: "Error saving credentials: The stub received bad data"
• Solution: Restart Docker Desktop
• Token Expiration: AWS credentials expire after 12 hours maximum

IAM Permission Requirements

• EKS Nodes: Must have AmazonEC2ContainerRegistryReadOnly policy attached to instance role
• Missing Policy Symptom: Pods stuck in ImagePullBackOff state for 45+ minutes
• Error Message: "Failed to pull image: rpc error: code = Unknown desc = Error response from daemon: pull access denied"

Repository Management

• Critical Difference: ECR repositories must be created before first push (unlike Docker Hub auto-creation)
• Creation Command: aws ecr create-repository --repository-name my-app
• Case Sensitivity: Repository names are case-sensitive

Resource Requirements and Costs

Pricing Structure

• Storage: ~$0.10/GB/month
• Data Transfer: ~$0.09/GB outbound
• Cross-Region Replication: $27/month for 100GB across 3 regions
• Free Tier: 500MB storage for 12 months (new accounts only)
• Reality Check: Budget minimum $50/month for microservices architecture

Performance Thresholds

• Large Images: 20GB+ models cause significant upload/startup delays
• Cross-Region Impact: Pulling from us-east-1 to eu-west-1 causes 5+ minute pod start times
• Concurrent Operations: Handles multiple operations until hitting internet bandwidth limits

Critical Warnings and Failure Modes

Lifecycle Policy Disasters

• Risk: JSON policies can delete production images without warning
• Common Failure: Policies delete tagged production images that are 30+ days old
• Prevention: Tag production images with prod- prefix and exclude from cleanup
• Impact: 4-hour production outages when images are unavailable

Vulnerability Scanner Reality

• Behavior: Flags every OpenSSL version from the last decade
• Base Image Problem: Reports unfixable vulnerabilities in Alpine/Node base images
• Security Theater: Most alerts are not exploitable in container context
• Recommendation: Filter by severity, ignore noise

Network Configuration Issues

• CodeBuild VPC Problem: Requires NAT gateways or VPC endpoints to reach ECR
• Error Message: "dial tcp: lookup 123456789.dkr.ecr.us-west-2.amazonaws.com: no such host"
• Solution Time: Plan full weekend for VPC networking configuration

Implementation Specifications

Image Constraints

• Layer Size: Maximum 52,000 MiB (~51GB) per layer
• Total Size: Practically unlimited but impacts performance
• Immutability: Enable on production repositories to prevent latest overwrites

Replication Configuration

• Cross-Region: Available but expensive due to data transfer charges
• Cache Refresh: Not automatic, requires manual policy configuration
• Pull-Through Cache: Bypasses Docker Hub rate limits (100 pulls/6 hours)

Integration Requirements

• EKS: Smooth integration once IAM is configured correctly
• CodeBuild: Works in VPC with proper networking setup
• Kubernetes External: Requires AWS credentials via IRSA or IAM users

Operational Patterns

Migration Complexity

• Time Investment: 6 hours for 200+ images, 14 hours for CI/CD pipeline updates
• Process: Re-tag all images, update deployment configurations
• Breaking Changes: All CI/CD workflows require modification

Troubleshooting Common Issues

• "no basic auth credentials": Re-authenticate or check credential expiration
• ImagePullBackOff: Usually IAM permissions, check node group policies
• Repository not found: Create repository first, ECR doesn't auto-create
• Replication failures: Verify configuration filters and naming conventions

Decision Criteria

When to Choose ECR

• Positive: Already using AWS services (EKS, ECS, CodeBuild)
• Positive: Need vulnerability scanning integration
• Positive: Require cross-region replication

When to Avoid ECR

• Negative: Cloud-agnostic architecture requirements
• Negative: Simple containerization needs
• Negative: Team lacks AWS IAM expertise
• Negative: Cost sensitivity for storage-heavy workloads

Comparison Matrix

Registry	Hosting	Monthly Cost (est.)	Auth Complexity	Production Ready
ECR	AWS Managed	$50+	High (IAM hell)	Yes
Docker Hub	Docker Managed	$7/repo	Low	Yes (with rate limits)
Harbor	Self-hosted	Infrastructure costs	Medium	Yes
GCR	Google Managed	$26/100GB	Medium	Yes
ACR	Azure Managed	$167/100GB	Medium	Yes

Critical Commands

# Authentication (run every 12 hours)
aws ecr get-login-password --region us-west-2 | docker login --username AWS --password-stdin 123456789.dkr.ecr.us-west-2.amazonaws.com

# Repository creation (required before first push)
aws ecr create-repository --repository-name my-app

# Image tagging for migration
docker tag old-image:latest 123456789.dkr.ecr.us-west-2.amazonaws.com/new-repo:latest

# Troubleshooting authentication
docker system prune -a  # Clear Docker cache
systemctl restart docker  # Linux Docker restart

Resource Documentation Priority

1. ECR User Guide: Comprehensive but dry documentation
2. IAM Service Integration: Essential for understanding permissions
3. Lifecycle Policy Examples: Critical for preventing image deletion disasters
4. EKS Workshop: Focus on ECR-specific sections only
5. Terraform ECR Provider: Infrastructure-as-code implementation
6. GitHub Actions ECR: CI/CD integration patterns

Implementation Checklist

• Create repositories before first push
• Configure IAM policies for EKS nodes
• Set up lifecycle policies with production exclusions
• Enable vulnerability scanning (prepare to ignore base image CVEs)
• Configure pull-through cache for Docker Hub rate limit mitigation
• Set up cross-region replication if required
• Test authentication process across all environments
• Budget for data transfer costs in multi-region setups