Comprehensive Guide to AWS ECR (Elastic Container Registry)

Introduction

In this blog, we will explore AWS Elastic Container Registry (ECR), a fully managed container image registry service from Amazon Web Services. We’ll cover the fundamental concepts of ECR and provide a practical, step-by-step guide to using it effectively, from setting up a repository to pushing and pulling Docker images. Let’s dive in!

Table of Contents

1. What is AWS ECR?
2. Key Benefits of ECR
3. Getting Started with AWS ECR
   • Creating an ECR Repository
   • Installing AWS CLI
   • Configuring AWS CLI
4. Pushing Docker Images to ECR
5. Pulling Docker Images from ECR
6. Working with ECR Image Scanning
7. Implementing ECR Lifecycle Policies
8. ECR Integration with AWS Services
9. ECR Best Practices
10. Troubleshooting Common Issues
11. ECR Pricing Overview
12. Cleaning Up Resources
13. Conclusion

1. What is AWS ECR?

AWS Elastic Container Registry (ECR) is a fully managed container image registry service provided by Amazon Web Services (AWS). It allows developers to store, manage, and deploy Docker container images securely and efficiently. ECR is designed to integrate seamlessly with other AWS services, such as Amazon Elastic Container Service (ECS) and Amazon Elastic Kubernetes Service (EKS), making it a key service in a containerized application workflow.

By using ECR, you can easily store your Docker images and make them available for deployment to ECS or EKS clusters. ECR also ensures that your container images are highly available and can be accessed from anywhere in the world.

ECR consists of two main offerings:

• Private repositories: Secure storage for your proprietary container images
• Public repositories: Through Amazon ECR Public Gallery, allowing you to share and discover container images

2. Key Benefits of ECR

AWS ECR provides several advantages that make it a go-to solution for managing Docker container images:

• Security: ECR ensures your images are secure by offering encryption at rest and private repositories by default. Only authorized users can access the images, ensuring data privacy and security. ECR also integrates with AWS Identity and Access Management (IAM) for fine-grained access control.

• Integration: ECR integrates smoothly with other AWS services like ECS, EKS, and AWS Fargate. This seamless integration allows you to deploy your containers with ease and manage them effectively.

• Scalability: Being a fully managed service, ECR scales automatically to accommodate growing container image storage needs without manual intervention.

• Availability: ECR guarantees high availability, so your images are accessible at any time without worrying about downtime during critical deployments.

• Lifecycle Policies: ECR allows you to set lifecycle policies to manage your container images. These policies help in automating the cleanup of unused or old images, ensuring cost-effective storage management.

• Image Scanning: ECR provides built-in vulnerability scanning to identify security issues in your container images, helping you maintain a secure environment.

• Cross-Region and Cross-Account Replication: ECR supports replicating your container images across AWS regions and accounts, enhancing disaster recovery and availability.

Layman Example: Think of ECR as a cloud-based “warehouse” where you store your Docker containers (like products). You don’t need to worry about maintaining the warehouse, its security, or availability—AWS does that for you. You can set rules for automatic “restocking” (pushing new images) and “cleaning out old inventory” (lifecycle policies), and it seamlessly connects with your “delivery system” (ECS/EKS).

3. Getting Started with AWS ECR

Let’s go over how to get started with AWS ECR.

Creating an ECR Repository

1. Open the AWS Management Console.
2. Navigate to the Amazon ECR service by typing “ECR” in the search bar.
3. Click on Create repository.
4. Enter a unique name for your repository.
5. Optionally, enable image scanning on push (which scans images for vulnerabilities).
6. You can also add tags to help organize your repositories.
7. Click Create repository to finish.

Now you’ve got your own repository to store Docker images.

Example Repository Creation with AWS CLI:

If you prefer using the CLI, you can create a repository with the following command:

aws ecr create-repository \
    --repository-name my-application \
    --image-scanning-configuration scanOnPush=true \
    --region us-east-1

This command creates a new repository named “my-application” with scan-on-push enabled in the us-east-1 region.

Installing AWS CLI

To interact with ECR from your local machine, you need the AWS CLI installed. Follow these instructions to install it:

1. For Windows, macOS, or Linux, you can follow the instructions in the AWS CLI User Guide.

2. Once installed, you can check if it’s working by running:

   aws --version
   

This will return the version of the AWS CLI installed, confirming that it’s ready for use.

Configuring AWS CLI

Once AWS CLI is installed, you need to configure it with your AWS credentials:

1. Open your terminal (or command prompt) and run:

   aws configure
   

2. You’ll be prompted to enter your AWS Access Key ID, Secret Access Key, default region, and preferred output format (e.g., JSON). You can find your access keys in the AWS Management Console under IAM (Identity and Access Management).

Example Configuration:

AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE
AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Default region name [None]: us-east-1
Default output format [None]: json

Best Practice: Instead of using your root AWS account credentials, create an IAM user with appropriate permissions and use those credentials.

4. Pushing Docker Images to ECR

After setting up your ECR repository and configuring the AWS CLI, you can push Docker images to your repository.

Step 1: Build your Docker image locally

First, create a Docker image by running the following command in your project directory (where the Dockerfile is located):

docker build -t my-application:latest .

This command builds the Docker image with the name “my-application” and the tag “latest” using the Dockerfile in the current directory.

Example Dockerfile:

FROM node:14-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 3000
CMD ["npm", "start"]

This is a simple Dockerfile for a Node.js application.

Step 2: Tag the image for ECR

Once the image is built, you need to tag it with the URI of your ECR repository:

aws_account_id=$(aws sts get-caller-identity --query Account --output text)
region=$(aws configure get region)
ecr_repo_uri=$aws_account_id.dkr.ecr.$region.amazonaws.com/my-application

docker tag my-application:latest $ecr_repo_uri:latest

This script gets your AWS account ID and region automatically, then tags your image with the ECR repository URI.

Step 3: Login to ECR

To push the image, you need to authenticate Docker with ECR:

aws ecr get-login-password --region $region | docker login --username AWS --password-stdin $aws_account_id.dkr.ecr.$region.amazonaws.com

This command retrieves a temporary password from AWS and logs in to the ECR registry.

Step 4: Push the image to ECR

Now that you’re logged in, you can push your image to the ECR repository:

docker push $ecr_repo_uri:latest

This command uploads the Docker image to the ECR repository, making it available for use in ECS, EKS, or other AWS services.

Example Complete Push Script:

Here’s a complete bash script for building, tagging, and pushing a Docker image to ECR:

#!/bin/bash
# Set variables
image_name="my-application"
tag="latest"
aws_account_id=$(aws sts get-caller-identity --query Account --output text)
region=$(aws configure get region)
ecr_repo_uri=$aws_account_id.dkr.ecr.$region.amazonaws.com/$image_name

# Build the image
echo "Building Docker image..."
docker build -t $image_name:$tag .

# Tag the image for ECR
echo "Tagging image for ECR..."
docker tag $image_name:$tag $ecr_repo_uri:$tag

# Login to ECR
echo "Logging in to ECR..."
aws ecr get-login-password --region $region | docker login --username AWS --password-stdin $aws_account_id.dkr.ecr.$region.amazonaws.com

# Push to ECR
echo "Pushing image to ECR..."
docker push $ecr_repo_uri:$tag

echo "Image pushed successfully to $ecr_repo_uri:$tag"

You can save this as push-to-ecr.sh, make it executable with chmod +x push-to-ecr.sh, and run it when you want to update your ECR repository.

5. Pulling Docker Images from ECR

To use Docker images stored in ECR on other systems or services:

1. First, authenticate Docker to access your ECR registry:

aws ecr get-login-password --region $region | docker login --username AWS --password-stdin $aws_account_id.dkr.ecr.$region.amazonaws.com

2. Then, use the following command to pull an image:

docker pull $aws_account_id.dkr.ecr.$region.amazonaws.com/my-application:latest

This command downloads the image from ECR to your local machine, where you can then run it using Docker.

Example: Running the Pulled Image:

docker run -p 3000:3000 $aws_account_id.dkr.ecr.$region.amazonaws.com/my-application:latest

This command runs the container and maps port 3000 from the container to port 3000 on your local machine.

6. Working with ECR Image Scanning

ECR offers built-in vulnerability scanning for your container images, helping you identify potential security issues.

Enabling Vulnerability Scanning

You can enable scanning in two ways:

1. Scan on Push: Images are automatically scanned when pushed to the repository.
2. Manual Scanning: Scan images as needed.

To enable Scan on Push for a new repository:

aws ecr create-repository \
    --repository-name my-application \
    --image-scanning-configuration scanOnPush=true \
    --region us-east-1

To enable Scan on Push for an existing repository:

aws ecr put-image-scanning-configuration \
    --repository-name my-application \
    --image-scanning-configuration scanOnPush=true \
    --region us-east-1

Starting a Manual Scan

