AWS 154: Amazon ECR
Why this lesson matters
Operate private image repositories with immutable tags or digest pinning, scanning, encryption, access policies, replication, and lifecycle cleanup.
ECR is the software-supply-chain boundary between a build and a deployment. A successful push proves registry storage, not that the image is trusted, runnable on the target architecture, free of exploitable packages, authorized for production or retained for rollback.
What you will be able to do
By the end, you can:
- explain amazon ecr in plain language;
- locate the current service controls in the AWS Management Console;
- run the matching CloudShell or AWS CLI queries and explain every important field;
- draw the identity, network, data, failure, and monitoring path;
- choose the service from requirements and reject it when those requirements are absent;
- diagnose a failed or misleading result from evidence;
- state the cost owner and prove cleanup or a no-create result.
Before you start
- Use a personal AWS account only when its owner has approved the lesson. Do not use the root user for daily work.
- CloudShell is the default command environment. AWS028 explains CloudShell; AWS029 and AWS030 explain local AWS CLI installation and profiles.
- The course example Region is
ap-south-1. Global services and services with a required control Region are called out in their commands. - Run
aws sts get-caller-identityprivately. Redact the account number before sharing evidence. - Never paste access keys, passwords, secret values, private object data, presigned URLs, or full account-specific ARNs into a submission.
- This is a no-create lesson. Every Console action and AWS CLI command is read-only. Create the practical artifact locally.
- Console wording can change. Use the Console service search if a menu label has moved, then confirm the current field in the official documentation.
The core model
| Question | What it means in this lesson |
|---|---|
| Purpose | Operate private image repositories with immutable tags or digest pinning, scanning, encryption, access policies, replication, and lifecycle cleanup. |
| Scope and boundary | The learner must identify the account and Region scope, resource boundary, identity path, data or network path, failure behavior, observability, and cleanup ownership for Amazon ECR. |
| Evidence of success | Success means the Console fields, CLI result, workload behavior, monitoring evidence, and architecture claim agree. An available state alone is not enough for Amazon ECR. |
| Cost model | Requests, running capacity, storage, logs, data transfer, retained state, and optional features must be priced for the exact design. |
| Safe rejection rule | Avoid deploying latest without digest control or deleting every old image before rollout rollback has expired. |
How the request flows
+----------------------+
| Built image |
+----------------------+
|
v
+-----------------------+
| ECR push and digest |
+-----------------------+
|
v
+---------------------------+
| Scanner and policy gate |
+---------------------------+
|
v
+---------------------------------+
| Runtime pulls pinned artifact |
+---------------------------------+For Amazon ECR, the important boundary is this: The learner must identify the account and Region scope, resource boundary, identity path, data or network path, failure behavior, observability, and cleanup ownership for Amazon ECR. Success means the Console fields, CLI result, workload behavior, monitoring evidence, and architecture claim agree. An available state alone is not enough for Amazon ECR. That is why the lesson pairs the Console with CLI output and a practical artifact. One interface may hide a field, use a cached view, or be scoped differently. Matching evidence is stronger than a screenshot alone.
Architecture decision table
| Situation | Direction | Reason |
|---|---|---|
| Requirement matches | Use ECR for AWS-integrated OCI image storage and distribution. | Select only after scope, behavior, security, recovery, operations, and price evidence agree. |
| Requirement does not match | Avoid deploying latest without digest control or deleting every old image before rollout rollback has expired. | Rejecting an attractive service is a valid architecture result. |
| No create permission or cost approval | Use supplied evidence and local design work | Learning does not depend on creating an hourly resource. |
| Existing resource is unknown or unowned | Inspect only, then stop | Never change or delete a resource merely because it resembles a course example. |
Repository, manifest, tag and digest
A private repository is Regional. An image push uploads compressed layers and a manifest; layers may be shared/deduplicated, while the manifest digest identifies exact content. Multi-architecture images use an OCI/Docker manifest list that maps platform to child digest. ECS/EKS pulls authenticate to the registry, fetch the manifest and layers, then verifies/extracts locally. ECR authorization tokens are temporary registry credentials derived from AWS identity; never store them in source control.
Tag mutability allows prod or latest to move. Prefer tag immutability with documented exclusions only for approved workflows, and record/deploy the digest. Digest pinning improves reproducibility but also means patched base images do not appear automatically; rebuild, scan, sign, promote and roll out a new digest. Cross-account pulls need both identity permissions and repository policy where applicable. Pull-through cache/public ECR/cross-Region replication have different trust, upstream-rate, namespace and ownership models.
Basic scanning and enhanced scanning/Inspector integration differ in frequency, coverage and finding lifecycle. Define severity/exploitability/age exceptions, scan-on-push plus continuous rescans as supported, and a deploy gate that references the exact digest. Generate SBOM and provenance/signature using the organization's signing system; ECR encryption and image signing solve different problems. A zero-finding scan does not prove safe application code.
Replication copies eligible images according to registry rules to destination Regions/accounts asynchronously. It does not replicate every repository setting/policy/lifecycle assumption automatically; test pull and permissions in the destination. Lifecycle policies select by tag status/prefix/count/age, evaluate rules in priority order and expire images asynchronously. Preview before applying and protect every digest referenced by production/rollback - even an untagged manifest may still be needed by a running revision.
Use KMS CMK only when key-control requirements justify policy, grant, availability and deletion risk; changing encryption behavior has repository-lifecycle constraints. Monitor push/pull failures, scan findings, replication, repository storage and CloudTrail. Cost includes GB-month, cross-Region/account transfer, enhanced scanning and build/network paths; layers retained by many manifests can surprise cleanup expectations.
AWS Management Console, step by step
Sign in with the normal non-root learning identity. Write the expected starting state before opening the service.
- Use the Console service search and open Elastic Container Registry, Private registry and Repositories; confirm the account and Region before reading the page.
- Inspect the supplied or owned resource's status, configuration, permissions, networking, encryption, monitoring, tags, and dependencies without changing it.
- Open the related metrics, logs, events, or history view and record one timestamped signal that would prove or disprove the expected behavior.
- Return to the resource list, clear filters, and record the final inventory. On the read-only track, do not choose Create, Save, or Delete.
CloudShell and AWS CLI, step by step
Start with a known caller and Region:
export AWS_DEFAULT_REGION="ap-south-1"
aws sts get-caller-identity --query Arn --output text
aws configure listRedact the account part of the ARN in shared evidence. Now run the topic queries:
aws ecr describe-repositories --query 'repositories[].{Name:repositoryName,Mutability:imageTagMutability,Scan:scanningConfiguration.scanOnPush,Encryption:encryptionConfiguration.encryptionType}' --output table
aws ecr describe-images --repository-name replace-with-repository --query 'imageDetails[].{Digest:imageDigest,Tags:imageTags,Pushed:imagePushedAt,Size:imageSizeInBytes}' --output table
aws ecr get-lifecycle-policy --repository-name replace-with-repository --output jsonExpected interpretation
Tags are mutable labels unless controlled; the digest identifies image content. Scan findings and lifecycle policy need separate review and deployment gates.
Practical work
Create p08-ecr-policy.md with repository naming, tag mutability, digest deployment, scan gate, KMS decision, cross-Region replication, pull permissions, retention, rollback image, and deletion protection.
Add build provenance and SBOM ownership, multi-architecture manifest policy, base-image rebuild SLA, cross-account CI push and runtime pull trust, lifecycle preview and emergency CVE flow. Test tag overwrite denial, wrong-account pull, expired auth token, KMS denial, wrong CPU architecture, critical-finding gate, replication lag and lifecycle rule that would delete the rollback digest. Include exact recovery and exception expiry.
Diagnose this topic from its own evidence
Push/pull 403 requires caller, token registry/Region, action, repository policy, SCP and KMS evidence. manifest unknown means repository/tag/digest/platform or replication state; it is not fixed by broader IAM. A task CannotPullContainerError also requires subnet DNS/NAT/ECR API+DKR/S3 endpoint and execution-role checks. Scan absent/stale requires registry scanning configuration, image digest and Inspector status. Lifecycle “did not delete” is asynchronous and rule-selection evidence must come from preview/evaluation.
Cost and cleanup
Requests, running capacity, storage, logs, data transfer, retained state, and optional features must be priced for the exact design.
Knowledge check
- What operational purpose is this lesson solving?
Expected direction: Operate private image repositories with immutable tags or digest pinning, scanning, encryption, access policies, replication, and lifecycle cleanup.
- Which scope or ownership boundary must be proved first?
Expected direction: The learner must identify the account and Region scope, resource boundary, identity path, data or network path, failure behavior, observability, and cleanup ownership for Amazon ECR.
- What evidence is strong enough to accept the result?
Expected direction: Success means the Console fields, CLI result, workload behavior, monitoring evidence, and architecture claim agree. An available state alone is not enough for Amazon ECR.
- Which tempting design or shortcut must be rejected?
Expected direction: Avoid deploying latest without digest control or deleting every old image before rollout rollback has expired.
- Which cost dimensions and retained resources need an owner?
Expected direction: Requests, running capacity, storage, logs, data transfer, retained state, and optional features must be priced for the exact design.
Lesson acceptance
Pass when the learner deploys conceptually by digest, governs immutable tags, authentication/policies/KMS, scanning/SBOM/signing, replication and safe lifecycle preview with rollback protection. Negative tests must distinguish registry, network, architecture and runtime failures. Fail if latest identifies a release, scan success equals approval, or cleanup expires a running/rollback digest.