pixie-lab 0.4.1__tar.gz → 0.4.2__tar.gz

{pixie_lab-0.4.1 → pixie_lab-0.4.2}/.github/workflows/cicd.yaml

@@ -191,6 +191,67 @@ jobs:
             ~/system_imaging/disk/pixie-usbboot-pc-x86_64-v*.iso
             ~/system_imaging/disk/pixie-usbboot-pc-x86_64-v*.sha256
 
+  build-live-env-image:
+    name: Build pixie-live-env image
+    # The image the live-env boot modes nbdboot: the nosi arch-headless
+    # base disk image with the pixie CLI + pixie-on-tty1 service injected
+    # (cijoe/tasks/live-env-image.yaml). Unlike the live-build bakes this
+    # does NOT run debootstrap/mksquashfs; it qemu-nbd-mounts a copy of a
+    # pulled base image, injects userspace, slims, and gzips. Wired to
+    # ``test`` so we don't pay for the ORAS pull + qemu transform on a
+    # broken lint/typecheck.
+    needs: test
+    runs-on: ubuntu-latest
+    # 60 min cap for the same reason as build-media: the real ORAS pull
+    # of the arch-headless base (~1.6 GiB) + decompress + qemu transform
+    # + gzip dominate wall clock.
+    timeout-minutes: 60
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Install build dependencies (qemu-nbd, rsync, nbd module)
+        run: |
+          set -eu
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends \
+            qemu-utils rsync gzip
+          # The transform attaches a copy of the base image to /dev/nbdX
+          # via qemu-nbd; load the module with partition scanning so the
+          # root partition shows up as nbdXp1.
+          sudo modprobe nbd max_part=16
+          ls -la /dev/nbd0
+
+      - name: Install cijoe
+        run: pipx install --force cijoe
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+
+      - name: Build pixie-live-env image
+        run: make live-env-image
+
+      # cijoe captures the full run (per-command output + report.html)
+      # under cijoe/cijoe-output/. Upload it ALWAYS so a transform
+      # failure leaves a diagnosable artifact.
+      - name: Upload cijoe output
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: cijoe-output-live-env-image
+          path: cijoe/cijoe-output
+          if-no-files-found: warn
+
+      - name: Upload artifact (pixie-live-env-image)
+        uses: actions/upload-artifact@v7
+        with:
+          name: pixie-live-env-image-x86_64
+          path: |
+            ~/system_imaging/disk/pixie-live-env-x86_64.img.gz
+            ~/system_imaging/disk/pixie-live-env-x86_64.img.gz.sha256
+            ~/system_imaging/disk/pixie-live-env-x86_64.content-sha256
+            ~/system_imaging/disk/pixie-live-env-catalog.toml
+          if-no-files-found: error
+
   test-pxe:
     name: PXE bootstrap chain test (containerized pixie + client QEMU VM)
     # Independent of the media bake: the chain test only needs the
@@ -650,6 +711,7 @@ jobs:
       - build-container
       - build-wheel
       - build-media
+      - build-live-env-image
       - test-pxe
       - test-pxe-nbdboot
       - test-pxe-inventory
@@ -692,6 +754,7 @@ jobs:
       - build-container
       - build-wheel
       - build-media
+      - build-live-env-image
       - test-pxe
       - test-pxe-nbdboot
       - test-pxe-inventory
@@ -737,6 +800,7 @@ jobs:
       - build-container
       - build-wheel
       - build-media
+      - build-live-env-image
       - test-pxe
       - test-pxe-nbdboot
       - test-pxe-inventory
@@ -759,6 +823,15 @@ jobs:
           pattern: pixie-*-pc-x86_64
           merge-multiple: true
           path: release-assets