aws ecr start-image-scan \
    --repository-name my-application \
    --image-id imageTag=latest \
    --region us-east-1

Viewing Scan Results

To view scan results for an image:

aws ecr describe-image-scan-findings \
    --repository-name my-application \
    --image-id imageTag=latest \
    --region us-east-1

This returns a list of vulnerabilities found in the image, including severity levels and possible remediation steps.

7. Implementing ECR Lifecycle Policies

Lifecycle policies help you manage the lifecycle of images in your ECR repositories, automating the cleanup of unused or old images.

Creating a Lifecycle Policy

Here’s an example of a lifecycle policy that keeps only the 10 most recent images and deletes images older than 90 days:

{
  "rules": [
    {
      "rulePriority": 1,
      "description": "Keep only 10 images",
      "selection": {
        "tagStatus": "any",
        "countType": "imageCountMoreThan",
        "countNumber": 10
      },
      "action": {
        "type": "expire"
      }
    },
    {
      "rulePriority": 2,
      "description": "Expire images older than 90 days",
      "selection": {
        "tagStatus": "any",
        "countType": "sinceImagePushed",
        "countUnit": "days",
        "countNumber": 90
      },
      "action": {
        "type": "expire"
      }
    }
  ]
}

Save this JSON to a file named lifecycle-policy.json, then apply it to your repository:

aws ecr put-lifecycle-policy \
    --repository-name my-application \
    --lifecycle-policy-text file://lifecycle-policy.json \
    --region us-east-1

Viewing Lifecycle Policies

To view the lifecycle policy for a repository:

aws ecr get-lifecycle-policy \
    --repository-name my-application \
    --region us-east-1

Testing Lifecycle Policies

You can test how a lifecycle policy would affect your repository without actually deleting any images:

aws ecr get-lifecycle-policy-preview \
    --repository-name my-application \
    --region us-east-1

8. ECR Integration with AWS Services

ECR is designed to work seamlessly with other AWS services. Let’s see how it integrates with some key services:

Integration with Amazon ECS

1. Create an ECS Task Definition that references your ECR image:

{
  "family": "my-application",
  "executionRoleArn": "arn:aws:iam::123456789012:role/ecsTaskExecutionRole",
  "containerDefinitions": [
    {
      "name": "my-application",
      "image": "123456789012.dkr.ecr.us-east-1.amazonaws.com/my-application:latest",
      "essential": true,
      "portMappings": [
        {
          "containerPort": 3000,
          "hostPort": 3000
        }
      ]
    }
  ],
  "requiresCompatibilities": ["FARGATE"],
  "networkMode": "awsvpc",
  "cpu": "256",
  "memory": "512"
}

Save this to task-definition.json and register it:

aws ecs register-task-definition --cli-input-json file://task-definition.json

2. Create or update an ECS service to use your task definition:

aws ecs create-service \
    --cluster my-cluster \
    --service-name my-application-service \
    --task-definition my-application:1 \
    --desired-count 1 \
    --launch-type FARGATE \
    --network-configuration "awsvpcConfiguration={subnets=[subnet-12345678],securityGroups=[sg-12345678],assignPublicIp=ENABLED}"

Integration with Amazon EKS

To use ECR images with Amazon EKS, you need to configure your Kubernetes deployment to pull from ECR.

1. Create an IAM role for your EKS nodes with permissions to pull from ECR.

2. Create a Kubernetes deployment manifest that references your ECR image:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-application
spec:
  replicas: 2
  selector:
    matchLabels:
      app: my-application
  template:
    metadata:
      labels:
        app: my-application
    spec:
      containers:
        - name: my-application
          image: 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-application:latest
          ports:
            - containerPort: 3000

Save this to deployment.yaml and apply it:

kubectl apply -f deployment.yaml

Integration with AWS Lambda

With AWS Lambda container image support, you can use ECR images as the deployment package for your Lambda functions.

1. Create a Lambda function using an ECR image:

aws lambda create-function \
    --function-name my-lambda-function \
    --package-type Image \
    --code ImageUri=123456789012.dkr.ecr.us-east-1.amazonaws.com/my-application:latest \
    --role arn:aws:iam::123456789012:role/lambda-ex

9. ECR Best Practices

Following are some best practices to make the most of AWS ECR:

Security Best Practices

• Use IAM roles with least privilege: Only grant the necessary permissions to users and roles that need to interact with ECR.
• Enable scan on push: Automatically scan images for vulnerabilities when they’re pushed to the repository.
• Implement resource-based policies: Control who can access your ECR repositories with specific policies.
• Use immutable tags: Consider enforcing immutable tags to prevent images from being overwritten.

