Skipping “what is a container registry” — this is the model experienced engineers reach for when reasoning about ECR in production.

Images are content-addressed — tags are just pointers

The actual identity of an image in ECR is its manifest digest — a SHA-256 hash of its manifest content — not its tag. A tag like myapp:v1.2 is a mutable pointer that ECR maps to a specific digest at push time; pushing a new image with the same tag simply repoints that tag to a new digest, but the old digest and its layers still exist and remain pullable by digest until explicitly deleted or expired by a lifecycle policy. This distinction is why “immutable tags” (a repository setting) doesn’t freeze the image — it prevents the tag from being repointed at all, forcing a genuinely new tag for any new push, which is the actual mechanism behind supply-chain guarantees like “this exact tag has only ever referred to one build.”

Layers are shared and deduplicated across repositories within a registry

ECR stores image layers as content-addressable blobs at the registry level (per AWS account, per Region), not per repository. If two different repositories in the same registry both include a layer with an identical digest — for example, the same base OS layer used by ten different application images — that layer is stored once and referenced by every manifest that needs it. This is why deleting an image doesn’t necessarily free storage proportional to its declared size: shared layers persist as long as any other manifest still references them, and lifecycle policies operate on manifests and tags, not directly on the underlying shared layer storage.

Pull-through cache is a proxy, not a mirror

A pull-through cache repository doesn’t pre-populate images — it lazily fetches and caches an image from a configured upstream registry (Docker Hub, Quay, another ECR registry) the first time it’s requested, then serves that cached copy for subsequent pulls until a refresh interval elapses. This matters operationally: the first pull after configuring a pull-through cache still depends on upstream registry availability and rate limits, and a private VPC with no internet egress needs a NAT gateway or VPC endpoint path to the upstream registry for that first cache-miss pull to succeed at all.

What actually happens between “docker push” and an image being pullable, scanned, and replicated.

A push begins with a client authentication step — ecr:GetAuthorizationToken returns a short-lived (12-hour) token used as the Docker login credential, scoped to the entire registry, not a single repository. Once authenticated, the Docker client pushes each layer as a blob, and ECR checks whether that layer’s digest already exists in the registry before accepting the upload — if it does, the client skips re-uploading a layer it already has, which is the mechanism behind fast pushes of images sharing a common base layer with something already stored.

After all layers are present, the client pushes the manifest, which references those layers by digest. ECR validates the manifest against the OCI or Docker V2 schema, computes its digest, and only then does the push complete — before this point, no image exists from the registry’s perspective, even if individual layers were already uploaded. Once the manifest is stored, if a scan-on-push configuration is active, ECR queues the image for vulnerability scanning asynchronously; the push itself does not block on scan completion.

graph TD
    A[docker push] --> B[GetAuthorizationToken]
    B --> C{Layer digest already in registry?}
    C -->|Yes| D[Skip upload, reference existing layer]
    C -->|No| E[Upload layer blob]
    D --> F[All layers present]
    E --> F
    F --> G[Push manifest]
    G --> H[Validate schema, compute digest]
    H --> I[Manifest stored - image now exists]
    I --> J[Scan-on-push queued async]
    I --> K[Replication rules evaluated async]
    J --> L[Basic or Enhanced Scan Results]
    K --> M[Cross-Region / Cross-Account Copy]
        

An image’s operational lifecycle in ECR runs on two independent tracks that engineers frequently conflate: the lifecycle policy track, which governs automatic expiration of images based on rules like “keep only the last 10 tagged images matching a prefix” or “expire untagged images after 14 days,” and the scan findings track, which is refreshed independently and doesn’t influence whether a lifecycle policy expires an image — a critically vulnerable image is not automatically protected from expiration, and a clean image is not automatically protected from a lifecycle rule that happens to target it.

Enhanced scanning differs from basic scanning in a way that affects this lifecycle materially: it re-evaluates already-pushed images continuously as new CVEs are published, meaning an image that was clean at push time can later surface new findings without ever being re-pushed — a fact that matters for any automation assuming “scanned once” means “permanently assessed.”

ECR’s pull performance at scale is dominated by two factors: layer cache hit rate on the consuming compute (a Fargate task or EC2 instance that’s never pulled a given base layer before pays the full download cost, while one with a warm local cache doesn’t), and cross-Region pull latency when workloads in one Region pull from a registry hosted in another. Cross-Region replication exists specifically to address the second factor — replicating images to a registry local to each Region a workload runs in avoids repeated cross-Region data transfer on every cold pull.

