Docker and OCI in the pipeline — the container build and the registry

Docker and OCI artefacts sit at the application-image layer of the IaC model. They are the unit of work the orchestrator schedules - Kubernetes pulls an image by digest and runs it as a container, and Terraform and Ansible do not see the image at all. The build pipeline that produces the image is the subject of this lesson.

Where Docker sits in the flow

flowchart LR
    A["Git commit of source and Dockerfile"] --> B["BuildKit buildx build"]
    B --> C["Image manifest and layers"]
    C --> D["cosign sign and attest"]
    D --> E["Push to OCI registry by digest"]
    E --> F["Tag is human label, digest is identity"]
    F --> G["GitOps manifest updated to digest"]
    G --> H["Controller pulls by digest and runs"]

Three properties of this flow are worth pulling out:

• The build is deterministic. Given the same Dockerfile, source commit, and base image digest, the build produces the same image digest. The cache is keyed by content.
• The digest is the identity. The sha256:... value is what the registry stores, what the controller pulls, and what the cluster runs. The tag is a movable human-readable label.
• The push happens after sign. cosign (or an equivalent) signs before push, so the signature covers the same bytes that land in the registry. Re-tagging later does not invalidate the signature.

The build stage

The pipeline’s build stage runs BuildKit, not the legacy builder. BuildKit is the daemon-based, parallelisable, content-addressable builder that has been Docker’s default since the 23.0 release:

docker buildx build --platform linux/amd64,linux/arm64 \
  --tag registry.example.com/app:build-$BUILD_ID \
  --tag registry.example.com/app:latest \
  --push .

The --platform flag tells BuildKit to produce a manifest list containing one image per architecture. The --push flag pushes the result directly to the registry; without it, the image sits in the build cache. The two --tag flags attach a build-tag and a latest tag to the same digest; the build-tag is what the pipeline records, the latest tag is a moving label that should never be pinned in production.

The build is the gating step for the pipeline. If it fails - base image digest not found, COPY path does not exist, RUN step returns non-zero - nothing downstream runs.

The registry and the digest

The registry stores images by digest. Every push writes a manifest, a config blob, and a set of layer blobs; the digest is computed over the manifest and identifies the image as a whole. A re-push of the same bytes produces the same digest; a re-tag of a different image produces a different digest under the same tag.

For multi-arch builds, the registry stores one manifest list per platform-set. The manifest list is itself content-addressed and has its own digest. The cluster pulls the manifest list, selects the entry that matches its node architecture, and pulls the per-arch image.

Production discipline

The production framing of Docker in a pipeline has three rules:

1. Pin by digest in production manifests. Tags are for humans, digests are for clusters. The pipeline updates the digest on promotion.
2. Sign before push, attest in CI. cosign signs the digest; the in-toto attestation records the source commit and build parameters.
3. Multi-arch is built, not patched. A pipeline that produces amd64 and then docker manifest creates an arm64 alias has lost the content-addressable guarantee.

Cross-course references

• Containers for Production Sysadmins - Parts VII-X (BuildKit and registries) cover the build cache and content-addressable layer model.
• Containers for Production Sysadmins - Parts XI-XIV (Supply chain) cover cosign, in-toto, and SLSA Build L3.
• Kubernetes for Production Sysadmins - Parts XI-XIV (GitOps controllers) cover how the controller consumes the digest-pinned image references.
• Observability for Production Sysadmins - Parts XXVII-XXX (Registry audit) cover the registry pull log.

Quiz