Skip to content

Rootless OCI image import into kbox rootfs #17

@jserv

Description

@jserv

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:

  1. Pull: fetch manifest and layers from registry (skopeo or equivalent).
    Multi-arch manifest selection is required (x86_64 and aarch64 support).
  2. Unpack: extract layers handling full OCI semantics (whiteouts, opaque
    directories, hardlinks, symlinks, xattrs, special files).
  3. 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.
  4. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions