Ecr Diagnostics

ECR Diagnostics

When to use

Any ECR investigation where the console alone is insufficient — push/pull failures, authentication problems, image scanning issues, lifecycle policy misconfigurations, replication failures, security policy errors, or performance bottlenecks.

Investigation workflow

Step 1 — Collect and triage

aws ecr describe-repositories
aws ecr describe-images --repository-name <repo> --query 'imageDetails[*].{tag:imageTags,pushed:imagePushedAt,size:imageSizeInBytes,scan:imageScanStatus}'
aws ecr get-login-password --region <region> | docker login --username AWS --password-stdin <account>.dkr.ecr.<region>.amazonaws.com
aws ecr get-authorization-token
aws ecr describe-registry

Step 2 — Deep dive

aws ecr get-repository-policy --repository-name <repo>
aws ecr get-lifecycle-policy --repository-name <repo>
aws ecr describe-image-scan-findings --repository-name <repo> --image-id imageTag=<tag>
aws ecr describe-image-replication-status --repository-name <repo> --image-id imageTag=<tag>
aws ecr describe-pull-through-cache-rules
aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventSource,AttributeValue=ecr.amazonaws.com --max-results 20
aws cloudwatch get-metric-statistics --namespace AWS/ECR --metric-name RepositoryPullCount --dimensions Name=RepositoryName,Value=<repo> --start-time <start> --end-time <end> --period 3600 --statistics Sum

Read references/guardrails.md before concluding on any ECR issue.

Tool quick reference

Gotchas: ECR

• Auth tokens expire after 12 hours: ECR authorization tokens are valid for exactly 12 hours. Docker clients must re-authenticate after expiry. CI/CD pipelines must refresh tokens before each build.
• Tag immutability is per-repository: Once enabled, you cannot push an image with a tag that already exists. This prevents overwriting latest or other mutable tags. Disable immutability or use unique tags.
• Lifecycle policies evaluate asynchronously: Policy changes don't take effect immediately. ECR evaluates lifecycle rules periodically (typically within 24 hours). Don't expect instant image cleanup.
• Image scanning is not real-time: Basic scanning uses the Clair engine and scans on push. Enhanced scanning uses Amazon Inspector and provides continuous scanning. Results may take minutes to appear.
• Cross-account pull requires both IAM and repository policy: The pulling account needs IAM permissions AND the repository must have a resource policy granting access to the pulling account's principal.
• ECR has a rate limit on pull operations: Authenticated pulls are limited to 1000 per second per region. Unauthenticated pulls from ECR Public are more restricted. Use VPC endpoints to avoid NAT gateway bottlenecks.
• Replication does not copy lifecycle policies: When replicating to another region or account, only images are replicated. Lifecycle policies, repository policies, and scanning configurations must be set up separately.
• ECR Public has separate authentication: ECR Public uses aws ecr-public get-login-password and authenticates to public.ecr.aws, not the private registry endpoint.
• Image manifest size limit is 4 MB: Individual image manifests cannot exceed 4 MB. Multi-architecture manifests (manifest lists) have the same limit.
• Untagged images accumulate: Pushing a new image with an existing tag makes the old image untagged. Without lifecycle policies, untagged images accumulate and increase storage costs.

Anti-hallucination rules

1. Always cite specific repository names, image digests, or API responses as evidence.
2. Auth tokens expire after 12 hours — never claim they are permanent or long-lived.
3. Lifecycle policies are asynchronous — never claim immediate effect after policy creation.
4. Cross-account access requires BOTH IAM policy and repository policy — never suggest only one.
5. Replication does not copy policies — never claim lifecycle or repository policies replicate.
6. Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.

22 runbooks