Image Registry & Distribution

OCI Distribution Spec

The Open Container Initiative Distribution Specification defines how registries store and serve container images. Docker Registry HTTP API V2 is the de facto implementation. containerd, Podman, BuildKit, and every cloud registry (ECR, GCR, ACR, GHCR) implement the same contract—your tooling works everywhere once you understand the primitives.

v2 API endpoints

Content-addressable blobs

Blobs are stored by SHA256 digest—the hash of the bytes, not the filename. Layer tarballs, image config JSON, and manifest JSON are all blobs. Identical content across repositories deduplicates at storage level. A push uploads only blobs the registry does not already have.

Manifest types

Tags vs digests

# Inspect manifest and resolve digest
docker pull nginx:alpine
docker inspect --format '{{index .RepoDigests 0}}' nginx:alpine

# Pull by immutable digest (not tag)
docker pull nginx@sha256:abc123...

# Query registry API directly
curl -sI -H 'Accept: application/vnd.docker.distribution.manifest.v2+json' \
  https://registry-1.docker.io/v2/library/nginx/manifests/alpine

Official images

Images under the library/ namespace (e.g. nginx, postgres, node) are maintained by Docker or upstream vendors. They follow best practices: minimal layers, regular CVE patches, documented Dockerfiles. Prefer official images over random user repos for base layers.

Rate limits (anonymous vs authenticated)

Login, tag, push, pull workflow

# Authenticate (stores creds in ~/.docker/config.json)
docker login

# Build and tag with your Docker Hub username
docker build -t myuser/myapp:1.0.0 .
docker tag myuser/myapp:1.0.0 myuser/myapp:latest

# Push both tags
docker push myuser/myapp:1.0.0
docker push myuser/myapp:latest

# Pull on another machine
docker pull myuser/myapp:1.0.0

Multi-arch builds with buildx

A single tag can point to a manifest list containing amd64 and arm64 variants. docker buildx cross-compiles and pushes all platforms in one command. Kubernetes and Docker automatically select the correct arch at pull time.

# Create a buildx builder (once)
docker buildx create --name multiarch --use
docker buildx inspect --bootstrap

# Build and push multi-platform image
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t myuser/myapp:1.0.0 \
  --push .

# Verify manifest list
docker buildx imagetools inspect myuser/myapp:1.0.0

Comparison table

Self-hosted Distribution (minimal)

# Run local registry (dev only — no TLS/auth)
docker run -d -p 5000:5000 --name registry registry:2

# Push to insecure local registry (add to daemon.json insecure-registries)
docker tag myapp:latest localhost:5000/myapp:latest
docker push localhost:5000/myapp:latest

Architect decision framework

• Already on AWS/GCP/Azure? — Use the native registry; IAM integration eliminates credential sprawl.
• Multi-cloud or on-prem? — Harbor as a central hub with replication to cloud registries.
• GitHub-centric CI? — GHCR with OIDC eliminates long-lived registry passwords in secrets.
• Artifact diversity? — Nexus if you need Docker + Maven + npm in one proxy/cache layer.

Authentication with get-login-password

# One-time login (token valid 12 hours)
aws ecr get-login-password --region us-east-1 | \
  docker login --username AWS --password-stdin \
  123456789012.dkr.ecr.us-east-1.amazonaws.com

# Create repository
aws ecr create-repository --repository-name myapp --region us-east-1

# Tag and push
docker tag myapp:latest 123456789012.dkr.ecr.us-east-1.amazonaws.com/myapp:latest
docker push 123456789012.dkr.ecr.us-east-1.amazonaws.com/myapp:latest

Lifecycle policies

ECR lifecycle rules automatically expire old images—critical for cost control when every CI run pushes a new tag. Rules filter by tag prefix, age, or count and delete matching manifests.

{
  "rules": [
    {
      "rulePriority": 1,
      "description": "Keep last 30 sha-tagged images",
      "selection": {
        "tagStatus": "tagged",
        "tagPrefixList": ["sha-"],
        "countType": "imageCountMoreThan",
        "countNumber": 30
      },
      "action": { "type": "expire" }
    },
    {
      "rulePriority": 2,
      "description": "Expire untagged images after 7 days",
      "selection": {
        "tagStatus": "untagged",
        "countType": "sinceImagePushed",
        "countUnit": "days",
        "countNumber": 7
      },
      "action": { "type": "expire" }
    }
  ]
}

Image scanning

ECR basic scanning (Clair-based) runs on push when enabled. ECR enhanced scanning uses Amazon Inspector for continuous CVE monitoring across OS and language packages. Findings surface in the console and via EventBridge for pipeline gates.

Cross-account access

Share images across AWS accounts with a repository policy granting ecr:BatchGetImage and ecr:GetDownloadUrlForLayer to a trusted account root or IAM role. EKS nodes in Account B pull from Account A's ECR without duplicating images.

