Registries and Image Distribution

Introduction

Container images are useful only when they can be stored, identified, retrieved, verified, and delivered reliably to the environments that run them. A registry is the distribution service that performs these functions. It provides repositories for images, supports authentication and authorization, stores immutable content, and exposes interfaces used by Docker, containerd, Kubernetes, CI/CD systems, and security tools.

In a small development project, an engineer may build an image locally and run it directly. In professional DevOps, however, images move through a controlled supply chain: source code is built, an image is tested, the image is stored in a registry, and an approved version is promoted to staging or production. This process must address naming, tagging, access control, vulnerability management, provenance, retention, availability, and rollback.

This chapter explains how public and private registries operate and how to design practical image-distribution workflows.

Learning Objectives

By the end of this chapter, you should be able to:

• distinguish registries, repositories, images, manifests, and layers;
• use image names, tags, and digests correctly;
• compare public and private registries;
• configure authentication and repository permissions safely;
• design tagging, promotion, retention, and cleanup policies;
• explain image provenance, signing, and verification;
• diagnose common distribution failures; and
• construct a reliable image-promotion workflow.

1. The Registry as a Distribution System

A container registry is a server-side repository for container artifacts. It normally implements the OCI Distribution Specification or the compatible Docker Registry HTTP API. Examples include Docker Hub, GitHub Container Registry, Amazon Elastic Container Registry, Google Artifact Registry, Azure Container Registry, Harbor, and self-hosted registry installations.

The terms below describe different layers of the system:

An image reference commonly has the form:

registry.example.com/team/application:release-2025-03

The registry host is registry.example.com, the repository is team/application, and the tag is release-2025-03. If no registry host is written, Docker commonly interprets a reference such as ubuntu:24.04 as an image obtained from Docker Hub.

A registry does not usually store each image as one large file. Layers are stored independently and are reused when images share common base content. This reduces storage and transfer time. When a client pulls an image, it first obtains the manifest, then downloads the configuration and layers it does not already possess.

2. Manifests, Layers, and Content Addressability

A manifest records the media type, configuration descriptor, and layer descriptors. Each descriptor includes a digest and size. The digest is calculated from the content, so the same content produces the same identifier. This property enables deduplication and integrity checking.

A simplified image relationship is:

Image reference
      |
      v
Tag or digest --> Manifest / image index
                       |
             ---------------------
             |         |         |
          Config    Layer 1   Layer 2 ...

A tag is convenient for people but is not inherently immutable. A repository administrator can move latest from one manifest to another. A digest, by contrast, identifies a particular content object. Therefore, a deployment specification should preferably record an image by digest, for example:

registry.example.com/acme/payments@sha256:9f2a...d81c

The digest shown here is illustrative. In real use it must be copied from the registry or deployment tooling.

A multi-platform image uses an image index. The index points to platform-specific manifests. A client selects the appropriate manifest using operating system, CPU architecture, and sometimes variant. A build intended for both x86-64 and ARM64 should therefore publish a multi-platform index rather than assuming that one architecture can execute everywhere.

3. Public and Private Registries

Public registries

Public registries make images available to a broad audience. They are useful for open-source software, standard base images, demonstrations, and community collaboration. Their advantages include easy access, large ecosystems, and mature tooling. Their risks include typosquatting, malicious or compromised images, rate limits, availability dependence, and uncertainty about maintenance quality.

A public image should not be trusted merely because it is popular. Teams should inspect its publisher, maintenance history, documentation, vulnerability status, signature or attestation information, and licensing conditions.

Private registries

Private registries restrict access to an organization or selected collaborators. They are appropriate for proprietary applications, internal base images, regulated workloads, and release candidates. They may be hosted by a cloud provider, operated as a managed service, or installed within an organization using software such as Harbor or a registry implementation.

Private registries provide stronger control over identity, network access, retention, audit logs, replication, and geographic placement. They also create operational responsibilities: backups, upgrades, certificate management, capacity planning, monitoring, and disaster recovery.

4. Authentication and Authorization

Authentication answers “Who are you?” Authorization answers “What may you do?” A secure registry requires both.

Common authentication approaches include:

• username and password, preferably replaced by a short-lived access token;
• cloud-provider identity and temporary credentials;
• robot or machine accounts for automation;
• workload identity, where a CI system receives narrowly scoped credentials; and
• single sign-on using an organization’s identity provider.

A typical Docker login operation is:

docker login registry.example.com

