Skip to content

Week 4 - Image Internals: Manifest Lists, Index, Annotations, Sparse Pulls

4.1 Conceptual Core

  • A manifest list / index points to per-platform manifests. The runtime selects the matching one. This is how docker pull nginx works on both ARM and x86.
  • Annotations are a key/value sidecar on manifests, configs, and layers. Standardized keys: org.opencontainers.image.source, .revision, .created, .licenses, .description. Use them; downstream tools read them.
  • Sparse / lazy pulls-eStargz and Zstd:chunked formats let containers start before all layers are fully transferred. containerd snapshotters (stargz-snapshotter) implement this.

4.2 Mechanical Detail

  • The index spec is in image-spec/image-index.md. Key field: manifests[] with platform descriptors (os, architecture, optional variant, os.version).
  • Annotations propagate through: build → manifest → registry → consumer. buildah and podman set them automatically when given the right flags.
  • eStargz: a TAR-compatible format with a footer containing per-file offsets. The snapshotter pulls only the metadata initially and fetches files on access.

4.3 Lab-"Build a Multi-Arch Image By Hand"

  1. Build an image for linux/amd64 and linux/arm64 separately (use buildah --arch= or docker buildx).
  2. Use skopeo to assemble a manifest list pointing to both.
  3. Push to your local registry.
  4. Pull from each architecture; verify the right manifest is selected.
  5. Add OCI annotations (source, revision, created); verify they survive the pipeline.

4.4 Hardening Drill

  • Annotate every built image with provenance: source repo URL + commit SHA. This is the precursor to SLSA (week 19).

4.5 Production Readiness Slice

  • Configure containerd (week 9) to use the `stargz-snapshotter - measure container startup time for a large image (1+ GB) with vs without lazy pulling.

Month 1 Capstone Deliverable

A oci-foundations/ workspace: 1. runc-bundle/ - week 2's hand-rolled runtime bundle with hardening. 2.daemonless-pipeline/ - skopeo - based image-handling scripts. 3.multiarch-build/ - week 4's hand-assembled multi-arch image with annotations. 4. A RUNBOOK.md covering: registry setup, image inspection, signature verification flow.

Comments