Amazon ECR

What ECR is

ECR is AWS’s own container registry. You push a built image to a repository, and your compute pulls it by URI when it deploys or starts a task. ECS and Fargate, App Runner, Lambda container functions, and plain Docker on EC2 all pull from it. It stores other OCI artifacts too, like Helm charts.

Past storage, it does the things you’d otherwise bolt on: vulnerability scanning on push, lifecycle policies that expire old images, tag immutability, cross-region and cross-account replication, and a pull-through cache that mirrors upstream registries like Docker Hub into your private registry.

Design Beaver models ECR as a regional, API-accessed registry rather than a subnet-resident resource, and it validates as you draw which services pull from it and what that pull actually needs.

When to use ECR (and when not to)

Reach for ECR when you’re already running containers on AWS and you want the registry next to the compute. IAM controls access, so there’s no second set of registry credentials to rotate. Scan-on-push, lifecycle cleanup, and replication come with it. If Docker Hub rate limits are breaking your builds, a pull-through cache rule solves that without changing how your images are referenced.

Don’t add it to an architecture that isn’t running containers — a registry only earns its place when something pulls images from it. It isn’t an object store for arbitrary files, and it isn’t a CDN. ECR serves the registry protocol, not a cacheable website.

Variants: private and public registries

The real choice is one registry type. Everything else — scan-on-push, tag immutability, lifecycle rules — is a per-repository toggle inside whichever you pick.

ECR pricing in plain English

You pay for what you store and what leaves the region. Pulls to same-region compute cost nothing, which makes co-location the single easiest saving.

How ECR connects to other services

Every ECR edge is a pull, and every pull is done by the platform — the ECS agent, the App Runner service, the Lambda service, or a Docker client using an instance profile. Your application code is not calling ECR through the SDK.

• ←ECS

  ECS (on EC2 or Fargate) pulls the container image from an ECR private repository when it starts a task, using the image URI in the task definition (aws_account_id.dkr.ecr.region.amazonaws.com/repo:tag)

• ←App Runner

  App Runner deploys a service from a container image stored in an ECR private repository, pulling the image when the service is created or a new image is deployed

• ←Lambda

  A Lambda function packaged as a container image (up to 10 GB) is deployed from an ECR private repository — during function create/update, the Lambda service pulls the image from ECR, optimizes it, and deploys it

• ←EC2

  An application or CI job running Docker on an EC2 instance pulls (or pushes) images to an ECR repository with `docker pull` / `docker push` after authenticating to the registry

• ←VPC Endpoint

  Compute in a private subnet reaches ECR privately through AWS PrivateLink interface VPC endpoints, with no internet gateway or NAT needed for the pull

That distinction decides where the permission goes, and it’s the thing people get wrong:

• ECS and Fargate pull with the task execution role, not the task role. It needs ecr:GetAuthorizationToken, ecr:BatchGetImage, and ecr:GetDownloadUrlForLayer.
• App Runner pulls with an access role trusting build.apprunner.amazonaws.com. The managed policy AWSAppRunnerServicePolicyForECRAccess covers it.
• Lambda container functions are pulled by the Lambda service at deploy time.
• EC2 running Docker authenticates and pulls using the instance profile.

One detail that breaks hand-written policies: ecr:GetAuthorizationToken is registry-wide and must be granted on Resource: *. The auth token isn’t scoped to a single repository, so a policy that carefully limits it to one repo ARN just fails.

What ECR can’t connect to

A registry looks like it should plug into more things than it does. Design Beaver flags the edges that don’t exist rather than letting them onto the canvas.

• ✕Route 53

  Route 53 is DNS; ECR is not a DNS target you point a domain at. Image pulls go to the AWS-managed registry endpoint (aws_account_id.dkr.ecr.region.amazonaws.com) using the Docker registry protocol with AWS authentication — you don't front a registry with a custom Route 53 record, so there is no architectural edge between them.

• ✕RDS

  A relational database and a container image registry have no native integration. Images are not stored in, pulled from, or otherwise exchanged with RDS — an application would use ECR (for its image) and RDS (for its data) independently, never as a direct connection.

• ✕CloudFront

  CloudFront is a CDN for cacheable HTTP content; ECR is not a CloudFront origin. Container image pulls use the OCI/Docker registry protocol with per-request AWS auth (and store layers in S3), not cacheable HTTP objects delivered through an edge network, so ECR is not fronted by CloudFront.

Anti-patterns Design Beaver catches

These three account for most ECR incidents — two break deploys, one quietly inflates the bill.

Gotchas that bite in production

• Private-subnet pulls need three endpoints. ecr.api, ecr.dkr, and the S3 gateway endpoint, because layers live in S3. Miss the S3 one and the manifest fetch succeeds while the layer download hangs — the confusing failure where connectivity “looks fine.”
• Execution role, not task role. The ECS agent fetches the image before your container starts. ECR permissions on the task role produce CannotPullContainer every time.
• GetAuthorizationToken can’t be scoped. Grant it on Resource: *. Scoping it to a repository ARN is a policy that will never authorize a pull.
• Images accumulate silently. Without a lifecycle policy every CI build stays forever, and you keep paying to store images nothing will pull again.

Further reading

• Official AWS documentation
• Using Amazon ECR images with Amazon ECS
• Amazon ECR interface VPC endpoints (PrivateLink)