Skip to content

Week 1 - The OCI Image Spec

1.1 Conceptual Core

  • An OCI image is content-addressed: every blob (layer, config, manifest) is named by sha256:<digest>. Identity = content. Immutable.
  • Top-level: a manifest lists the config and layers for one platform. An index lists multiple manifests for multi-platform images (linux/amd64, linux/arm64, etc.).
  • Layers are tar archives representing filesystem changesets, often gzip-compressed (application/vnd.oci.image.layer.v1.tar+gzip).
  • Configs are JSON documents describing entrypoint, env, working dir, exposed ports, volumes, labels.

1.2 Mechanical Detail

  • The manifest schema (image-spec/specs-go/v1/manifest.go in the spec repo). Keys: mediaType, schemaVersion, config (descriptor), layers ([]descriptor), annotations.
  • Descriptor structure: mediaType, digest, size, optional urls and annotations.
  • The OCI layout on local disk: a directory with oci-layout, index.json, and blobs/sha256/<digest> files. Use skopeo copy docker://nginx:latest oci:./nginx-layout:latest and inspect.
  • Distinguish OCI mediaType from the older Docker v2.2 mediaType-they're nearly isomorphic but not identical. skopeo and modern registries handle both.

1.3 Lab-"An Image Without Docker"

  1. skopeo copy docker://alpine:3.19 oci:./alpine-layout:3.19. Inspect the layout. Read index.json, the manifest blob, the config blob.
  2. Find a layer blob, decompress, list its contents (tar tzf <blob>).
  3. Compute one of the layer digests yourself (sha256sum) and verify.
  4. Modify the config (e.g., change the entrypoint) by writing a new config blob, generating a new manifest, updating index.json. Verify with skopeo inspect oci:./alpine-layout:3.19.

1.4 Hardening Drill

  • Read CVE history of registry-side spec misinterpretations (e.g., the 2018 layer-extraction symlink attacks). Internalize that any tool processing untrusted images must validate paths during extraction.

1.5 Production Readiness Slice

  • Spin up a local registry: docker run -d --rm -p 5000:5000 registry:2 (or, true to the spirit of the curriculum, run it under podman). skopeo copy oci:./alpine-layout:3.19 docker://localhost:5000/alpine:3.19. You now have a registry you control.

Comments