Credentials should not be placed directly in shell history, Dockerfiles, source repositories, or unencrypted CI variables. In automation, a secret manager or the CI platform’s protected secret facility should supply credentials. A token should have the minimum necessary scope, such as read-only access for a production deployment job or write access only for a publishing job.

Authorization is commonly implemented through repository- or project-level roles. A useful separation is:

• developers: pull approved base images and push development images;
• CI publishers: push build outputs but not alter production policy;
• release managers: promote approved artifacts;
• deployment agents: pull production images only; and
• registry administrators: manage projects, policies, and infrastructure.

The principle of least privilege reduces the consequences of stolen credentials. Push permissions should be especially restricted because an attacker who can replace a production tag may execute malicious code in downstream environments.

Transport security is also essential. Registries should use TLS certificates, and clients should validate the registry certificate. Disabling certificate verification may be acceptable only in a controlled laboratory environment; it is unsafe for production because it permits interception or impersonation.

5. Naming, Tagging, and Versioning

A repository naming standard should communicate ownership and service identity. For example:

registry.example.com/platform/orders
registry.example.com/platform/orders-base
registry.example.com/platform/orders-migrations

Tags should be useful to humans and automation. Common forms include:

• semantic release tags: 1.8.2;
• environment tags: staging, production;
• source tags: main-7f3a2c1;
• build tags: build-1842; and
• date tags: 2025-03-08.

Tags are mutable unless the registry enforces immutability. A tag such as latest is particularly ambiguous: it may mean the latest build, latest stable release, or latest image pushed by a developer. It should not normally be used as the sole production deployment identifier.

A robust convention separates human intent from machine identity. For example, an image may be published with:

orders:1.8.2
orders:1.8
orders:production

The deployment record should additionally save the digest. The 1.8.2 tag expresses the release, while the digest proves exactly which bytes were deployed. If a tag is moved later, a digest-pinned deployment remains reproducible.

Semantic Versioning uses the pattern MAJOR.MINOR.PATCH. In its usual interpretation, incompatible API changes increment MAJOR, backward-compatible functionality increments MINOR, and backward-compatible defect corrections increment PATCH. Teams must define whether image changes such as base-image updates qualify as a patch release; consistency matters more than the particular policy.

Useful practices include:

1. Never use a mutable tag as the only production reference.
2. Include a source revision or build identifier in CI-generated tags.
3. Do not overwrite release tags after publication.
4. Enable immutable tags where supported.
5. Record the image digest in deployment logs and release records.
6. Keep repository names stable even when implementation details change.

6. Publishing and Pulling Images

A basic publication workflow is:

docker build -t registry.example.com/acme/orders:1.8.2 .
docker push registry.example.com/acme/orders:1.8.2
docker image inspect registry.example.com/acme/orders:1.8.2
docker pull registry.example.com/acme/orders:1.8.2

In professional workflows, the build should occur in a controlled CI environment. Before pushing, the pipeline should run tests, inspect the image, scan dependencies, and attach metadata. The pipeline should fail if required quality or security gates are not satisfied.

Docker Buildx can produce multi-platform images. A conceptual command is:

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t registry.example.com/acme/orders:1.8.2 \
  --push .

The exact builder configuration varies. The important point is that the result is pushed as an image index containing platform-specific manifests.

Pull performance depends on network bandwidth, latency, registry capacity, authentication overhead, and the number and size of missing layers. Layer reuse is improved when frequently changing application files are placed in later Dockerfile layers and stable dependencies are placed earlier. This is a build-design concern as well as a distribution concern.

For high-availability environments, organizations may use registry replication or regional mirrors. A pull-through cache can reduce repeated downloads from an external registry, but cache policy, freshness, authentication, and legal licensing must be considered.

7. Promotion Through Environments

Promotion is the controlled movement of an already-built artifact from one environment to another. The central principle is “build once, promote many.” Rebuilding separately for test and production can create different layers, dependencies, or compiler outputs, weakening confidence that the tested artifact is the deployed artifact.

A typical flow is:

Source commit
    ↓
Build and unit tests
    ↓
Image tagged with commit/build identity
    ↓
Security and policy checks
    ↓
Development or integration deployment
    ↓
Approval and acceptance tests
    ↓
Production deployment by digest

Promotion can be implemented by copying the same manifest and layers to another repository or by changing an environment tag that points to the approved digest. The latter is convenient, but the promotion record must preserve the digest and approval evidence.

For example, an image initially identified as:

registry.example.com/acme/orders:build-1842

