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"¶

Build an image for linux/amd64 and linux/arm64 separately (use buildah --arch= or docker buildx).
Use skopeo to assemble a manifest list pointing to both.
Push to your local registry.
Pull from each architecture; verify the right manifest is selected.
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.