Thales Maciel
6083e2dde5
The golden-image Dockerfile + catalog pipeline replaces the entire
manual rootfs-build stack. With that shipped, the per-distro shell
flows are dead code.
Removed:
- scripts/customize.sh, scripts/interactive.sh, scripts/verify.sh
- scripts/make-rootfs{,-void,-alpine}.sh
- scripts/register-{void,alpine}-image.sh
- scripts/make-{void,alpine}-kernel.sh
- internal/imagepreset/ (only consumer was `banger internal packages`,
which fed customize.sh)
- examples/{void,alpine}.config.toml
- Makefile targets: rootfs, rootfs-void, rootfs-alpine, void-kernel,
alpine-kernel, void-register, alpine-register, void-vm, alpine-vm,
verify-void, verify-alpine, plus the ALPINE_RELEASE / *_IMAGE_NAME
/ *_VM_NAME variables
The void-6.12 kernel catalog entry is also gone — golden image pairs
with generic-6.12 and nothing else in the catalog depended on it.
Consolidated: imagemgr now holds the small DebianBasePackages list +
package-hash helper inline, so the `image build --from-image` flow
(still supported) no longer pulls from a separate imagepreset package.
Net: 3,815 lines deleted, 59 added. No runtime functionality removed
beyond the `banger internal packages` subcommand (hidden, used only
by the deleted customize.sh).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
134 lines
5.3 KiB
Markdown
134 lines
5.3 KiB
Markdown
# Kernel catalog
|
|
|
|
The kernel catalog ships pre-built Firecracker-ready kernel bundles so users
|
|
don't have to compile anything. The catalog is embedded into the banger
|
|
binary and updated each release.
|
|
|
|
End-user flow:
|
|
|
|
```bash
|
|
banger kernel list --available # browse the catalog
|
|
banger kernel pull void-6.12 # download a bundle (no sudo, no make)
|
|
banger image register --name void --rootfs … --kernel-ref void-6.12
|
|
```
|
|
|
|
## Architecture
|
|
|
|
Two parts:
|
|
|
|
1. **`internal/kernelcat/catalog.json`** — a JSON manifest embedded into the
|
|
banger binary via `go:embed`. Each entry carries a name, distro, arch,
|
|
kernel version, tarball URL, and tarball SHA256. Updating the catalog
|
|
means editing this file in the repo and rebuilding banger.
|
|
|
|
2. **Tarballs at `https://kernels.thaloco.com/`** — Cloudflare R2 bucket
|
|
`banger-kernels`, fronted by a public custom domain. Each tarball is
|
|
`<name>-<arch>.tar.zst` and contains `vmlinux`, optional `initrd.img`,
|
|
and an optional `modules/` tree at the archive root.
|
|
|
|
The `banger kernel pull` flow streams the tarball, verifies its SHA256
|
|
against the embedded catalog entry, decompresses it (zstd), extracts it
|
|
into `~/.local/state/banger/kernels/<name>/`, and writes a manifest. Path
|
|
traversal entries and unsafe symlinks are rejected.
|
|
|
|
## Kernel types
|
|
|
|
**`generic-<version>`** — built from upstream kernel.org sources with
|
|
Firecracker's official config. All essential drivers (virtio_blk,
|
|
virtio_net, ext4, vsock) compiled in — no modules, no initramfs. This
|
|
is the kernel the golden image pairs with and the recommended kernel
|
|
for OCI-pulled images. Build with `scripts/make-generic-kernel.sh`.
|
|
|
|
## Adding or updating an entry
|
|
|
|
The repo has no CI for kernel publishing yet. Catalog updates are manual
|
|
and infrequent (kernel version bumps every few weeks at most).
|
|
|
|
```bash
|
|
# 1. Build the kernel locally.
|
|
scripts/make-generic-kernel.sh
|
|
|
|
# 2. Import it into the local catalog so the canonical layout exists.
|
|
banger kernel import generic-6.12 \
|
|
--from build/manual/generic-kernel \
|
|
--distro generic \
|
|
--arch x86_64
|
|
|
|
# 3. Package, upload, patch catalog.json.
|
|
scripts/publish-kernel.sh generic-6.12 \
|
|
--description "Generic Firecracker kernel 6.12 (all drivers built-in, no initrd)"
|
|
|
|
# 4. Review and commit the catalog change.
|
|
git diff -- internal/kernelcat/catalog.json
|
|
git add internal/kernelcat/catalog.json
|
|
git commit -m 'kernel catalog: add/update generic-6.12'
|
|
|
|
# 5. Rebuild so the new catalog is embedded.
|
|
make build
|
|
```
|
|
|
|
`scripts/publish-kernel.sh` reads the locally-imported entry under
|
|
`~/.local/state/banger/kernels/<name>/`, builds a tar+zstd archive, uploads
|
|
it to R2 via `rclone`, HEAD-checks the public URL, and patches
|
|
`internal/kernelcat/catalog.json` with the new URL, SHA256, and size.
|
|
|
|
Environment overrides if the defaults need to change:
|
|
`RCLONE_REMOTE`, `RCLONE_BUCKET`, `BASE_URL`, `BANGER_KERNELS_DIR`.
|
|
|
|
## Removing an entry
|
|
|
|
1. Delete the line from `internal/kernelcat/catalog.json` and commit.
|
|
2. Delete the tarball from R2: `rclone delete r2:banger-kernels/<name>-<arch>.tar.zst`.
|
|
3. Rebuild banger.
|
|
|
|
Already-pulled local copies on user machines are not invalidated — they
|
|
keep working until the user runs `banger kernel rm <name>`. That's
|
|
intentional: pulling is idempotent, removing should not break anyone in
|
|
the middle of a workflow.
|
|
|
|
## Versioning conventions
|
|
|
|
- **Entry names**: `<distro>-<major.minor>` (e.g. `void-6.12`,
|
|
`alpine-3.23`). The major.minor is the kernel line, not the distro
|
|
release. Patch-level bumps reuse the entry name and replace the
|
|
tarball; minor bumps create a new entry (`void-6.13`).
|
|
- **Architecture**: only `x86_64` is published today. The `arch` field in
|
|
the catalog schema is additive — adding `arm64` later is a config
|
|
change, not a schema change.
|
|
- **Tarball layout**: contents at the archive root (no top-level
|
|
versioned directory). `vmlinux` is required; `initrd.img` and
|
|
`modules/` are optional. Symlinks inside `modules/` are allowed but
|
|
must resolve within the archive.
|
|
|
|
## Trust model
|
|
|
|
The embedded `catalog.json` carries the SHA256 of each tarball. `banger
|
|
kernel pull` rejects any download whose hash doesn't match. This protects
|
|
against transport corruption and against an attacker swapping a tarball
|
|
on R2 without also pushing a banger release.
|
|
|
|
It does **not** protect against a compromise of the banger source repo
|
|
itself — an attacker who can land a commit can change both the catalog
|
|
SHA256 and the tarball. GPG/sigstore signing is deferred until banger is
|
|
public and the threat model justifies the operational overhead.
|
|
|
|
## Hosting
|
|
|
|
Tarballs live in Cloudflare R2 (bucket `banger-kernels`), served at the
|
|
custom domain `kernels.thaloco.com`. The bucket is publicly readable;
|
|
writes require the `banger-kernels-publish` API token (kept locally,
|
|
never committed). R2's free tier covers the expected traffic comfortably
|
|
(zero egress fees, generous storage).
|
|
|
|
If hosting ever moves, catalog entries can be migrated by reuploading the
|
|
tarballs and editing the URLs in `catalog.json` — no other code changes
|
|
required.
|
|
|
|
## Tech debt
|
|
|
|
- Kernel publishing is manual; there is no CI yet. `scripts/make-generic-kernel.sh`
|
|
plus `scripts/publish-kernel.sh` is fine while refreshes are
|
|
infrequent and maintainer-only. CI becomes relevant once banger
|
|
goes public.
|
|
- `make lint-shell` runs at `--severity=error` only. Tightening to
|
|
`--severity=warning` is a nice-to-have but low priority.
|