---

name: aws-ecr compatibility: opencode completeness: 95 content-types:

• guidance
• examples
• do-dont
• config description: '"Manages container image repositories with ECR for secure storage, scanning" replication, and integration with EKS, ECS, and Lambda for container deployments.' license: MIT maturity: stable metadata: domain: cncf output-format: manifests related-skills: aws-eks, aws-iam, aws-kms, cubefs role: reference scope: infrastructure triggers: container registry, container security, containers, docker images, ecr, image repository, image scanning, vulnerability scanning archetypes:
  • educational
  • strategic anti_triggers:
  • brainstorming
  • vague ideation
  • non-containerized architecture response_profile: verbosity: medium directive_strength: low abstraction_level: strategic version: "1.0.0"

---

ECR (Elastic Container Registry)

Manage container images securely with vulnerability scanning, lifecycle policies, replication, and integration with container orchestration services.

TL;DR Checklist

• Enable image scanning for vulnerability detection
• Configure lifecycle policies to manage image versions
• Use image tags for versioning (not latest)
• Enable cross-region replication for disaster recovery
• Implement pull-through cache for upstream registries
• Encrypt images at rest with KMS
• Use repository policies to control access
• Monitor image push/pull with CloudTrail
• Set up resource cleanup for untagged images
• Implement image signing for integrity verification

---

When to Use

Use ECR when:

• Running container workloads on AWS (ECS, EKS, Lambda)
• Needing private container registry
• Requiring vulnerability scanning
• Building CI/CD pipelines with containers
• Needing image lifecycle management

---

When NOT to Use

Avoid ECR for:

• Public open-source images (Docker Hub is fine)
• Non-AWS container deployments (use Docker Hub, Quay)

---

Purpose and Use Cases

Primary Purpose: Provide secure, managed container image registry with vulnerability scanning, lifecycle management, and AWS service integration.

Common Use Cases:

1. Container Storage — Store application images for ECS/EKS
2. CI/CD Pipelines — Build and push images automatically
3. Vulnerability Scanning — Automatic security assessment
4. Image Replication — Multi-region disaster recovery
5. Access Control — Fine-grained permission management

---

Architecture Design Patterns

Pattern 1: Secure ECR Repository with Scanning

