Registries Basics

A container registry stores and serves OCI images, and this page covers the everyday commands and hygiene for running private registries like Harbor, ECR, ACR, and GCR/Artifact Registry.

You build and push with Docker; on nodes, containerd via the CRI pulls and runs those same images.

Prerequisites

• Docker Engine 29.6.1 with BuildKit (default) for building and pushing.
• A registry you can push to: Harbor, AWS ECR, Azure ACR, or Google Artifact Registry.
• kubectl against a cluster running Kubernetes 1.36.2 (nodes use containerd via the CRI).
• Optional CLIs for cloud registries: aws, az, or gcloud.

Basic Examples

1. Anatomy of an image reference

Every pull or push resolves a reference made of registry, repository, and tag or digest.

# registry-host / repository : tag
harbor.example.com/team-a/api:1.4.0
 
# registry-host / repository @ digest (immutable)
harbor.example.com/team-a/api@sha256:9b2c...e1

• The host defaults to Docker Hub when omitted, which you rarely want in production.
• The repository is the path to a specific image within the registry.
• A tag is mutable; a @sha256: digest names exact, immutable bytes.
• Pulling by digest guarantees the same content every time.

2. Log in to a private registry

Authenticating writes a credential the Docker client reuses for later pushes and pulls.

docker login harbor.example.com -u ci-robot
# password or token is read from stdin when piped

• Credentials are stored in ~/.docker/config.json by default.
• Use a robot or service account, not a human login, for CI.
• Cloud registries mint short-lived tokens instead (see examples 6 and 7).

3. Tag and push an image

A push uploads only the layers the registry does not already have.

docker build -t harbor.example.com/team-a/api:1.4.0 .
docker push harbor.example.com/team-a/api:1.4.0

• The build tag must include the registry host to push there.
• BuildKit deduplicates layers, so repeated pushes are fast.
• Record the digest printed on push for immutable deploys.
• The repository is created on first push in most registries, subject to your permissions.

4. Pull by digest for reproducibility

Pinning the digest removes any ambiguity about which bytes you run.

docker pull harbor.example.com/team-a/api@sha256:9b2c...e1

• The same digest always resolves to identical content.
• Use this form in Kubernetes manifests for production workloads.
• Digests are safe to share across environments and clusters.

5. Inspect a manifest without pulling layers

docker buildx imagetools reads the manifest directly from the registry.

docker buildx imagetools inspect harbor.example.com/team-a/api:1.4.0

• Shows platforms in a multi-arch index (for example linux/amd64, linux/arm64).
• Reveals the digest each tag currently points to.
• Lists attached attestations such as SBOMs and provenance when present.
• Useful in CI to resolve a tag to its digest before deploying.

6. Authenticate to AWS ECR

ECR issues a temporary token that Docker uses as a password.

aws ecr get-login-password --region us-east-1 \
  | docker login --username AWS --password-stdin \
    123456789012.dkr.ecr.us-east-1.amazonaws.com

• The token is short-lived, so this runs at the start of a CI job.
• ECR repositories are private by default.
• IAM policy controls who can push versus pull.

7. Authenticate to Google Artifact Registry

gcloud configures Docker to use your Google credentials as a helper.

gcloud auth configure-docker us-docker.pkg.dev
docker push us-docker.pkg.dev/my-project/team-a/api:1.4.0

• The credential helper refreshes tokens automatically.
• Artifact Registry replaces the older Container Registry (gcr.io).
• Repositories are regional, so pick a region near your cluster.

Intermediate Examples

8. Use an image in Kubernetes with a pull secret

Private images need a Secret referenced by the pod's imagePullSecrets.

apiVersion: v1
kind: Pod
metadata:
  name: api
spec:
  imagePullSecrets:
    - name: harbor-creds
  containers:
    - name: api
      image: harbor.example.com/team-a/api@sha256:9b2c...e1

• Create the secret with kubectl create secret docker-registry harbor-creds ....
• The kubelet passes the credential to containerd at pull time.
• Digest-pinned images make rollouts deterministic.
• Bind the secret to a ServiceAccount to avoid repeating it per pod.

9. Enable immutable tags and retention in Harbor

Registry-side policy stops tags from being overwritten and cleans old images.

# Harbor: project settings enforce these, or via API
# 1. Enable "Immutable tags" rules (for example match "v*")
# 2. Add a tag retention policy: keep last 10 pulled per repository

• Immutable tag rules reject a push that would move an existing tag.
• Retention policies bound storage growth from CI churn.
• Combine with a vulnerability scan gate to block unsafe pulls.
• Similar features exist as ECR lifecycle policies and ACR retention.

10. Scan an image before promoting it

Scanning catches known CVEs before an image reaches production.

trivy image --severity HIGH,CRITICAL \
  harbor.example.com/team-a/api:1.4.0

• Fail the CI job on HIGH or CRITICAL findings you have not accepted.
• Harbor, ECR, and ACR also offer built-in scanning on push.
• Rescan periodically, since new CVEs appear for images already published.
• Pair scanning with SBOMs for faster triage when a CVE lands.
• Treat scanning as a gate in CI, not just a report you read later.

11. Practice private-registry hygiene

A few habits keep a private registry secure, cheap, and reliable across Harbor, ECR, ACR, and Artifact Registry.

• Keep repositories private by default and grant pull access per namespace or team.
• Enable server-side vulnerability scanning so every push is checked automatically.
• Set retention or lifecycle rules to expire untagged and stale images.
• Run a pull-through cache for public bases to survive upstream outages and rate limits.
• Store signatures and SBOMs alongside images so trust metadata travels with the digest.

Stack versions: This page was written for Kubernetes 1.36.2, Docker Engine 29.6.1 (BuildKit default), containerd (CRI runtime on nodes), Helm 3, Compose v2, Argo CD (latest - verify at build), and Gateway API (GA - verify controller support at build).