may be promoted so that orders:production references the same digest. The bytes should not be rebuilt merely because the target environment changed. Configuration such as database endpoints and credentials belongs outside the image and should be injected by deployment configuration or a secret-management system.

A promotion policy may require:

• successful automated tests;
• vulnerability results below an approved severity threshold;
• license compliance;
• image signature verification;
• review by an authorized person; and
• a documented rollback target.

8. Image Provenance, Signing, and Supply-Chain Security

Provenance describes how, where, and from what source an artifact was produced. Useful provenance may include source repository, commit, builder identity, build timestamp, dependency information, workflow run, and build parameters. This information supports incident investigation and software-supply-chain assurance.

A software bill of materials (SBOM) lists components contained in an image, such as operating-system packages and language dependencies. It does not prove that the image is safe, but it improves visibility and supports vulnerability response.

A vulnerability scanner compares discovered components with vulnerability databases. Results require judgment: a vulnerability may be unreachable, exploitable only under unusual conditions, fixed in a later version, or incorrectly detected. A “no findings” result is not proof of absence because databases and scanners are incomplete.

Signing attaches a cryptographic statement to an artifact or digest. Verification checks that the statement was produced by a trusted signer and refers to the expected content. Modern tools can also attach attestations for provenance or SBOMs. A practical trust policy might require that production images:

• originate from an approved repository;
• have a valid signature from the CI identity;
• possess provenance showing an approved workflow;
• meet vulnerability and license policy; and
• be referenced by a digest.

Keys and signing identities must be protected. Short-lived identity-based signing is generally preferable to a long-lived private key stored in a build server. Trust roots, rotation procedures, revocation decisions, and emergency response should be documented.

9. Retention, Garbage Collection, and Cost Control

Registries accumulate development tags, failed builds, obsolete releases, and unreferenced layers. Retention policies control this growth while preserving artifacts needed for rollback, audit, and legal obligations.

A policy might retain:

• all immutable production releases for one year;
• the most recent ten successful development builds;
• release candidates for ninety days; and
• failed or unpromoted builds for fourteen days.

The exact periods depend on recovery objectives, compliance requirements, storage cost, and release frequency. Deleting a tag does not necessarily delete a layer immediately, because the layer may be referenced by another manifest. Garbage collection must be performed according to the registry’s rules and should never run while it can corrupt active uploads or referenced content.

Retention must be coordinated with rollback. If an operator promises rollback to any production release from the last six months, those images and their metadata must remain available for six months. A useful governance question is not “How much storage can we delete?” but “Which recovery and audit capabilities must remain possible?”

10. Reliability and Failure Handling

Common distribution failures include:

• unauthorized: credentials are missing, expired, or insufficient;
• denied: authentication succeeded but authorization failed;
• manifest unknown: the repository or tag does not exist, or the wrong registry was used;
• TLS or certificate errors: the endpoint or trust configuration is incorrect;
• rate limiting: the client exceeded a registry quota;
• network timeout: connectivity, routing, proxy, or registry capacity is impaired; and
• platform mismatch: no image manifest matches the client’s operating system and architecture.

Troubleshooting should proceed systematically:

1. Confirm the complete image reference, including registry host and tag.
2. Test DNS and TLS connectivity.
3. Authenticate again using a valid, least-privilege credential.
4. Check repository permissions and whether the tag exists.
5. Inspect the manifest and supported platforms.
6. Review registry, proxy, CI, or node logs.
7. Retry transient failures with bounded exponential backoff.

Retries should not continue indefinitely. A deployment system should distinguish transient network errors from permanent authorization or policy failures. Pulling by digest also prevents a deployment from silently changing because a tag moved between retries.

Reliability planning should include registry backups or replication, monitoring of storage and latency, certificate-expiry alerts, capacity thresholds, and a documented response for registry unavailability. A registry outage can prevent new deployments and, depending on node caches and orchestration behavior, may affect scaling or replacement of workloads.

11. Governance, Legal, and Ethical Considerations

Image distribution is a governance activity, not merely a technical operation. Organizations should define ownership for repositories, approval requirements, acceptable base images, and incident response.

Important concerns include:

• Licensing: Base images and packages may impose obligations such as attribution or source-code availability.
• Privacy: Image layers can accidentally contain credentials, private keys, personal data, or internal source code. Removing a file in a later layer does not necessarily remove it from registry history.
• Export and residency: Some organizations must control where artifacts and build metadata are stored.
• Auditability: Pushes, promotions, deletions, approvals, and authentication events may need to be logged.
• Fair access: Shared registries require quotas and naming policies so that one team does not consume disproportionate capacity.
• Incident response: A compromised image must be quarantined, consumers identified, credentials rotated, and a clean replacement distributed.