AWSTemplateFormatVersion: '2010-09-09'
Resources:
  # ECR Repository
  ApplicationRepository:
    Type: AWS::ECR::Repository
    Properties:
      RepositoryName: application-images
      EncryptionConfiguration:
        EncryptionType: KMS
        KmsKey: !GetAtt RepositoryEncryptionKey.Arn
      ImageScanningConfiguration:
        ScanOnPush: true
      LifecyclePolicy:
        LifecyclePolicyText: |
          {
            "rules": [
              {
                "rulePriority": 1,
                "description": "Keep last 10 images tagged, expire untagged",
                "selection": {
                  "tagStatus": "tagged",
                  "tagPrefixList": ["v"],
                  "countType": "imageCountMoreThan",
                  "countNumber": 10
                },
                "action": {
                  "type": "expire"
                }
              },
              {
                "rulePriority": 2,
                "description": "Expire untagged images after 7 days",
                "selection": {
                  "tagStatus": "untagged",
                  "countType": "sinceImagePushed",
                  "countUnit": "days",
                  "countNumber": 7
                },
                "action": {
                  "type": "expire"
                }
              }
            ]
          }
      RepositoryPolicyText:
        Version: '2012-10-17'
        Statement:
          - Sid: AllowECSTaskPull
            Effect: Allow
            Principal:
              AWS: arn:aws:iam::123456789012:role/ecsTaskRole
            Action:
              - ecr:GetAuthorizationToken
              - ecr:GetDownloadUrlForLayer
              - ecr:BatchGetImage
              - ecr:BatchCheckLayerAvailability
          - Sid: AllowEKSNodesPull
            Effect: Allow
            Principal:
              AWS: arn:aws:iam::123456789012:role/nodeGroupRole
            Action:
              - ecr:GetAuthorizationToken
              - ecr:GetDownloadUrlForLayer
              - ecr:BatchGetImage
              - ecr:BatchCheckLayerAvailability
          - Sid: DenyUnencryptedTransport
            Effect: Deny
            Principal: '*'
            Action: 'ecr:*'
            Condition:
              Bool:
                aws:SecureTransport: 'false'
      Tags:
        - Key: Application
          Value: main

  # KMS Key for Image Encryption
  RepositoryEncryptionKey:
    Type: AWS::KMS::Key
    Properties:
      Description: KMS key for ECR repository encryption
      KeyPolicy:
        Version: '2012-10-17'
        Statement:
          - Sid: Enable IAM User Permissions
            Effect: Allow
            Principal:
              AWS: !Sub 'arn:aws:iam::${AWS::AccountId}:root'
            Action: 'kms:*'
            Resource: '*'
          - Sid: Allow ECR to use key
            Effect: Allow
            Principal:
              Service: ecr.amazonaws.com
            Action:
              - 'kms:Decrypt'
              - 'kms:GenerateDataKey'
            Resource: '*'

  # ECR Lifecycle Policy for Cleanup
  ImageCleanupFunction:
    Type: AWS::Lambda::Function
    Properties:
      FunctionName: ecr-image-cleanup
      Runtime: python3.11
      Handler: index.handler
      Role: !GetAtt CleanupRole.Arn
      Code:
        ZipFile: |
          import boto3
          import json
          from datetime import datetime, timedelta
          
          ecr = boto3.client('ecr')
          
          def handler(event, context):
              repo_name = 'application-images'
              max_age_days = 30
              
              # List images
              response = ecr.list_images(repositoryName=repo_name)
              
              to_delete = []
              for image in response.get('imageIds', []):
                  if 'imageTag' not in image:  # Untagged
                      image_detail = ecr.describe_images(
                          repositoryName=repo_name,
                          imageIds=[image]
                      )
                      push_time = image_detail['imageDetails'][0]['imagePushedAt']
                      age = datetime.now(push_time.tzinfo) - push_time
                      
                      if age > timedelta(days=max_age_days):
                          to_delete.append(image)
              
              if to_delete:
                  ecr.batch_delete_image(
                      repositoryName=repo_name,
                      imageIds=to_delete
                  )
              
              return {
                  'statusCode': 200,
                  'deleted': len(to_delete)
              }

  CleanupRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: '2012-10-17'
        Statement:
          - Effect: Allow
            Principal:
              Service: lambda.amazonaws.com
            Action: sts:AssumeRole
      ManagedPolicyArns:
        - arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
      Policies:
        - PolicyName: ECRAccess
          PolicyDocument:
            Version: '2012-10-17'
            Statement:
              - Effect: Allow
                Action:
                  - ecr:ListImages
                  - ecr:DescribeImages
                  - ecr:BatchDeleteImage
                Resource: !GetAtt ApplicationRepository.RepositoryUri

  # CloudWatch Alarms
  ScanFailuresAlarm:
    Type: AWS::CloudWatch::Alarm
    Properties:
      AlarmName: ecr-scan-failures
      MetricName: ImageScanFailures
      Namespace: AWS/ECR
      Statistic: Sum
      Period: 3600
      EvaluationPeriods: 1
      Threshold: 1
      ComparisonOperator: GreaterThanOrEqualToThreshold
      Dimensions:
        - Name: RepositoryName
          Value: !Ref ApplicationRepository

Outputs:
  RepositoryUri:
    Value: !GetAtt ApplicationRepository.RepositoryUri
    Description: ECR repository URI
  RepositoryName:
    Value: !Ref ApplicationRepository
    Description: ECR repository name

Key Elements:

• ECR repository with KMS encryption
• Image scanning enabled on push
• Lifecycle policy for version management
• Repository policy for fine-grained access
• Lambda for automated cleanup
• CloudWatch alarms for scan failures

Pattern 2: Cross-Region Replication