+      - name: Download pixie-live-env image
+        # The nbdboot live-env image (arch-headless + injected pixie CLI
+        # / service): the gzipped disk image + its .sha256, the
+        # .content-sha256 sidecar (the value an operator sets
+        # PIXIE_LIVE_ENV_IMAGE_SHA to), and the catalog fragment.
+        uses: actions/download-artifact@v8
+        with:
+          name: pixie-live-env-image-x86_64
+          path: release-assets
       - name: List release assets
         run: ls -la release-assets
       - name: Assemble live-env fetch tarball
@@ -798,7 +871,10 @@ jobs:
 
             ## Media assets attached here
 
-            - `pixie-live-env-x86_64.tar.gz` — the live-env trio packaged for pixie's in-app **Fetch live-env** action (the default `PIXIE_LIVE_ENV_SRC`). Click Fetch live-env on the dashboard and pixie pulls + stages this itself; no manual bake or copy.
-            - `pixie-netboot-pc-x86_64-*.{vmlinuz,initrd,squashfs}` — the same live-env (netboot-pc bake) as loose files, if you prefer to stage `PIXIE_LIVE_ENV_DIR` (`data/live-env/`) by hand. Used by the `pixie-flash-once` / `pixie-flash-always` / `pixie-inventory` / `pixie-tui` boot modes.
+            - `pixie-live-env-x86_64.img.gz` — the **nbdboot** live-env image: the nosi `arch-headless` base disk image with the pixie CLI + `pixie-on-tty1` service injected. Fetch it from the **Catalog** tab (it seeds into a fresh catalog), then set `PIXIE_LIVE_ENV_IMAGE_SHA` to select it for the `pixie-flash-once` / `pixie-flash-always` / `pixie-inventory` / `pixie-tui` boot modes so they nbdboot this image ephemerally.
+            - `pixie-live-env-x86_64.content-sha256` — the raw-image sha256 to set `PIXIE_LIVE_ENV_IMAGE_SHA` to (identical to the `content_sha256` pixie assigns after fetching the `pixie-live-env` catalog entry).
+            - `pixie-live-env-catalog.toml` — the catalog fragment (the `pixie-live-env` disk image + its arch-headless netboot bundle) with `content_sha256` filled in; the shipped `catalog.toml` also lists these entries.
+            - `pixie-live-env-x86_64.tar.gz` — the older squashfs live-env trio for pixie's in-app **Fetch live-env** action (the default `PIXIE_LIVE_ENV_SRC`) and the `PIXIE_LIVE_ENV_DIR` staging path.
+            - `pixie-netboot-pc-x86_64-*.{vmlinuz,initrd,squashfs}` — the squashfs live-env (netboot-pc bake) as loose files, if you prefer to stage `PIXIE_LIVE_ENV_DIR` (`data/live-env/`) by hand.
             - `pixie-usbboot-pc-x86_64-*.iso` — bootable USB / ISO media for the pixie live env (uncompressed; `dd` / Etcher / Ventoy ready).
             - `*.sha256` — checksums for the above.

{pixie_lab-0.4.1 → pixie_lab-0.4.2}/CHANGELOG.md

@@ -11,6 +11,33 @@ operator-facing summary.
 
 ## [Unreleased]
 
+## [0.4.2] - 2026-07-26
+
+### Added
+
+**The live-env boots as an ephemeral-nbdboot disk image, not a
+live-boot squashfs.** The inventory / tui / flash boot modes now
+nbdboot a normal disk image (nosi `arch-headless` with the pixie CLI +
+`pixie-on-tty1` service injected) with a tmpfs overlay, instead of
+fetching a live-boot squashfs. This fixes boxes whose NIC never came up
+under the old Debian live-boot initramfs (dual-NIC Intel `igb` among
+them): the image rides the same dracut ramboot path that nbdboot
+already uses, which brings those NICs up. Point pixie at it by fetching
+the `pixie-live-env` catalog entry and setting `PIXIE_LIVE_ENV_IMAGE_SHA`
+(or the `live_env.image_sha` setting) to its content sha; the image ships
+as a release asset (`pixie-live-env-x86_64.img.gz`, under 2 GB) built and
+published by CI.
+
+### Fixed
+
+**Rootfs extraction picks the Linux root partition by GPT type.** The
+fetcher extracted partition 1 as `rootfs.raw`, correct for the
+ubuntu/debian cloud images (root at p1) but not for arch/fedora, whose
+images place BIOS-boot + ESP first and root at p3 -- there it produced a
+1 MiB stub that could not mount. It now selects by type (Linux-root GUID,
+then the largest Linux filesystem, then the largest non-firmware/boot/swap
+partition), so every nosi image extracts its real root.
+
 ## [0.4.1] - 2026-07-25
 
 ### Changed

