rib — Rust Image Builder
rib is a rootless OCI image builder written in Rust. Its name references the project that inspired it, Jib. It packages prebuilt artifacts and runtime files without a Docker daemon, privileged containers, or commands executed inside the image being built.
rib creates reproducible COPY layers using file operations and publishes
the result directly to a registry, an OCI archive, or a Docker archive.
When to use rib
Use rib when an application has already been built and you need to:
- package a binary, a frontend, or another set of files as an OCI image;
- build the image without root access or a container runtime;
- integrate image packaging and signing into a CI/CD pipeline.
rib does not process Dockerfiles. If image preparation requires RUN or
other Dockerfile-specific instructions, use a compatible builder such as
BuildKit or
Buildah.
rib can be installed directly in a build-environment image so Docker or
Kubernetes can cache that image normally. Repeated builds do not require a
mandatory full pull of the base image: its root filesystem is not unpacked
unless the selected output requires it.
How to navigate this book
| Goal | Chapter |
|---|---|
Install rib and build the first image | Getting started |
| Understand the project’s scope | Purpose and design principles |
| Learn about manifests, configs, layers, and digests | OCI image model |
| Configure a Rust project | Cargo integration |
| Add image building and signing to GitLab CI | CI/CD, Docker, and Kubernetes |
| Configure caching, logs, timeouts, and concurrency | Operations |
| Review security properties | Reproducibility and security |
| Study rib internals | Architecture |
| Check whether rib fits a particular use case | Limitations |
For a first look, read Purpose and design principles and Getting started. The remaining chapters can be used as reference material when configuring a particular build scenario.
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.
Purpose and design principles
rib handles the final stage of a build pipeline. Once an application has
been compiled and tested, it packages the artifact and required runtime files
as an image and publishes it to a registry or writes it to an archive.
source code
│
▼
compile and test
│
▼
artifact + runtime files
│
▼
rib
├──► registry
├──► OCI archive
└──► Docker archive
For Rust projects, cargo rib build first runs cargo build and then passes
the resulting artifact into the common image pipeline. The standalone
rib build command does not build the application itself.
Rootless builds through file operations
rib never starts a process inside the image being assembled. It creates new
layers exclusively from files selected by --copy or
[package.metadata.rib]. It only needs permission to read inputs, write
temporary tar/gzip files, access the OCI Distribution API, and write a local
archive when requested.
No Docker daemon, container runtime, overlay filesystem, mount namespace,
Docker socket, or build container is required. Ownership and permissions in
the resulting image are written directly into tar headers, so image-level
chown does not require equivalent host privileges. This makes Docker and
Kubernetes builds ordinary unprivileged workloads.
Working with a base image
Initially, rib fetches only the base manifest, configuration, and layer
descriptors. It does not perform the equivalent of a full docker pull.
When publishing to a registry, OCI content addressing is used:
- a blob already present in the target repository is not uploaded again;
- repositories on the same registry use cross-repository mount when allowed;
- only a missing blob is downloaded from the source and uploaded to the target.
The registry remains both the source of truth and the store of reusable layers. OCI and Docker archives must contain every base layer and therefore download all of them. A registry output downloads only blobs that the target could not reuse.
Caching the build environment
CI jobs commonly run in Docker containers or Kubernetes pods. rib can be
included directly in the build-environment image—for example, in a Node.js
Alpine image containing the frontend toolchain. The runner’s container runtime
caches this image normally, so later jobs start in an environment where the OS
dependencies, Node.js, and rib are already available.
Application dependency caches such as node_modules, the Cargo registry, and
target remain normal CI caches. rib build --cache stores only downloaded
base-image blobs; it does not cache newly built COPY layers between runs.
Composition with signing systems
rib deliberately delegates signing to tools such as cosign. Human-readable
progress and the final summary go to stderr. When stdout is redirected or used
in command substitution, stdout contains only the manifest digest:
IMAGE_DIGEST="$(rib build ... --to registry:registry.example.com/team/app:v1)"
cosign sign "registry.example.com/team/app@${IMAGE_DIGEST}"
The script does not parse logs. The immutable digest can be passed directly to signing, attestation, or deployment tooling.
Deliberate boundaries
rib does not process Dockerfiles or execute arbitrary image commands. It
does not support RUN, install packages while packaging, perform cross-
compilation or emulation, infer Cargo artifacts or linkage, build a multi-
platform index in one invocation, sign images, or generate SBOM/provenance.
Use a full Dockerfile-compatible builder when the final root filesystem must
be modified through RUN. rib is intended for prepared files that need a
rootless, reproducible, automation-friendly packaging stage.
Getting started
Installation
crates.io
Installing the published crate requires Rust 1.88 or later:
cargo install rust-image-builder --version 0.1.0 --locked
Omit --version to install the latest published version:
cargo install rust-image-builder --locked
Package page: rust-image-builder 0.1.0 on crates.io.
GitHub Releases
Prebuilt binaries do not require a Rust installation. Archives and checksum files are available from GitHub release v0.1.0.
Example for Linux x86_64 with glibc:
version=v0.1.0
archive="rib-${version}-x86_64-unknown-linux-gnu.tar.gz"
base_url="https://github.com/kuzmenkodm/rib/releases/download/${version}"
curl -LO "${base_url}/${archive}"
curl -LO "${base_url}/${archive}.sha256"
sha256sum --check "${archive}.sha256"
tar -xzf "${archive}"
mkdir -p "$HOME/.local/bin"
install -m 0755 rib cargo-rib "$HOME/.local/bin/"
Ensure $HOME/.local/bin is in PATH. On Windows, download
rib-v0.1.0-x86_64-pc-windows-msvc.zip, verify it against the accompanying
.sha256 file, extract rib.exe and cargo-rib.exe, and add their directory
to PATH.
From source
git clone https://github.com/kuzmenkodm/rib.git
cd rib
cargo install --path . --locked
All installation methods provide two binaries:
rib— the standalone CLI for packaging existing files;cargo-rib— the Cargo subcommand invoked ascargo rib build.
Display the current command-line reference with:
rib build --help
cargo rib build --help
Building from a registry image
The following command adds a prebuilt executable to an Alpine base image and publishes the result directly to a registry:
IMAGE_DIGEST="$(rib build \
--from alpine:3.22 \
--platform linux/amd64 \
--copy ./server:/app/server,mode=0755 \
--entrypoint /app/server \
--to registry:registry.example.com/team/server:v1)"
rib fetches the base manifest and configuration but does not perform a full
preliminary pull. Inherited layers are reused by digest in the registry.
IMAGE_DIGEST receives the digest of the published manifest.
Building from scratch
Use an empty base for a statically linked executable:
rib build \
--from scratch \
--platform linux/amd64 \
--copy ./server:/server,mode=0755,chown=65532:65532 \
--entrypoint /server \
--user 65532:65532 \
--to oci-archive:dist/server.tar@server:v1
scratch is a special marker for an empty base and must be written exactly in
that form. scratch:latest is treated as an ordinary image reference that
rib will attempt to fetch from a registry.
scratch contains no dynamic loader, system libraries, CA certificates, or
shell. Include every runtime dependency in the artifact or add it through
another --copy option.
The --copy format
<source>:<destination>[,mode=<octal>][,chown=<uid>[:<gid>]]
Examples:
--copy ./server:/usr/local/bin/server,mode=0755
--copy ./config:/etc/server/,chown=65532:65532
--copy 'target/release/*.so:/usr/local/lib/'
Each --copy creates a separate layer, and layer order follows option order.
Destination syntax resembles Dockerfile COPY, but only the subset described
in this book is implemented. Symbolic links are unsupported, and a destination
for multiple glob matches must end in /. Quote glob patterns so rib, not
the shell, expands them.
Output destinations
--to can be supplied more than once:
registry:<image-reference>
oci-archive:<path>[@<tag>]
docker-archive:<path>[@<tag>]
Example:
rib build ... \
--to registry:registry.example.com/team/server:v1 \
--to oci-archive:dist/server-oci.tar@server:v1 \
--to docker-archive:dist/server-docker.tar@server:v1
Destinations are processed sequentially and do not form one transaction.
Authentication
Supply an explicit credential as:
--credential 'registry.example.com=user:password'
Alternatively, rib reads the auths section from one Docker configuration.
It selects an explicitly supplied --docker-config, then
$DOCKER_CONFIG/config.json, then ~/.docker/config.json. It does not search
other files after selecting a configuration. An explicit --credential
overrides the selected Docker configuration.
Architecture
This chapter describes the internal components and the overall build pipeline. The following chapters cover layer construction, OCI configuration and manifests, and output formats in more detail.
The standalone rib build CLI and the cargo rib build integration converge
on the same pipeline:
rib build ─────────────┐
├──► ImageBuildSpec ──► BuildRequest
cargo rib build ─► cargo ┘ │
▼
┌────────────────────────────────────┐
│ base image + parallel COPY build │
└─────────────────┬──────────────────┘
▼
ImageBundle
│
┌─────────────────┼─────────────────┐
▼ ▼ ▼
OCI archive Docker archive registry
Once an ImageBuildSpec exists, the request source no longer affects image
processing.
Module responsibilities
| Module | Responsibility |
|---|---|
cli | Parses standalone CLI options into a build specification |
cargo_integration | Coordinates cli, config, plan, and process for arguments, metadata, build planning, and Cargo execution |
app::spec | Defines settings, merges transport overrides, and validates build requests |
app::build | Coordinates the build |
app::runtime | Initializes tracing and handles interruption signals |
builder::copy | Parses --copy, expands globs, and resolves image destinations |
builder::layer | Creates a deterministic tar/gzip layer and its identifiers |
image | Stores the platform, base image, and layer sources |
image::assemble | Produces the final configuration, manifest, and ImageBundle |
registry | Wraps oci-client, preserves manifest bytes, and delegates retry policy to registry::retry |
app::push | Chooses blob reuse, cross-repository mount, or upload |
blob | LayerStore shares local files, cache lookup, and downloads; concurrent requests for a digest share one download |
cache | Verifies cached base layers and publishes complete entries atomically |
archive | Writes OCI and Docker archives |
auth | Reads Docker configuration and explicit credentials, and canonicalizes registry names |
progress | Provides terminal, CI-line, and quiet progress modes |
The rib and cargo-rib binaries delegate to rib::run() and
rib::run_cargo(), keeping lifecycle and error handling shared. These entry
points are internal to the binaries and are not a supported, stable library API.
Request normalization
Standalone options become BuildArgs and then ImageBuildSpec. Cargo
integration builds the same specification after merging
[package.metadata.rib] with CLI values. BuildRequest::try_from validates
the main invariants before network or filesystem work starts:
--jobsis greater than zero;- at least one
--todestination is present; --platformmatches<os>/<arch>[/<variant>];- every
--labelis akey=valuepair; - a port without a protocol receives
/tcp; --creation-timeisepoch,now, or valid RFC 3339;- the exact word
scratchdenotes an empty base; everything else is parsed as anoci_client::Reference.
Downstream components therefore consume one validated request type regardless of the entry point.
Two independent initial branches
Fetching base metadata and creating local layers are independent and run
concurrently. The network branch is absent for scratch:
registry base scratch
───────────── ───────
fetch manifest + config ──┐ create empty config ──┐
├─► assemble ├─► assemble
build COPY layers ─────────┘ build COPY layers ────┘
Only the base manifest and configuration are downloaded at this point. Base layer bytes are fetched later for a self-contained archive or when a target registry cannot reuse a layer.
Async and blocking boundaries
Registry access uses the asynchronous oci-client API. Filesystem traversal,
tar creation, and gzip compression are CPU- and disk-bound, so every --copy
runs in tokio::task::spawn_blocking rather than on Tokio worker threads.
A semaphore of size --jobs limits simultaneous layer builders. Separate
semaphores with the same numeric limit constrain later blob downloads and
uploads. Results carry their original indices and are reordered before
assembly, so completion timing cannot change manifest layer order.
Assembly as the model boundary
Before assembly, the system holds base descriptors/configuration and local
Layer values with their digest, diff_id, and temporary storage. The
assembler combines them into:
ImageBundle {
config,
config_bytes,
config_digest,
manifest_bytes,
manifest_digest,
layers: Vec<LayerSource>,
}
All registry and archive outputs consume the same bundle and ordered layer list. Every destination in one invocation consequently has the same manifest digest.
Temporary-data lifecycle
A built layer owns an Arc<LayerStorage> for a temporary directory containing
layer.tar.gz and, only when a Docker archive is requested, layer.tar.
Cloning an image bundle shares these files rather than copying them.
Downloaded base layers are indexed by digest and reused across destinations in
one run. Without --cache, temporary data is removed when its last owner is
dropped. With --cache, base blobs remain under .rib-cache or
--cache-path and are verified by digest before reuse. Built COPY layers are
not cached between runs. Verification runs on the blocking pool. Downloads use
private staging files and publish atomically after validation, so complete blobs
are never truncated. Each reader opens a separate file with its own cursor.
Errors and cancellation
Errors at parsing, layer building, download, assembly, archive writing, and
registry publication boundaries receive contextual messages. If a --copy
worker fails, a shared cancellation token stops the remaining wrappers; the
coordinator waits for them and returns the original contextual error.
Blocking COPY, archive, and decompression writers check cancellation between writes. Ctrl-C and, on Unix, SIGTERM cancel the top-level operation. Temporary directories are owned by RAII values and are cleaned when work is cancelled or fails; an archive is persisted only after its cancellation-safe write finishes.
The oci-client and oci-spec boundary
oci-client is used only for registry transport: authentication, manifest
resolution, blob checks, mounts, uploads, and downloads. oci-spec is the
canonical in-memory model for platform, descriptors, configuration, and
manifest assembly. Adapter code converts registry values once at the boundary,
so archive generation and assembly do not depend on registry transport types.
Building COPY layers
Each --copy option creates one deterministic gzip-compressed filesystem
layer. This chapter explains path resolution, metadata normalization, hashing,
and concurrency.
Syntax
<source>:<destination>[,mode=<octal>][,chown=<uid>[:<gid>]]
source may be a file, directory, or glob. destination is an absolute path
inside the image. mode overrides normalized permissions; chown sets numeric
UID and GID (GID defaults to UID when omitted).
--copy ./server:/usr/local/bin/server,mode=0755,chown=65532:65532
--copy ./config:/etc/server/
--copy 'target/release/*.so:/usr/local/lib/'
Quote globs so the shell does not expand them before rib receives them.
Windows drive paths are supported, for example
--copy 'C:\project\app.exe:/app/app.exe'. Artifact paths are treated literally,
including names containing glob characters. Names copied into the image must
be UTF-8; invalid names produce an error instead of a lossy replacement.
Resolving sources and destinations
A single file copied to a destination without a trailing slash receives that
exact path. A file copied to a destination ending in / keeps its basename.
Directory contents are rooted below the selected destination. Multiple glob
matches require a destination ending in /, preventing ambiguous replacement
of several files with one path.
Source paths from standalone CLI options are relative to the current working
directory. Cargo metadata paths are resolved relative to that package’s
Cargo.toml; CLI additions to cargo rib build remain relative to the process
working directory.
Image paths are normalized and rejected if they contain empty, . or ..
components. Symbolic links and special filesystem objects are rejected rather
than followed. Directory traversal is recursive, but only regular files and
directories enter the layer.
Producing a deterministic tar stream
The complete entry list is collected and sorted by destination path before tar writing. Tar metadata is normalized:
- modification time is
0; - UID/GID default to
0, unlesschownoverrides them; - user and group names are empty;
- explicit
modewins; otherwise directories use0755, executable files use0755, and other files use0644; - entry order is stable.
Only the executable bit is inherited from a source file. Host ownership, timestamps, umask, and traversal order do not leak into the image. Directory entries are added as needed so extraction does not depend on implicit parent creation.
Hashing and compression in one pass
The uncompressed tar stream is hashed while being sent to gzip:
source files
│
▼
tar::Builder
│
▼
CancellableWriter
│
▼
SplitWriter
├──► HashingWriter ──► optional layer.tar
│ └── diff_id + uncompressed_size
│
└──► GzEncoder
▼
HashingWriter<File> ──► layer.tar.gz
└── digest + compressed_size
HashingWriter forwards bytes while updating SHA-256 and a size counter.
Source data is read once. The uncompressed layer.tar is persisted only for a
Docker archive; otherwise diff_id is calculated without retaining that
stream. Gzip uses a fixed compression setting.
The result is represented as:
Layer {
diff_id,
descriptor,
uncompressed_size,
storage: Arc<LayerStorage>,
}
Concurrency preserves order
All copy directives enter a JoinSet, with a semaphore limiting active work to
--jobs. CPU- and disk-heavy work runs on the blocking thread pool. Each
result retains its input index:
COPY #1 ───────────────► result #1 ─┐
COPY #2 ─────► result #2 ├──► [#1, #2, #3]
COPY #3 ─────────► result #3 ───────┘
The coordinator orders results by directive position, not completion time. If two layers write the same image path, the later directive wins.
Temporary disk usage
At minimum, every new layer needs a compressed temporary blob. Docker archive output additionally needs the uncompressed tar:
registry / OCI archive:
sum of compressed COPY-layer sizes
Docker archive:
compressed COPY layers + uncompressed COPY layers
Archive outputs also download base layers. Docker archives temporarily
decompress them one at a time. The final archive’s temporary file is created
beside its destination and does not consume TMPDIR; layer temporary files do.
Plan CI storage for both filesystems. The tempfile crate follows the
TMPDIR environment variable on Unix.
Image configuration, manifest, and scratch
Assembly combines the base image, new layers, and runtime metadata into one
immutable ImageBundle. It is a CPU-only step over oci-spec values; it does
not access the network or filesystem.
Base-image representation
Image {
source: Option<ImageSource>,
config: ImageConfiguration,
layers: Vec<Descriptor>,
}
Some(ImageSource) records a real registry reference and its manifest digest.
None represents scratch. An empty base intentionally has no fabricated
registry identity that could leak into annotations or publication logic.
Registry base images
For a normal image reference, the registry adapter:
- selects credentials;
- fetches a manifest or selects a matching manifest from an image index;
- fetches the small configuration JSON;
- verifies its SHA-256 against the manifest descriptor;
- verifies OS, architecture, and optional variant against
--platform; - converts layer descriptors from
oci-clienttooci-spec; - retains descriptors without downloading layer bytes.
Before assembly, rib also verifies that the base layer count equals the
number of rootfs.diff_ids. A mismatch indicates an invalid base image.
FROM scratch
The exact word scratch means an entirely empty filesystem. rib creates no
registry client, downloads nothing, builds a fresh ImageConfiguration for
the selected platform, and starts with empty layers, diff IDs, and history. It
adds no base-image name or digest annotations.
scratch:latest and qualified references containing scratch are ordinary
registry image names. Once the empty base exists, local layers are added in the
same way as for any other image.
For a useful scratch image, supply a self-contained executable, an explicit
entrypoint, CA certificates for outbound TLS when needed, and every other
runtime file such as configuration, timezone, or user data. Rust applications
commonly use a musl target, but toolchain installation and cross-compilation
remain the user’s responsibility.
Updating the configuration
The assembler clones the base configuration or starts with an empty one, then:
- sets
created; - appends every new layer’s
diff_id; - appends one non-empty history entry per new layer when history exists;
- applies requested runtime metadata;
- verifies history/rootfs consistency;
- serializes the configuration;
- calculates its digest.
New history entries use:
rib copy (<uncompressed-size> bytes uncompressed)
They omit host paths and the full CLI, avoiding publication of internal CI paths or sensitive arguments.
Merging runtime metadata
- An explicit
--entrypointreplaces the baseEntrypoint. - Replacing it clears inherited
Cmdunless--keep-cmdis set or a new--cmdis supplied. Explicit--cmdreplaces the inherited value. --labelmerges into base labels and overwrites matching keys.--portextends base ports without duplicates.--workdirand--userchange only when explicitly supplied.- Other base metadata, including
Env, is preserved.
For scratch, only explicitly supplied runtime fields exist, alongside the
builder-generated platform, creation time, rootfs, and history.
History/rootfs invariant
Every history entry without empty_layer: true must correspond to exactly one
rootfs.diff_ids entry:
count(history where empty_layer != true) == count(rootfs.diff_ids)
Metadata-only history does not count. A base configuration with no history
keeps it absent. A scratch configuration starts with an empty history array,
so every new layer receives an entry.
Building the manifest
The assembler creates the configuration descriptor, keeps base layer
descriptors in order, appends new descriptors, adds the
org.opencontainers.image.created annotation, and records the real base name
and digest when applicable. It then serializes and hashes the manifest.
A scratch manifest has no base-image annotations. Each layer retains its
origin:
LayerSource::Built(Layer)
LayerSource::FromBase {
descriptor,
source: ImageSource,
}
Output code can therefore read a local blob, lazily download a base blob, or avoid a download through cross-repository mount without changing the manifest.
Registries and archive formats
Every output receives the same assembled ImageBundle; writers do not rebuild
the configuration or manifest. Registry, OCI archive, and Docker archive
outputs from one invocation therefore represent the same image and have the
same manifest digest.
No preliminary base-image pull
The initial request fetches only the manifest, configuration, and descriptors. Base layer bytes are downloaded only when:
- an OCI or Docker archive needs to be self-contained; or
- a target registry lacks a blob and cannot mount it from the source repository.
For archive output, unique base blobs are downloaded concurrently under the
--jobs limit before archive writing begins. For registry output, existing
blobs are detected by digest and reused; same-registry sources also attempt a
cross-repository mount. scratch has no base-layer download stage.
OCI archive
An OCI archive is a tar file containing an OCI Image Layout:
oci-layout
index.json
blobs/sha256/<manifest-hex>
blobs/sha256/<config-hex>
blobs/sha256/<layer-hex>
...
index.json contains one descriptor for the selected platform. A tag supplied
as --to oci-archive:image.tar@app:v1 becomes the descriptor annotation
org.opencontainers.image.ref.name, which import tools use as the image tag.
Configuration, manifest, and compressed layers are stored at paths derived from their digests. Duplicate digests are written once.
rib build ... \
--to oci-archive:dist/image.tar@example/app:v1
Docker archive
A Docker archive is compatible with docker save and docker load:
manifest.json
<config-hex>.json
<diff-id-hex>/layer.tar
...
manifest.json contains optional RepoTags and an ordered layer list. Unlike
OCI archives, Docker archives store uncompressed layers and are usually much
larger. When such an output is requested, rib retains an uncompressed tar for
each new layer and decompresses gzip- or zstd-compressed base layers into
temporary files as needed.
rib build ... \
--to docker-archive:dist/image.tar@example/app:v1
Atomic archive writing
An archive is first written to a temporary file beside its destination. The
writer finishes the tar, flushes buffers, calls fsync on the file, and
atomically renames it to the target path. If an earlier step fails, an existing
destination remains unchanged. Keeping the temporary file beside the target is
required because atomic rename is guaranteed only within one filesystem.
Registry publication
For each unique layer, rib uses the first applicable method:
blob exists in the target repository?
├── yes ─► reuse it
└── no
├── base layer from the same registry ─► attempt cross-repository mount
│ ├── success
│ └── failure ─┐
└── built layer or another registry ──────────────────┴─► upload
Cross-repository mount adds a reference to a blob already stored elsewhere in the same registry without transferring its bytes. Built layers are streamed from local temporary storage. A required base layer is downloaded lazily and then streamed to the target.
Layers upload concurrently under the --jobs limit. Configuration is uploaded
after layers, and the manifest is published last:
layers ──► config ──► manifest
│
└── the tag moves at this point
Manifest publication is the commit point. Until then, an existing tag still references its previous manifest; a failure cannot expose a partially uploaded image under the new tag.
Streaming and retries
Uploads use 4 MiB chunks and never load a complete layer into memory. A retry reopens and retransmits the file from the beginning; resumable upload is not implemented.
Timeouts, connection failures, HTTP 408, 425, 429, 500, and 502–599
are retried up to the configured attempt count with exponential backoff and
jitter. Authentication and digest errors are not retried. Small configuration
and manifest JSON values remain in memory, while layer memory usage stays
bounded regardless of image size.
Authentication and transport
Credential resolution for a registry is:
- explicit
--credential <registry>=<user>:<password>; authsin the one selected Docker configuration;- anonymous access.
The Docker configuration is selected from --docker-config, then
$DOCKER_CONFIG/config.json, then ~/.docker/config.json. No fallback to
other files occurs after selection. Docker Hub aliases are canonicalized to
registry-1.docker.io. credsStore and credHelpers are not executed.
Source and target registries use separate clients. --from-plain-http and
--from-skip-tls affect only the source role; corresponding --to-* options
affect every registry destination in that invocation. Use insecure transport
only for controlled local or development registries.
Cargo integration
The package installs cargo-rib, which Cargo invokes as:
cargo rib build
The integration converts Cargo metadata and CLI arguments into an
ImageBuildSpec, then uses the same image pipeline as rib build.
Operation sequence
cargo rib build:
- runs
cargo metadata --format-version 1 --no-deps; - selects a workspace package;
- reads
[package.metadata.rib]from itsCargo.toml; - merges metadata and CLI arguments;
- runs
cargo build --manifest-path <path>with the configured Cargo args; - verifies that
artifactexists and is a regular file; - adds it as the final
COPYlayer with mode0755; - assembles and publishes the image through the common pipeline.
Artifact path, platform, and base image are explicit. The integration does not infer a binary target, architecture, or linkage type.
Configuration location and format
Configuration belongs in [package.metadata.rib] for the selected package.
Field names use kebab-case, and unknown fields are errors. After metadata and
CLI merging, artifact, platform, from, and at least one to destination
are required. Any of them may come from either source; to is not restricted
to CI and is a normal metadata field.
Artifact and Cargo fields
| Field | Type and default | Description and example |
|---|---|---|
artifact | String; required after merging | Regular file produced by Cargo, for example "target/x86_64-unknown-linux-musl/release/taskd". Metadata paths are relative to Cargo.toml. |
cargo-args | String array; [] | Arguments after cargo build --manifest-path <path>, for example ["--release", "--locked", "--target", "x86_64-unknown-linux-musl", "--bin", "taskd"]. |
destination | String; /app/<artifact name> | Absolute artifact path in the image, for example "/usr/local/bin/taskd". It cannot end in /; the artifact is the final layer with mode 0755. |
copies | String array; [] | Extra layers such as ["config/default.toml:/etc/taskd/config.toml", "assets:/opt/taskd/assets/"], inserted before the artifact. Metadata sources are relative to Cargo.toml. |
Each copies item uses:
<source>:<destination>[,mode=<octal>][,chown=<uid>[:<gid>]]
copies = [
"config/default.toml:/etc/taskd/config.toml,mode=0644,chown=65532:65532",
"assets:/opt/taskd/assets/",
]
Base, platform, and destinations
| Field | Type and default | Description and example |
|---|---|---|
platform | String; required after merging | <os>/<arch>[/<variant>], such as "linux/amd64" or "linux/arm64/v8". The artifact is not inspected for compatibility. |
from | String; required after merging | A base such as "alpine:3.22", a digest-qualified reference, or exact "scratch". |
to | String array; [], at least one after merging | Registry, OCI archive, or Docker archive destinations. Multiple values are allowed. |
Relative archive paths in metadata are resolved from the Cargo.toml
directory. CLI destinations are appended after metadata destinations:
[package.metadata.rib]
to = ["oci-archive:dist/taskd.tar@taskd:local"]
cargo rib build --to registry:registry.example.com/team/taskd:v1
This creates both outputs. There is no CLI replacement mode for to; omit the
metadata field when a CI job should publish only to its dynamic destination.
Container runtime configuration
| Field | Type and default | Description and example |
|---|---|---|
entrypoint | String or string array; [destination] | OCI Entrypoint, such as "/taskd --log-format json" or ["/taskd", "--log-format", "json"]. Replacing it clears inherited Cmd unless cmd or keep-cmd = true is set. |
cmd | String or string array; not explicitly set | OCI Cmd, such as ["serve", "--port", "8080"]; replaces inherited Cmd. |
labels | String array; [] | key=value labels merged with base labels; duplicate keys are overwritten. |
ports | String array; [] | Ports such as ["8080", "8443/tcp", "8125/udp"]; omitted protocols become /tcp. |
workdir | String; inherited | Process working directory, for example "/var/lib/taskd". |
user | String; inherited | OCI user such as "65532:65532", "1000", or "app"; existence is not checked in rootfs. |
keep-cmd | Boolean; false | Retains base Cmd when Entrypoint changes; does not override explicit cmd. |
creation-time | String; "epoch" | "epoch", "now", or RFC 3339 such as "2026-08-27T12:00:00Z". Use epoch for reproducibility. |
String entrypoint and cmd values use shell quoting rules. Arrays specify
argv without further parsing and are preferable when argument boundaries must
be exact.
Concurrency and cache
| Field | Type and default | Description and example |
|---|---|---|
jobs | Positive integer; available CPUs capped at 4 | Maximum simultaneous layer builds and blob transfers. |
cache | Boolean; false | Enables persistent caching of downloaded base layers, not built layers. |
cache-path | String; ".rib-cache" when enabled | Cache directory such as "/cache/rib". This field alone does not enable caching. Relative paths use the process working directory. |
Registry client fields
| Field | Type and default | Description |
|---|---|---|
connect-timeout | Positive integer; 30 | Connection timeout in seconds. |
read-timeout | Positive integer; 60 | Registry read timeout in seconds. |
max-attempts | Positive integer; 3 | Maximum attempts for each registry operation. |
from-plain-http | Boolean; false | HTTP for the source registry; development use only. |
from-skip-tls | Boolean; false | Disables source TLS certificate verification; not for production. |
to-plain-http | Boolean; false | HTTP for every registry destination; development use only. |
to-skip-tls | Boolean; false | Disables certificate verification for every registry destination; not for production. |
Credentials, Docker configuration, and progress mode are intentionally absent
from metadata. Supply them through --credential, --docker-config, and
--progress or the environment; do not put secrets in Cargo.toml.
Metadata and CLI merging
- CLI scalar values replace metadata values.
- Explicit boolean flags replace metadata:
--cacheand--cache=trueenable caching, while--cache=falsedisables it. The same syntax applies to--keep-cmd,--from-plain-http,--from-skip-tls,--to-plain-http, and--to-skip-tls. Omitting the flag retains the metadata value. to,copies,labels,ports, and Cargo arguments are concatenated with metadata values first.- The artifact is always the final layer.
- Artifact and copy sources from metadata are relative to
Cargo.toml; CLI sources are relative to the current working directory.
Cargo arguments from the CLI follow -- and are appended after cargo-args:
cargo rib build -- --release --locked --bin taskd
Complete configuration example
This example includes every supported metadata field:
[package]
name = "taskd"
version = "0.1.0"
edition = "2021"
rust-version = "1.94"
[package.metadata.rib]
artifact = "target/x86_64-unknown-linux-musl/release/taskd"
cargo-args = [
"--release",
"--locked",
"--target", "x86_64-unknown-linux-musl",
"--bin", "taskd",
]
destination = "/taskd"
copies = [
"config/default.toml:/etc/taskd/config.toml,mode=0644,chown=65532:65532",
"assets:/opt/taskd/assets/",
]
platform = "linux/amd64"
from = "scratch"
to = [
"registry:registry.example.com/team/taskd:v1",
"oci-archive:dist/taskd.tar@taskd:v1",
]
entrypoint = ["/taskd"]
cmd = ["serve", "--port", "8080"]
labels = [
"org.opencontainers.image.title=taskd",
"org.opencontainers.image.version=0.1.0",
]
ports = ["8080/tcp"]
workdir = "/"
user = "65532:65532"
keep-cmd = false
creation-time = "epoch"
jobs = 4
cache = true
cache-path = ".rib-cache"
connect-timeout = 30
read-timeout = 60
max-attempts = 3
from-plain-http = false
from-skip-tls = false
to-plain-http = false
to-skip-tls = false
With to configured, no CLI destination is required:
cargo rib build
Credentials remain external:
cargo rib build \
--credential "registry.example.com=${REGISTRY_USER}:${REGISTRY_PASSWORD}"
For a CI-generated tag, omit metadata to and pass it dynamically:
cargo rib build \
--credential "$CI_REGISTRY=$CI_REGISTRY_USER:$CI_REGISTRY_PASSWORD" \
--to "registry:$CI_REGISTRY_IMAGE/taskd:$CI_COMMIT_SHORT_SHA"
This is a configuration choice, not a limitation of Cargo integration.
Configuration without metadata
Every required value can be supplied through CLI options:
cargo rib build \
--artifact target/x86_64-unknown-linux-musl/release/taskd \
--platform linux/amd64 \
--from scratch \
--to registry:registry.example.com/team/taskd:v1 \
--destination /taskd \
--copy config/default.toml:/etc/taskd/config.toml \
--entrypoint /taskd \
-- \
--release --locked --target x86_64-unknown-linux-musl --bin taskd
Workspace package selection
When the current directory is within a Cargo package, that package is chosen.
From a virtual workspace root, selection succeeds only with one
workspace.default-member or a single package in the workspace. For an
ambiguous workspace, run cargo rib build from the required package directory.
Integration limitations
cargo rib build does not detect artifact architecture or linkage, add dynamic
loaders or shared libraries, install Rust targets, cross-compile, or discover
certificates and other runtime files. With from = "scratch", include all
dependencies in the artifact or list them in copies.
Operations
rib is designed primarily for non-interactive CI/CD use while retaining the
same interface locally. Production pipelines should pin the builder version,
platform, base-image digest, and network settings.
Progress, stderr, and stdout
--progress accepts:
| Mode | Behavior |
|---|---|
auto | Interactive UI when stderr is a terminal; line output otherwise |
color | Forces the interactive UI |
plain | Stable line-oriented CI messages |
quiet | Hides progress while retaining the final summary |
Progress, warnings, and the summary go to stderr. When stdout is not a terminal, a successful build writes only the manifest digest, without a prefix or trailing newline:
IMAGE_DIGEST="$(rib build \
--progress plain \
--from scratch \
--platform linux/amd64 \
--copy ./server:/server,mode=0755 \
--entrypoint /server \
--to registry:registry.example.com/team/server:v1)"
cosign sign "registry.example.com/team/server@${IMAGE_DIGEST}"
Do not enable shell tracing around commands containing credentials, because
the shell may log raw arguments before rib starts.
Concurrency
--jobs limits concurrent COPY builds, base-blob downloads, and target-blob
uploads. The default is the available CPU count capped at four. Increasing it
may improve network throughput while increasing CPU, disk, and registry load.
Reduce it under tight ephemeral-storage or bandwidth limits.
Destinations are processed sequentially in declaration order. Layer operations within one registry destination are concurrent.
Temporary data and base-layer cache
Layer temporary files use the system temporary directory (TMPDIR on Unix).
Registry and OCI outputs normally retain only compressed local layers. Docker
archive output also retains uncompressed layers. The archive’s own temporary
file is created beside its final path.
For large images, provision storage for compressed local layers, downloaded base layers, uncompressed Docker layers, and the temporary final archive.
Downloaded base blobs are not persistent by default. Enable caching with:
rib build ... --cache
rib build ... --cache --cache-path /cache/rib
The default path is ./.rib-cache. Cached blobs are rehashed before reuse.
This cache stores downloaded base layers only; it neither stores built layers
nor replaces Cargo/npm caches. Multiple rib processes may share the directory:
writers use separate staging files and publish atomically after digest and size
verification. Incomplete downloads never replace complete entries. Cache
verification runs on the blocking pool under --jobs and observes cancellation.
A direct push to the same registry usually needs no local cache because
registry-side blob reuse avoids downloads.
Network transport
Defaults are a 30-second connect timeout, a 60-second read timeout, three
attempts, and HTTPS with certificate verification. Configure these through
--connect-timeout, --read-timeout, and --max-attempts.
Source and target insecure options are separate:
--from-plain-http,--from-skip-tls;--to-plain-http,--to-skip-tls.
The target options affect all registry destinations in the invocation. Use them only for trusted development infrastructure.
Multiple destinations
rib build \
--from alpine:3.22 \
--platform linux/amd64 \
--copy ./server:/app/server,mode=0755 \
--entrypoint /app/server \
--to registry:registry.example.com/team/server:v1 \
--to oci-archive:dist/server-oci.tar@server:v1 \
--to docker-archive:dist/server-docker.tar@server:v1
The configuration and manifest are created once, so all outputs have one manifest digest. They do not form a transaction: failure of a later output does not roll back completed registry publications or archives.
Logs and diagnostics
Enable detailed logs with:
RIB_LOG=rib=debug rib build --progress plain ...
RUST_LOG is intentionally not used because cargo rib build launches a user
Rust project that may interpret it. Use plain, quiet, or auto in CI;
color may emit terminal control sequences.
Termination and partially published data
Ctrl-C and, on Unix, SIGTERM cancel the top-level operation. Copy, archive, and layer-decompression writers check cancellation during writes. A cancelled archive remains temporary and is not published at its target path.
Archives become visible through an atomic rename only after a complete write and file synchronization. Registry manifests are sent after layers and the configuration. Unreferenced blobs uploaded before an error can remain until normal registry garbage collection.
CI/CD, Docker, and Kubernetes
rib runs as an ordinary unprivileged process. A job needs no Docker socket,
Docker-in-Docker, privileged container, or access to the node’s container
runtime. This applies to shell, Docker, and Kubernetes executors.
A practical build image contains the application’s compiler/runtime, rib or
cargo-rib, and pipeline tools such as cosign and the Vault CLI. The runner
caches this image through its normal container mechanism; no separate build
daemon cache has to be transferred between jobs.
Building a frontend and signing with cosign
This GitLab job assumes that frontend contains built static files, the base
image contains execenv and static-web-server, the job image contains
rib, Vault, and cosign, and Vault has the corresponding JWT role and
Transit key.
default:
tags:
- core-os
stages:
- Build
build_image_rib:
image: registry.gitlab.com/devdsk/education/rust/rib/rib:v0.1.0
stage: Build
id_tokens:
VAULT_ID_TOKEN:
aud: https://gitlab.com
variables:
VAULT_AUTH_PATH: auth/jwt/login
VAULT_AUTH_ROLE: cosign
TRANSIT_SECRET_ENGINE_PATH: cosign
VAULT_ADDR: https://vault.core-os.ru
COSIGN_KEY: hashivault://cosign
HOME: /tmp
script:
- |
IMAGE_DIGEST="$(
rib build \
--from "$CI_REGISTRY_IMAGE/frontend-base:1.0" \
--credential "$CI_REGISTRY=$CI_REGISTRY_USER:$CI_REGISTRY_PASSWORD" \
--copy "./frontend:/frontend,chown=65532:65532" \
--entrypoint "/execenv -m error -f /frontend/config.js --exec /static-web-server -p 8787 -d /frontend -g info" \
--to "registry:$CI_REGISTRY_IMAGE/taskd-frontend:$CI_COMMIT_SHORT_SHA"
)"
- |
VAULT_TOKEN="$(
vault write --field=token "$VAULT_AUTH_PATH" \
role="$VAULT_AUTH_ROLE" \
jwt="$VAULT_ID_TOKEN"
)"
export VAULT_TOKEN
- cosign login "$CI_REGISTRY" -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD"
- >
cosign sign --tlog-upload=false
"${CI_REGISTRY_IMAGE}/taskd-frontend@${IMAGE_DIGEST}"
Progress stays visible on stderr, while IMAGE_DIGEST receives only
sha256:...; cosign signs the immutable manifest rather than a mutable tag.
There is no preliminary base pull. Because source and target use one GitLab
registry, inherited blobs can be reused or mounted without passing through the
job filesystem.
Building a Rust project through Cargo integration
Include cargo-rib in an image that already contains the Rust toolchain and
the x86_64-unknown-linux-musl target. GitLab caches the builder image, while
the Cargo registry and target use the standard CI cache.
default:
tags:
- core-os
variables:
CARGO_HOME: "$CI_PROJECT_DIR/.cargo"
stages:
- Build
cache:
key:
files:
- Cargo.lock
prefix: "$CI_COMMIT_REF_SLUG"
paths:
- .cargo/registry/index/
- .cargo/registry/cache/
- .cargo/git/db/
- target/
build_image_rib:
image: registry.gitlab.com/devdsk/education/rust/taskd/rust-builder/rust-rib:alpine3.24
stage: Build
script:
- >
cargo rib build
--credential "$CI_REGISTRY=$CI_REGISTRY_USER:$CI_REGISTRY_PASSWORD"
--to "registry:$CI_REGISTRY_IMAGE/taskd:$CI_COMMIT_SHORT_SHA"
Image parameters live next to the source in Cargo.toml. This example passes
--to because its tag is generated by the pipeline; a fixed destination can
instead use metadata to.
[package]
name = "taskd"
version = "0.1.0"
edition = "2021"
rust-version = "1.94"
[package.metadata.rib]
artifact = "target/x86_64-unknown-linux-musl/release/taskd"
platform = "linux/amd64"
from = "scratch"
destination = "/taskd"
entrypoint = "/taskd"
workdir = "/"
user = "65532:65532"
ports = ["8080"]
creation-time = "epoch"
jobs = 4
cargo-args = [
"--release",
"--locked",
"--target", "x86_64-unknown-linux-musl",
]
cargo rib build runs Cargo, verifies the artifact, adds it last with mode
0755, and publishes the image. A scratch artifact must be statically linked
or accompanied by all runtime dependencies through copies.
Running in a Kubernetes executor
With GitLab Runner’s Kubernetes executor, these jobs require no custom
Kubernetes manifest. The runner creates an ordinary pod from the selected job
image. Configure only normal resource requests and limits, network access to
the registries and secret services, and sufficient emptyDir/ephemeral storage
for Cargo outputs, temporary layers, and archives. No host paths, Docker socket,
or privileged security context are required.
Reproducibility and security
What a reproducible result means
With identical inputs and the same rib and dependency versions,
reproducibility means byte-for-byte identical layers, configuration, manifest,
and digest—not merely equivalent filesystem contents.
rib removes common tar/gzip variability:
- tar entries are sorted;
- every entry has
mtime = 0; - default UID/GID is
0, and user/group names are empty; - permissions follow fixed normalization rules;
- gzip uses a fixed compression setting;
- image creation time defaults to the Unix epoch;
- concurrently built layers are restored to input order.
--creation-time now intentionally makes configuration and manifest depend on
wall-clock time. For reproducibility, use epoch or a fixed RFC 3339 value such
as the commit time.
Factors that affect output
Result bytes depend on source contents and executable bits, copy list and
order, explicit mode/ownership, platform, base configuration and descriptors,
runtime metadata, and the exact rib and serialization/compression dependency
versions.
Base tags are mutable. Pin a digest for strict repeatability:
rib build \
--from alpine@sha256:<manifest-digest> \
--platform linux/amd64 \
...
Treat the builder version as part of provenance and pin it in CI.
Data integrity
Downloaded base configuration bytes are rehashed and checked against the manifest descriptor. Assembly verifies layer/diff-ID counts and history consistency. The summary goes to stderr; redirected stdout receives only the manifest digest, which can be stored as an immutable deployment reference.
rib does not sign or create provenance. Pass the digest to a dedicated tool:
IMAGE_DIGEST="$(rib build ... --to registry:registry.example.com/team/app:v1)"
cosign sign "registry.example.com/team/app@${IMAGE_DIGEST}"
Credentials
- Prefer a read-only Docker configuration or an external secret store over a literal password.
- Never store credentials in
Cargo.toml; metadata deliberately excludes them. - Do not use
set -xaround--credential. - Scope tokens to the required repositories and pull/push permissions.
- Where the threat model requires it, use separate source and target registry accounts. Credentials are selected by registry host, so separate identities for two repositories on the same host are not supported within one run.
TLS
HTTPS with certificate verification is the default. Plain HTTP removes
encryption; --*-skip-tls keeps HTTPS but disables server identity validation.
Source and destination roles are configured separately, but an insecure target
option affects every target registry in that invocation. Do not combine a
development target requiring --to-skip-tls with a production target in the
same command.
--copy as a trust boundary
rib reads every explicitly selected file and every glob match. There is no
.dockerignore equivalent. Broad source directories can accidentally include
.env, private keys, credentials, source code, .git, or logs. Prefer narrow
paths and inspect resulting images or archives in CI.
Symbolic-link sources and special files are rejected. Destination paths with
empty, . or .. components are also rejected, preventing unexpected
filesystem traversal.
scratch and runtime security
scratch minimizes included files but does not automatically secure an
application. Keep static dependencies updated, add CA certificates when
needed, set a non-root user, exclude secrets, provide application-level logs,
metrics and health checks, and scan the executable itself.
Minimal images contain no shell for interactive diagnosis. In Kubernetes,
plan for ephemeral debug containers rather than relying on kubectl exec into
the application image.
Publication safety
An archive replaces its target only after a complete write, file
synchronization, and atomic rename. A registry manifest is published only after
all layers and configuration are available. These mechanisms prevent partial
results from becoming visible, but multiple --to destinations are still not
one transaction and cannot roll one another back.
Limitations
Image construction
- Only file addition through
COPYand runtime metadata changes are supported; there is noRUNor Dockerfile parser. - Package installation and whiteout layers for removing base files are absent.
- Symbolic links and special source files are rejected.
- File names copied into the image must be UTF-8; invalid names are rejected instead of being silently replaced.
- One invocation creates one platform-specific manifest. Build a multi-platform index with another tool or pipeline stage.
scratchcontains no libc, CA certificates, shell, or runtime files.
Caching
- Without
--cache, downloaded base blobs are removed after the process exits. - The cache stores only downloaded base layers, not built
COPYlayers. - Registry-side blob checks and cross-repository mounts normally make a local cache unnecessary for repeated pushes to the same registry.
Cargo integration
- Artifact, platform, and base image are explicit.
- Cross-compilation, target installation, and binary-target selection are not automatic.
- Artifact architecture and linkage are not inspected.
- In an ambiguous workspace, run the command from the required package.
Registries and publication
- Multiple destinations are sequential and non-transactional.
- A failure in a later destination does not roll back earlier results.
- Blob retries restart from the beginning; resumable upload is absent.
- Docker credential helpers are not executed; only explicit credentials and
the
authssection are supported. - Signing, SBOM, and provenance are external; stdout exposes the manifest
digest for tools such as
cosign.
Possible future work
- caching built layers;
- multi-platform index generation;
- registry-native referrers for SBOM and provenance;
- resumable uploads;
- external credential providers and cloud workload identity;
- coordination across multiple publication destinations.