Introduction

When registries make sense

A container registry is essential when you are building and deploying containerized applications. If your CI/CD pipeline produces Docker images, you need somewhere to store them between the build step and the deployment step. Even for small projects, a registry gives you a versioned history of your images that you cannot get from local Docker storage.

Use a registry when you need image promotion between environments. An image built once in the CI pipeline should flow from dev to staging to production without rebuilding. The registry holds the canonical artifact at each stage.

For teams with multiple services, a shared registry lets different pipelines pull base images and intermediate layers without repeatedly downloading from public sources. This speeds up builds and reduces external dependencies.

The line is when you start deploying to anything beyond your local machine. If your pipeline produces an image and that image needs to run somewhere else — a staging server, a Kubernetes cluster, a colleague’s machine — you need a registry. Local Docker storage does not survive past the machine that built it.

For solo projects or experiments that never leave your local Docker context, you can skip a registry entirely. Run docker build && docker run and you are done. The moment you want to share an image or deploy it to a remote environment, that changes. A registry is not a luxury you add when you have many services; it is infrastructure you need as soon as you have more than one environment.

When to skip or simplify

If your application is not containerized and never will be, a container registry does not add value. Some projects are better served by plain artifact storage (S3, GCS) for JARs, binaries, or Helm charts.

For personal projects or experiments that never leave your local machine, running a local registry or skipping one entirely makes sense. You can always add a registry later when the project grows.

The clearest case for skipping a registry is non-containerized workloads. If your artifact is a compiled binary, a Helm chart, or a zip file that gets deployed via a different mechanism, a container registry is the wrong tool. Store those in S3 or GCS with lifecycle policies.

There is also the case of genuinely experimental work. A spike to validate whether a particular base image works for your application does not need a production-grade registry with replication and access controls. You can build and run locally, then push to a registry once the approach is validated. The registry is a deployment infrastructure concern, not a development infrastructure concern.

What I watch out for is the trap of thinking you will add a registry later “when the project grows.” In practice, adding a registry retroactively means changing every CI job that pushes images and every deployment that pulls them. It is easier to start with a basic registry setup and simplify it if it turns out you do not need it than to retrofit one later.

Registry Architecture Flow

flowchart LR
    A[Developer] -->|docker build| B[CI Pipeline]
    B -->|docker push| C[Container Registry]
    C -->|docker pull| D[Staging Cluster]
    C -->|docker pull| E[Production Cluster]
    F[Scanner] -->|periodic scan| C

Registry Options

Cloud-provider registries:

Provider	Service	Notes
AWS	ECR	Integrated with IAM, VPC endpoints
Azure	ACR	Geo-replication, webhook integration
GCP	GCR	Integrated with Cloud Build, IAM
Google	Artifact Registry	Successor to GCR, multi-format

Self-hosted options:

Registry	Best For
Harbor	Enterprise with authentication, replication
GitLab Container Registry	GitLab-integrated deployments
Docker Hub	Public images, simple needs
ChartMuseum	Helm charts alongside images

AWS ECR example:

# Create ECR repository
aws ecr create-repository \
  --repository-name myapp/backend \
  --image-scanning-configuration scanOnPush=true \
  --encryption-configuration encryptionType=AES256

# Login to ECR
aws ecr get-login-password --region us-east-1 | \
  docker login --username AWS --password-stdin 123456789.dkr.ecr.us-east-1.amazonaws.com

# Push image
docker build -t myapp/backend:1.0.0 .
docker push 123456789.dkr.ecr.us-east-1.amazonaws.com/myapp/backend:1.0.0

Azure ACR example:

# Create ACR
az acr create \
  --resource-group mygroup \
  --name myregistry \
  --sku Standard \
  --location eastus

# Enable admin user
az acr update -n myregistry --admin-enabled true

# Login and push
az acr login --name myregistry
docker build -t myregistry.azurecr.io/myapp:1.0.0 .
docker push myregistry.azurecr.io/myapp:1.0.0

Image Tagging Strategies