{pixie_lab-0.4.1 → pixie_lab-0.4.2}/Makefile

@@ -23,7 +23,7 @@ endif
 
 .PHONY: help \
         deps test lint format format-check typecheck ci wheel \
-        media-deps build ipxe test-pxe test-usb-ventoy \
+        media-deps build live-env-image ipxe test-pxe test-usb-ventoy \
         clean
 
 help:
@@ -43,6 +43,8 @@ help:
 	@echo "  media-deps    pipx install cijoe"
 	@echo "  build         build a media image (override VARIANT below)"
 	@echo "                  -> ~/system_imaging/disk/pixie-<variant>.*"
+	@echo "  live-env-image  build the pixie-live-env disk image (arch-headless"
+	@echo "                  base + pixie CLI/service) nbdbooted by the live-env modes"
 	@echo "  ipxe          build pixie's custom iPXE -> IPXE_OUT/ipxe.efi (default dist/ipxe/)"
 	@echo "  test-pxe      end-to-end PXE bootstrap chain test"
 	@echo "                  (needs podman + QEMU + KVM + dnsmasq; a few min wall clock)"
@@ -107,6 +109,15 @@ media-deps:
 build:
 	cd cijoe && cijoe $(MEDIA_TASK) --monitor -c configs/$(VARIANT).toml
 
+# Build the pixie-live-env disk image: pull the nosi arch-headless base
+# via ORAS, inject the pixie CLI + pixie-on-tty1 service, slim + gzip,
+# and publish the asset (< 2 GiB) plus its sha256 / content-sha256
+# sidecars and a catalog fragment. The live-env boot modes nbdboot this
+# image; PIXIE_LIVE_ENV_IMAGE_SHA selects it (= the content-sha256).
+# Needs qemu-nbd + passwordless sudo + uv + the nbd kernel module.
+live-env-image:
+	cd cijoe && cijoe tasks/live-env-image.yaml --monitor -c configs/live-env-image.toml
+
 # Build pixie's slim iPXE binary (bin-x86_64-efi/ipxe.efi) with the
 # embedded chain-loader baked in. Landed in the container image so a
 # fresh deploy gets the one-bootfile chain guarantee without needing