Operational Best Practices

• Implement consistent tagging strategy: Use meaningful and consistent tags for your images (e.g., semantic versioning or build IDs).
• Use lifecycle policies: Automatically clean up old or unused images to manage costs.
• Cross-region replication: For mission-critical applications, replicate your images across regions for disaster recovery.
• Regular vulnerability scanning: Scan your images regularly, not just at push time.
• Use Docker layer caching: Structure your Dockerfiles to take advantage of layer caching for faster builds.

Cost Optimization

• Delete unused images: Use lifecycle policies to remove unused images to reduce storage costs.
• Use appropriate image sizes: Optimize your Docker images to be as small as possible.
• Consider public repositories: If you’re distributing open-source software, use ECR Public Gallery to avoid data transfer costs.

10. Troubleshooting Common Issues

Here are some common issues you might encounter when working with ECR and how to resolve them:

Authentication Issues

Issue: Error response from daemon: Get "https://123456789012.dkr.ecr.us-east-1.amazonaws.com/v2/": unauthorized: authentication required

Solution:

• Your Docker login may have expired. ECR authentication tokens are valid for 12 hours.
• Run the login command again:

  aws ecr get-login-password --region $region | docker login --username AWS --password-stdin $aws_account_id.dkr.ecr.$region.amazonaws.com
  

Permission Issues

Issue: An error occurred (AccessDeniedException) when calling the GetAuthorizationToken operation: User is not authorized to perform: ecr:GetAuthorizationToken

Solution:

• The IAM user or role doesn’t have the necessary permissions.
• Attach the AmazonECR-FullAccess policy or a custom policy with the required permissions.

Rate Limiting

Issue: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit

Solution:

• This is a Docker Hub issue, not an ECR issue.
• Use ECR as your primary registry to avoid Docker Hub rate limits.

Image Not Found

Issue: Error response from daemon: manifest for 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-application:latest not found: manifest unknown

Solution:

• Verify that the image exists in your ECR repository.
• Check the tag and repository name for typos.
• Ensure you’re using the correct AWS region.

11. ECR Pricing Overview

Understanding ECR pricing helps you optimize costs:

Storage Costs

• First 50 TB per month: $0.10 per GB
• Next 450 TB per month: $0.09 per GB
• Over 500 TB per month: $0.08 per GB

Data Transfer

• Inbound data transfer (Internet/AWS regions): Free
• Outbound to same region: Free
• Outbound to other AWS regions: $0.01 per GB
• Outbound to Internet: Standard AWS data transfer rates

API Requests

• $0.01 per 1,000 PUT, COPY, POST, or LIST requests
• $0.01 per 10,000 GET and other requests

Cost Optimization Tips:

• Use lifecycle policies to automatically clean up unused images.
• Optimize your Docker images to be as small as possible.
• Consider multi-stage builds to reduce final image size.
• For development environments, consider pulling images once and sharing them locally rather than having each developer pull separately.

12. Cleaning Up Resources

When you’re done using resources, it’s important to clean up to avoid unnecessary costs.

Deleting Images from a Repository

To delete specific images:

aws ecr batch-delete-image \
    --repository-name my-application \
    --image-ids imageTag=latest \
    --region us-east-1

Deleting an ECR Repository

To delete a repository:

1. Ensure there are no images in the repository, or delete them using the command above.
2. Delete the repository:

aws ecr delete-repository \
    --repository-name my-application \
    --force \
    --region us-east-1

The --force flag allows you to delete the repository even if it contains images.

By cleaning up resources, you ensure that your AWS account remains cost-effective and free of unused data.

13. Conclusion

AWS ECR is an essential service for developers using containers. It provides a secure, scalable, and highly available solution for storing and managing Docker images. In this blog, we covered how to create an ECR repository, push and pull Docker images, implement security and lifecycle policies, and integrate with other AWS services.

ECR’s seamless integration with AWS services like ECS, EKS, and Lambda makes it a cornerstone for containerized applications in the AWS ecosystem. By following the best practices and leveraging the features covered in this guide, you can ensure that your container images are securely stored, efficiently managed, and readily available for deployment.

With the steps provided, you’re now ready to integrate ECR into your containerized application workflow and streamline the deployment of your containers on AWS services.

Additional Resources

• AWS ECR User Guide
• ECR API Reference
• Docker Documentation
• AWS Container Services Overview