Tags identify image versions and control which code deploys where.

Common tagging patterns:

Pattern	Example	Use Case
Git SHA	a1b2c3d	Precise traceability
Semantic version	1.2.3	Releases
Date-time	202603251430	CI/CD timestamps
latest	latest	Default, avoid for prod
Environment	prod, staging	Environment promotion

Recommended strategy for production:

# Always tag with multiple identifiers
IMAGE="myregistry.azurecr.io/myapp/backend"

# SHA for exact traceability
docker build -t $IMAGE:sha-$(git rev-parse --short HEAD)

# Semantic version from tag
docker build -t $IMAGE:$(cat VERSION)

# Date-time for CI builds
docker build -t $IMAGE:$(date +%Y%m%d%H%M%S)

# Don't use :latest in production manifests
# Instead:
kubectl set image deployment/myapp backend=$IMAGE:sha-a1b2c3d

Immutable tags for releases:

# Helm values for production deployment
image:
  repository: myregistry.azurecr.io/myapp/backend
  tag: "v1.2.3" # Immutable once released
  pullPolicy: IfNotPresent # Only pulls if not present

Vulnerability Scanning

Integrate scanning into your pipeline to catch vulnerabilities before deployment.

Trivy in CI/CD:

# GitHub Actions
- name: Run Trivy vulnerability scanner
  uses: aquasecurity/trivy-action@master
  with:
    image-ref: myregistry.azurecr.io/myapp:${{ github.sha }}
    format: "sarif"
    output: "trivy-results.sarif"
    severity: "CRITICAL,HIGH"
    exit-code: "1" # Fail on critical vulnerabilities

- name: Upload Trivy results to GitHub Security tab
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: "trivy-results.sarif"

Harbor scanning:

Harbor integrates Trivy and other scanners natively. Configure in /etc/harbor/harbor.yml:

# Enable CVE prevention
vulnerability:
  severity: # Reject push if severity >= this level
    - high
    - critical
  stop_uploading: true
  stop_downloading: true
  update_bulk: "1h"

Gatekeeper policy:

# OPA Gatekeeper constraint for image signatures
apiVersion: constraints.gatekeeper.sh/v1beta1
kind: K8sRequiredImageTag
metadata:
  name: require-tag
spec:
  match:
    kinds:
      - apiGroups: [""]
        kinds: ["Pod"]
  parameters:
    namespaces: ["production"]
    exemptImages:
      - "myregistry.azurecr.io/base-image:*"

Image Promotion Between Environments

Promote images through environments with validation at each stage.

GitLab CI image promotion:

stages:
  - build
  - scan
  - staging
  - production

build:
  stage: build
  script:
    - docker build -t $IMAGE:build-$CI_COMMIT_SHA .
    - docker push $IMAGE:build-$CI_COMMIT_SHA

scan:
  stage: scan
  script:
    - trivy image --exit-code 1 --severity HIGH,CRITICAL $IMAGE:build-$CI_COMMIT_SHA
  allow_failure: false

promote:staging:
  stage: staging
  script:
    - docker tag $IMAGE:build-$CI_COMMIT_SHA $IMAGE:staging-$CI_COMMIT_SHA
    - docker push $IMAGE:staging-$CI_COMMIT_SHA
    - curl -X POST "https://argo.example.com/api/v1/apps/myapp/sync" \
      -d '{"prune":true,"dryRun":false}'
  only:
    - main

promote:production:
  stage: production
  script:
    - docker tag $IMAGE:build-$CI_COMMIT_SHA $IMAGE:production-$CI_COMMIT_SHA
    - docker push $IMAGE:production-$CI_COMMIT_SHA
    -  # Update deployment manifests or trigger ArgoCD
  when: manual
  only:
    - main

Digest-based promotion for immutability:

# Get image digest
DIGEST=$(docker inspect --format='{{index .RepoDigests 0}}' myregistry.azurecr.io/myapp:1.0.0)
echo $DIGEST
# Output: myregistry.azurecr.io/myapp@sha256:abc123...

