README
¶
embedimg — embedded curated runtime images (ADR-0054)
This package go:embeds funcd's curated runtime image tars into the binary so funcd is
self-contained: at startup the ctrmanager imports the matching-arch
tar into its privately-managed containerd (client.Import) and the platform runs functions
with no registry pull (the k3s/dockerd model).
The committed .tar files are PLACEHOLDERS
nodejs22.tar and python314.tar as committed are tiny (<1 KB) clearly-labeled
stand-ins, not real OCI images. They exist for one reason: go:embed needs a file at
compile time, and embedimg.Tar(...) must return a non-empty reader for the ADR-0054
non-gated unit test. go build and just ci are green on these placeholders.
Real multi-MB per-arch images are never committed: they are a release/integration
artifact. Building them requires docker on a Linux target and importing them requires
root + a live containerd — the deferred Linux integration lane (FUNCD_IT=1).
Producing the real images (release / integration time)
The real images replace the placeholders via:
just build-runtime-images # docker build the distroless images, docker save -> gzip -9 OCI tars
This recipe (see the repo justfile) builds:
images/runtime/nodejs22/Dockerfile— node ongcr.io/distroless/nodejs22-debian12images/runtime/python314/Dockerfile— custom distroless Python 3.14 ongcr.io/distroless/cc-debian12
exports each to an OCI tar at gzip max compression (-9, shared base layers where possible),
and writes them into this directory as nodejs22.tar / python314.tar, per arch (a
per-arch release build embeds its own matching-arch image — ADR-0054). The recipe is not
run by just ci.
Keeping the working tree clean after a build (skip-worktree)
build-runtime-images overwrites the committed placeholders with real 30–100 MB tars, which
would otherwise leave the working tree permanently dirty and risk a git commit -a staging a
build artifact. To prevent that, the recipe first runs just embedimg-pin, which sets git's
skip-worktree bit on the three *.tar files: git then ignores the local overwrite, so
git status/git commit never see it and you never have to git checkout the tars after a lane
run. The index keeps the placeholder blob, so commits and the check-hygiene guard are unaffected.
The bit is local to each clone (it lives in .git/index, not shared through the repo) — hence
the recipes, so a fresh clone can opt in with one command:
just embedimg-pin # ignore local image-build overwrites (auto-run by build-runtime-images)
just embedimg-unpin # clear it — needed before a legitimate placeholder update (e.g. a git pull)
check-hygiene remains the backstop: even with the bit off, it blocks committing a >4 KB blob.
Override (no registry by default)
A runtime with an --image runtime=ref override (ImageOverride, mapped by
ctrmanager.Config.ImageFor) runs that ref instead of its curated image. The embed serves only
the image it carries (funcd/runtime-<rt>:latest). A runtime image is pulled only from a registry
the operator chose (ctrmanager.Config.Pullable): an imageOverride entry or a custom
imagePrefix (e.g. ghcr.io/pyvvo/…). With the default prefix only the embedded images are used,
so a runtime in neither embed nor override is a fault.NotFound — never a silent miss.
Documentation
¶
Overview ¶
Package embedimg carries funcd's curated runtime images baked into the binary (ADR-0054). At release/integration time each per-arch curated image is exported to an OCI tar and embedded here via go:embed; at startup the ctrmanager imports the matching tar into the privately-managed containerd (client.Import) so the platform runs functions with NO registry pull (the k3s/dockerd self-contained model).
PLACEHOLDER NOTE (impl-time, honest): the committed nodejs22.tar / python314.tar are tiny (<1 KB) clearly-labeled STAND-INS, not real OCI images — they exist only so the embed directive has a file at compile time and Tar(...) returns a non-empty reader (the ADR-0054 non-gated unit test). The REAL multi-MB per-arch distroless tars are produced by `just build-runtime-images` and overwrite the placeholders before the binary ships (see README.md). `go build` / `just ci` are green on the placeholder; building and importing the real images is the Linux+root release/integration concern.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Tar ¶
Tar returns the embedded OCI image tar for a runtime ("nodejs22"/"python314") as a fresh, UNCOMPRESSED reader ready for containerd's client.Import (which reads a raw tar stream, not a gzip one). The curated export may be gzip-compressed (e.g. `docker save`-style output): if the embedded bytes start with the gzip magic, Tar transparently wraps them in a gzip.Reader so the caller always sees a plain tar. ok==false means "no embedded tar for this runtime" — the driver then pulls the ref only when the operator chose its registry (an imageOverride entry or a custom imagePrefix); any other ref, and a pull that finds no image, is the driver's NotFound wrapping runtime.ErrImageUnavailable (ADR-0149), never a silent miss. The returned reader is independent per call.
func TarForImageRef ¶
TarForImageRef maps a curated image reference to its embedded OCI tar, so the containerd driver can import the embed into the function's own containerd namespace on demand (no registry pull — ADR-0054). Only the image an embedded tar carries matches: the ref must normalize to "docker.io/funcd/runtime-<rt>:latest" (so "funcd/runtime-nodejs22" and "funcd/runtime-nodejs22:latest" do). Any other ref — an ImageOverride such as "ghcr.io/pyvvo/runtime-nodejs22:v2", another tag, registry or digest — reports ok==false and the driver pulls it: importing the tar would run the curated image in its place.
Types ¶
This section is empty.
Source Files