Secrets should never be baked into images. Build logs, labels, and image history should also be reviewed because sensitive values can leak through build arguments or verbose commands.

12. Illustrative Case: Northstar Payments

Background

Northstar Payments is an illustrative organization operating a payment-processing API. Developers previously pushed images to a shared public repository using the tag latest. Production servers pulled that tag during deployment.

Problem

A developer accidentally pushed a test image containing a debugging endpoint. The production deployment pulled the changed latest tag without a source review. The team also discovered that the registry had no retention policy and that no one could identify which source commit was running.

Analysis

The underlying weaknesses were not just the accidental push. The workflow lacked immutable release references, separation between development and production repositories, least-privilege access, promotion controls, and deployment records containing image digests.

Approach and solution

Northstar introduced the following process:

1. CI builds images only from protected branches.
2. Each image receives a tag containing the release version and source revision.
3. Tests, SBOM generation, vulnerability scanning, and policy checks run before publication.
4. Development images are pushed to a restricted repository.
5. An approved image is signed and promoted without rebuilding.
6. Production deployment manifests reference the digest.
7. Production pull credentials have read-only access.
8. Release tags are immutable, and latest is prohibited in production.
9. Registry audit logs and promotion approvals are retained.
10. Failed builds are deleted after fourteen days, while production releases are retained for one year.

Outcome

The organization can now identify the source and build process for a running image, prevent ordinary developers from changing production artifacts, and roll back to a retained digest. Deployment became more predictable, although the team accepted additional administration for signing, scanning, and registry policy management.

Learning points

The case demonstrates that reliable image distribution combines technical mechanisms with governance. A registry alone cannot guarantee safe deployment. Trust depends on the complete chain from source, through build and verification, to promotion and runtime pull.

13. Best-Practice Checklist

Before adopting a registry workflow, verify that the organization can answer “yes” to the following questions:

• Are repositories named consistently and owned by identifiable teams?
• Are public and private artifacts clearly separated?
• Are CI and deployment credentials short-lived and least-privileged?
• Are release tags immutable or supplemented by digests?
• Is the same artifact promoted rather than rebuilt?
• Are supported platforms explicitly tested?
• Are images scanned and accompanied by useful SBOM and provenance data?
• Are signatures verified before production deployment?
• Are retention policies compatible with rollback requirements?
• Are registry availability, storage, certificates, and audit logs monitored?
• Is there a documented response to compromised images and leaked credentials?

Contemporary Developments

Container distribution is increasingly treated as part of software supply-chain security. OCI artifacts allow registries to store more than runnable images, including signatures, SBOMs, provenance attestations, Helm charts, and other related objects. Cloud workload identity reduces the need for permanently stored registry passwords. Admission policies can reject unsigned or unapproved images before they enter a cluster. Multi-architecture publishing is also becoming routine as ARM-based laptops, cloud instances, and edge devices grow in use.

These developments do not eliminate judgment. Organizations still need to determine which identities are trusted, which vulnerabilities are acceptable, how long evidence must be retained, and how quickly compromised artifacts can be replaced.

Chapter Summary

Registries provide the storage and distribution layer for container images and related OCI artifacts. A repository groups image versions; manifests describe configurations and layers; image indexes support multiple platforms; tags provide convenient labels; and digests provide stable content identity. Public registries offer accessibility, while private registries provide stronger organizational control but require operational management.

Secure distribution depends on authentication, authorization, TLS, least privilege, immutable release practices, and careful secret handling. A professional workflow builds an image once, tests and scans it, records provenance, signs it, and promotes the same digest through environments. Retention policies must balance storage cost with rollback and audit requirements. Reliability requires monitoring, replication or backup planning, controlled retries, and systematic troubleshooting.

Ultimately, image distribution is a supply-chain discipline. Trust is established through evidence linking source code, build identity, image content, approval, and deployment.

Key Terms

Registry: A service that stores and distributes container artifacts.

Repository: A named collection of related image versions.

Manifest: Metadata describing an image configuration and its layers.

Image index: A manifest that references platform-specific image manifests.

Layer: A content-addressed filesystem change set in an image.

Tag: A human-readable label that may refer to a mutable manifest.

Digest: A cryptographic content identifier for an artifact.