# Deploy by digest (immutable)
docker run myregistry.azurecr.io/myapp@sha256:abc123...

Registry Caching for Faster Builds

Cache images to reduce build times and external dependencies.

GitHub Actions cache for Docker:

- uses: docker/setup-buildx-action@v3
  with:
    driver-opts: |
      image=moby/buildkit:buildx-stable
      network=host

- uses: docker/build-push-action@v5
  with:
    push: true
    tags: myregistry.azurecr.io/myapp:${{ github.sha }}
    cache-from: type=gha
    cache-to: type=gha,mode=max

Registry mirror for air-gapped environments:

# Deploy a pull-through cache
helm install registry-cache stable/docker-registry \
  --set pullThrough.enabled=true \
  --set cache.remoteURL=https://registry-1.docker.io

# Configure Docker daemon on nodes
# /etc/docker/daemon.json
{
  "registry-mirrors": ["https://cache.mycorp.example.com"]
}

Access Control and Authentication

Control who can push, pull, and manage images.

AWS ECR IAM policies:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::123456789:role/deploy-role"
      },
      "Action": [
        "ecr:GetDownloadUrlForLayer",
        "ecr:BatchGetImage",
        "ecr:BatchCheckLayerAvailability"
      ]
    },
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::123456789:role/ci-service-account"
      },
      "Action": ["ecr:*"]
    }
  ]
}

Azure RBAC for ACR:

# Reader role for production pods
az role assignment create \
  --assignee-object-id $(kubectl get serviceaccount default -n production -o jsonpath='{.metadata.uid}') \
  --role AcrPull \
  --scope /subscriptions/.../resourceGroups/mygroup/providers/Microsoft.ContainerRegistry/registries/myregistry

# Contributor for CI/CD pipelines
az role assignment create \
  --assignee $CI_SERVICE_PRINCIPAL_ID \
  --role Contributor \
  --scope /subscriptions/.../resourceGroups/mygroup/providers/Microsoft.ContainerRegistry/registries/myregistry

Kubernetes image pull secrets:

# Create image pull secret
kubectl create secret docker-registry acr-secret \
  --docker-server=myregistry.azurecr.io \
  --docker-username=myuser \
  --docker-password=$(az keyvault secret show --name acr-password --vault-name myvault -o tsv --query value) \
  --docker-email=myuser@example.com

# Reference in service account
apiVersion: v1
kind: ServiceAccount
metadata:
  name: myapp-sa
  namespace: production
imagePullSecrets:
  - name: acr-secret

Production Failure Scenarios

Common Registry Failures

These failures show up most often in registry postmortems. The table captures the immediate impact and a short-term fix, but each one has deeper causes worth understanding before your pipeline hits them.

Failure	Impact	Mitigation
Registry authentication token expired	Cannot pull or push images, deployments fail	Use service accounts with rotating credentials
Image not found after tag deletion	Deployment tries to pull deleted image	Never delete tags in production, use immutable tags
Quota exceeded on cloud registry	Cannot push new images	Monitor storage usage, set lifecycle policies
Network partition to registry	Builds cannot push, deployments cannot pull	Use multi-region replication, local registry cache
Vulnerability scan blocking deploys	Critical CVE stops production deployment	Define triage process for CVEs, do not scan blindly

Token expiry is the most common because it is the most invisible. Service accounts with long-lived credentials work fine for months, then fail at the worst possible moment — during a production incident when someone is already stressed and debugging a deployment. Use workload identity or OIDC federation instead, so credentials rotate automatically without any human involvement.

Tag deletion seems like good hygiene when a CI pipeline clears out old build tags to save space. The problem is that production deployments often reference those tags indirectly — a canary pointing to myapp:staging-latest or a Helm release resolving myapp:{{ .Values.imageTag }} at install time. Delete the tag, and the next deployment fails even though the image itself is still there.