{
  "Version": "2012-10-17",
  "Statement": [{
    "Sid": "AllowCrossAccountPull",
    "Effect": "Allow",
    "Principal": { "AWS": "arn:aws:iam::987654321098:root" },
    "Action": [
      "ecr:GetDownloadUrlForLayer",
      "ecr:BatchGetImage",
      "ecr:BatchCheckLayerAvailability"
    ]
  }]
}

Pull-through cache

ECR pull-through cache rules proxy upstream registries (Docker Hub, Quay, Kubernetes registry, another ECR). First pull fetches and caches upstream; subsequent pulls serve from ECR—reducing Hub rate limits and egress latency.

# Create pull-through rule for Docker Hub (console or CLI)
aws ecr create-pull-through-cache-rule \
  --ecr-repository-prefix docker-hub \
  --upstream-registry-url registry-1.docker.io

# Pull via cache prefix
docker pull 123456789012.dkr.ecr.us-east-1.amazonaws.com/docker-hub/library/nginx:alpine

VPC endpoints

Interface VPC endpoints for ecr.api and ecr.dkr keep image pulls off the public internet. Pair with an S3 gateway endpoint—layer blobs are stored in S3 behind ECR. Private EKS nodes pull images without NAT gateway egress costs.

Cosign (Sigstore)

Cosign signs OCI images with keyless OIDC (GitHub Actions, GitLab) or static keys. Signatures attach as separate artifacts in the registry—no manifest modification. Verification policies gate deploys in Kubernetes (Kyverno, policy-controller) and CI.

# Generate key pair (or use keyless in CI with OIDC)
cosign generate-key-pair

# Sign image after push
cosign sign --key cosign.key myregistry/myapp@sha256:abc123...

# Verify before deploy
cosign verify --key cosign.pub myregistry/myapp@sha256:abc123...

# Keyless signing in GitHub Actions (Fulcio + Rekor)
COSIGN_EXPERIMENTAL=1 cosign sign myregistry/myapp@${{ steps.meta.outputs.digest }}

SBOM generation (Syft) and scanning (Grype)

A Software Bill of Materials (SBOM) lists every package in an image. Syft generates SBOMs in SPDX or CycloneDX format; Grype scans SBOMs or images directly for CVEs. Attach SBOMs as OCI artifacts alongside the image for audit and policy enforcement.

# Generate SBOM from image
syft myapp:latest -o spdx-json > sbom.spdx.json

# Scan image for CVEs
grype myapp:latest --fail-on high

# Attach SBOM to registry (Cosign OCI artifact)
cosign attach sbom --sbom sbom.spdx.json myregistry/myapp:sha256-abc123...

Docker Content Trust (Notary v1)

Docker Content Trust (DCT) signs tags via Notary. Enable with export DOCKER_CONTENT_TRUST=1—unsigned images are rejected on pull. Largely superseded by Cosign in new projects, but still present in Docker Enterprise workflows and ACR content trust.

BuildKit attestations

BuildKit can embed SLSA provenance and SBOM attestations at build time. Attestations are stored as OCI artifacts linked to the image digest—verifiable proof of builder identity, source repo, and build parameters.

# Build with provenance and SBOM attestations
docker buildx build \
  --provenance=true \
  --sbom=true \
  -t myregistry/myapp:1.0.0 \
  --push .

# Inspect attestations
docker buildx imagetools inspect myregistry/myapp:1.0.0 --format '{{json .Attestations}}'

Scanner comparison

Trivy — CLI and CI

# Scan local image
trivy image myapp:latest

# Fail CI on HIGH/CRITICAL CVEs
trivy image --exit-code 1 --severity HIGH,CRITICAL myapp:latest

# Scan filesystem (Dockerfile context before build)
trivy fs --security-checks vuln,secret .

# JSON output for dashboards
trivy image -f json -o results.json myapp:latest

Grype — SBOM-aware scanning

# Scan directly
grype myapp:latest

# Scan from Syft SBOM (reproducible — same SBOM, same results)
syft myapp:latest -o cyclonedx-json | grype

# Gate on critical only
grype myapp:latest --fail-on critical

Docker Scout

docker scout quickview and docker scout compare show CVE counts and recommend smaller or fewer-vulnerable base images. Integrates with Docker Hub and Desktop—useful for developer education, less for hard CI gates.

Shift-left CI scanning pipeline

A mature pipeline scans at multiple stages:

1. Pre-build — trivy fs on Dockerfile + context (secrets, misconfigs)
2. Post-build — trivy image or grype on the built image
3. Post-push — Registry-native scan (ECR Inspector, Harbor Trivy, Docker Scout) for continuous monitoring
4. Pre-deploy — Admission policy rejects images over CVE threshold or without signatures

# GitHub Actions excerpt — build, scan, sign, push
- name: Build image
  run: docker build -t ${{ env.IMAGE }}:${{ github.sha }} .

- name: Scan with Trivy
  uses: aquasecurity/trivy-action@master
  with:
    image-ref: ${{ env.IMAGE }}:${{ github.sha }}
    severity: CRITICAL,HIGH
    exit-code: '1'

- name: Sign with Cosign
  run: cosign sign --yes ${{ env.IMAGE }}@${{ steps.digest.outputs.digest }}