Authentication tokens are registry-scoped and last 12 hours, which matters for high-throughput CI/CD systems: re-authenticating on every single push or pull call adds unnecessary API overhead at scale, so pipelines should cache and reuse the token for its full validity window rather than calling GetAuthorizationToken per operation.

Spotify has publicly discussed operating ECR at very large scale across many microservice repositories, citing cross-Region replication specifically as the mechanism that let them keep pull latency consistent for services deployed across multiple Regions without building their own image-mirroring infrastructure — a pattern that generalizes directly to any multi-Region ECS or EKS deployment.

ECR’s storage layer inherits Amazon S3’s durability characteristics under the hood, and the service’s control plane is Regional and multi-AZ, meaning you don’t design for ECR’s own internal redundancy. The reliability design decisions that matter are about Regional dependency and replication configuration for your specific deployment topology.

Without cross-Region replication configured, a Region-wide ECR service disruption (rare, but architecturally possible) would block new pulls of images not already cached locally on running compute in that Region — existing running tasks are unaffected since they don’t re-pull already-running container images, but new task starts or scale-out events would stall. Teams running genuinely multi-Region active-active workloads treat cross-Region replication as a hard requirement, not an optimization, specifically to remove this single-Region dependency from their deployment path.

ECR access control operates at two layers that need to be reasoned about together: IAM policies attached to principals (users, roles) control what actions a principal can take against ECR broadly, while repository policies — resource-based policies attached directly to a specific repository — control which principals, including those in other AWS accounts, can access that specific repository without needing a cross-account IAM role assumption. A repository policy granting a partner account pull access is the standard pattern for sharing specific images without exposing the entire registry.

Image tag immutability and lifecycle policies both function as supply-chain integrity controls when combined deliberately: immutable tags prevent a compromised CI system or malicious insider from silently swapping the image behind a production tag, while enhanced scanning’s continuous re-evaluation means a previously-approved image can later be flagged, which is why some regulated environments require re-validation gates rather than treating “passed scan once” as permanent clearance.

Every push, pull authentication, and repository management action is logged to AWS CloudTrail, making it the primary forensic source for questions like “who pushed this tag” or “when was this repository policy last changed” — critical for supply-chain incident investigation. Scan findings themselves are queryable via the ECR API and are also forwarded to Security Hub if that integration is enabled, letting scan results flow into the same centralized findings pipeline as other security tooling rather than requiring a dedicated ECR-specific dashboard.

EventBridge receives events for image scan completion and image push actions, which is the standard integration point for automated gating — a Lambda function subscribed to the scan-completion event can automatically tag an image as “approved” or trigger a deployment pipeline step only once results are in, rather than the pipeline polling the scan API on a fixed interval.

A production ECR architecture for a multi-account organization commonly centralizes a shared “golden image” registry in a dedicated tooling account, with cross-account repository policies granting pull-only access to workload accounts, while each workload account maintains its own application-specific repositories for images built from its own CI pipeline — combining centralized governance of base images with decentralized ownership of application images.

graph TD
    CI[CI/CD Pipeline] -->|push app image| APPREPO[App Repository - Workload Account]
    GOLDEN[Golden Base Image Registry - Tooling Account] -->|cross-account pull policy| APPBUILD[App Image Build Stage]
    APPBUILD --> APPREPO
    APPREPO -->|replication rule| REGION2[Replicated Copy - Secondary Region]
    APPREPO --> SCAN[Enhanced Scanning via Inspector]
    SCAN --> SECHUB[Security Hub Forwarding]
    APPREPO -->|deploy by digest| RUNTIME[ECS / EKS / Lambda]
        

Pull-through cache repositories are typically deployed per-VPC or per-account for public base images (Docker Hub official images, public ECR Gallery images) specifically to insulate CI/CD pipelines from public registry rate limiting, a pattern that became especially common after Docker Hub introduced pull-rate limits for anonymous and free-tier accounts.

Snap Inc. has publicly discussed centralizing base container images in a dedicated ECR registry account with cross-account repository policies granting scoped pull access to hundreds of workload accounts, explicitly citing reduced duplicate storage and consistent base-image patching as the motivating factors for that centralized pattern.

Financial-services organizations under regulatory scrutiny commonly point to ECR’s tag immutability combined with CloudTrail’s push-event logging as the mechanism that satisfies “prove which exact artifact was deployed to production and when” audit requirements, replacing manual deployment logs with a queryable, tamper-evident record.

Robinhood has described using ECR enhanced scanning’s continuous re-evaluation specifically to catch newly disclosed CVEs in long-lived base images without requiring every dependent application team to manually re-scan or rebuild — illustrating enhanced scanning’s real value as an ongoing monitoring capability rather than a one-time push-time gate.