Quota errors are predictable if you monitor for them. Cloud registries charge per storage byte and per API call, and both have hard limits. Set a storage alert at 80% of your quota and run cleanup before you hit the wall. Teams usually find out about quota issues the hard way — when a release pipeline stops working and they have to delete images under pressure.

Image Pull Failures

flowchart TD
    A[Pod Schedule] --> B{Pull Image}
    B -->|Success| C[Pod Starts]
    B -->|Fail| D{Error Type}
    D -->|Image Not Found| E[Check tag exists in registry]
    D -->|Auth Failed| F[Refresh pull secret]
    D -->|Quota Exceeded| G[Delete old images]
    E --> H[Redeploy]
    F --> H
    G --> H

Observability Hooks

What to monitor:

• Image push success/failure rate
• Pull request latency by region
• Storage consumption growth rate
• Vulnerability scan results trend
• Authentication failure spikes

# AWS ECR - check repository size
aws ecr describe-repositories --query 'repositories[].{name:repositoryName,size:imageScanningConfiguration.scanOnPush}'

# Azure ACR - check usage
az acr show-usage --name myregistry

# Docker Hub - check rate limits
curl -s -o /dev/null -w "%{http_code}" https://hub.docker.com/v2/

Common Pitfalls / Anti-Patterns

Using the :latest tag in production manifests

When your manifest references myapp:latest, you have no idea which image actually deployed. If you need to roll back, you cannot because :latest keeps changing. Always use specific immutable tags (commit SHA, semantic version, or date-based).

The core problem with :latest is that it severs the link between your source code and your running deployment. Your CI pipeline builds an image and pushes it with a tag. Minutes later, someone else pushes a different image with the same :latest tag. By the time your deployment picks up that image, it could be running code from a completely different commit — or even a different branch. Rolling back becomes impossible because you cannot tell which image :latest pointed to at any given time.

Consider a real incident: a team deploys using :latest, and hours later their production is broken. They run kubectl rollout undo expecting to restore the previous version, but the previous “version” is whatever someone happened to push last. There is no version history to fall back on. The fix requires manually identifying the last known good SHA and retagging, which takes far longer than a simple git revert.

The solution is straightforward: tag every image with an immutable identifier tied to your source. Commit SHA tags (sha-abc1234) give you exact traceability — if a deployment fails, you know exactly which commit caused it. In your Kubernetes manifests, reference that SHA directly:

# In your CI pipeline, extract and embed the SHA
IMAGE="myregistry.azurecr.io/myapp/backend"
SHA=$(git rev-parse --short HEAD)
docker build -t $IMAGE:sha-$SHA .
docker push $IMAGE:sha-$SHA

# In your Helm values or kustomization overlay
image:
  tag: "sha-abc1234"  # Immutable, tied to git commit

If you must use environment-based tags, reserve those for promotion workflows (staging, production) rather than as a substitute for immutable versioning. The rule: production manifests should never reference a tag that can be overwritten.

Not scanning images before deployment

Pushing unscanned images to production means you discover vulnerabilities after they are running. Integrate Trivy or similar scanners into your CI pipeline and block pushes when critical CVEs are found.

Without scanning, a known CVE sits quietly in your base image while the CI pipeline builds and pushes your app image, the deployment rolls out, and hours later a security audit surfaces the problem — requiring an emergency patch rollout to an already-deployed fleet.

A scanning step runs after the build and push. Trivy pulls the image manifest, downloads each layer, and matches packages against CVE databases (NVD, RHEL, Debian security advisories). Severity thresholds determine when a scan fails the build.

# GitHub Actions - scan before promoting
scan:
  stage: scan
  script:
    - trivy image \
      --severity CRITICAL,HIGH \
      --exit-code 1 \
      --ignore-unfixed \
      myregistry.azurecr.io/myapp:$CI_COMMIT_SHA
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

Blocking thresholds depend on your risk tolerance. A typical setup blocks on CRITICAL findings in any environment, blocks on HIGH in production, and logs MEDIUM/LOW for weekly triage. When a critical CVE has no patch, you can pin to an older base image that predates the vulnerability, apply a vendor mitigation if one exists, or document an exception with sign-off from your security team — not just the deployment team.

