Amazon ECR: Container Image Registry
AWS's managed Docker/OCI image registry — where the container images that ECS and EKS actually pull from live, with IAM-based access control and vulnerability scanning built in.
Want a visual for this topic?
Generate a diagram tailored to Amazon ECR: Container Image Registry — the AI picks whichever visual (architecture, flowchart, ER diagram, etc.) best fits this specific AWS concept.
Sign in to generate a visual →🎓 Learning objectives
- •Explain what ECR is and how it relates to Docker Hub or any other container registry
- •Push and pull an image to/from ECR using the Docker CLI and understand the authentication step involved
- •Describe ECR's image scanning feature and lifecycle policies
- •Understand how ECS/EKS task definitions reference an ECR image URI
What is it?
Amazon ECR (Elastic Container Registry) is AWS's fully managed, private container image registry — the storage and distribution layer for the Docker/OCI images that ECS, EKS, Lambda container images, and any other container runtime pull from. It's functionally comparable to Docker Hub, but private by default, backed by S3 for durable storage, integrated with IAM for push/pull access control, and located inside your own AWS account and region for low-latency pulls from ECS/EKS in the same region.
Why it exists
Before ECR, teams running containers on AWS either used Docker Hub (a third-party dependency outside AWS's IAM/networking boundary, with its own separate credentials and a history of rate-limiting pulls) or self-hosted a private registry themselves. ECR exists to remove that third-party dependency entirely — private images live inside your own AWS account, access is controlled with the same IAM policies you already use everywhere else, and pulls from ECS/EKS in the same region avoid any public internet hop.
Problem it solves
It solves the problem of needing a private, access-controlled place to store application container images that's fully integrated with the same IAM and networking boundary as the compute (ECS/EKS/Lambda) that will run them — without depending on a third-party registry as a hard dependency for every deployment.
Intuition
The one thing that trips people up coming from Docker Hub: there's no persistent username/password login. Every docker login to ECR uses a token that AWS generates from your current IAM credentials and that expires in 12 hours — so ECR access control is really just IAM access control, not a separate registry-specific credential system.
Analogy
A private, company-only app store for container images: your CI pipeline is the app developer submitting a build, ECR is the store that holds every version, scans each submission for known security issues before it's allowed to ship, and ECS/EKS are the devices that download and run whatever version you tell them to.
Technical explanation
aws ecr get-login-password calls the GetAuthorizationToken API, which returns a base64-encoded token valid for 12 hours, derived from the calling identity's IAM permissions — this is why ECR needs no separate registry account system at all. Image layers are content-addressed and deduplicated at the layer level across all repositories in an account's registry, so pushing an image that shares base layers with an already-pushed image only uploads the new layers. Enhanced scanning integrates with Inspector's continuous rescan mechanism, meaning an image already sitting in ECR gets automatically rescanned and flagged if a new CVE is published for a package it contains, not just at the moment it was pushed.
Architecture
Each ECR repository holds multiple tagged (and untagged) image versions, with layers stored in S3 and a metadata index tracking tags/digests. Push/pull access is governed by IAM policies (identity-based, for your own account's users/roles) and optionally a repository policy (resource-based, for cross-account access) — the same dual-policy pattern as S3 bucket access. Image scanning runs as a separate async job triggered on push (or on a schedule for enhanced scanning) and writes findings to a scan-results API, optionally forwarded into Security Hub. ECS task definitions and Kubernetes Pod specs both simply reference the full image URI (<account>.dkr.ecr.<region>.amazonaws.com/<repo>:<tag>), and the underlying container runtime handles the actual pull using IAM-derived credentials the task execution role already has.
Workflow
- Create an ECR repository (one per application/service, typically). 2) Authenticate Docker to ECR using a short-lived token obtained via the AWS CLI (
aws ecr get-login-password | docker login). 3) Tag your locally built image with the full ECR repository URI. 4)docker pushthe tagged image. 5) Reference that same image URI in an ECS task definition or Kubernetes Pod spec, which pulls it on deployment. 6) Set a lifecycle policy on the repository to automatically expire old images and control storage growth.
Example
A CI/CD pipeline builds a new Docker image on every merge to main, tags it with the Git commit SHA, pushes it to an ECR repository, and then updates the ECS service's task definition to reference the new image tag — ECS then performs a rolling deployment, pulling the new image from ECR onto each replacement task.
Real-world usage
Nearly every ECS or EKS deployment on AWS pulls its application images from ECR rather than Docker Hub, specifically to keep the entire deploy path — build, scan, push, pull, run — inside one IAM-governed boundary. Teams commonly set a lifecycle policy like 'keep the last 20 tagged images, expire untagged images after 1 day' to balance rollback capability against storage cost, and wire ECR's scan findings into Security Hub so a critical CVE in a base image shows up alongside every other security finding in one place.
Trade-offs
ECR trades the broad public discoverability of Docker Hub (searching for a public base image) for tight IAM integration and private-by-default security — which is exactly the tradeoff most companies want for their own application images, while still pulling public base images (Ubuntu, Node, Python) from Docker Hub or the ECR Public Gallery. Enhanced scanning costs more than basic scanning but catches more, and continuously rather than only at push time.
Visual explanation
Picture a labeled shelf (the ECR repository) inside a locked room (your AWS account). CI drops a new labeled box (image tag) on the shelf after every build. A scanner (image scanning) checks each box for hazards the moment it's placed. ECS/EKS reach onto the shelf and grab the exact labeled box their task definition asks for, using a key (IAM role) that only works while it's freshly cut (the 12-hour auth token).
Advantages
- —
IAM-based access control — no separate registry credentials to manage or rotate
- —
Private by default, with images stored durably on S3 under the hood
- —
Built-in vulnerability scanning (basic via Clair, enhanced via Inspector integration) with no separate tool needed
- —
Same-region pulls from ECS/EKS avoid public internet latency and egress cost
- —
Cross-account and cross-region replication supported natively for multi-account or multi-region deployments
Disadvantages
- —
Storage cost accrues for every pushed image tag/layer indefinitely unless a lifecycle policy is configured — a very active CI pipeline can accumulate significant storage cost from years of old, unused tags
- —
Enhanced scanning has a real per-image cost that basic scanning doesn't, and needs to be explicitly enabled per repository
- —
Cross-account pulls require correctly configuring a repository policy — a common source of ECS task failures (
ImagePullBackOff-equivalent) when the task execution role in the consuming account isn't granted access - —
Unlike Docker Hub, there's no single global public namespace — public sharing requires explicitly using the separate ECR Public Gallery
Common mistakes
- —
Never setting a lifecycle policy and letting a repository accumulate thousands of stale image tags, silently growing the storage bill
- —
Forgetting that the ECR login token expires in 12 hours — a CI pipeline step that authenticates once and reuses the token across a long-running job will start failing pulls partway through
- —
Tagging every push as
:latestinstead of a unique tag (commit SHA or semantic version) — this makes rollbacks and audit trails effectively impossible since:latestis a moving target - —
Not enabling scan-on-push and only discovering a critical CVE in a base image months after it shipped to production
In the AWS Console
- 1
ECR → Repositories → Create repository
Create a new private ECR repository.
Enable 'Scan on push' at creation time rather than adding it later — it's a one-click toggle here.
- 2
ECR → Repositories → [your repo] → View push commands
View the push commands for the new repository, which include the exact `docker login`, `docker tag`, and `docker push` commands for your account.
- 3
ECR → Repositories → [your repo] → [image tag] → Scan findings tab
After a push, review the scan findings for the pushed image.
🎤 Interview questions
What is Amazon ECR, and how does it relate to Docker Hub? (Listen for: a fully managed, private-by-default container image registry, functionally equivalent to Docker Hub but integrated with IAM for access control and living inside your AWS account/region; images are referenced by a full registry URI like <account>.dkr.ecr.<region>.amazonaws.com/<repo>:<tag>)
How does Docker authenticate to push an image to ECR? (Listen for: aws ecr get-login-password piped into docker login — this exchanges IAM credentials for a short-lived Docker registry auth token, rather than a permanent username/password)
What does ECR image scanning do? (Listen for: scans image layers for known OS and package vulnerabilities (CVEs) either on push or on a schedule; basic scanning uses the open-source Clair database, enhanced scanning integrates with Inspector for continuous, deeper scanning)
What is an ECR lifecycle policy? (Listen for: a rule-based policy that automatically expires old images — e.g., 'keep only the last 10 tagged images' or 'expire untagged images after 14 days' — to control storage cost and repository clutter, since ECR otherwise keeps every pushed image forever)
Can an ECS task in one AWS account pull an image from an ECR repository in a different account? (Listen for: yes, via an ECR repository policy granting the other account's task execution role pull permissions — the same cross-account resource-based-policy pattern used by S3 bucket policies)