46 lines
2.1 KiB
Markdown
46 lines
2.1 KiB
Markdown
# OCI import — internals
|
|
|
|
> **Advanced reading.** This document describes implementation details of the
|
|
> OCI import pipeline. It is not needed for day-to-day use of
|
|
> `banger image pull`. User-facing documentation is in
|
|
> [`docs/oci-import.md`](oci-import.md).
|
|
|
|
## Architecture
|
|
|
|
`internal/imagepull/` owns the mechanics:
|
|
|
|
- **`Pull`** wraps `go-containerregistry`'s `remote.Image` with the
|
|
`linux/amd64` platform pinned. Layer blobs cache under
|
|
`/var/cache/banger/oci/blobs/` (system install) or
|
|
`~/.cache/banger/oci/blobs/` (dev mode) and populate lazily during
|
|
flatten.
|
|
- **`Flatten`** replays layers oldest-first into a staging directory,
|
|
applies whiteouts, rejects unsafe paths plus filenames that banger's
|
|
debugfs ownership fixup cannot encode safely. Returns a `Metadata`
|
|
map of per-file uid/gid/mode from tar headers.
|
|
- **`BuildExt4`** runs `mkfs.ext4 -F -d <staging> -E root_owner=0:0`
|
|
at the size of the pre-truncated file — no mount, no sudo, no
|
|
loopback. Requires `e2fsprogs ≥ 1.43`.
|
|
- **`ApplyOwnership`** streams a batched `set_inode_field` script to
|
|
`debugfs -w` to rewrite per-file uid/gid/mode to the captured tar-
|
|
header values.
|
|
- **`InjectGuestAgents`** uses the same `debugfs` scripting to drop
|
|
banger's guest assets into the ext4 with root ownership:
|
|
vsock agent binary, network bootstrap + unit, first-boot script +
|
|
unit, `multi-user.target.wants` symlinks, vsock modules-load
|
|
config, `/var/lib/banger/first-boot-pending` marker.
|
|
|
|
`internal/daemon/images_pull.go` orchestrates `pullFromOCI`:
|
|
|
|
1. Parse + validate the OCI ref, derive a default name when `--name`
|
|
is omitted (`debian-bookworm` from
|
|
`docker.io/library/debian:bookworm`).
|
|
2. Resolve kernel info via `resolveKernelInputs` (auto-pulls from
|
|
`kernelcat` if `--kernel-ref` names a catalog entry that isn't
|
|
yet local).
|
|
3. Stage at `<ImagesDir>/<id>.staging`; extract layers to a temp
|
|
tree under `$TMPDIR`.
|
|
4. `BuildExt4` → `ApplyOwnership` → `InjectGuestAgents`.
|
|
5. `imagemgr.StageBootArtifacts` stages the kernel triple alongside.
|
|
6. Atomic `os.Rename` publishes the artifact dir.
|
|
7. Persist a `model.Image{Managed: true, …}` record.
|