Existing images need rescanning too. New CVEs drop daily, and an image that was clean last week might not be today. Both Harbor and ECR support automatic rescanning when vulnerability databases update. Wire up notifications so your team hears about new critical findings before an auditor does.

Leaving unused images in the registry

Old images accumulate and consume storage. Without lifecycle policies, your registry bill grows while nobody knows which images are actually in use. Set up retention policies that delete images not referenced by any deployment.

Images pile up because every CI run produces a tag, and feature branches generate dozens per day. A repository that started with 10 images can easily have 500 within a quarter. Most of those tags never see a deployment — abandoned branches, failed runs after the push step. Every layer is stored, and the bill grows quietly until you actually look.

Lifecycle policies handle this:

AWS ECR lifecycle policies use rule-based filtering. You can target untagged images older than a certain number of days, or images with a tag prefix that no longer matches any active deployment:

# Create lifecycle policy - expire untagged images after 14 days
aws ecr put-lifecycle-policy \
  --repository-name myapp/backend \
  --lifecycle-policy-text '{
    "rules": [{
      "rulePriority": 1,
      "description": "Expire untagged images",
      "selection": {
        "tagStatus": "untagged",
        "countType": "sinceImagePushed",
        "countUnit": "days",
        "countNumber": 14
      },
      "action": {"type": "expire"}
    }]
  }'

Azure ACR lifecycle policies support similar rules with tag-based filtering. You can preserve release tags (matching v*) while expiring build tags (matching build-*):

az acr task create \
  --name image-cleanup \
  --registry myregistry \
  --cmd myregistry.azurecr.io/myapp:placeholder \
  --schedule "0 9 * * *" \
  --context /dev/null

# Purge policy via ACR task
az acr config task update \
  --name image-cleanup \
  --cmd "acr purge --filter 'myapp:build-.*' --ago 7d"

Harbor supports lifecycle rules through its UI and API, with options to retain by tag suffix, count, or days since last pull.

Auditing unused images: Before applying any cleanup policy, identify what is actually in use. Query your deployment records to find which tags or digests your Kubernetes clusters are running. Cross-reference against your registry inventory — anything not in a deployment record is a candidate for deletion.

# ECR - list untagged images with age
aws ecr list-images \
  --repository-name myapp/backend \
  --filter '{"tagStatus": "UNTAGGED"}' \
  --query 'imageIds[*].[imagePushedAt,imageDigest]' \
  --output table

# Harbor - API to list repositories and their usage
curl -s "https://harbor.mycorp.com/api/v2/projects/myapp/repositories" \
  -H "Authorization: Bearer $TOKEN" | jq '.[] | {name, tags_count}'

Beyond storage, a repository with tens of thousands of images gets slow to query — CI pipelines that call the registry for the latest tag start timing out. Cleanup keeps operations fast at scale.

Mixing image sources in one pipeline

Using Docker Hub for base images, your private registry for app images, and a third-party registry for dependencies makes it hard to track where each piece comes from. Keep a clear lineage from build to registry to deployment.

Fragmented sources add external dependencies with their own failure modes. Docker Hub goes down during a critical deploy and your pipeline fails — even though your app image is fine in ACR. A third-party registry retires an image version and your builds break silently.

Fragmented sources also kill traceability. When your pipeline pulls node:18-alpine from Docker Hub today, that tag could point to a different image next month as patches ship. Your production image changes without any code change on your end. You no longer know what is running.

The fix is straightforward: mirror public images into your private registry during infrastructure setup, not during the application pipeline. Your CI then pulls everything from one place.

# Mirror a public image into your private registry
docker pull docker.io/library/node:18-alpine
docker tag node:18-alpine myregistry.azurecr.io/base/node:18-alpine
docker push myregistry.azurecr.io/base/node:18-alpine