{pixie_lab-0.4.1 → pixie_lab-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pixie-lab
-Version: 0.4.1
+Version: 0.4.2
 Summary: Bare-metal netboot appliance: catalog + fetch + NBD + PXE + TFTP + operator TUI in one container
 Project-URL: Homepage, https://github.com/safl/pixie
 Project-URL: Repository, https://github.com/safl/pixie

pixie_lab-0.4.2/cijoe/configs/live-env-image.toml

@@ -0,0 +1,34 @@
+# pixie live-env image - build configuration
+#
+# Drives the transform that turns the nosi ``arch-headless`` base disk
+# image into the ``pixie-live-env`` image pixie nbdboots ephemerally for
+# the live-env boot modes. See cijoe/tasks/live-env-image.yaml.
+#
+# Usage:
+#   cijoe tasks/live-env-image.yaml --config configs/live-env-image.toml --monitor
+# (or via the Makefile dispatcher: ``make live-env-image``)
+
+[pixie]
+variant = "live-env-image"
+
+[cijoe.workflow]
+fail_fast = true
+
+[live-env-image]
+# The nosi base disk image + its netboot bundle (kernel + initrd). The
+# transform only mutates userspace, so the pixie-live-env image reuses
+# arch-headless's own kernel/initrd unchanged -- ``netboot_src`` points
+# straight at the arch-headless netboot bundle.
+base_src = "oras://ghcr.io/safl/nosi/arch-headless:latest"
+netboot_src = "oras://ghcr.io/safl/nosi/arch-headless-netboot:latest"
+
+# The stable release-asset URL the shipped catalog entry references
+# (``.../releases/latest/download/pixie-live-env-x86_64.img.gz``), so a
+# fresh pixie can Fetch it from the Catalog tab like any nosi image.
+catalog_src = "https://github.com/safl/pixie/releases/latest/download/pixie-live-env-x86_64.img.gz"
+
+image_name = "pixie-live-env"
+
+# Where the published asset + sidecars + catalog fragment land. Mirrors
+# the netboot-pc / usbboot-pc variants so all media live under one tree.
+publish.dir = "{{ local.env.HOME }}/system_imaging/disk"

pixie_lab-0.4.2/cijoe/scripts/live_env_image.py

@@ -0,0 +1,307 @@
+"""
+Build + publish the pixie-live-env disk image
+=============================================
+
+Produces the ``pixie-live-env`` image that pixie nbdboots ephemerally
+for the live-env boot modes (``pixie-flash-once`` / ``-always`` /
+``pixie-inventory`` / ``pixie-tui``). The renderer selects this image
+via the ``PIXIE_LIVE_ENV_IMAGE_SHA`` setting; the value an operator
+sets there is the ``content_sha256`` this build computes and publishes
+(see step 5 below and the ``.content-sha256`` sidecar).
+
+Pipeline:
+
+1. ``uv build --wheel`` the current pixie-lab, then assemble a vendored
+   CLI tree: ``pip install --target`` the pixie package (``--no-deps``)
+   plus only the pure-Python CLI runtime deps (``rich`` + ``tomlkit``).
+   The CLI reaches the server over stdlib ``urllib`` -- NOT httpx -- so
+   the heavy fastapi / uvicorn / pydantic base deps are deliberately
+   left out. The image's stock ``python3`` runs this tree.
+
+2. Pull the nosi ``arch-headless`` base disk image via ORAS, reusing
+   pixie's own resolver (``python -m pixie.oras_pull``) so the bytes +
+   digest match a live catalog Fetch. Decompress the ``img.gz`` to a
+   raw disk image.
+
+3. Run ``live_env_transform.sh`` (privileged: qemu-nbd + mount) to
+   inject the vendored CLI + the ``pixie-on-tty1`` service trio and
+   slim conservatively, emitting a raw disk image.
+
+4. sha256 the RAW image -> ``content_sha256`` (== PIXIE_LIVE_ENV_IMAGE_SHA);
+   gzip it to ``pixie-live-env-x86_64.img.gz`` (the release asset);
+   assert the gzipped asset is < 2 GiB (GitHub's per-file release
+   limit) and fail otherwise.
+
+5. Emit alongside the asset: its ``.sha256`` checksum, a
+   ``.content-sha256`` sidecar carrying the raw-image sha (the value
+   for ``PIXIE_LIVE_ENV_IMAGE_SHA``), and ``pixie-live-env-catalog.toml``
+   -- a catalog fragment (the bindable disk image with its
+   ``netboot_src`` + the arch-headless netboot bundle it points at) the
+   release job merges into the shipped ``catalog.toml`` so the image is
+   fetchable via the Catalog tab like any other.
+
+The cwd at run time is ``cijoe/`` (the Makefile cd's there), so the
+repo root is ``Path.cwd().parent``. Requires: passwordless sudo,
+qemu-utils (qemu-nbd + qemu-img), the ``nbd`` module, rsync, gzip, and
+``uv`` on PATH. Skipped for any variant other than ``live-env-image``.
+
+Retargetable: False
+"""
+
+from __future__ import annotations
+
+import errno
+import logging as log
+import shutil
+from argparse import ArgumentParser
+from pathlib import Path
+
+# Reuse the pyproject version reader so the published asset + catalog
+# fragment carry the same stamped version as the other bakes.
+from usb_iso_build import _read_pixie_version
+
+# GitHub's per-file release-asset hard limit. The gzipped image must
+# land under this or the release upload is rejected downstream, so we
+# gate here (loud, early) instead.
+RELEASE_ASSET_LIMIT = 2 * 1024 * 1024 * 1024
+
+# Stable, unversioned asset basename so the catalog + settings default
+# can reference ``.../releases/latest/download/<name>`` at a fixed URL
+# (mirrors how the live-env tarball + catalog.toml are published).
+ASSET_BASENAME = "pixie-live-env-x86_64.img.gz"
+CATALOG_FRAGMENT_BASENAME = "pixie-live-env-catalog.toml"
+CONTENT_SHA_BASENAME = "pixie-live-env-x86_64.content-sha256"
+
+# Defaults; overridable via the ``[live-env-image]`` config table.
+DEFAULT_BASE_SRC = "oras://ghcr.io/safl/nosi/arch-headless:latest"
+DEFAULT_NETBOOT_SRC = "oras://ghcr.io/safl/nosi/arch-headless-netboot:latest"
+DEFAULT_CATALOG_SRC = (
+    "https://github.com/safl/pixie/releases/latest/download/pixie-live-env-x86_64.img.gz"
+)
+DEFAULT_IMAGE_NAME = "pixie-live-env"
+
+
+def add_args(parser: ArgumentParser):
+    del parser  # no flags; signature kept for cijoe consistency
+
+
+def _sha256_of(cijoe, path: Path) -> str | None:
+    err, state = cijoe.run_local(f"sha256sum {path}")
+    if err:
+        return None
+    out = state.output() if hasattr(state, "output") else str(state)
+    fields = out.strip().split()
+    return fields[0] if fields else None
+
+
+def _build_vendored_cli(cijoe, repo_root: Path, build_dir: Path) -> Path | None:
+    """Build the wheel and assemble the vendored CLI tree. Returns the
+    vendor dir on success, ``None`` on failure."""
+    wheel_out = build_dir / "wheel"
+    if wheel_out.exists():
+        shutil.rmtree(wheel_out)
+    wheel_out.mkdir(parents=True)
+
+    err, _ = cijoe.run_local(f"sh -c 'cd {repo_root} && uv build --wheel --out-dir {wheel_out}'")
+    if err:
+        log.error("uv build --wheel failed")
+        return None
+    wheels = sorted(wheel_out.glob("pixie_lab-*-py3-none-any.whl"))
+    if not wheels:
+        log.error(f"no pixie_lab wheel produced in {wheel_out}")
+        return None
+    wheel = wheels[-1]
+
+    vendor = build_dir / "vendor"
+    if vendor.exists():
+        shutil.rmtree(vendor)
+    vendor.mkdir(parents=True)
+
+    # The pixie package only (no deps -- installing the full wheel would
+    # drag fastapi / uvicorn / httpx / pydantic, which are compiled,
+    # version-specific, and unused by the CLI).
+    err, _ = cijoe.run_local(f"uv pip install --target {vendor} --no-compile --no-deps {wheel}")
+    if err:
+        log.error("uv pip install (pixie package, --no-deps) failed")
+        return None
+    # The pure-Python CLI runtime deps. rich powers the wizard; tomlkit
+    # backs the catalog round-trip the CLI can reach. Both ship as
+    # ``py3-none-any`` wheels, so they import under the image's own
+    # python3 regardless of its minor version.
+    err, _ = cijoe.run_local(f"uv pip install --target {vendor} --no-compile rich tomlkit")
+    if err:
+        log.error("uv pip install (rich + tomlkit) failed")
+        return None
+    return vendor
+
+
+def main(args, cijoe):
+    del args
+    cijoe_dir = Path.cwd()
+    repo_root = cijoe_dir.parent
+    pixie_media = repo_root / "pixie-media"
+
+    variant = cijoe.getconf("pixie", {}).get("variant", "")
+    if variant != "live-env-image":
+        log.info(f"Skipping live_env_image (variant={variant!r}; only 'live-env-image' runs)")
+        return 0
+
+    conf = cijoe.getconf("live-env-image", {})
+    base_src = conf.get("base_src", DEFAULT_BASE_SRC)
+    netboot_src = conf.get("netboot_src", DEFAULT_NETBOOT_SRC)
+    catalog_src = conf.get("catalog_src", DEFAULT_CATALOG_SRC)
+    image_name = conf.get("image_name", DEFAULT_IMAGE_NAME)
+    publish_dir_str = conf.get("publish", {}).get("dir")
+    if not publish_dir_str:
+        log.error("live-env-image.publish.dir is unset in the config")
+        return errno.EINVAL
+    publish_dir = Path(publish_dir_str)
+    publish_dir.mkdir(parents=True, exist_ok=True)
+
+    if not pixie_media.exists():
+        log.error(f"pixie-media tree missing: {pixie_media}")
+        return errno.ENOENT
+
+    build_dir = cijoe_dir / "_build" / "live-env-image"
+    if build_dir.exists():
+        # The transform's scratch is torn down internally, but the raw
+        # base image is owned by the invoking user; a plain rm is fine.
+        err, _ = cijoe.run_local(f"sudo rm -rf {build_dir}")
+        if err:
+            log.error(f"failed to remove stale build dir {build_dir}")
+            return err
+    build_dir.mkdir(parents=True)
+
+    pixie_version = _read_pixie_version(cijoe_dir)
+    log.info(f"Building {image_name} v{pixie_version} from base {base_src}")
+
+    # 1. Vendored CLI tree.
+    vendor = _build_vendored_cli(cijoe, repo_root, build_dir)
+    if vendor is None:
+        return errno.EIO
+
+    # 2. Pull + decompress the base image, reusing pixie's ORAS resolver.
+    base_gz = build_dir / "base.img.gz"
+    err, _ = cijoe.run_local(
+        f"sh -c 'cd {repo_root} && uv run python -m pixie.oras_pull {base_src} {base_gz}'"
+    )
+    if err:
+        log.error(f"failed to pull base image {base_src}")
+        return err
+    base_raw = build_dir / "base.img"
+    err, _ = cijoe.run_local(f"sh -c 'gzip -dc {base_gz} > {base_raw}'")
+    if err:
+        log.error("failed to decompress the base image")
+        return err
+
+    # 3. Transform: inject CLI + service trio, slim, fstrim.
+    out_raw = build_dir / "pixie-live-env.img"
+    transform = cijoe_dir / "scripts" / "live_env_transform.sh"
+    err, _ = cijoe.run_local(
+        f"sudo bash {transform} "
+        f"--base {base_raw} --out {out_raw} --vendor {vendor} "
+        f"--media {pixie_media} --force"
+    )
+    if err:
+        log.error("live_env_transform.sh failed")
+        return err
+    # The transform chown's the output back to us, but be defensive.
+    cijoe.run_local(f"sudo chown $(id -u):$(id -g) {out_raw}")
+
+    # 4. Content-address on the RAW image (matches pixie's img.gz fetch:
+    #    decompress -> sha of the raw disk image), then gzip the asset.
+    content_sha = _sha256_of(cijoe, out_raw)
+    if not content_sha:
+        log.error(f"failed computing content sha256 of {out_raw}")
+        return errno.EIO
+    log.info(f"content_sha256 (PIXIE_LIVE_ENV_IMAGE_SHA) = {content_sha}")
+
+    asset_path = publish_dir / ASSET_BASENAME
+    err, _ = cijoe.run_local(f"sh -c 'gzip -c {out_raw} > {asset_path}'")
+    if err:
+        log.error("failed gzipping the live-env image asset")
+        return err
+
+    asset_bytes = asset_path.stat().st_size
+    log.info(f"asset {asset_path.name}: {asset_bytes} bytes ({asset_bytes / 2**30:.2f} GiB)")
+    if asset_bytes >= RELEASE_ASSET_LIMIT:
+        log.error(
+            f"{asset_path.name} is {asset_bytes / 2**30:.2f} GiB, "
+            f">= the 2 GiB GitHub release-asset limit; tighten the transform slim"
+        )
+        return errno.EFBIG
+
+    # 5. Sidecars + catalog fragment.
+    asset_sha = _sha256_of(cijoe, asset_path)
+    if not asset_sha:
+        log.error("failed computing sha256 of the gzipped asset")
+        return errno.EIO
+    (publish_dir / f"{ASSET_BASENAME}.sha256").write_text(
+        f"{asset_sha}  {ASSET_BASENAME}\n", encoding="utf-8"
+    )
+    (publish_dir / CONTENT_SHA_BASENAME).write_text(f"{content_sha}\n", encoding="utf-8")
+
+    fragment = _catalog_fragment(
+        image_name=image_name,
+        catalog_src=catalog_src,
+        netboot_src=netboot_src,
+        content_sha=content_sha,
+        version=pixie_version,
+    )
+    (publish_dir / CATALOG_FRAGMENT_BASENAME).write_text(fragment, encoding="utf-8")
+
+    cijoe.run_local(f"ls -la {publish_dir}")
+    log.info(
+        f"published {ASSET_BASENAME} (+ .sha256, {CONTENT_SHA_BASENAME}, "
+        f"{CATALOG_FRAGMENT_BASENAME}) to {publish_dir}"
+    )
+    return 0
+
+
+def _catalog_fragment(
+    *,
+    image_name: str,
+    catalog_src: str,
+    netboot_src: str,
+    content_sha: str,
+    version: str,
+) -> str:
+    """Render the catalog fragment (no ``version =`` header; the release
+    job appends these ``[[images]]`` blocks to the shipped catalog).
+
+    Two peer entries: the bindable disk image (with a filled-in
+    ``content_sha256`` == PIXIE_LIVE_ENV_IMAGE_SHA, and a
+    ``netboot_src`` URL cross-reference) and the arch-headless netboot
+    bundle it points at, so the nbdboot renderer resolves the pair.
+    """
+    disk_desc = (
+        "pixie live-env (nosi arch-headless + the pixie CLI + pixie-on-tty1 service). "
+        "nbdbooted ephemerally for the live-env boot modes."
+    )
+    bundle_desc = (
+        "Netboot bundle for arch-headless: vmlinuz + initrd so pixie can nbdboot the "
+        "pixie-live-env image over NBD."
+    )
+    return f"""\
+# pixie-live-env {version} -- the image the live-env boot modes
+# (pixie-flash-once / -always / pixie-inventory / pixie-tui) nbdboot
+# ephemerally. Set PIXIE_LIVE_ENV_IMAGE_SHA to the content_sha256 below
+# to select it (that sha is the sha256 of the raw disk image, which is
+# exactly what pixie content-addresses this img.gz to after fetching).
+
+[[images]]
+name = "{image_name}"
+src = "{catalog_src}"
+format = "img.gz"
+arch = "x86_64"
+description = "{disk_desc}"
+netboot_src = "{netboot_src}"
+content_sha256 = "{content_sha}"
+
+[[images]]
+name = "nosi arch-headless netboot bundle"
+src = "{netboot_src}"
+format = "tar.gz"
+arch = "x86_64"
+description = "{bundle_desc}"
+"""