Amazon ECR in Production: IAM, Digests, Scanning, Lifecycle Rules, and Replication

Amazon Elastic Container Registry stores Docker/OCI images and other OCI-compatible artifacts in repositories scoped to an AWS registry. Authentication proves who is calling; IAM and repository policies decide which actions that identity may perform. CI should use a short-lived role through workload federation rather than a long-lived access key.

Tags are labels; digests are identity

An image digest identifies manifest content. A tag such as latest is a mutable pointer and can move between digests, so production manifests should pin an approved digest or an immutable release tag with recorded provenance. Enable tag immutability where replacement would undermine rollback or audit evidence.

Scanning and retention

ECR supports vulnerability scanning, but findings are inputs to a policy—not proof that an image is safe. Define severity thresholds, exception expiry, and rebuild expectations. Lifecycle policies expire or archive matching images; preview a policy before enabling it and retain every artifact still referenced by production, rollback, or an investigation.

Replication and access

Cross-Region and cross-account replication can reduce pull latency and improve recovery options. Repository policies, lifecycle rules, and some settings do not automatically become identical everywhere, so replication needs a configuration audit. Private endpoints reduce public-network dependency for private workloads, while KMS options and default encryption protect data at rest.

Integrations and failure modes

ECS task definitions and EKS pods can pull directly from ECR when execution or node identities have the correct permissions. Common failures come from expired login tokens, wrong region/account endpoints, missing KMS permissions, network paths, or a tag that moved unexpectedly. Log push and policy events, alert on scanning regressions, and periodically prove that disaster-recovery regions can actually pull the required digests.

Authentication paths and policy layers

The Docker client does not speak IAM directly. aws ecr get-login-password obtains an authorization token for the registry endpoint, and the client passes that token to docker login; AWS documents the token as valid for twelve hours. Interactive operators should obtain it from a short-lived AWS session, while CI should assume a narrowly scoped role through its platform’s identity federation. A successful login is not authorization to every repository operation. Identity policies, repository policies, service control policies, permissions boundaries, KMS policy, and endpoint policy can all participate in the final decision.

Separate push and pull duties. A deployment role generally needs read operations such as BatchGetImage and layer download calls, not image deletion or policy management. A publisher needs upload operations only for its target repository. Repository policies are useful for cross-account access, but the destination account should still constrain principals and actions explicitly. Test the complete path with the real workload identity; an administrator’s successful pull proves little about an ECS execution role or an EKS pod.

Release evidence and rollback safety

A defensible release records the source revision, build system identity, image digest, scan result, signature or attestation when used, and the environment that accepted the artifact. Promote the same digest between environments instead of rebuilding from the same Git commit: toolchains, package indexes, and base tags can change between builds. If tags remain mutable for developer convenience, production policy can still require digests and reject an unapproved manifest.

Lifecycle rules need an explicit rollback horizon. ECR evaluates rule priority and applies expiration to matching images; a policy that keeps “the last ten” is unsafe when ten CI builds can occur before an incident is noticed. Retain deployed digests, known-good rollback digests, legal holds, and incident evidence independently of age-based cleanup. Preview the policy, compare its candidates with deployment inventory, and only then activate it.

Recovery and verification runbook

Replication is asynchronous, so a replicated repository is not proof of a usable recovery path. Periodically resolve an expected tag to its digest in each destination, pull that digest from a runner located on the recovery network, and verify that required KMS keys, IAM principals, VPC endpoints, DNS, and egress rules work. Record replication failures and image-pull latency as operational signals.

When a pull fails, inspect the exact registry hostname, repository, tag or digest, caller identity, token age, platform architecture, and manifest media type before changing permissions. Broadly granting ecr:* can hide the immediate symptom while creating a supply-chain control failure. CloudTrail data and management events, ECR scan findings, repository policy changes, and lifecycle-policy previews together provide a more useful audit trail than Docker’s final error string alone.

A production acceptance checklist

Before declaring a repository ready, prove that an authorized publisher can push a test manifest, an unauthorized principal is denied, and the actual deployment identity can pull by digest from every required network. Confirm tag mutability policy, default encryption, scanning configuration, lifecycle preview, replication destinations, and CloudTrail coverage. Record repository ownership and an escalation path; a registry shared by many teams without an accountable owner accumulates stale permissions and ambiguous retention rules.

For each release, resolve the human-readable tag to the server-reported digest after push and compare that digest with the deployment manifest. Pull the digest into a clean environment and inspect the platform manifest so an ARM64 node is not surprised by an x86-only image. If signatures or attestations are part of policy, verify them at admission or promotion time and preserve the verification result. A scan completed before a new vulnerability disclosure is not permanent evidence, so trigger rescanning or rebuild evaluation according to the organization’s vulnerability process.

Finally, test destructive controls safely. Apply lifecycle changes in preview, exercise recovery from an unintended tag movement, and verify that a protected production digest cannot be overwritten. These checks turn ECR from passive storage into a controlled release boundary.

Related:

Sources: