Amazon ECR Explained: How to Create a Repository and Push a Docker Image

You've built a Docker image locally and now need a secure, AWS-native place to store it before deploying to ECS or EKS. Amazon ECR (Elastic Container Registry) is that place — a fully managed container registry that eliminates the operational overhead of running your own registry while integrating natively with IAM, ECS, and other AWS services.

TL;DR

StepActionTool
1Create an ECR repositoryAWS Console / CLI
2Authenticate Docker to ECRAWS CLI + Docker
3Tag your local imageDocker CLI
4Push the image to ECRDocker CLI
5Verify the image in ECRAWS Console / CLI

What is Amazon ECR?

Amazon Elastic Container Registry (ECR) is a fully managed Docker-compatible container image registry hosted by AWS. Think of it as a private Docker Hub that lives inside your AWS account, governed by IAM, and co-located with your compute services.

Key characteristics:

  • Private by default: Every repository is private unless you explicitly create a public repository via ECR Public.
  • IAM-integrated: Access is controlled via IAM identity policies and ECR resource-based repository policies.
  • Regional service: Repositories exist within a specific AWS region. Your ECS tasks should pull from the same region to avoid cross-region data transfer costs.
  • Image scanning: ECR supports basic and enhanced vulnerability scanning via Amazon Inspector.
  • Lifecycle policies: Automate cleanup of old or untagged images to control storage costs.

Architecture: Local Image → ECR → ECS

graph LR Dev["Developer Workstation"] -->|docker build| LocalImg["Local Image"] LocalImg -->|docker tag| TaggedImg["Tagged Image"] AWSCLI["AWS CLI"] -->|GetAuthorizationToken| Token["Auth Token"] Token -->|docker login| DockerDaemon["Docker Daemon"] TaggedImg -->|docker push| ECR["Amazon ECR Repository"] DockerDaemon --> ECR ECR -->|pull at launch| ECS["Amazon ECS Task"]
  1. Developer workstation builds a Docker image locally using docker build.
  2. The AWS CLI generates a temporary authorization token, allowing Docker to authenticate against the ECR registry endpoint.
  3. The image is tagged with the ECR repository URI and pushed via standard Docker push.
  4. Amazon ECR stores the image layers in its managed, encrypted storage.
  5. Amazon ECS (or EKS) pulls the image from ECR at task/pod launch time using the task execution role.

Prerequisites

  • AWS CLI v2 installed and configured (aws configure) with a profile that has ECR permissions.
  • Docker Desktop or Docker Engine installed and running locally.
  • A Docker image already built locally (we'll use my-app:latest as the example).

Required IAM Permissions

The IAM identity performing these steps needs, at minimum, the following permissions. Apply least privilege — scope the resource ARN to your specific repository once it exists.

🔽 Click to expand — IAM Policy (least privilege) 
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "CreateAndDescribeRepositories",
      "Effect": "Allow",
      "Action": [
        "ecr:CreateRepository",
        "ecr:DescribeRepositories"
      ],
      "Resource": "*"
    },
    {
      "Sid": "PushImageToRepository",
      "Effect": "Allow",
      "Action": [
        "ecr:GetAuthorizationToken"
      ],
      "Resource": "*"
    },
    {
      "Sid": "PushImageLayers",
      "Effect": "Allow",
      "Action": [
        "ecr:BatchCheckLayerAvailability",
        "ecr:InitiateLayerUpload",
        "ecr:UploadLayerPart",
        "ecr:CompleteLayerUpload",
        "ecr:PutImage",
        "ecr:DescribeImages"
      ],
      "Resource": "arn:aws:ecr:us-east-1:123456789012:repository/my-app"
    }
  ]
}

Note: ecr:GetAuthorizationToken is an account-level action and does not support resource-level restrictions — it must use "Resource": "*".

Step 1: Create an ECR Repository

A repository is the namespace that holds all versions (tags) of a single container image. Create one per application or service.

aws ecr create-repository \
  --repository-name my-app \
  --region us-east-1 \
  --image-scanning-configuration scanOnPush=true \
  --encryption-configuration encryptionType=AES256

The response includes the repositoryUri — save this value. It follows the pattern:

123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app

Replace 123456789012 with your actual AWS account ID and us-east-1 with your target region.

Step 2: Authenticate Docker to Your ECR Registry

ECR uses short-lived authorization tokens. The AWS CLI retrieves a token and pipes it directly into docker login.

aws ecr get-login-password \
  --region us-east-1 \
| docker login \
  --username AWS \
  --password-stdin \
  123456789012.dkr.ecr.us-east-1.amazonaws.com

On success, Docker outputs: Login Succeeded. The username is always the literal string AWS — this is not a placeholder.

Analogy: Think of this step like getting a temporary visitor badge at a secure office building. The AWS CLI is the front desk — it verifies your identity (IAM credentials) and issues a time-limited badge (the auth token). Docker uses that badge to enter the ECR registry. The badge expires, so you'll need a new one in each new terminal session or CI/CD pipeline run.

Step 3: Tag Your Local Image

Docker requires the image name to match the destination registry URI exactly. Tag your existing local image with the full ECR repository URI.

docker tag my-app:latest \
  123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app:latest

This does not copy the image — it creates an alias pointing to the same image layers. You can verify with docker images.

Step 4: Push the Image to ECR

docker push 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app:latest

Docker uploads only the layers that don't already exist in ECR (layer deduplication). For subsequent pushes of the same base image, only changed layers are transferred.

Step 5: Verify the Push

Confirm the image is stored in ECR using the CLI:

aws ecr describe-images \
  --repository-name my-app \
  --region us-east-1

You should see an entry with your image tag, digest, and push timestamp in the response.

Full Push Workflow at a Glance

sequenceDiagram participant Dev as Developer participant CLI as AWS CLI participant ECR_API as ECR API participant Docker as Docker Daemon participant Reg as ECR Registry Dev->>CLI: aws ecr get-login-password CLI->>ECR_API: GetAuthorizationToken ECR_API-->>CLI: Auth Token CLI->>Docker: docker login with token Docker-->>Dev: Login Succeeded Dev->>Docker: docker tag my-app ECR_URI/my-app:latest Dev->>Docker: docker push ECR_URI/my-app:latest Docker->>Reg: Upload image layers Reg-->>Docker: Push complete Dev->>CLI: aws ecr describe-images CLI-->>Dev: Image metadata confirmed

Production Considerations

ConcernRecommendation
Image tagging strategyAvoid relying solely on :latest. Use immutable tags like Git commit SHAs or semantic versions for traceability.
Immutable tagsEnable imageTagMutability=IMMUTABLE on the repository to prevent tag overwrites.
Lifecycle policiesDefine lifecycle rules to expire untagged images and retain only the last N tagged images, controlling storage costs.
Cross-account accessUse ECR repository policies to grant pull access to other AWS accounts (e.g., a separate production account).
ECS task execution roleAttach the AmazonECSTaskExecutionRolePolicy managed policy (or equivalent) to your ECS task execution role so ECS can pull images from ECR.
CI/CD pipelinesUse OIDC-based IAM roles (e.g., GitHub Actions OIDC) instead of long-lived access keys for pipeline authentication.

Enabling Immutable Tags (Recommended)

aws ecr put-image-tag-mutability \
  --repository-name my-app \
  --image-tag-mutability IMMUTABLE \
  --region us-east-1

Glossary

TermDefinition
ECR RepositoryA named namespace within ECR that stores all tagged versions of a single container image.
Repository URIThe full registry endpoint + repository name used as the Docker image name for push/pull operations.
Authorization TokenA short-lived credential issued by ecr:GetAuthorizationToken that Docker uses to authenticate with the ECR registry endpoint.
Image DigestA SHA256 hash of the image manifest, providing a content-addressable, immutable reference to a specific image version.
Lifecycle PolicyA set of rules that automatically expire images in an ECR repository based on age or count criteria.

Next Steps

  • 📖 Amazon ECR User Guide — Official Documentation
  • Configure an ECS Task Definition pointing to your new ECR image URI to deploy the container.
  • Set up ECR lifecycle policies to automate image cleanup and manage storage costs.
  • Integrate ECR scanning with Amazon Inspector for continuous vulnerability assessment of your images.

Related Posts

Comments

Post a Comment

Popular posts from this blog

EC2 No Internet Access in Custom VPC: Attaching an Internet Gateway and Fixing Route Tables

Launching an EC2 instance in a custom VPC only to find it cannot reach the internet is one of the most common networking pitfalls in AWS — and it almost always comes down to two missing pieces: an Internet Gateway (IGW) and a correctly configured Route Table. This post walks you through the exact architecture, the root cause, and the precise steps to fix it. TL;DR Step Action Why It Matters 1 Create and attach an Internet Gateway to your VPC Without an IGW, there is no path between your VPC and the public internet 2 Add a 0.0.0.0/0 route pointing to the IGW in your subnet's Route Table The route table is the traffic director — without this entry, outbound packets have nowhere to go 3 Assign a Public IP or Elastic IP to the EC2 instance The IGW performs NAT only for instances with a public IP address 4 Verify Security Group allows outbound traffic Security Groups are stateful firewalls; outbound rules...
Read more

IAM User vs. IAM Role: Why Your EC2 Instance Should Never Use a User

Choosing between an IAM User and an IAM Role is one of the most consequential security decisions in AWS — get it wrong and you either expose long-lived credentials or block your application entirely. This post cuts through the confusion and gives you a definitive answer for the EC2-to-S3 access pattern. TL;DR — Quick Comparison Dimension IAM User IAM Role Identity type A person or a static service account An assumable identity for AWS services, users, or external principals Credential type Long-lived Access Key ID + Secret Access Key Short-lived, auto-rotating STS tokens (max 12 h by default) Credential rotation Manual — you must rotate keys yourself Automatic — AWS rotates them transparently Stored on EC2? Yes — in ~/.aws/credentials or env vars (risky) No — delivered via the In...
Read more

EC2 SSH Connection Timeout: The Exact Security Group Rules You Need to Fix It

You've launched a fresh EC2 instance, fired up your terminal, and run ssh ec2-user@<your-ip> — only to watch the cursor hang until Connection timed out kills your hope. This is one of the most common EC2 onboarding blockers, and it almost always traces back to a misconfigured Security Group inbound rule. TL;DR Check What to Verify Correct Value Protocol Security Group inbound rule protocol TCP Port Destination port in the inbound rule 22 Source Allowed source CIDR or IP Your public IP (e.g., 203.0.113.10/32 ) or 0.0.0.0/0 for testing Instance State EC2 instance status checks 2/2 checks passed Subnet Route Table Route to Internet Gateway (public subnet) 0.0.0.0/0 → igw-xxxxxxxx Public IP / EIP Instance has a reachable public address Public IPv4 or Elastic IP assigned Why "Connection Timed Out" Specifically? A timeout (as opposed to Connection refused ) means your TC...
Read more