Migrate Docker Hub Images to Amazon ECR (Elastic Container Registry)

Hey there, Darian Vance here. As a Senior DevOps Engineer at TechResolve, I’ve seen my fair share of CI/CD pipelines. One of the biggest bottlenecks I used to face was our reliance on public Docker Hub images. I’ll never forget the Monday morning our entire build farm ground to a halt because we hit an anonymous pull limit. That was the catalyst. Moving our critical base images to a private, managed registry like Amazon ECR wasn’t just a nice-to-have; it became essential for our stability and security. It puts us in control.

This guide is the lean, no-fluff workflow I’ve developed to migrate and sync images. Let’s get this done so you can get back to building.

Prerequisites

Before we start, make sure you have the following ready to go:

• An AWS Account with IAM permissions to manage ECR repositories and get authentication tokens. Specifically, you’ll need policies like AmazonEC2ContainerRegistryFullAccess or a more granular custom policy.
• A Docker Hub Account, especially if you need to pull private images.
• AWS CLI installed and configured on your machine (run aws configure).
• Docker Engine installed and running locally.
• Python 3. I’ll use a simple Python script to automate the process. You’ll also need the Boto3 library, which you can typically install by running pip install boto3 in your terminal.

The Step-by-Step Guide

Step 1: Create Your ECR Repository

First things first, you need a home for your images in AWS. You can do this via the AWS Console, CLI, or an Infrastructure as Code tool. For simplicity, let’s use the console.

1. Navigate to the Elastic Container Registry (ECR) service in the AWS Console.
2. Click Create repository.
3. Choose your visibility settings (I almost always use Private for internal images).
4. Give it a meaningful name, like project-x/base-api or shared/ubuntu-custom.
5. Important Settings: I highly recommend enabling Tag immutability to prevent image tags from being overwritten. This saves a lot of headaches with versioning. Also, enabling Scan on push is a fantastic, free security feature that checks your images for known vulnerabilities.
6. Click Create repository. That’s it.

Pro Tip: Establish a clear naming convention for your repositories from day one. I use a <team-or-project>/<application> format. It makes IAM policies and general organization much easier to manage as your team grows.

Step 2: Authenticate Docker with Your ECR Registry

Your local Docker client needs to be authenticated with AWS to push images. ECR uses short-lived tokens for this, which is great for security. The easiest way to get one is with the AWS CLI.

Run this command in your terminal. Remember to replace the placeholders with your actual AWS region and account ID.

aws ecr get-login-password --region your-aws-region | docker login --username AWS --password-stdin your-aws-account-id.dkr.ecr.your-aws-region.amazonaws.com

This command fetches a temporary authentication token from ECR and securely pipes it directly to the docker login command. If it succeeds, you’ll see a “Login Succeeded” message. This token is valid for 12 hours.

Step 3: The Migration Script (Python)

Now for the core logic. Manually pulling, tagging, and pushing images is tedious and error-prone. A simple script makes it repeatable and reliable.

I’ll skip the standard virtualenv setup since you likely have your own workflow for that. Just ensure you have the boto3 library available in your Python environment. Let’s jump straight to the Python logic. Save this as something like migrate_images.py.

import subprocess
import boto3

# --- Configuration ---
# Your AWS Account ID and region.
AWS_ACCOUNT_ID = "123456789012"
AWS_REGION = "us-east-1"

# A list of Docker Hub images to migrate.
# Format: ('dockerhub_image:tag', 'ecr_repo_name')
IMAGES_TO_MIGRATE = [
    ('python:3.9-slim-buster', 'base-images/python'),
    ('nginx:1.21-alpine', 'base-images/nginx'),
    # Add any other images you need here
]

# --- Script Logic ---
def run_command(command):
    """A helper function to run shell commands and check for errors."""
    print(f"Executing: {' '.join(command)}")
    result = subprocess.run(command, capture_output=True, text=True)
    if result.returncode != 0:
        print(f"Error executing command: {result.stderr}")
        return False
    print(result.stdout)
    return True