# Configure registry mirror in daemon for air-gapped environments
# /etc/docker/daemon.json
{
  "registry-mirrors": ["https://myregistry.azurecr.io"]
}

Tag pinning for reproducibility: Beyond keeping sources centralized, pin the full image reference — registry, repository, tag, and digest — in your build files. A node:18-alpine tag is mutable; myregistry.azurecr.io/base/node:18-alpine@sha256:abc123 is not. When you pin by digest, the exact content is guaranteed regardless of when you pull.

If a scanner tool is only available from a vendor’s registry, pull it once during infrastructure setup and store the image in your private registry. Your CI references the internal copy. The vendor’s registry is no longer on your critical path.

Forgetting about cross-region replication

If your production cluster is in us-west-2 but your registry is only in us-east-1, every image pull crosses the country. Configure replication for the regions where your clusters run.

Image pulls mean manifest fetches and layer downloads. A manifest is a few kilobytes; layers can be hundreds of megabytes. If your registry is in us-east-1 and your cluster is in us-west-2, every layer download crosses the continental US. A 500MB image with 10 layers means 5GB of cross-country traffic per deploy — multiplied across every replica. A rolling update of 20 replicas pulls 100GB across regions, plus egress charges, plus latency spikes that can timeout fast rollouts.

Provider-specific replication options:

Provider	Replication Method	Configuration
AWS ECR	Multi-region replication via same repository	Enable in repository settings, replicate to selected regions
Azure ACR	Geo-replication to paired regions	Enable during creation or via --geo-replication-enabled
GCP Artifact Registry	Multi-region repositories	Create repository in us-west1 and us-east1 separately
Harbor	Replication policies between Harbor instances	Configure push or pull replication rules per project

# AWS ECR - enable cross-region replication
aws ecr create-repository \
  --repository-name myapp/backend \
  --image-scanning-configuration scanOnPush=true \
  --encryption-configuration encryptionType=AES256 \
  --region us-west-2  # Separate repository in target region

# Azure ACR - enable geo-replication
az acr create \
  --resource-group mygroup \
  --name myregistry \
  --sku Standard \
  --location eastus

az acr update -n myregistry --geo-replications eastus2,westus

# Verify replication status
az acr replication list -r myregistry --query '[].{region:location,status:status}'

Pull-through cache as an alternative: If multi-region replication is too expensive or complex, deploy a pull-through cache in each region. The cache mirrors images on first pull, so subsequent pulls are local. This is especially useful for base images that change infrequently — you pay the cross-region cost once, then all subsequent pulls are local.

# Harbor pull-through cache configuration
# /etc/harbor/harbor.yml
registry:
  # Pull-through cache for Docker Hub
  relativeurl: /proxy
  storage_driver: s3
 :

Replication lags. An image pushed to the primary region takes time to appear in secondaries — if your deployment automation races ahead of replication, it pulls a missing image. Monitor replication status and gate deployments on image availability in the target region.

Trade-off Analysis

Registry	Hosted vs Self-Hosted	Auth	Cost	Best For
Docker Hub	Both	Docker Auth	Free tier / paid	Open source images
ECR	Cloud-hosted	IAM	Pay per storage + egress	AWS workloads
GCR / Artifact Registry	Cloud-hosted	IAM + VMDF	Pay per storage + egress	GCP workloads
ACR	Cloud-hosted	IAM + admin keys	Pay per storage + egress	Azure workloads
Harbor	Self-hosted	OIDC, LDAP, local	Infrastructure cost	Enterprise / air-gapped
GitHub Packages	Cloud-hosted	GitHub token	Storage + bandwidth	GitHub-native workflows
GitLab Container Registry	Cloud-hosted	GitLab token	Storage + bandwidth	GitLab-native workflows

Interview Questions

Further Reading

Official Documentation

Vendor documentation is the ground truth when the CLI flags or UI screens described here stop matching reality. Check these links before filing an issue or assuming something is broken.

