OCI image model
An OCI image is a collection of content-addressed objects connected by
descriptors. rib creates those objects directly according to the OCI Image
Specification, without a Docker daemon or a temporary container.
This chapter defines the terms layer, digest, manifest, and configuration used throughout the rest of this book.
Analogy: an image as filesystem patches
Start with an empty filesystem. Each layer is a set of changes applied to it: add a file, replace a file, or add a directory. Applying all layers in order produces the container filesystem, much like applying a sequence of Git commits produces a repository state.
rib does not implement every Dockerfile operation. It creates one kind of
layer: take files from the host and place them at selected image paths. Such a
layer is requested with --copy.
Descriptors and digests
Every layer, configuration, and manifest is identified by a SHA-256 hash of its own bytes. This hash is the object’s digest. Changing one byte changes the digest.
A descriptor is a small JSON value that specifies how to locate and verify an object:
{
"mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
"digest": "sha256:def456...",
"size": 28471122
}
The descriptor contains only the media type, size, and digest. The actual bytes
are stored separately—by digest in a registry or under blobs/ in an OCI
archive. This is content-addressable storage: location is derived from content.
If two builds produce the same layer bytes, the registry sees the same digest
and does not need a second upload.
Layer: a filesystem change
A layer is a tar archive describing a change relative to preceding layers. Layers are applied in manifest order, so a later layer can replace a path from an earlier one.
Every layer created from --copy is deterministic and gzip-compressed. It
contains only explicitly selected files and directories. rib executes no
container commands and computes no filesystem diff.
Multiple layers may be built concurrently, but rib restores command-line
order before assembling the image. Completion order therefore never changes
the image semantics or digest.
Configuration: how the container runs
The image configuration is JSON containing runtime metadata rather than file contents:
architecture,os, and optionalvariantidentify the target platform;config.Entrypoint,config.Cmd, andconfig.Envdescribe process startup;config.WorkingDirandconfig.Userset the working directory and user;config.ExposedPortsandconfig.Labelsdeclare ports and labels;rootfs.diff_idslists uncompressed layer identifiers in application order;historyrecords layer-producing and metadata-only operations;createdrecords the image creation time.
For a registry base image, rib clones the base configuration, appends layer
and history data, sets created, and applies explicitly requested runtime
metadata such as --entrypoint and --label. Other fields, including the
base Env, are preserved; the current CLI does not modify Env.
For scratch, the configuration is created from nothing. The standalone CLI
uses --platform or its linux/amd64 default; Cargo integration requires the
platform through metadata or the CLI. Layer and history lists start empty.
scratch is a special exact keyword, not an image stored in a registry.
Manifest: the table of contents for one image
A manifest connects one configuration with an ordered layer list:
{
"schemaVersion": 2,
"mediaType": "application/vnd.oci.image.manifest.v1+json",
"config": {
"mediaType": "application/vnd.oci.image.config.v1+json",
"digest": "sha256:abc123...",
"size": 1842
},
"layers": [
{
"mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
"digest": "sha256:def456...",
"size": 28471122
}
]
}
One manifest describes one platform-specific image. A registry tag is a
mutable reference to either a manifest digest or a multi-platform index. A
manifest digest is immutable because it is calculated from the manifest
bytes. For production, registry.example.com/app@sha256:... therefore
identifies one result more reliably than a tag.
Image index: multiple platforms under one tag
An image index lists platform-specific manifest descriptors, allowing a
client to select the appropriate image for linux/amd64, linux/arm64, and
other platforms.
rib builds exactly one platform per invocation. When the base reference
resolves to an index, it selects the manifest matching --platform. The
output remains a platform-specific manifest, not a new multi-platform index.
An OCI archive contains an index.json, but it has a single reference to the
built manifest.
Why layers have both digest and diff_id
Each compressed layer has two SHA-256 identifiers:
diff_id = sha256(layer.tar) — uncompressed content
digest = sha256(layer.tar.gz) — compressed bytes that are transferred
The same tar stream can be compressed by different tools or settings, changing
the gzip bytes and digest while leaving diff_id unchanged. Consequently:
digestidentifies the blob stored in registries and OCI archives and is written tomanifest.layers[i].digest;diff_ididentifies the unpacked result and is written toconfig.rootfs.diff_ids[i].
Configurations and manifests are content-addressed in the same way:
config_digest = sha256(config.json bytes)
manifest_digest = sha256(manifest.json bytes)
Changing metadata such as a label changes the configuration bytes, which changes its descriptor inside the manifest and therefore changes the final manifest digest. The final digest fingerprints the complete image, including metadata rather than filesystem contents alone.
An image is an immutable graph
tag ───────► manifest digest or image index digest
│
├──► manifest ─► config descriptor ──► config JSON
│ │
│ └──► ordered layer descriptors
│ │
│ └──► compressed layer blobs
└──► image index ─► platform-specific manifest descriptors
Existing objects are never rewritten. A build creates a new graph root: rib
reuses base-layer descriptors, appends new layers, and creates a new
configuration and manifest while old blobs remain untouched.
The next chapters explain why this model is useful in rootless CI/CD and how
it is implemented inside rib.