Resources:
  # Replication Configuration
  RegistryReplicationConfig:
    Type: AWS::ECR::RegistryReplicationConfig
    Properties:
      Rules:
        - Destinations:
            - Region: eu-west-1
              RegistryId: !Ref 'AWS::AccountId'
            - Region: ap-southeast-1
              RegistryId: !Ref 'AWS::AccountId'
          RepositoryFilters:
            - Filter: PREFIX_LIST
              FilterValue:
                - prod
          Destinations:
            - Region: eu-west-1
              RegistryId: !Ref 'AWS::AccountId'
            - Region: ap-southeast-1
              RegistryId: !Ref 'AWS::AccountId'

Key Elements:

• Automatic replication to secondary regions
• Disaster recovery for container images
• All regions stay in sync

---

Integration Approaches

1. Integration with ECS

ECR + ECS enables:

• Task definitions pull images from ECR
• No credentials needed (IAM roles)
• Automatic image updates

2. Integration with EKS

ECR + EKS enables:

• Pods pull images from ECR
• IRSA for access without credentials
• Multi-region replication for HA

3. Integration with CodePipeline

CodePipeline + ECR enables:

• CI/CD automated image builds
• Image scanning in pipeline
• Deployment to production

4. Integration with Lambda

Lambda + ECR enables:

• Container images for Lambda functions
• Vulnerability scanning
• Secure image storage

---

Common Pitfalls

❌ Pitfall 1: No Image Tagging Strategy

Problem: Cannot track versions; hard to rollback.

Solution:

• Tag with semantic versioning (v1.0.0)
• Tag with commit SHA for traceability
• Never use 'latest' in production

❌ Pitfall 2: Unbounded Image Growth

Problem: Repository grows indefinitely; storage costs.

Solution:

• Implement lifecycle policies
• Expire untagged images (7-30 days)
• Limit tagged image count (keep last N)

❌ Pitfall 3: No Vulnerability Scanning

Problem: Deploy vulnerable images; security breaches.

Solution:

• Enable image scanning on push
• Block deployment of high-severity images
• Regular scans of existing images

❌ Pitfall 4: No Encryption

Problem: Images stored unencrypted; data exposure risk.

Solution:

• Enable KMS encryption at rest
• Use customer-managed keys
• Enforce secure transport

❌ Pitfall 5: Overly Permissive Repository Policy

Problem: Unauthorized users can pull/push images.

Solution:

• Use least-privilege repository policies
• Separate policies for pull vs. push
• Audit access via CloudTrail

---

Best Practices Summary

Category	Best Practice
Tagging	Semantic versioning; commit SHA; no 'latest'
Scanning	Enable on push; block high-severity
Cleanup	Lifecycle policies; regular maintenance
Security	KMS encryption; secure transport only
Replication	Multi-region for disaster recovery

---

Related Skills

Skill	Purpose
cncf-aws-eks	Container orchestration with images
cncf-aws-iam	Repository access control
cncf-aws-kms	Image encryption

---

Core Workflow

1. Assess Requirements — Understand the use case, scale, integration needs, and existing infrastructure. Checkpoint: Document requirements, constraints, and success criteria.

2. Design Architecture — Plan component interactions, data flow, and deployment strategy using cloud-native best practices. Checkpoint: Verify the architecture addresses all requirements and follows CNCF conventions.

3. Implement & Configure — Create manifests, configurations, and deployment scripts. Include resource limits, health checks, and observability hooks. Checkpoint: Validate all YAML against schema and test in a staging environment.

4. Deploy & Monitor — Apply manifests to the cluster, verify component health, and confirm observability is working. Checkpoint: Confirm all pods/services are running, probes passing, and metrics/alerts configured.

---

Constraints

MUST DO

• Include at least one complete working YAML manifest example
• Note when content is auto-generated vs. manually verified
• Reference relevant CNCF project documentation

MUST NOT DO

• Deploy manifests without testing in a staging environment first
• Use deprecated API versions (e.g., apps/v1beta1)
• Omit resource limits and requests in Kubernetes manifests

---

Live References

Authoritative documentation links for this skill's domain. The model follows markdown links at load time to resolve external references and inline content.

• Primary Documentation
• API Reference or Getting Started
• Configuration Guide
• Best Practices
• Common Patterns or Tutorials