• Docker Registry Documentation - Self-hosted registry setup, configuration options for storage backends, authentication, and notifications
• Harbor Documentation - Enterprise registry with replication, CVE scanning via Trivy, and OIDC-based authentication
• AWS ECR Documentation - Cloud-native image registry with IAM integration, lifecycle policies, and multi-region replication
• Azure ACR Documentation - Container registry on Azure with geo-replication, webhook triggers, and Azure RBAC integration

Related Guides

The registry sits between your CI pipeline and your clusters. These guides cover the adjacent pieces — what happens before you push an image, and what happens after you pull one.

• CI/CD Pipeline Design - Pipeline architecture patterns that complement registry setup, including multi-stage pipelines with gated promotion and artifact passing between stages
• Deployment Strategies - Deployment patterns and rollout strategies that work with immutably-tagged images, including blue-green and canary deployments
• Automated Testing in CI/CD - Testing strategies and quality gates, including where vulnerability scanning fits in a pipeline relative to unit and integration tests

Tools and References

Trivy and Clair both scan for CVEs but pull from different databases with different update cadences. Cosign is a different animal — it solves the trust problem, not the vulnerability problem. Knowing which tool does which keeps you from reaching for the wrong one at 2am.

• Trivy - Vulnerability scanner for containers and infrastructure as code, used in this guide for CI integration and Harbor’s built-in scanning
• Clair - Static vulnerability analysis for containers, originally developed by CoreOS and now maintained by Quay; different CVE database update cadence than Trivy
• Cosign - Container image signing and verification as part of Sigstore’s keyless signing workflow; pairs with OPA Gatekeeper or Kyverno for admission control
• OPA Gatekeeper - Policy enforcement for Kubernetes that can validate image signatures, enforce tag constraints, and require vulnerability scan results before deployment

Conclusion

Key Takeaways

A few themes show up again and again when I look at registry incidents.

First: immutability. Every other practice in this guide depends on the image your pipeline built being the same image that runs in production. That guarantee breaks when you use mutable tags, store credentials in plain text, or skip vulnerability scanning because the pipeline is already slow enough. Tags are the contract between your build and your deployment — make that contract immutable.

Second: scanning. A CVE in a base image affects every deployment that uses it. Running Trivy in CI catches some of those. Policy gates that actually block critical CVEs from reaching production are what take you from checking a box to reducing risk.

Third: credentials. Rotating long-lived passwords or managing Docker Hub credentials across a cluster is overhead that cloud IAM eliminates. Use workload identity or OIDC federation and credentials take care of themselves.

Fourth: replication. Teams that treat multi-region replication as a performance optimization usually end up learning what it is actually for — infrastructure resilience — during an outage.

Run the checklist below to see where you stand on each of these.

Registry Health Checklist

Run these before a production deployment or as part of a regular health check. Treat failures here as blockers, not warnings.

The examples use ACR and ECR syntax. Swap the CLI and flags for your provider — what each command checks stays the same.

# Verify you can pull your production image
docker pull myregistry.azurecr.io/myapp:prod && echo "Pull successful"

# Check for critical CVEs before deploying
trivy image --severity CRITICAL,HIGH myregistry.azurecr.io/myapp:v1.2.3

# List unused images (older than 90 days)
aws ecr list-images --repository-name myapp --filter '{"tagStatus": "UNTAGGED"}'

# Verify pull secret works in Kubernetes
kubectl get secret acr-secret --output jsonpath='{.data.\.dockerconfigjson}' | base64 -d

Run the pull check first when a deployment fails. If docker pull works but your pod doesn’t start, look at Kubernetes config, not the registry.

Run the Trivy scan against the exact tag you plan to deploy. Scanning :latest or a staging tag while deploying something different doesn’t verify anything.

Unused image audits catch accumulation before it hits your quota. Run monthly, and watch your storage growth rate — a CloudWatch alarm or equivalent keeps you from getting surprised.

The Kubernetes pull secret check catches expired credentials before they show up as ImagePullBackOff in production. If the decoded secret looks stale, refresh it before your next deployment window.