Problem
Users must manually prepare ext4 images before running kbox. There is no
import pipeline from OCI/Docker image references to a kbox-usable rootfs
artifact.
Proposed Changes
Support --image=docker://alpine:latest by implementing rootless OCI pull,
extraction, and ext4 materialization:
- Pull: fetch manifest and layers from registry (skopeo or equivalent).
Multi-arch manifest selection is required (x86_64 and aarch64 support).
- Unpack: extract layers handling full OCI semantics (whiteouts, opaque
directories, hardlinks, symlinks, xattrs, special files).
- Materialize: convert extracted directory tree into an ext4 image via
rootless mke2fs -d, preserving UID/GID ownership metadata baked into
ext4 inodes. This bridges the gap between umoci's directory output and
kbox's ext4 image requirement.
- Cache: layer-level caching keyed by digest for fast subsequent runs.
Integrate with or extend the existing mkrootfs.sh image creation flow.
Considerations
- Integrity vs signatures: pull-by-digest provides integrity and
reproducibility. Signature verification (cosign/notation) is a separate,
optional feature and should not be conflated with digest-based integrity.
Mutable tags (:latest) should work but documentation should recommend
digest pinning for reproducibility.
- Rootless UID/GID: fake-ownership via xattrs during unpack phase,
translated into real ext4 inodes by mke2fs -d. Verify this works for
root-owned files (UID 0) when running as unprivileged user.
- Multi-arch: manifest list / OCI index selection must match the host
architecture. Critical since kbox targets both x86_64 and aarch64.
- OCI edge cases: whiteout files (
.wh.*), opaque directories
(.wh..wh..opq), hardlinks across layers, file capabilities in xattrs,
device nodes (may need to skip or synthesize).
- Registry auth: support for private registries, token-based auth,
rate limiting (Docker Hub), and offline/cached operation.
- Alternative to ext4: longer-term, host directory mounting via 9p or
virtiofs could eliminate the ext4 materialization step entirely, but that
is a separate architectural change.
Problem
Users must manually prepare ext4 images before running kbox. There is no
import pipeline from OCI/Docker image references to a kbox-usable rootfs
artifact.
Proposed Changes
Support
--image=docker://alpine:latestby implementing rootless OCI pull,extraction, and ext4 materialization:
Multi-arch manifest selection is required (x86_64 and aarch64 support).
directories, hardlinks, symlinks, xattrs, special files).
rootless
mke2fs -d, preserving UID/GID ownership metadata baked intoext4 inodes. This bridges the gap between umoci's directory output and
kbox's ext4 image requirement.
Integrate with or extend the existing
mkrootfs.shimage creation flow.Considerations
reproducibility. Signature verification (cosign/notation) is a separate,
optional feature and should not be conflated with digest-based integrity.
Mutable tags (
:latest) should work but documentation should recommenddigest pinning for reproducibility.
translated into real ext4 inodes by
mke2fs -d. Verify this works forroot-owned files (UID 0) when running as unprivileged user.
architecture. Critical since kbox targets both x86_64 and aarch64.
.wh.*), opaque directories(
.wh..wh..opq), hardlinks across layers, file capabilities in xattrs,device nodes (may need to skip or synthesize).
rate limiting (Docker Hub), and offline/cached operation.
virtiofs could eliminate the ext4 materialization step entirely, but that
is a separate architectural change.