def get_ecr_uri(repo_name):
    """Constructs the full ECR repository URI."""
    return f"{AWS_ACCOUNT_ID}.dkr.ecr.{AWS_REGION}.amazonaws.com/{repo_name}"

def main():
    """Main function to migrate images."""
    print("--- Starting Docker Image Migration to ECR ---")

    # Step 1: Ensure we are authenticated with ECR
    # This assumes you have already run the 'aws ecr get-login-password' command.
    # For a fully automated script, you could use boto3 to get the token.
    
    for dockerhub_image, ecr_repo in IMAGES_TO_MIGRATE:
        print(f"\n--- Processing: {dockerhub_image} ---")
        
        # Step 2: Pull the image from Docker Hub
        if not run_command(['docker', 'pull', dockerhub_image]):
            print(f"Failed to pull {dockerhub_image}. Skipping.")
            continue
            
        # Step 3: Tag the image for ECR
        ecr_uri = get_ecr_uri(ecr_repo)
        tag = dockerhub_image.split(':')[-1] # Extract the tag (e.g., '3.9-slim-buster')
        ecr_image_with_tag = f"{ecr_uri}:{tag}"
        
        if not run_command(['docker', 'tag', dockerhub_image, ecr_image_with_tag]):
            print(f"Failed to tag {dockerhub_image}. Skipping.")
            continue
            
        # Step 4: Push the image to ECR
        if not run_command(['docker', 'push', ecr_image_with_tag]):
            print(f"Failed to push {ecr_image_with_tag}. Skipping.")
            continue
            
        print(f"Successfully migrated {dockerhub_image} to {ecr_image_with_tag}")

    print("\n--- Migration Complete ---")

if __name__ == "__main__":
    main()

To run it, simply execute python3 migrate_images.py from your terminal. The script will pull each image, retag it with your ECR repository URI, and push it up. Simple and effective.

Step 4: Automate It (Optional, but Recommended)

For base images that receive security updates (like Python, Node, etc.), I like to run this script on a schedule to pull in the latest versions. A simple cron job works perfectly for this.

Pro Tip: Before automating, make sure your script is idempotent. For instance, you could use the AWS SDK (Boto3) to check if an image with that specific tag already exists in ECR before attempting to pull and push, saving bandwidth and compute time. For now, since we enabled tag immutability, a re-run will just fail on the push if the tag exists, which is a safe default.

To run this script every Monday at 2 AM, you could set up a cron job like this:

0 2 * * 1 python3 path/to/your/migrate_images.py

This ensures your base images are kept fresh without any manual intervention.

Where I’ve Tripped Up Before (Common Pitfalls)

• IAM Permissions: The most common issue. Your user or role needs more than just read access. It requires permissions like ecr:GetAuthorizationToken, ecr:InitiateLayerUpload, ecr:UploadLayerPart, ecr:CompleteLayerUpload, and ecr:PutImage. Using the managed AmazonEC2ContainerRegistryFullAccess policy is an easy way to start.
• Region Mismatch: Double-check that the region you specify in your AWS CLI authentication command matches the region where your ECR repository lives. It’s an easy mistake to make.
• Incorrect Tagging: The ECR image tag must be exact: <account_id>.dkr.ecr.<region>.amazonaws.com/<repo_name>:<tag>. A typo here will cause the push to fail. My script handles this, but it’s a frequent manual error.

Conclusion

That’s the whole process. By moving your images to ECR, you gain a private, secure, and highly-available container registry that integrates seamlessly with the rest of your AWS infrastructure, from ECS and EKS to CodeBuild. You eliminate public registry rate limits as a source of failure and get better control over your software supply chain. It’s a foundational step for building a robust, production-grade system.

Hope this guide helps streamline your workflow. Happy building!

— Darian Vance

Darian Vance

Lead Cloud Architect & DevOps Strategist

With over 12 years in system architecture and automation, Darian specializes in simplifying complex cloud infrastructures. An advocate for open-source solutions, he founded TechResolve to provide engineers with actionable, battle-tested troubleshooting guides and robust software alternatives.

🤖 Frequently Asked Questions