Jonatan Matajonmatum.com
conceptsnotesexperimentsessays
© 2026 Jonatan Mata. All rights reserved.v2.1.1
Concepts

Container Registries

Repositories for storing, versioning, and distributing container images, from public registries like Docker Hub to private registries like ECR.

evergreen#containers#registry#docker#ecr#ghcr#images

What it is

A container registry is a centralized repository for storing, versioning, and distributing Docker container images. It works like npm for Node.js packages or Maven for Java artifacts, but specifically designed for container images that follow the OCI (Open Container Initiative) standard.

Container registries implement the OCI Distribution specification, which defines REST APIs for pushing, pulling, and managing container images. Each image is identified by a repository name and tag, like nginx:1.25 or myapp:v2.1.0. Registries also support SHA256 digest addressing for immutable references.

In modern container-based architectures, the registry acts as the central distribution point between the build process (CI/CD) and runtime environments (Kubernetes, ECS, Docker Swarm). Without a reliable registry, there's no scalable way to distribute containerized applications.

Comparison of major registries

RegistryTypeFree limitsKey featuresUse cases
Docker HubPublic/Private1 private repo, 200 pulls/6hOfficial images, largest ecosystemOpen source projects, prototyping
Amazon ECRPrivate (AWS)500MB/month freeNative ECS/EKS integration, vulnerability scanningAWS applications, enterprise environments
GitHub GHCRPublic/Private500MB freeGitHub Actions integration, SSO authenticationGitHub projects, automated CI/CD
Google Artifact RegistryPrivate (GCP)0.5GB freeMulti-format (Docker, npm, Maven), vulnerability analysisGCP ecosystem, multi-language projects
Azure ACRPrivate (Azure)NoneGeo-replication, Tasks for automated buildsAzure applications, global distribution

Image signing and verification

Modern container security requires verifying image integrity and provenance. Registries support multiple signing mechanisms:

# Sign with cosign (recommended)
cosign sign --key cosign.key myregistry.io/myapp:v1.0.0
 
# Verify before deployment
cosign verify --key cosign.pub myregistry.io/myapp:v1.0.0
 
# Sign with notation (CNCF standard)
notation sign myregistry.io/myapp:v1.0.0
 
# Admission policy in Kubernetes
apiVersion: v1
kind: ConfigMap
metadata:
  name: cosign-policy
data:
  policy.yaml: |
    apiVersion: v1alpha1
    kind: ClusterImagePolicy
    metadata:
      name: require-signature
    spec:
      images:
      - glob: "myregistry.io/**"
      authorities:
      - key:
          data: |
            -----BEGIN PUBLIC KEY-----
            MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE...
            -----END PUBLIC KEY-----

Multi-architecture builds

Modern registries support multi-architecture manifests to distribute the same image to different platforms (AMD64, ARM64, etc.):

# Dockerfile with multi-arch support
FROM --platform=$BUILDPLATFORM node:20-alpine AS builder
ARG TARGETPLATFORM
ARG BUILDPLATFORM
RUN echo "Building on $BUILDPLATFORM for $TARGETPLATFORM"
 
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
 
FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY . .
EXPOSE 3000
CMD ["node", "server.js"]
# Build and push multi-arch with Docker Buildx
docker buildx create --use
docker buildx build --platform linux/amd64,linux/arm64 \
  -t myregistry.io/myapp:v1.0.0 --push .
 
# Registry stores a manifest list that references
# architecture-specific images
docker manifest inspect myregistry.io/myapp:v1.0.0

Mirroring and distribution

For organizations with multiple regions or network restrictions, registries offer mirroring capabilities:

Loading diagram...
# Pull-through cache configuration in ECR
apiVersion: v1
kind: ConfigMap
metadata:
  name: registry-mirror-config
data:
  config.yaml: |
    mirrors:
      docker.io:
        endpoint:
          - https://123456789.dkr.ecr.us-east-1.amazonaws.com
      registry-1.docker.io:
        endpoint:
          - https://123456789.dkr.ecr.us-east-1.amazonaws.com

Retention policies and cleanup

Registries accumulate images quickly. Retention policies automate cleanup:

{
  "rules": [
    {
      "rulePriority": 1,
      "description": "Keep last 10 production images",
      "selection": {
        "tagStatus": "tagged",
        "tagPrefixList": ["v"],
        "countType": "imageCountMoreThan",
        "countNumber": 10
      },
      "action": {
        "type": "expire"
      }
    },
    {
      "rulePriority": 2,
      "description": "Delete untagged images older than 1 day",
      "selection": {
        "tagStatus": "untagged",
        "countType": "sinceImagePushed",
        "countUnit": "days",
        "countNumber": 1
      },
      "action": {
        "type": "expire"
      }
    }
  ]
}

CI/CD pipeline integration

Registries are critical components in modern CI/CD pipelines:

# GitHub Actions with GHCR
name: Build and Push
on:
  push:
    branches: [main]
 
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      
      - name: Login to GHCR
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      
      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: |
            ghcr.io/${{ github.repository }}:latest
            ghcr.io/${{ github.repository }}:${{ github.sha }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

Why it matters

The choice of container registry directly affects deployment speed, security, and operational costs. A poorly configured registry can become a bottleneck that slows down all deployments, especially in microservices architectures with dozens of services.

Platform teams must consider network latency (registries close to clusters), security capabilities (vulnerability scanning, image signing), and integration with existing tools. A private registry is essential for enterprise applications, but adds operational complexity that must be managed proactively.

The trend toward managed registries (ECR, GHCR, Artifact Registry) reduces operational burden, but introduces vendor dependencies that must be evaluated against the benefits of automatic availability and scalability.

References

  • Amazon ECR — AWS, 2024. Official documentation for AWS container registry.
  • Docker Hub | Docker Docs — Docker, 2024. Complete guide to the most widely used container registry.
  • Working with the Container registry - GitHub Docs — GitHub, 2024. Official GitHub Container Registry documentation.
  • GitHub - opencontainers/distribution-spec: OCI Distribution Specification · GitHub — OCI, 2024. Standard specification for container registry APIs.
  • Cosign - Sigstore — Sigstore, 2024. Tool for container image signing and verification.
  • Artifact Registry documentation | Google Cloud Documentation — Google Cloud, 2024. Google Cloud's multi-format registry.
  • Continuous Integration — Martin Fowler, 2006. Foundational article on continuous integration and artifacts.

Related content

  • Docker

    Container platform that packages applications with all dependencies into portable, consistent units that run identically in any environment.

  • CI/CD

    Continuous Integration and Continuous Delivery/Deployment — practices that automate code integration, testing, and delivery to production. Foundation of modern software engineering.

  • Container Security

    Practices and tools for securing containers throughout their lifecycle: image building, runtime, orchestration, and compliance.

  • Terraform AWS Serverless Modules

    Collection of 13 Terraform modules published on the Terraform Registry for deploying serverless architectures on AWS, with 12 examples covering basic ECS to full-stack CRUD with DynamoDB and AgentCore with MCP.

  • Kubernetes

    Container orchestration platform that automates deployment, scaling, and management of containerized applications at scale, becoming the de facto standard for cloud native.

Concepts