Content addressability: Identification of content by a digest derived from that content.

Public registry: A registry intended for broad or community access.

Private registry: A registry restricted to an organization or selected users.

Authentication: Verification of an identity.

Authorization: Determination of permitted actions.

Least privilege: Granting only the access required for a task.

Promotion: Moving an approved artifact to a later environment without rebuilding it.

Provenance: Evidence describing how and from what source an artifact was produced.

SBOM: A software bill of materials listing components in an artifact.

Image signing: Attaching a cryptographic statement to an artifact or digest.

Retention policy: Rules defining how long artifacts and metadata are preserved.

Multi-platform image: An image index containing manifests for multiple operating systems or architectures.

Immutable tag: A tag that registry policy prevents from being overwritten.

Review Questions

5 Short Answer Questions

1. What is the difference between an image tag and an image digest?
2. Why should production deployments generally avoid relying only on latest?
3. Distinguish authentication from authorization in a registry.
4. What information can an SBOM provide?
5. Why is “build once, promote many” preferable to rebuilding for every environment?

5 Long Answer Questions

1. Compare the advantages, risks, and operational responsibilities of public and private registries.
2. Explain how manifests, layers, and image indexes work together during a pull operation.
3. Design a tagging and versioning policy for a team that releases a web service weekly.
4. Explain how provenance, signatures, vulnerability scanning, and admission policies contribute to supply-chain security.
5. Discuss how retention and garbage collection should be designed around rollback and audit requirements.

3 Analytical / Application Questions

1. A production deployment references service:stable, but the tag was moved after approval. What controls would you introduce to ensure reproducibility and explain why?
2. A CI job can push to every repository and delete production images. Analyze the risks and propose a revised identity and authorization model.
3. A company operates in three regions and experiences slow image pulls during large-scale deployments. Recommend a distribution architecture and identify the trade-offs involving replication, caching, consistency, cost, and availability.

Multiple Choice Questions with Answers

Question 1

Which identifier most reliably specifies the exact image content to deploy?

A. The latest tag

B. A content digest

C. The repository name

D. The image creation date

Correct Answer: B. A content digest

Question 2

What is the primary purpose of an image index?

A. To store registry passwords

B. To delete unused layers

C. To map platforms to platform-specific manifests

D. To compile application source code

Correct Answer: C. To map platforms to platform-specific manifests

Question 3

Which practice best follows the principle of least privilege?

A. Giving every developer administrator access

B. Using one shared permanent password

C. Giving a deployment agent read-only access to production images

D. Allowing CI to delete all repositories

Correct Answer: C. Giving a deployment agent read-only access to production images

Question 4

What does “build once, promote many” mean?

A. Rebuild the image separately in every environment

B. Promote the tested artifact without rebuilding it

C. Use only one image tag for all projects

D. Build an image only after production approval

Correct Answer: B. Promote the tested artifact without rebuilding it

Question 5

Which statement about tags is correct?

A. All tags are cryptographically immutable

B. A tag can be moved to another manifest unless policy prevents it

C. Tags always contain the source commit

D. Tags cannot be used with private registries

Correct Answer: B. A tag can be moved to another manifest unless policy prevents it

Question 6

What is the main function of an SBOM?

A. To list software components contained in an artifact

B. To encrypt registry traffic

C. To assign network addresses to containers

D. To replace image authentication

Correct Answer: A. To list software components contained in an artifact

Question 7

A registry returns denied after a user successfully logs in. What is the most likely explanation?

A. The user is authenticated but lacks authorization for the operation

B. The image definitely has no layers

C. The client selected the wrong CPU architecture

D. The registry has automatically signed the image

Correct Answer: A. The user is authenticated but lacks authorization for the operation

Question 8

Why should secrets not be placed in a Dockerfile?

A. They make images multi-platform

B. They may remain visible in image history or layers

C. They prevent all caching

D. They disable TLS certificates

Correct Answer: B. They may remain visible in image history or layers

Question 9

Which retention decision is most directly connected to rollback capability?

A. Deleting all old production images immediately

B. Retaining the artifacts required by the rollback period

C. Keeping only the mutable latest tag

D. Removing registry audit logs

Correct Answer: B. Retaining the artifacts required by the rollback period

Question 10

What does image signing primarily provide?

A. Evidence that a trusted identity approved or produced a particular artifact

B. Automatic vulnerability removal

C. Guaranteed application correctness

D. Faster layer compression

Correct Answer: A. Evidence that a trusted identity approved or produced a particular artifact