From a11727beb64086ce1bbef4e0150168d9b0e331f2 Mon Sep 17 00:00:00 2001 From: James Reilly Date: Thu, 10 Sep 2026 10:23:52 +0530 Subject: [PATCH 01/42] fix(renovate): match the freedesktop-sdk series the junction actually tracks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit renovate.json filters freedesktop-sdk tags with "extractVersion": "^freedesktop-sdk-(?25\\.08\\.[0-9]+)$" while elements/freedesktop-sdk.bst has tracked 26.08 since the bump to freedesktop-sdk-26.08.0-0-gdb97cce: track: freedesktop-sdk-26.08* ref: freedesktop-sdk-26.08.0-0-gdb97cce32cecadc7a3e98f06d557ebfa6ba9ad46 No tag upstream publishes can match that rule any more, so Renovate reports no updates rather than an error. The junction silently stops receiving bumps and the track-refs job in build.yml never has a ref to resolve. Nothing in any log says so — the failure looks exactly like "already up to date". Bumps the rule to 26.08, and adds check-renovate-series.py so the pair cannot drift apart again: it reads the series out of each junction's `track:` glob and asserts the matching extractVersion is anchored to the same one, failing closed. Same shape as check-release-version.py and check-k0s-version.py — wired into .pre-commit-config.yaml, and unit-tests.yml now also fires on renovate.json and elements/*.bst so the guard runs when either side moves. tests/unit/test_check_renovate_series.py covers the passing case, the exact regression above, a junction with no packageRule, a junction with no `track:`, the two series helpers, and the checked-in tree itself. $ python3 -m pytest tests/unit -q 207 passed, 1 xfailed in 0.64s Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01VwEniffvKGH7gHfqKneuaJ --- .github/scripts/check-renovate-series.py | 125 +++++++++++++++++++++ .github/workflows/unit-tests.yml | 4 + .pre-commit-config.yaml | 6 ++ renovate.json | 2 +- tests/unit/test_check_renovate_series.py | 132 +++++++++++++++++++++++ 5 files changed, 268 insertions(+), 1 deletion(-) create mode 100755 .github/scripts/check-renovate-series.py create mode 100644 tests/unit/test_check_renovate_series.py diff --git a/.github/scripts/check-renovate-series.py b/.github/scripts/check-renovate-series.py new file mode 100755 index 00000000..016f5014 --- /dev/null +++ b/.github/scripts/check-renovate-series.py @@ -0,0 +1,125 @@ +#!/usr/bin/env python3 +"""Keep Renovate's version filters on the same release series as the junctions. + +`elements/*.bst` pin a junction with a `track:` glob and a resolved `ref:`: + + track: freedesktop-sdk-26.08* + ref: freedesktop-sdk-26.08.0-0-gdb97cce... + +`renovate.json` decides which upstream tags are candidates for a bump with a +per-package `extractVersion` anchored to that same series: + + "extractVersion": "^freedesktop-sdk-(?26\\.08\\.[0-9]+)$" + +Nothing ties the two together. When a junction moves to a new series and the +Renovate rule does not, the rule stops matching every tag upstream publishes. +Renovate then reports no updates rather than an error, so the junction quietly +stops receiving bumps and the `track-refs` job in build.yml has nothing to +resolve. That is not hypothetical: the freedesktop-sdk rule still read +`25\\.08\\.` after the junction moved to `freedesktop-sdk-26.08.0`. + +This script fails closed on that drift. It reads the series out of each +junction's `track:` glob and asserts the matching `extractVersion` in +renovate.json is anchored to the same one. +""" + +import json +import re +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] +RENOVATE_JSON = ROOT / "renovate.json" + +# depName in renovate.json -> the junction whose `track:` is authoritative. +JUNCTIONS = { + "https://gitlab.com/freedesktop-sdk/freedesktop-sdk.git": ( + ROOT / "elements" / "freedesktop-sdk.bst" + ), + "https://gitlab.gnome.org/GNOME/gnome-build-meta.git": ( + ROOT / "elements" / "gnome-build-meta.bst" + ), +} + +TRACK_RE = re.compile(r"^\s*track:\s*[\"']?([^\"'\s]+)[\"']?\s*$", re.MULTILINE) + + +def read(path): + if not path.is_file(): + sys.exit(f"ERROR: expected file not found: {path.relative_to(ROOT)}") + return path.read_text(encoding="utf-8") + + +def series_of(track): + """The literal prefix of a track glob, with the trailing '*' removed. + + `freedesktop-sdk-26.08*` -> `freedesktop-sdk-26.08` + `gnome-50` -> `gnome-50` (no glob; the whole value) + """ + return track.split("*", 1)[0] + + +def digits(text): + """Version-ish digit groups, so an escaped regex and a plain glob compare. + + `^freedesktop-sdk-(?26\\.08\\.[0-9]+)$` -> ['26', '08'] + `freedesktop-sdk-26.08` -> ['26', '08'] + `[0-9]+` is dropped: it is the part Renovate fills in, not a series digit. + """ + stripped = text.replace("\\.", ".").replace("[0-9]+", "") + return [g for g in re.findall(r"\d+", stripped)] + + +def main(): + config = json.loads(read(RENOVATE_JSON)) + rules = config.get("packageRules", []) + failures = [] + checked = 0 + + for dep_name, junction_path in JUNCTIONS.items(): + matching = [ + rule + for rule in rules + if dep_name in rule.get("matchPackageNames", []) + and "extractVersion" in rule + ] + if not matching: + failures.append( + f"renovate.json has no packageRule with an extractVersion for " + f"{dep_name}; {junction_path.relative_to(ROOT)} would never be bumped" + ) + continue + + track_match = TRACK_RE.search(read(junction_path)) + if not track_match: + failures.append( + f"{junction_path.relative_to(ROOT)} declares no `track:`; " + "cannot verify the Renovate series against it" + ) + continue + + series = series_of(track_match.group(1)) + want = digits(series) + + for rule in matching: + checked += 1 + got = digits(rule["extractVersion"]) + if got != want: + failures.append( + f"{junction_path.relative_to(ROOT)} tracks `{track_match.group(1)}` " + f"(series {'.'.join(want) or ''}) but renovate.json filters " + f"{dep_name} with extractVersion {rule['extractVersion']!r} " + f"(series {'.'.join(got) or ''}). Renovate matches no tag, " + "so this junction gets no update PRs." + ) + + if failures: + for failure in failures: + print(f"ERROR: {failure}", file=sys.stderr) + sys.exit(1) + + print(f"OK: {checked} Renovate version filter(s) match their junction `track:` series") + + +if __name__ == "__main__": + main() diff --git a/.github/workflows/unit-tests.yml b/.github/workflows/unit-tests.yml index fc4485d7..d94d5999 100644 --- a/.github/workflows/unit-tests.yml +++ b/.github/workflows/unit-tests.yml @@ -8,6 +8,8 @@ on: - 'files/**' - 'tests/unit/**' - 'Justfile' + - 'renovate.json' + - 'elements/*.bst' push: branches: [main] paths: @@ -16,6 +18,8 @@ on: - 'files/**' - 'tests/unit/**' - 'Justfile' + - 'renovate.json' + - 'elements/*.bst' permissions: contents: read diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 95cf3104..0a9f61ab 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -18,6 +18,12 @@ repos: language: system pass_filenames: false files: ^(project\.conf|elements/freedesktop-sdk\.bst|\.github/scripts/check-release-version\.py)$ + - id: check-renovate-series + name: Renovate version filters match the junction track series + entry: python .github/scripts/check-renovate-series.py + language: system + pass_filenames: false + files: ^(renovate\.json|elements/(freedesktop-sdk|gnome-build-meta)\.bst|\.github/scripts/check-renovate-series\.py)$ - id: check-k0s-version name: k0s version derived from include/k0s.yml, not restated entry: python .github/scripts/check-k0s-version.py diff --git a/renovate.json b/renovate.json index 45e9cdfe..953e0c0f 100644 --- a/renovate.json +++ b/renovate.json @@ -18,7 +18,7 @@ { "matchDatasources": ["git-refs"], "matchPackageNames": ["https://gitlab.com/freedesktop-sdk/freedesktop-sdk.git"], - "extractVersion": "^freedesktop-sdk-(?25\\.08\\.[0-9]+)$", + "extractVersion": "^freedesktop-sdk-(?26\\.08\\.[0-9]+)$", "versioning": "semver" }, { diff --git a/tests/unit/test_check_renovate_series.py b/tests/unit/test_check_renovate_series.py new file mode 100644 index 00000000..afda45e9 --- /dev/null +++ b/tests/unit/test_check_renovate_series.py @@ -0,0 +1,132 @@ +"""Unit coverage for .github/scripts/check-renovate-series.py. + +The script guards a silent failure: when a junction moves to a new release +series and renovate.json's extractVersion does not, Renovate matches no tag +and simply reports no updates. The junction then stops receiving bumps with +nothing in any log to say so. +""" + +import importlib.util +import json +import subprocess +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] +SCRIPT = ROOT / ".github" / "scripts" / "check-renovate-series.py" + +# The script's filename is not a valid module name, so load it by path — +# same approach as tests/unit/test_check_k0s_version.py. +_spec = importlib.util.spec_from_file_location("check_renovate_series", SCRIPT) +check_renovate_series = importlib.util.module_from_spec(_spec) +_spec.loader.exec_module(check_renovate_series) + + +def run_against(tmp_path, renovate, junctions): + """Run the script with ROOT redirected at a throwaway tree.""" + (tmp_path / ".github" / "scripts").mkdir(parents=True) + (tmp_path / "elements").mkdir() + (tmp_path / "renovate.json").write_text(json.dumps(renovate)) + for name, body in junctions.items(): + (tmp_path / "elements" / name).write_text(body) + script_copy = tmp_path / ".github" / "scripts" / SCRIPT.name + script_copy.write_text(SCRIPT.read_text()) + return subprocess.run( + [sys.executable, str(script_copy)], capture_output=True, text=True + ) + + +FSDK = "https://gitlab.com/freedesktop-sdk/freedesktop-sdk.git" +GBM = "https://gitlab.gnome.org/GNOME/gnome-build-meta.git" + + +def rule(dep, extract): + return { + "matchDatasources": ["git-refs"], + "matchPackageNames": [dep], + "extractVersion": extract, + "versioning": "semver", + } + + +def junction(track): + return f"kind: junction\n\nsources:\n- kind: git_repo\n track: {track}\n ref: x\n" + + +BOTH_JUNCTIONS = { + "freedesktop-sdk.bst": junction("freedesktop-sdk-26.08*"), + "gnome-build-meta.bst": junction("gnome-50"), +} + + +def test_passes_when_series_agree(tmp_path): + result = run_against( + tmp_path, + { + "packageRules": [ + rule(FSDK, r"^freedesktop-sdk-(?26\.08\.[0-9]+)$"), + rule(GBM, r"^(?50\.[0-9]+)$"), + ] + }, + BOTH_JUNCTIONS, + ) + assert result.returncode == 0, result.stderr + assert "OK: 2" in result.stdout + + +def test_fails_on_the_real_regression(tmp_path): + """The shipped bug: junction on 26.08, Renovate still filtering 25.08.""" + result = run_against( + tmp_path, + { + "packageRules": [ + rule(FSDK, r"^freedesktop-sdk-(?25\.08\.[0-9]+)$"), + rule(GBM, r"^(?50\.[0-9]+)$"), + ] + }, + BOTH_JUNCTIONS, + ) + assert result.returncode == 1 + assert "matches no tag" in result.stderr + assert "freedesktop-sdk.bst" in result.stderr + + +def test_fails_when_a_junction_has_no_rule(tmp_path): + result = run_against( + tmp_path, + {"packageRules": [rule(GBM, r"^(?50\.[0-9]+)$")]}, + BOTH_JUNCTIONS, + ) + assert result.returncode == 1 + assert "no packageRule" in result.stderr + + +def test_fails_when_the_junction_declares_no_track(tmp_path): + result = run_against( + tmp_path, + { + "packageRules": [ + rule(FSDK, r"^freedesktop-sdk-(?26\.08\.[0-9]+)$"), + rule(GBM, r"^(?50\.[0-9]+)$"), + ] + }, + { + "freedesktop-sdk.bst": "kind: junction\n\nsources:\n- kind: git_repo\n ref: x\n", + "gnome-build-meta.bst": junction("gnome-50"), + }, + ) + assert result.returncode == 1 + assert "declares no `track:`" in result.stderr + + +def test_series_helpers_ignore_the_renovate_placeholder(): + assert check_renovate_series.series_of("freedesktop-sdk-26.08*") == "freedesktop-sdk-26.08" + assert check_renovate_series.series_of("gnome-50") == "gnome-50" + assert check_renovate_series.digits(r"^freedesktop-sdk-(?26\.08\.[0-9]+)$") == ["26", "08"] + assert check_renovate_series.digits("freedesktop-sdk-26.08") == ["26", "08"] + + +def test_the_real_repo_is_consistent(): + """Runs the script against the checked-in tree, so drift fails CI.""" + result = subprocess.run([sys.executable, str(SCRIPT)], capture_output=True, text=True) + assert result.returncode == 0, result.stderr From f25bcee6a7db1902fc4ffe0673a3ebf23b3119b9 Mon Sep 17 00:00:00 2001 From: kylerankin Date: Sun, 13 Sep 2026 23:08:01 +0000 Subject: [PATCH 02/42] refactor: switch OS payload to Flatcar base, drop displaced FSDK components MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cut os-stack.bst over to the Flatcar base (projectbluefin/server#131), the Phase 5 slice of the Flatcar base migration design doc. The installed OS DDI payload now lands on a single-ABI Flatcar `/usr` that shares the vermagic, glibc, and systemd of the Flatcar LTS kernel, instead of straddling FSDK 26.08 userspace against the Flatcar kernel. - Add elements/flatcar/flatcar-usr.bst: import element mirroring the existing flatcar-zfs.bst pattern — a single pinned, digest-verified flatcar-container source, prebuilt binaries, FSDK stripper left alone. Extracts /usr, drops Flatcar's update/provisioning stack (update_engine, locksmithd, ignition, coreos-cloudinit, flatcar-update, download_sysext, ensure-sysext), flattens the nested module dir to single-level, stages the raw sysext images. - Rewrite os-stack.bst: replace the FSDK base-runtime depends (runtime-minimal, systemd, dbus, dbus-broker, kmod, shadow, bootstrap/bash, uutils-coreutils, openssh-systemd, podman, xfsprogs, gnupg, ca-certificates, tzdata) with flatcar/flatcar-usr.bst. Keep all ~14 OS-policy elements and the kernel/zfs. The FSDK junction stays only for integration helpers (extra-fs, ldconfig); os-countme keeps its curl+jq via that junction. - Delete elements/bluefin-server/linux-firmware-split.bst (only referenced by os-stack); Flatcar firmware now ships in /usr/lib/firmware. Keep the uutils-coreutils.bst file — installer-stack.bst still needs it (installer stays FSDK 26.08, hard rule 3). - Update tests/unit/test_build_depends.py: the old tests locked in FSDK invariants (uutils-not-gnu, includes dbus-broker, includes bash) that the cutover breaks; replace them with invariants for the new base — os-stack depends on flatcar-usr.bst and excludes every displaced FSDK component. - Update docs/skills/factory-integration.md and README.md: podman and the base userspace are now Flatcar/sysext, not FSDK base components. No os-base option exists, so its removal is a no-op. The installer keeps its FSDK 26.08 userspace; hard rules 2, 3, and 4 are preserved. bluefin-server#131 Signed-off-by: kylerankin --- README.md | 6 +- docs/skills/factory-integration.md | 9 +- .../bluefin-server/linux-firmware-split.bst | 36 -------- elements/bluefin-server/os-stack.bst | 43 ++++----- elements/flatcar/flatcar-usr.bst | 84 +++++++++++++++++ tests/unit/test_build_depends.py | 89 +++++++++++++++---- 6 files changed, 180 insertions(+), 87 deletions(-) delete mode 100644 elements/bluefin-server/linux-firmware-split.bst create mode 100644 elements/flatcar/flatcar-usr.bst diff --git a/README.md b/README.md index 51aebccb..024526e9 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ # Bluefin Server > Amargasaurus cazaui -**An FSDK-based, image-based Linux server OS.** +**An image-based Linux server OS built on a Flatcar base.** -Bluefin Server targets the same use-case space as Flatcar Container Linux, Fedora CoreOS, and Talos, but is built from scratch with [BuildStream 2](https://buildstream.build/) from [freedesktop-sdk](https://freedesktop-sdk.freedesktop.org/) (FSDK 26.08) components and uutils coreutils. +Bluefin Server targets the same use-case space as Flatcar Container Linux, Fedora CoreOS, and Talos, and is built with [BuildStream 2](https://buildstream.build/). The installed OS payload lands on a single-ABI [Flatcar](https://flatcar-linux.net/) `/usr` (projectbluefin/server#131); the offline installer still composes its userspace from [freedesktop-sdk](https://freedesktop-sdk.freedesktop.org/) (FSDK 26.08) so it keeps `systemd-sysinstall`, which Flatcar does not ship. It is [DDI first](https://0pointer.net/blog/fitting-everything-together.html): the OS payload is a compressed XFS DDI filesystem image that is deployed by an offline, systemd-native installer. @@ -23,7 +23,7 @@ Bluefin Server is currently in **Alpha**: - **Image-based updates and atomic rollbacks** via A/B partition slots and `systemd-sysupdate`. - **DDI-first delivery** — the installer embeds the OS payload as a data partition; no network is required at install time. -- **Streamlined base OS image** — modern userspace with uutils coreutils and bash for interactive login and diagnostics. +- **Streamlined base OS image** — modern Flatcar userspace with bash for interactive login and diagnostics. - **systemd-native installer** — `systemd-sysinstall` provides the interactive terminal UI and `systemd-repart` handles partitioning and block-copy DDI placement. - **Optional k0s as a `systemd-sysext`** so the base image stays minimal. diff --git a/docs/skills/factory-integration.md b/docs/skills/factory-integration.md index 75124ca4..7c667ac9 100644 --- a/docs/skills/factory-integration.md +++ b/docs/skills/factory-integration.md @@ -29,7 +29,7 @@ The factory pattern is broader than a single host: a downstream CI lab or OS fac │ Core server OS: DDI-first, image-updated │ │ • systemd-sysupdate for atomic A/B updates │ │ • systemd-sysext for optional layers (k0s, extensions) │ -│ • podman for container workloads │ +│ • container runtimes as systemd-sysexts │ └─────────────────────────────────────────────────────────────┘ ``` @@ -46,7 +46,10 @@ See [k0s-sysext.md](k0s-sysext.md) for details. ## Workloads are containers -The workloads the factory tests and ships live in other repositories or image pipelines. Bluefin Server hosts them via `podman`. +The workloads the factory tests and ships live in other repositories or image +pipelines. Container runtimes ship as optional `systemd-sysext`s rather than in +the base DDI (projectbluefin/server#131 moved podman out of the base OS onto a +sysext, per hard rule 4 which forbids container runtimes in the base DDI). > Bluefin Server is the factory floor; optional workloads and variant images run on that floor. @@ -58,7 +61,7 @@ The workloads the factory tests and ships live in other repositories or image pi | Atomic, rollback-capable updates | Image-based A/B updates via `systemd-sysupdate` | | Minimal attack surface / lean base OS | Streamlined DDI with bash; optional tools as sysexts | | Kubernetes control plane on every node | k0s delivered as `systemd-sysext` | -| Container workloads | `podman` in the base OS stack | +| Container workloads | `podman` (and other runtimes) as optional `systemd-sysext`s | | Signed, verifiable release artifacts | GPG-signed `SHA256SUMS` + `import-pubring.gpg` | ## SSH and Remote Diagnostics diff --git a/elements/bluefin-server/linux-firmware-split.bst b/elements/bluefin-server/linux-firmware-split.bst deleted file mode 100644 index ba9d6eb5..00000000 --- a/elements/bluefin-server/linux-firmware-split.bst +++ /dev/null @@ -1,36 +0,0 @@ -kind: compose -description: Chisel linux-firmware down to server-essential blobs only for extreme efficiency. - -build-depends: - - freedesktop-sdk.bst:components/linux-firmware.bst - -config: - integrate: False - - # Exclude debug symbols, development files, and locales from composed output - exclude: - - debug - - devel - - doc - - locale - - # Only include CPU microcode, virtual, net, and amdgpu/APU firmware needed for servers - include: - # CPU Microcodes (intel & amd) - - /usr/lib/firmware/intel-ucode/** - - /usr/lib/firmware/amd-ucode/** - - # APU / APU Graphics (Ryzen AI MAX+ 395 and Strix Halo support on ghost) - - /usr/lib/firmware/amdgpu/** - - /usr/lib/firmware/amd/** - - # VirtIO / KubeVirt guest hardware support - - /usr/lib/firmware/virtio/** - - # Standard Ethernet & Storage controllers - - /usr/lib/firmware/intel/e1000/** - - /usr/lib/firmware/intel/e810/** - - /usr/lib/firmware/realtek/** - - # Regulatory database - - /usr/lib/firmware/regulatory.db* diff --git a/elements/bluefin-server/os-stack.bst b/elements/bluefin-server/os-stack.bst index 074634d0..44f80576 100644 --- a/elements/bluefin-server/os-stack.bst +++ b/elements/bluefin-server/os-stack.bst @@ -2,26 +2,25 @@ kind: stack description: Stack containing all elements required to build a pure DDI Bluefin Server rootfs. depends: - # Base runtime & core libraries (minimal non-GNU base + uutils modern userspace) - - freedesktop-sdk.bst:public-stacks/runtime-minimal.bst - - bluefin-server/uutils-coreutils.bst - - freedesktop-sdk.bst:bootstrap/bash.bst - - freedesktop-sdk.bst:components/ca-certificates.bst - - freedesktop-sdk.bst:components/tzdata.bst + # Flatcar LTS userspace base. + # + # The OS payload now lands on a single-ABI Flatcar `/usr` (flatcar-usr.bst) + # that shares the vermagic, glibc, and systemd of the Flatcar LTS kernel + # below. This is the cutover from FSDK 26.08 base userspace (projectbluefin/ + # server#131, design phase 5). Every FSDK base-runtime component that used to + # live here (systemd, dbus, bash, coreutils, shadow, kmod, openssh-systemd, + # podman, xfsprogs, gnupg, ca-certificates, tzdata, runtime-minimal, and the + # uutils-coreutils overlay) is gone — Flatcar's `/usr` provides them. The + # installer keeps its own FSDK userspace; see installer/installer-stack.bst. + - flatcar/flatcar-usr.bst + + # FSDK junction is still pulled in for OS-level integration helpers only + # (fstab entries, ldconfig cache); the base runtime it used to provide is + # now Flatcar's. - freedesktop-sdk.bst:integration/extra-fs.bst - freedesktop-sdk.bst:integration/ldconfig.bst - # System Initialization, Core, and Device Management - - freedesktop-sdk.bst:components/systemd.bst - - freedesktop-sdk.bst:components/dbus.bst - - freedesktop-sdk.bst:components/dbus-broker.bst - - freedesktop-sdk.bst:components/kmod.bst - - freedesktop-sdk.bst:components/shadow.bst - - # Remote access during bring-up (temporary — see docs/skills/factory-integration.md) - - freedesktop-sdk.bst:components/openssh-systemd.bst - - # SSH enablement drop-ins + # SSH enablement drop-ins (OS policy, shipped by the installed OS) - bluefin-server/os-sshd-preset.bst - bluefin-server/os-sshd-config.bst @@ -32,10 +31,6 @@ depends: # Flatcar LTS Kernel & Matching ZFS - flatcar/flatcar-kernel.bst - flatcar/flatcar-zfs.bst - - bluefin-server/linux-firmware-split.bst - - # Filesystem resizing support for growing root/var on first boot - - freedesktop-sdk.bst:components/xfsprogs.bst # Sysext Compatibility Identity - bluefin-server/os-release-flatcar.bst @@ -55,18 +50,12 @@ depends: # Public keyring for verifying SHA256SUMS manifests from GitHub Releases - bluefin-server/os-sysupdate-keys.bst - # gpg binary required by systemd-sysupdate to verify SHA256SUMS.gpg - - freedesktop-sdk.bst:components/gnupg.bst - # First-Boot Credentials Provisioning - bluefin-server/os-creds-prov.bst # Reboot Coordination for Kured - bluefin-server/os-kured-hook.bst - # Container Runtime support - - freedesktop-sdk.bst:components/podman.bst - # System Management Justfile - bluefin-server/os-justfile.bst diff --git a/elements/flatcar/flatcar-usr.bst b/elements/flatcar/flatcar-usr.bst new file mode 100644 index 00000000..40e6002b --- /dev/null +++ b/elements/flatcar/flatcar-usr.bst @@ -0,0 +1,84 @@ +kind: manual +description: | + Import the Flatcar LTS `/usr` as the Bluefin Server OS payload base. + + Replaces the FSDK 26.08 base userspace (systemd, glibc, bash, coreutils, + dbus, systemd-sysext) with a single-ABI Flatcar `/usr` that shares the + vermagic, glibc, and systemd of the Flatcar LTS kernel imported by + flatcar-kernel.bst and flatcar-zfs.bst. The installer keeps its own FSDK + userspace (see installer/installer-stack.bst); only the installed OS DDI + lands on this base. + + Mirrors flatcar-zfs.bst's import pattern: a single pinned, digest-verified + remote source, prebuilt binaries, no rebuild from source. + +(@): + - include/arch.yml + - include/flatcar.yml + +build-depends: + - base/base-stack.bst + - freedesktop-sdk.bst:components/tar.bst + - freedesktop-sdk.bst:components/gzip.bst + - freedesktop-sdk.bst:components/xz.bst + - freedesktop-sdk.bst:components/findutils.bst + - freedesktop-sdk.bst:components/coreutils.bst + - freedesktop-sdk.bst:components/squashfs-tools.bst + +variables: + # Prebuilt binaries: the FSDK stripper must not touch Flatcar's trees. + strip-binaries: "" + +sources: + # Complete OS tree: /usr (19,658 entries), /boot, /oem. Carries .DIGESTS, + # .DIGESTS.asc, and .sig companions for independent GPG verification. + - kind: remote + url: flatcar:stable/%{flatcar-board}/%{flatcar-version}/flatcar-container.tar.gz + ref: c533ff576e128d11ce240e01f818c358d75b9ff118b2dd9199fbf4684547a32c + +config: + install-commands: + - | + set -euo pipefail + + # Extract the complete Flatcar /usr into the element install root. + tar -xzf flatcar-container.tar.gz -C "%{install-root}" ./usr + + # --- Remove Flatcar's update + provisioning stack --------------------- + # Bluefin Server stays on systemd-sysupdate + Kured (design non-goal), + # so these upstream units are dropped rather than masked. Each rm names + # its replacement so a Flatcar bump that reintroduces a different tool + # fails loudly instead of silently regressing the update path. + rm -rf "%{install-root}/usr/bin/update_engine" \ + "%{install-root}/usr/bin/update_engine_client" \ + "%{install-root}/usr/lib/systemd/system/update_engine.service" \ + "%{install-root}/usr/lib/systemd/system/update_timer.service" \ + "%{install-root}/usr/bin/locksmithd" \ + "%{install-root}/usr/bin/ignition" \ + "%{install-root}/usr/bin/coreos-cloudinit" \ + "%{install-root}/usr/bin/flatcar-update" \ + "%{install-root}/usr/bin/download_sysext" \ + "%{install-root}/usr/lib/systemd/system/ensure-sysext.service" + + # --- Flatten Flatcar's nested module directory ------------------------ + # Flatcar nests modules at usr/lib/modules///. The rest of + # this tree (flatcar-kernel.bst, dracut, dracut/depmod) expects the + # single-level usr/lib/modules// layout, so collapse one level. + KVER="%{flatcar-kver}" + if [ -d "%{install-root}/usr/lib/modules/${KVER}/${KVER}" ]; then + mv "%{install-root}/usr/lib/modules/${KVER}/${KVER}" \ + "%{install-root}/usr/lib/modules/${KVER}.flatcar-nested" + find "%{install-root}/usr/lib/modules/${KVER}.flatcar-nested" \ + -mindepth 1 -maxdepth 1 -exec mv -t "%{install-root}/usr/lib/modules/${KVER}" {} + + rmdir "%{install-root}/usr/lib/modules/${KVER}.flatcar-nested" + fi + + # --- Stage the raw sysext images for runtime sysext usage ------------- + # Preserves Flatcar's prebuilt ZFS / Podman / containerd / docker + # squashfs sysexts under /usr/lib/sysexts, mirroring flatcar-zfs.bst. + mkdir -p "%{install-root}/usr/lib/sysexts" + for name in flatcar-zfs flatcar-podman containerd-flatcar docker-flatcar; do + if [ -e "${name}.raw" ]; then + install -D -m 0644 "${name}.raw" "%{install-root}/usr/lib/sysexts/${name}.raw" + fi + done diff --git a/tests/unit/test_build_depends.py b/tests/unit/test_build_depends.py index b2aa04ee..fca13312 100644 --- a/tests/unit/test_build_depends.py +++ b/tests/unit/test_build_depends.py @@ -72,32 +72,72 @@ def test_compose_elements_set_integrate_false(): ) -def test_os_stack_uses_uutils_not_gnu(): - """Bluefin Server OS must use uutils-coreutils, not GNU userspace.""" +def test_os_stack_uses_flatcar_base(): + """Bluefin Server OS payload now lands on the Flatcar `/usr` base. + + projectbluefin/server#131 cut os-stack.bst over to flatcar/flatcar-usr.bst + and deleted the displaced FSDK base-runtime components. The OS payload must + depend on flatcar-usr.bst and must NOT pull the FSDK base userspace it + replaced (the uutils-coreutils overlay, GNU runtime-minimal, etc.). The + installer keeps its own FSDK userspace (see test_installer_stack_...). + """ os_stack = ELEMENTS_DIR / "bluefin-server" / "os-stack.bst" data = yaml.safe_load(os_stack.read_text(encoding="utf-8")) depends = data.get("depends", []) - assert "bluefin-server/uutils-coreutils.bst" in depends, ( - "os-stack.bst must include bluefin-server/uutils-coreutils.bst" + assert "flatcar/flatcar-usr.bst" in depends, ( + "os-stack.bst must depend on flatcar/flatcar-usr.bst (projectbluefin/server#131)" + ) + assert "bluefin-server/uutils-coreutils.bst" not in depends, ( + "os-stack.bst must no longer ship the uutils-coreutils overlay; " + "Flatcar `/usr` provides coreutils (projectbluefin/server#131)" ) assert "freedesktop-sdk.bst:public-stacks/runtime-gnu.bst" not in depends, ( "os-stack.bst must NOT depend on GNU userspace (runtime-gnu.bst)" ) + for displaced in ( + "freedesktop-sdk.bst:public-stacks/runtime-minimal.bst", + "freedesktop-sdk.bst:components/systemd.bst", + "freedesktop-sdk.bst:components/dbus.bst", + "freedesktop-sdk.bst:components/dbus-broker.bst", + "freedesktop-sdk.bst:components/kmod.bst", + "freedesktop-sdk.bst:components/shadow.bst", + "freedesktop-sdk.bst:bootstrap/bash.bst", + "freedesktop-sdk.bst:components/openssh-systemd.bst", + "freedesktop-sdk.bst:components/podman.bst", + "freedesktop-sdk.bst:components/xfsprogs.bst", + "freedesktop-sdk.bst:components/gnupg.bst", + "freedesktop-sdk.bst:components/ca-certificates.bst", + "freedesktop-sdk.bst:components/tzdata.bst", + "bluefin-server/linux-firmware-split.bst", + ): + assert displaced not in depends, ( + f"os-stack.bst must no longer depend on {displaced} " + "(projectbluefin/server#131)" + ) -def test_os_stack_includes_dbus_broker(): - """Bluefin Server OS must include dbus and dbus-broker for system services.""" +def test_os_stack_userspace_comes_from_flatcar(): + """dbus, dbus-broker, and bash now come from Flatcar `/usr`, not FSDK components. + + projectbluefin/server#131 removed the FSDK dbus, dbus-broker, and + bootstrap/bash entries from os-stack.bst; flatcar/flatcar-usr.bst provides + them as part of the single-ABI Flatcar userspace. This test pins that the + old FSDK base-runtime entries are gone so a stray re-add is caught. + """ os_stack = ELEMENTS_DIR / "bluefin-server" / "os-stack.bst" data = yaml.safe_load(os_stack.read_text(encoding="utf-8")) depends = data.get("depends", []) - assert "freedesktop-sdk.bst:components/dbus.bst" in depends, ( - "os-stack.bst must include freedesktop-sdk.bst:components/dbus.bst for dbus.socket" - ) - assert "freedesktop-sdk.bst:components/dbus-broker.bst" in depends, ( - "os-stack.bst must include freedesktop-sdk.bst:components/dbus-broker.bst" - ) + for removed in ( + "freedesktop-sdk.bst:components/dbus.bst", + "freedesktop-sdk.bst:components/dbus-broker.bst", + "freedesktop-sdk.bst:bootstrap/bash.bst", + ): + assert removed not in depends, ( + f"os-stack.bst must no longer depend on {removed}; " + "Flatcar `/usr` provides it (projectbluefin/server#131)" + ) def test_installer_stack_includes_uutils_and_dbus(): @@ -117,14 +157,27 @@ def test_installer_stack_includes_uutils_and_dbus(): ) -def test_os_stack_includes_bash(): - """Bluefin Server OS must include bash for login and interactive access.""" - os_stack = ELEMENTS_DIR / "bluefin-server" / "os-stack.bst" - data = yaml.safe_load(os_stack.read_text(encoding="utf-8")) +def test_os_countme_depends_on_curl_and_jq(): + """os-countme.bst must ship curl and jq through the freedesktop-sdk junction. + + Regression test for projectbluefin/server#96: the curl dependency was + inferred rather than verified, so a wrong path would fail to resolve and + the minimal image (which ships neither curl nor jq) would not build. + Confirmed that the pinned freedesktop-sdk ref (freedesktop-sdk-26.08.0, + elements/freedesktop-sdk.bst) ships both elements/components/curl.bst and + elements/components/jq.bst, so the dependency must stay on this exact path. + """ + countme = ELEMENTS_DIR / "bluefin-server" / "os-countme.bst" + data = yaml.safe_load(countme.read_text(encoding="utf-8")) depends = data.get("depends", []) - assert "freedesktop-sdk.bst:bootstrap/bash.bst" in depends, ( - "os-stack.bst must include freedesktop-sdk.bst:bootstrap/bash.bst" + assert "freedesktop-sdk.bst:components/curl.bst" in depends, ( + "os-countme.bst must include freedesktop-sdk.bst:components/curl.bst " + "(projectbluefin/server#96)" + ) + assert "freedesktop-sdk.bst:components/jq.bst" in depends, ( + "os-countme.bst must include freedesktop-sdk.bst:components/jq.bst " + "(projectbluefin/server#96)" ) From e5fba15ef054bb755f526a3915db39066188d56b Mon Sep 17 00:00:00 2001 From: kylerankin Date: Mon, 14 Sep 2026 06:04:55 +0000 Subject: [PATCH 03/42] fix(installer): ld.so.conf uses Flatcar /usr/lib64, not Debian multiarch The installer's ld.so.conf hardcoded /usr/lib/x86_64-linux-gnu (the Debian/ Ubuntu multiarch path). On the Flatcar-based server image the FSDK libraries it needs to index (libc.so.6, libgcc_s.so.1, libkmod.so) live under /usr/lib64, so ldconfig cached the wrong path and the bad cache was copied over the build sandbox's own. Point both ld.so.conf entries at /usr/lib64. projectbluefin/server#132 (review item #6) --- elements/oci/bluefin-server-installer.bst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/elements/oci/bluefin-server-installer.bst b/elements/oci/bluefin-server-installer.bst index 44d9f300..37cd0680 100644 --- a/elements/oci/bluefin-server-installer.bst +++ b/elements/oci/bluefin-server-installer.bst @@ -107,7 +107,8 @@ config: # Configure dynamic linker search paths so ldconfig indexes FSDK libraries # (e.g. libc.so.6, libgcc_s.so.1, libkmod.so) for dracut-install - printf '/usr/lib/x86_64-linux-gnu\n/usr/lib/x86_64-linux-gnu/systemd\n' > /etc/ld.so.conf + # Flatcar ships FSDK libs under /usr/lib64, not the Debian multiarch path. + printf '/usr/lib64\n/usr/lib64/systemd\n' > /etc/ld.so.conf if [ -d /etc/ld.so.conf.d ]; then echo 'include /etc/ld.so.conf.d/*.conf' >> /etc/ld.so.conf fi @@ -115,7 +116,8 @@ config: # Build target-root linker cache and stage it at /etc/ld.so.cache for dracut mkdir -p /target-root/tmp /target-root/etc - printf '/usr/lib/x86_64-linux-gnu\n/usr/lib/x86_64-linux-gnu/systemd\n' > /target-root/tmp/ld.so.conf + # Flatcar ships FSDK libs under /usr/lib64, not the Debian multiarch path. + printf '/usr/lib64\n/usr/lib64/systemd\n' > /target-root/tmp/ld.so.conf if [ -d /target-root/etc/ld.so.conf.d ]; then echo 'include /etc/ld.so.conf.d/*.conf' >> /target-root/tmp/ld.so.conf fi From dca9fe7fc674e1cb8596a1536322921f7f5b4487 Mon Sep 17 00:00:00 2001 From: kylerankin Date: Mon, 14 Sep 2026 08:06:39 +0000 Subject: [PATCH 04/42] fix(flatcar): drop duplicate flatcar-usr.bst, provided by #140 --- elements/flatcar/flatcar-usr.bst | 84 -------------------------------- 1 file changed, 84 deletions(-) delete mode 100644 elements/flatcar/flatcar-usr.bst diff --git a/elements/flatcar/flatcar-usr.bst b/elements/flatcar/flatcar-usr.bst deleted file mode 100644 index 40e6002b..00000000 --- a/elements/flatcar/flatcar-usr.bst +++ /dev/null @@ -1,84 +0,0 @@ -kind: manual -description: | - Import the Flatcar LTS `/usr` as the Bluefin Server OS payload base. - - Replaces the FSDK 26.08 base userspace (systemd, glibc, bash, coreutils, - dbus, systemd-sysext) with a single-ABI Flatcar `/usr` that shares the - vermagic, glibc, and systemd of the Flatcar LTS kernel imported by - flatcar-kernel.bst and flatcar-zfs.bst. The installer keeps its own FSDK - userspace (see installer/installer-stack.bst); only the installed OS DDI - lands on this base. - - Mirrors flatcar-zfs.bst's import pattern: a single pinned, digest-verified - remote source, prebuilt binaries, no rebuild from source. - -(@): - - include/arch.yml - - include/flatcar.yml - -build-depends: - - base/base-stack.bst - - freedesktop-sdk.bst:components/tar.bst - - freedesktop-sdk.bst:components/gzip.bst - - freedesktop-sdk.bst:components/xz.bst - - freedesktop-sdk.bst:components/findutils.bst - - freedesktop-sdk.bst:components/coreutils.bst - - freedesktop-sdk.bst:components/squashfs-tools.bst - -variables: - # Prebuilt binaries: the FSDK stripper must not touch Flatcar's trees. - strip-binaries: "" - -sources: - # Complete OS tree: /usr (19,658 entries), /boot, /oem. Carries .DIGESTS, - # .DIGESTS.asc, and .sig companions for independent GPG verification. - - kind: remote - url: flatcar:stable/%{flatcar-board}/%{flatcar-version}/flatcar-container.tar.gz - ref: c533ff576e128d11ce240e01f818c358d75b9ff118b2dd9199fbf4684547a32c - -config: - install-commands: - - | - set -euo pipefail - - # Extract the complete Flatcar /usr into the element install root. - tar -xzf flatcar-container.tar.gz -C "%{install-root}" ./usr - - # --- Remove Flatcar's update + provisioning stack --------------------- - # Bluefin Server stays on systemd-sysupdate + Kured (design non-goal), - # so these upstream units are dropped rather than masked. Each rm names - # its replacement so a Flatcar bump that reintroduces a different tool - # fails loudly instead of silently regressing the update path. - rm -rf "%{install-root}/usr/bin/update_engine" \ - "%{install-root}/usr/bin/update_engine_client" \ - "%{install-root}/usr/lib/systemd/system/update_engine.service" \ - "%{install-root}/usr/lib/systemd/system/update_timer.service" \ - "%{install-root}/usr/bin/locksmithd" \ - "%{install-root}/usr/bin/ignition" \ - "%{install-root}/usr/bin/coreos-cloudinit" \ - "%{install-root}/usr/bin/flatcar-update" \ - "%{install-root}/usr/bin/download_sysext" \ - "%{install-root}/usr/lib/systemd/system/ensure-sysext.service" - - # --- Flatten Flatcar's nested module directory ------------------------ - # Flatcar nests modules at usr/lib/modules///. The rest of - # this tree (flatcar-kernel.bst, dracut, dracut/depmod) expects the - # single-level usr/lib/modules// layout, so collapse one level. - KVER="%{flatcar-kver}" - if [ -d "%{install-root}/usr/lib/modules/${KVER}/${KVER}" ]; then - mv "%{install-root}/usr/lib/modules/${KVER}/${KVER}" \ - "%{install-root}/usr/lib/modules/${KVER}.flatcar-nested" - find "%{install-root}/usr/lib/modules/${KVER}.flatcar-nested" \ - -mindepth 1 -maxdepth 1 -exec mv -t "%{install-root}/usr/lib/modules/${KVER}" {} + - rmdir "%{install-root}/usr/lib/modules/${KVER}.flatcar-nested" - fi - - # --- Stage the raw sysext images for runtime sysext usage ------------- - # Preserves Flatcar's prebuilt ZFS / Podman / containerd / docker - # squashfs sysexts under /usr/lib/sysexts, mirroring flatcar-zfs.bst. - mkdir -p "%{install-root}/usr/lib/sysexts" - for name in flatcar-zfs flatcar-podman containerd-flatcar docker-flatcar; do - if [ -e "${name}.raw" ]; then - install -D -m 0644 "${name}.raw" "%{install-root}/usr/lib/sysexts/${name}.raw" - fi - done From e55b3659d4541e8797c692b627cccb3f9e8b7d60 Mon Sep 17 00:00:00 2001 From: kylerankin Date: Mon, 14 Sep 2026 15:45:07 +0000 Subject: [PATCH 05/42] fix(installer): keep host ld.so.conf on Debian multiarch path The installer/dracut tooling is FSDK/Debian-based, so its libraries live under /usr/lib/x86_64-linux-gnu. The host ldconfig must index that path; /usr/lib64 is only correct for the Flatcar target-root cache (which the -r /target-root ldconfig builds and copies over the host cache). Keeping /usr/lib64 on the host risks FSDK libs not resolving during the build. Addresses hanthor's review comment on projectbluefin/server#132 (points 1 and 4). --- elements/oci/bluefin-server-installer.bst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/elements/oci/bluefin-server-installer.bst b/elements/oci/bluefin-server-installer.bst index 37cd0680..c7b282f7 100644 --- a/elements/oci/bluefin-server-installer.bst +++ b/elements/oci/bluefin-server-installer.bst @@ -107,8 +107,10 @@ config: # Configure dynamic linker search paths so ldconfig indexes FSDK libraries # (e.g. libc.so.6, libgcc_s.so.1, libkmod.so) for dracut-install - # Flatcar ships FSDK libs under /usr/lib64, not the Debian multiarch path. - printf '/usr/lib64\n/usr/lib64/systemd\n' > /etc/ld.so.conf + # The installer/dracut tooling is FSDK/Debian-based: its libraries live + # under the Debian multiarch path, so the host ldconfig must index that + # path (this cache is overwritten by the target cache below on purpose). + printf '/usr/lib/x86_64-linux-gnu\n/usr/lib/x86_64-linux-gnu/systemd\n' > /etc/ld.so.conf if [ -d /etc/ld.so.conf.d ]; then echo 'include /etc/ld.so.conf.d/*.conf' >> /etc/ld.so.conf fi From 312e11d0a2c79d145abd5aa7375abbfb9678669d Mon Sep 17 00:00:00 2001 From: Jorge Castro Date: Fri, 18 Sep 2026 13:10:04 -0400 Subject: [PATCH 06/42] ci(just): run the renovate series guard in validate `check-renovate-series.py` was wired into pre-commit and the unit suite but not into `just validate`, unlike its siblings `check-release-version.py` and `check-k0s-version.py`. Since AGENTS.md and docs/skills/ci-tooling.md point contributors at `just validate` as the merge-contract check, the new invariant was effectively unenforced there. Assisted-by: Claude Opus 4.6 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- Justfile | 1 + 1 file changed, 1 insertion(+) diff --git a/Justfile b/Justfile index f2dc1b23..1bae6d3f 100644 --- a/Justfile +++ b/Justfile @@ -55,6 +55,7 @@ tags: validate: python3 .github/scripts/check-release-version.py python3 .github/scripts/check-k0s-version.py + python3 .github/scripts/check-renovate-series.py just bst show --deps all oci/bluefin-server-ddi.bst just bst show --deps all oci/bluefin-server-installer.bst just bst show --deps all oci/k0s-sysext.bst From 45ca29e266742da3b8e10ab8069f041355131e45 Mon Sep 17 00:00:00 2001 From: mrbobbytables Date: Sat, 19 Sep 2026 14:13:25 +0000 Subject: [PATCH 07/42] ci: expand unit-tests workflow paths trigger Trigger unit tests on changes to elements/**, include/**, project.conf, .pre-commit-config.yaml, and .github/workflows/build.yml, which are read and asserted by the unit test suite. Fixes #187 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: mrbobbytables --- .github/workflows/unit-tests.yml | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/.github/workflows/unit-tests.yml b/.github/workflows/unit-tests.yml index fc4485d7..7012df6b 100644 --- a/.github/workflows/unit-tests.yml +++ b/.github/workflows/unit-tests.yml @@ -4,16 +4,26 @@ on: pull_request: paths: - '.github/scripts/**' + - '.github/workflows/build.yml' - '.github/workflows/unit-tests.yml' + - '.pre-commit-config.yaml' + - 'elements/**' - 'files/**' + - 'include/**' + - 'project.conf' - 'tests/unit/**' - 'Justfile' push: branches: [main] paths: - '.github/scripts/**' + - '.github/workflows/build.yml' - '.github/workflows/unit-tests.yml' + - '.pre-commit-config.yaml' + - 'elements/**' - 'files/**' + - 'include/**' + - 'project.conf' - 'tests/unit/**' - 'Justfile' From a13e40a9237496b4d08fbb06ff6fa8058524e7da Mon Sep 17 00:00:00 2001 From: hive-agent Date: Sat, 19 Sep 2026 14:16:52 +0000 Subject: [PATCH 08/42] fix(ci): pin just tool version in CI workflows taiki-e/install-action resolves just@latest at run time when no version is supplied, so the build tool that drives every job (just validate, just test-unit, DDI/kernel export recipes) was unpinned while every GitHub Action in the repo is SHA-pinned. Pin just to 1.58.0, the version CI already installs, so this changes no runtime behavior. Signed-off-by: hive-agent --- .github/workflows/build.yml | 4 ++-- .github/workflows/kernel.yml | 2 +- .github/workflows/unit-tests.yml | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index bf99f8ea..ed4cba99 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -39,7 +39,7 @@ jobs: - name: Set up just uses: taiki-e/install-action@7b8d4719ee4aaa279bdf55df38dacb9ebfe12a6c # v2 with: - tool: just + tool: just@1.58.0 - name: Track and Resolve BuildStream Refs env: @@ -77,7 +77,7 @@ jobs: - name: Set up just uses: taiki-e/install-action@7b8d4719ee4aaa279bdf55df38dacb9ebfe12a6c # v2 with: - tool: just + tool: just@1.58.0 - name: Validate Element Graph run: just validate diff --git a/.github/workflows/kernel.yml b/.github/workflows/kernel.yml index 6d420e86..3d1cf6e4 100644 --- a/.github/workflows/kernel.yml +++ b/.github/workflows/kernel.yml @@ -39,7 +39,7 @@ jobs: - name: Set up just uses: taiki-e/install-action@7b8d4719ee4aaa279bdf55df38dacb9ebfe12a6c # v2 with: - tool: just + tool: just@1.58.0 - name: Validate Element Graph run: just validate diff --git a/.github/workflows/unit-tests.yml b/.github/workflows/unit-tests.yml index fc4485d7..32bbcba1 100644 --- a/.github/workflows/unit-tests.yml +++ b/.github/workflows/unit-tests.yml @@ -41,7 +41,7 @@ jobs: - name: Set up just uses: taiki-e/install-action@7b8d4719ee4aaa279bdf55df38dacb9ebfe12a6c # v2 with: - tool: just + tool: just@1.58.0 - name: Run unit tests run: just test-unit From 8e96b1c41b1f036395fdcddcc480d8a139b597e4 Mon Sep 17 00:00:00 2001 From: hive-agent Date: Sat, 19 Sep 2026 15:02:27 +0000 Subject: [PATCH 09/42] fix(installer): align target ld.so.conf path + add linker-path contract test hanthor review on #132: - The target ld.so.conf was written to /target-root/tmp/ but read via 'ldconfig -r /target-root -f /tmp/ld.so.conf'. That only resolves because of the -r chroot; make both agree on host /tmp explicitly. - Add a contract test asserting the host indexes the Debian multiarch path and the target indexes Flatcar /usr/lib64, and that the two paths agree. projectbluefin/server#132 --- elements/oci/bluefin-server-installer.bst | 10 +++--- tests/unit/test_build_depends.py | 38 +++++++++++++++++++++++ 2 files changed, 44 insertions(+), 4 deletions(-) diff --git a/elements/oci/bluefin-server-installer.bst b/elements/oci/bluefin-server-installer.bst index c7b282f7..89d81098 100644 --- a/elements/oci/bluefin-server-installer.bst +++ b/elements/oci/bluefin-server-installer.bst @@ -117,14 +117,16 @@ config: ldconfig # Build target-root linker cache and stage it at /etc/ld.so.cache for dracut - mkdir -p /target-root/tmp /target-root/etc + # The conf lives at host /tmp (what ldconfig -f reads below); -r /target-root + # makes ldconfig write the cache to /target-root/etc/ld.so.cache instead. + mkdir -p /target-root/etc # Flatcar ships FSDK libs under /usr/lib64, not the Debian multiarch path. - printf '/usr/lib64\n/usr/lib64/systemd\n' > /target-root/tmp/ld.so.conf + printf '/usr/lib64\n/usr/lib64/systemd\n' > /tmp/ld.so.conf if [ -d /target-root/etc/ld.so.conf.d ]; then - echo 'include /etc/ld.so.conf.d/*.conf' >> /target-root/tmp/ld.so.conf + echo 'include /etc/ld.so.conf.d/*.conf' >> /tmp/ld.so.conf fi ldconfig -r /target-root -f /tmp/ld.so.conf - rm -f /target-root/tmp/ld.so.conf + rm -f /tmp/ld.so.conf cp /target-root/etc/ld.so.cache /etc/ld.so.cache # Run dracut in generic (non-hostonly) mode and explicitly add XFS, VirtIO, and NVMe storage drivers. diff --git a/tests/unit/test_build_depends.py b/tests/unit/test_build_depends.py index fca13312..1466ec33 100644 --- a/tests/unit/test_build_depends.py +++ b/tests/unit/test_build_depends.py @@ -181,5 +181,43 @@ def test_os_countme_depends_on_curl_and_jq(): ) +def test_installer_linker_paths_split_host_and_target(): + """Installer must index FSDK libs on the host and Flatcar libs in the target. + + projectbluefin/server#132 (hanthor review): the installer/dracut tooling is + FSDK/Debian-based, so the *host* ldconfig must index the Debian multiarch + path (/usr/lib/x86_64-linux-gnu) while the *target-root* cache must index + Flatcar's /usr/lib64. A host cache pointed only at /usr/lib64 would prevent + FSDK libraries from resolving during the installer build. The target conf is + written to host /tmp and read via `ldconfig -r /target-root -f /tmp/ld.so.conf` + so the two paths agree instead of relying on a hidden chroot resolve. + """ + installer = ELEMENTS_DIR / "oci" / "bluefin-server-installer.bst" + text = installer.read_text(encoding="utf-8") + + # Host linker search path (what the host ldconfig indexes). The printf + # format uses a literal backslash-n, so match it literally. + assert "/usr/lib/x86_64-linux-gnu\\n/usr/lib/x86_64-linux-gnu/systemd\\n" in text, ( + "installer must index the Debian multiarch path on the host ld.so.conf " + "(projectbluefin/server#132)" + ) + # Target linker search path (what the target-root cache indexes). + assert "/usr/lib64\\n/usr/lib64/systemd\\n" in text, ( + "installer must index Flatcar /usr/lib64 for the target-root cache " + "(projectbluefin/server#132)" + ) + # The target conf must not be written under /target-root/tmp and then read + # from a different location; both must agree on host /tmp. + assert "> /target-root/tmp/ld.so.conf" not in text, ( + "installer target ld.so.conf must be written to host /tmp, not " + "/target-root/tmp, matching the `ldconfig -f /tmp/ld.so.conf` read " + "(projectbluefin/server#132)" + ) + assert "ldconfig -r /target-root -f /tmp/ld.so.conf" in text, ( + "installer must read the target conf from /tmp with `-r /target-root " + "(projectbluefin/server#132)" + ) + + From 5f9ab234897a5f85ba2cfc2786eee46dc264ee40 Mon Sep 17 00:00:00 2001 From: hive-agent Date: Sat, 19 Sep 2026 15:22:46 +0000 Subject: [PATCH 10/42] =?UTF-8?q?fix(installer):=20revert=20ld.so.conf=20w?= =?UTF-8?q?rite=20path=20=E2=80=94=20-f=20resolves=20post-chroot?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit My previous commit (8e96b1c) wrote the target conf to host /tmp/ld.so.conf, but 'ldconfig -r /target-root -f /tmp/ld.so.conf' reads it post-chroot at /target-root/tmp/ld.so.conf, so the build would fail to find the config. Verified empirically that -r chroots the -f path. Revert the write to /target-root/tmp/ld.so.conf and document the post-chroot resolve instead. Fix the contract test, which had encoded the wrong paths. --- elements/oci/bluefin-server-installer.bst | 13 ++++---- tests/unit/test_build_depends.py | 38 +++++++++++------------ 2 files changed, 25 insertions(+), 26 deletions(-) diff --git a/elements/oci/bluefin-server-installer.bst b/elements/oci/bluefin-server-installer.bst index 89d81098..8b2daa98 100644 --- a/elements/oci/bluefin-server-installer.bst +++ b/elements/oci/bluefin-server-installer.bst @@ -117,16 +117,17 @@ config: ldconfig # Build target-root linker cache and stage it at /etc/ld.so.cache for dracut - # The conf lives at host /tmp (what ldconfig -f reads below); -r /target-root - # makes ldconfig write the cache to /target-root/etc/ld.so.cache instead. - mkdir -p /target-root/etc + # ldconfig -r chroots into /target-root, so the -f config path below is + # resolved to /target-root/tmp/ld.so.conf (post-chroot). Keep the write + # there too and the cache lands at /target-root/etc/ld.so.cache. + mkdir -p /target-root/tmp /target-root/etc # Flatcar ships FSDK libs under /usr/lib64, not the Debian multiarch path. - printf '/usr/lib64\n/usr/lib64/systemd\n' > /tmp/ld.so.conf + printf '/usr/lib64\n/usr/lib64/systemd\n' > /target-root/tmp/ld.so.conf if [ -d /target-root/etc/ld.so.conf.d ]; then - echo 'include /etc/ld.so.conf.d/*.conf' >> /tmp/ld.so.conf + echo 'include /etc/ld.so.conf.d/*.conf' >> /target-root/tmp/ld.so.conf fi ldconfig -r /target-root -f /tmp/ld.so.conf - rm -f /tmp/ld.so.conf + rm -f /target-root/tmp/ld.so.conf cp /target-root/etc/ld.so.cache /etc/ld.so.cache # Run dracut in generic (non-hostonly) mode and explicitly add XFS, VirtIO, and NVMe storage drivers. diff --git a/tests/unit/test_build_depends.py b/tests/unit/test_build_depends.py index 1466ec33..3110fac2 100644 --- a/tests/unit/test_build_depends.py +++ b/tests/unit/test_build_depends.py @@ -182,41 +182,39 @@ def test_os_countme_depends_on_curl_and_jq(): def test_installer_linker_paths_split_host_and_target(): - """Installer must index FSDK libs on the host and Flatcar libs in the target. - - projectbluefin/server#132 (hanthor review): the installer/dracut tooling is - FSDK/Debian-based, so the *host* ldconfig must index the Debian multiarch - path (/usr/lib/x86_64-linux-gnu) while the *target-root* cache must index - Flatcar's /usr/lib64. A host cache pointed only at /usr/lib64 would prevent - FSDK libraries from resolving during the installer build. The target conf is - written to host /tmp and read via `ldconfig -r /target-root -f /tmp/ld.so.conf` - so the two paths agree instead of relying on a hidden chroot resolve. + """Target-root ld.so.conf write and read must resolve to the same file. + + projectbluefin/server#132 (hanthor review): `ldconfig -r /target-root` chroots + into /target-root, so the `-f /tmp/ld.so.conf` path is resolved *post-chroot* to + /target-root/tmp/ld.so.conf. The conf is therefore written to /target-root/tmp/ + and read back via `-f /tmp/ld.so.conf`; the two must agree, not live on different + roots. The target cache indexes Flatcar's /usr/lib64 (the FSDK libs ship there, + not the Debian multiarch path). """ installer = ELEMENTS_DIR / "oci" / "bluefin-server-installer.bst" text = installer.read_text(encoding="utf-8") - # Host linker search path (what the host ldconfig indexes). The printf - # format uses a literal backslash-n, so match it literally. - assert "/usr/lib/x86_64-linux-gnu\\n/usr/lib/x86_64-linux-gnu/systemd\\n" in text, ( - "installer must index the Debian multiarch path on the host ld.so.conf " - "(projectbluefin/server#132)" - ) # Target linker search path (what the target-root cache indexes). assert "/usr/lib64\\n/usr/lib64/systemd\\n" in text, ( "installer must index Flatcar /usr/lib64 for the target-root cache " "(projectbluefin/server#132)" ) - # The target conf must not be written under /target-root/tmp and then read - # from a different location; both must agree on host /tmp. - assert "> /target-root/tmp/ld.so.conf" not in text, ( - "installer target ld.so.conf must be written to host /tmp, not " - "/target-root/tmp, matching the `ldconfig -f /tmp/ld.so.conf` read " + # Conf written to /target-root/tmp and read via `-f /tmp/ld.so.conf` under + # `-r /target-root` (which resolves to /target-root/tmp/ld.so.conf post-chroot). + assert "> /target-root/tmp/ld.so.conf" in text, ( + "installer must write the target ld.so.conf to /target-root/tmp, matching " + "the `ldconfig -r /target-root -f /tmp/ld.so.conf` read " "(projectbluefin/server#132)" ) assert "ldconfig -r /target-root -f /tmp/ld.so.conf" in text, ( "installer must read the target conf from /tmp with `-r /target-root " "(projectbluefin/server#132)" ) + # Cleanup removes the same post-chroot path it wrote. + assert "rm -f /target-root/tmp/ld.so.conf" in text, ( + "installer must clean up /target-root/tmp/ld.so.conf " + "(projectbluefin/server#132)" + ) From dd31769f2d0f91e465c93336029cc96cf01bbcd5 Mon Sep 17 00:00:00 2001 From: hive-agent Date: Sat, 19 Sep 2026 15:28:07 +0000 Subject: [PATCH 11/42] test(132): drop duplicate test_os_countme from #132 #122 adds test_os_countme_depends_on_curl_and_jq; #132 carried a verbatim copy that would conflict on merge (Python keeps the second silently). Per hanthor's coordination, land #122 first and let #132 drop its copy. --- tests/unit/test_build_depends.py | 24 ------------------------ 1 file changed, 24 deletions(-) diff --git a/tests/unit/test_build_depends.py b/tests/unit/test_build_depends.py index 3110fac2..3c8d9edc 100644 --- a/tests/unit/test_build_depends.py +++ b/tests/unit/test_build_depends.py @@ -157,30 +157,6 @@ def test_installer_stack_includes_uutils_and_dbus(): ) -def test_os_countme_depends_on_curl_and_jq(): - """os-countme.bst must ship curl and jq through the freedesktop-sdk junction. - - Regression test for projectbluefin/server#96: the curl dependency was - inferred rather than verified, so a wrong path would fail to resolve and - the minimal image (which ships neither curl nor jq) would not build. - Confirmed that the pinned freedesktop-sdk ref (freedesktop-sdk-26.08.0, - elements/freedesktop-sdk.bst) ships both elements/components/curl.bst and - elements/components/jq.bst, so the dependency must stay on this exact path. - """ - countme = ELEMENTS_DIR / "bluefin-server" / "os-countme.bst" - data = yaml.safe_load(countme.read_text(encoding="utf-8")) - depends = data.get("depends", []) - - assert "freedesktop-sdk.bst:components/curl.bst" in depends, ( - "os-countme.bst must include freedesktop-sdk.bst:components/curl.bst " - "(projectbluefin/server#96)" - ) - assert "freedesktop-sdk.bst:components/jq.bst" in depends, ( - "os-countme.bst must include freedesktop-sdk.bst:components/jq.bst " - "(projectbluefin/server#96)" - ) - - def test_installer_linker_paths_split_host_and_target(): """Target-root ld.so.conf write and read must resolve to the same file. From 668ffd1a7b68f7aaedd8e87b1a7fe7f57c280ab6 Mon Sep 17 00:00:00 2001 From: ci-maintainer Date: Sat, 19 Sep 2026 20:18:10 -0400 Subject: [PATCH 12/42] docs(ci-tooling): pin the tool version in the canonical just snippet The skill doc's install snippet still showed an unpinned 'tool: just', which is the form issue #188 removed from the workflows. A workflow copied from the doc would have reintroduced it, undoing this PR on the next new job. Update the snippet to 'tool: just@1.58.0', matching all four call sites, and explain that without a version install-action resolves just@latest at run time. Note that the version is repeated per call site so a bump has to change all of them in one commit. Add the half-done pin to Red Flags, add a checklist item for it under Verification, and record the 'tool: just always installs a working version' rationalization. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/skills/ci-tooling.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/docs/skills/ci-tooling.md b/docs/skills/ci-tooling.md index e236f99f..0ef33331 100644 --- a/docs/skills/ci-tooling.md +++ b/docs/skills/ci-tooling.md @@ -42,12 +42,21 @@ before adding an action. ### Installing `just` — taiki-e/install-action, not snap/cargo/apt +Pin the tool version too, not only the action SHA. Without `@`, +`install-action` resolves `just@latest` at run time, so the CI contract +(`just validate`, `just test-unit`, the DDI/kernel export recipes) runs against +a binary chosen by an upstream release rather than by a commit in this repo. + ```yaml - uses: taiki-e/install-action@b6b84cf49ebfe0176417bdce007c624f0db37f20 # v2 with: - tool: just + tool: just@1.58.0 ``` +The version is repeated at each call site — currently `build.yml` (two jobs), +`kernel.yml` and `unit-tests.yml`. Bumping `just` means changing all of them in +one commit, so CI never runs two versions at once. + ### Workflow permissions `.github/workflows/build.yml` defaults to a read-only token: @@ -130,10 +139,13 @@ uploaded to a GitHub Release tagged `installer-v`. |---|---| | "It's just a minor version tag, supply-chain risk is low." | One compromised tag push owns every repo using it. Pin to SHA. | | "I'll check what SHA other repos use later." | Check now — it's one `gh api` call and takes a few seconds. | +| "`tool: just` always installs a working version." | It installs whatever is latest that day. A `just` release can change recipe parsing or `--fmt` output and break CI with no commit in this repo. | ## Red Flags - Any `uses:` line with a mutable ref (`@v2`, `@main`, `@latest`). +- An `install-action` step whose `tool:` has no `@` — the pin is half + done, since the action is fixed but the binary it installs is not. - `sudo podman` in one step and plain `podman` in another step doing the same operation. - A new action not present in any sibling repo — check upstream first. @@ -141,6 +153,7 @@ uploaded to a GitHub Release tagged `installer-v`. ## Verification - [ ] Every `uses:` line has a full 40-character SHA and a `# vX` comment. +- [ ] Every `install-action` `tool:` names an explicit version (`just@1.58.0`). - [ ] `just validate` passes after workflow changes. - [ ] No new mutable action refs introduced. - [ ] The release signing step uploads detached `.gpg` signatures for every From e3ad84214b077d72b0f96d1c07df7eb22494c759 Mon Sep 17 00:00:00 2001 From: Bob Killen Date: Sun, 20 Sep 2026 04:55:26 -0500 Subject: [PATCH 13/42] fix(installer): bound root-a partition to guarantee room for var (#207) Caps `bluefin-server-root-a` at 8 GiB so the tail `/var` partition is always placeable on a 16 GiB target disk. Root cause of the `installer-test / Install and boot in QEMU` failure that has been red on main since 2026-09-14: serial evidence from run 35497423148 shows `Timed out waiting for device /dev/disk/by-partlabel/var` followed by emergency mode. Verified safe: the DDI payload is 2.16 GiB uncompressed (`zstd -l dist/ddi/bluefin-server-ddi-26.08.0.raw.zst`), well under the new 8 GiB cap and above the 4 GiB `SizeMinBytes`. Closes #161, closes #158, closes #175, closes #166. Assisted-by: Claude Opus 4.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/skills/ddi-installer.md | 2 +- files/installer/repart.d/20-root-a.conf | 2 +- tests/unit/test_repart_layout.py | 20 ++++++++++++++++++++ 3 files changed, 22 insertions(+), 2 deletions(-) diff --git a/docs/skills/ddi-installer.md b/docs/skills/ddi-installer.md index f6fdfcf1..a511f943 100644 --- a/docs/skills/ddi-installer.md +++ b/docs/skills/ddi-installer.md @@ -94,7 +94,7 @@ container runtime pod sandboxes. | Partition | Type | Size | Contents | |---|---|---|---| | ESP | vfat | 500 MiB – 1 GiB | `systemd-boot` + target OS UKI (`bluefin-server.efi`) | -| `bluefin-server-root-a` | XFS | 4 GiB – 16 GiB | OS root filesystem (copied from installer data partition) | +| `bluefin-server-root-a` | XFS | 4 GiB – 8 GiB | OS root filesystem (copied from installer data partition) | | `var` | XFS | ≥ 4 GiB | Writable persistent `/var`; grows to fill remaining disk | ## Installer Boot Flow diff --git a/files/installer/repart.d/20-root-a.conf b/files/installer/repart.d/20-root-a.conf index b10319bd..e843b30a 100644 --- a/files/installer/repart.d/20-root-a.conf +++ b/files/installer/repart.d/20-root-a.conf @@ -7,5 +7,5 @@ Type=root Label=bluefin-server-root-a CopyBlocks=/dev/disk/by-partlabel/bluefin-installer-data SizeMinBytes=4G -SizeMaxBytes=16G +SizeMaxBytes=8G GrowFileSystem=yes diff --git a/tests/unit/test_repart_layout.py b/tests/unit/test_repart_layout.py index bf5a0bd0..e21e5b46 100644 --- a/tests/unit/test_repart_layout.py +++ b/tests/unit/test_repart_layout.py @@ -180,6 +180,26 @@ def test_root_slot_grows_and_is_bounded_below_the_var_partition(): assert "SizeMaxBytes" in root, ( "the root slot must be capped, otherwise /var gets no space on small disks" ) + assert parse_size(root["SizeMaxBytes"]) <= 8 * 1024**3, ( + "the root slot must be capped at 8 GiB or less so /var fits on a 16 GiB disk" + ) + + +def test_bounded_partitions_leave_room_for_var_on_minimum_target_disk(): + # Smoke-test and minimal installer target disks are 16 GiB (SHOW_ME_THE_FUTURE_DISK_SIZE). + target_disk = 16 * 1024**3 + esp = next(s for s in partitions().values() if s["Type"] == "esp") + root = next(s for s in partitions().values() if s["Type"] == "root") + var = next(s for s in partitions().values() if s["Type"] == "var") + + esp_max = parse_size(esp["SizeMaxBytes"]) + root_max = parse_size(root["SizeMaxBytes"]) + var_min = parse_size(var["SizeMinBytes"]) + + assert esp_max + root_max + var_min <= target_disk, ( + f"ESP max ({esp_max}) + root max ({root_max}) + var min ({var_min}) " + f"exceeds 16 GiB target disk ({target_disk}), which starves /var" + ) def test_var_is_a_growing_xfs_tail(): From 1698c250bdf2d7a398b36f89ccb458ea7bd72bbd Mon Sep 17 00:00:00 2001 From: "kubestellar-hive[bot]" <280983584+kubestellar-hive[bot]@users.noreply.github.com> Date: Sun, 20 Sep 2026 05:55:35 -0400 Subject: [PATCH 14/42] =?UTF-8?q?[sec-check]=20fix:=20harden=20sshd=20drop?= =?UTF-8?q?-in=20=E2=80=94=20no=20root=20password=20login=20over=20network?= =?UTF-8?q?=20(#169)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Restores the sshd hardening reverted by 37c8356. The same commit seeds the well-known default root password `bluefin` into every DDI `/etc/shadow`; with `PermitRootLogin yes` + `PasswordAuthentication yes`, enabling sshd (the documented bring-up diagnostics path) exposes remote root with published credentials. Console/serial bring-up (root / bluefin via /etc/securetty + issue banner) and key-based remote diagnostics are preserved. Refs #168 — the seeded default password itself stays open; forcing rotation or per-install randomisation is a separate decision. Assisted-by: Claude Opus 4.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- files/os/ssh/sshd_config.d/bluefin-server.conf | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/files/os/ssh/sshd_config.d/bluefin-server.conf b/files/os/ssh/sshd_config.d/bluefin-server.conf index a06b12dc..4994e4a9 100644 --- a/files/os/ssh/sshd_config.d/bluefin-server.conf +++ b/files/os/ssh/sshd_config.d/bluefin-server.conf @@ -1,7 +1,11 @@ # SSH configuration for Bluefin Server. -# Bring-up diagnostics: permit root login with password and pubkey. +# Hardened defaults: no direct root password login, no password auth at all. +# Bring-up diagnostics stay available on the local console (root / bluefin, +# see the issue banner); for remote access inject an authorized_keys entry +# via the installer or systemd credentials. The seeded default password must +# never be usable over the network. -PermitRootLogin yes +PermitRootLogin prohibit-password PubkeyAuthentication yes -PasswordAuthentication yes -KbdInteractiveAuthentication yes +PasswordAuthentication no +KbdInteractiveAuthentication no From 55754043d0dca8ab5b7573b97c363b2dbb5bb70e Mon Sep 17 00:00:00 2001 From: "kubestellar-hive[bot]" <280983584+kubestellar-hive[bot]@users.noreply.github.com> Date: Sun, 20 Sep 2026 05:59:57 -0400 Subject: [PATCH 15/42] [scanner] fix: propagate lima-e2e browser-verification failures (#160) Assisted-by: Claude Opus 4.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- scripts/lima-e2e-kubestellar-test.sh | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/scripts/lima-e2e-kubestellar-test.sh b/scripts/lima-e2e-kubestellar-test.sh index fe760481..79ecff63 100755 --- a/scripts/lima-e2e-kubestellar-test.sh +++ b/scripts/lima-e2e-kubestellar-test.sh @@ -44,8 +44,6 @@ echo "==> Starting local kc-agent client connection..." ./files/bin/bluefin-kubestellar start --origin "http://localhost:8080,http://127.0.0.1:8080" echo "==> Running automated browser verification test..." -python3 tests/e2e/test_kubestellar_browser_login.py --console-url "http://127.0.0.1:8080" --agent-url "http://127.0.0.1:8585" --timeout 15 || { - echo "==> Browser login verification completed (console readiness check handled)." -} +python3 tests/e2e/test_kubestellar_browser_login.py --console-url "http://127.0.0.1:8080" --agent-url "http://127.0.0.1:8585" --timeout 15 echo "==> Lima VM end-to-end verification passed!" From e8aa8a69e98043625ff42c5da16a6339e97847b7 Mon Sep 17 00:00:00 2001 From: "kubestellar-hive[bot]" <280983584+kubestellar-hive[bot]@users.noreply.github.com> Date: Sun, 20 Sep 2026 05:59:59 -0400 Subject: [PATCH 16/42] =?UTF-8?q?test:=20executed=20coverage=20for=20docs-?= =?UTF-8?q?checks.py=20main()=20=E2=80=94=20new=20tests/unit/test=5Fdocs?= =?UTF-8?q?=5Fchecks=5Fmain.py=20(#106)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Assisted-by: Claude Opus 4.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- tests/unit/test_docs_checks_main.py | 253 ++++++++++++++++++++++++++++ 1 file changed, 253 insertions(+) create mode 100644 tests/unit/test_docs_checks_main.py diff --git a/tests/unit/test_docs_checks_main.py b/tests/unit/test_docs_checks_main.py new file mode 100644 index 00000000..9631e5fe --- /dev/null +++ b/tests/unit/test_docs_checks_main.py @@ -0,0 +1,253 @@ +"""Unit tests for ``main()`` in .github/scripts/docs-checks.py. + +``main()`` is the entry point the docs-checks CI workflow invokes, and it was +the only part of the validator with no executed coverage: tests/unit/ +test_docs_checks.py drives the helpers (load_fm, validate_frontmatter, +check_budget, check_stale_flags, check_internal_links, validate_skill) +directly and never runs the orchestration around them. + +That orchestration is what makes the gate a gate: + +* which files are budget-checked, and with which limits +* that *every* skill under docs/skills/ is validated and link-checked +* that the top-level docs are stale-flag and link-checked +* the process contract: exit 1 and a ``FAIL`` line when anything errored, + exit 0 with ``WARN`` lines when only warnings accumulated + +A regression in any of those keeps the workflow green while silently +checking less, which is the failure mode this file exists to catch. +""" + +import pytest + + +BUDGET_TARGETS = [ + # (relative path, hard limit, warning threshold) as passed by main() + ("AGENTS.md", 200, 150), + ("README.md", 200, 150), + ("CONTRIBUTING.md", 100, 80), + ("docs/MVP_1_0_READINESS.md", 250, 200), + ("docs/DOCUMENTATION_OVERHAUL_PLAN.md", 3000, 2500), +] + + +def write(root, relpath, text): + path = root / relpath + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(text) + return path + + +def skill_text(name, description="A skill.", meta_type="how-to", + status="stable", body="Body text.\n"): + return ( + "---\n" + f"name: {name}\n" + f"description: {description}\n" + "metadata:\n" + f" type: {meta_type}\n" + f" status: {status}\n" + "---\n" + f"\n{body}" + ) + + +@pytest.fixture +def tree(docs_checks, tmp_path): + """A minimal repo tree that ``main()`` passes cleanly on. + + ``docs_checks`` already repoints ROOT/DOCS_DIR/SKILLS_DIR at tmp_path and + creates docs/skills/, so this only has to supply the documents main() + unconditionally reads. + """ + for relpath, _limit, _warn in BUDGET_TARGETS: + write(tmp_path, relpath, "# Doc\n\nclean body\n") + return docs_checks + + +def run(module): + """Run main() and return (exit_code, stdout) instead of raising.""" + try: + module.main() + except SystemExit as exc: + return exc.code + return 0 + + +# --- clean tree ------------------------------------------------------------ + +def test_main_passes_on_a_clean_tree(tree, capsys): + write(tree.SKILLS_DIR, "good-skill.md", skill_text("good-skill")) + + assert run(tree) == 0 + out = capsys.readouterr().out + assert "Docs checks passed." in out + assert "FAIL" not in out + assert "WARN" not in out + + +def test_main_passes_with_no_skills_at_all(tree, capsys): + # Empty docs/skills/ must not be an error — the loop is a glob, not a + # required-at-least-one assertion. + assert run(tree) == 0 + assert "Docs checks passed." in capsys.readouterr().out + + +# --- failure contract ------------------------------------------------------ + +def test_main_exits_1_and_prints_fail_when_a_skill_is_invalid(tree, capsys): + write(tree.SKILLS_DIR, "bad-skill.md", skill_text("bad-skill", status="draft")) + + assert run(tree) == 1 + out = capsys.readouterr().out + assert "Errors:" in out + assert "FAIL" in out + assert "bad-skill.md" in out + assert "Docs checks passed." not in out + + +def test_main_exits_1_when_a_skill_has_no_front_matter(tree, capsys): + write(tree.SKILLS_DIR, "raw.md", "# No front matter\n") + + assert run(tree) == 1 + assert "missing YAML front-matter" in capsys.readouterr().out + + +def test_main_validates_every_skill_not_just_the_first(tree, capsys): + write(tree.SKILLS_DIR, "aaa-ok.md", skill_text("aaa-ok")) + write(tree.SKILLS_DIR, "mmm-ok.md", skill_text("mmm-ok")) + write(tree.SKILLS_DIR, "zzz-bad.md", skill_text("zzz-bad", meta_type="nonsense")) + + assert run(tree) == 1 + out = capsys.readouterr().out + assert "zzz-bad.md" in out + assert "aaa-ok.md" not in out + assert "mmm-ok.md" not in out + + +# --- warnings are non-fatal ------------------------------------------------ + +def test_main_prints_warnings_but_still_exits_0(tree, capsys): + # AGENTS.md warns above 150 lines and only errors above 200. + write(tree.ROOT, "AGENTS.md", "# Doc\n" + "line\n" * 160) + + assert run(tree) == 0 + out = capsys.readouterr().out + assert "Warnings:" in out + assert "WARN" in out + assert "AGENTS.md" in out + assert "Docs checks passed." in out + + +def test_main_prints_both_warnings_and_errors_when_both_accumulate(tree, capsys): + write(tree.ROOT, "README.md", "# Doc\n" + "line\n" * 160) + write(tree.SKILLS_DIR, "bad.md", skill_text("bad", status="draft")) + + assert run(tree) == 1 + out = capsys.readouterr().out + assert "Warnings:" in out + assert "Errors:" in out + + +# --- budget targets -------------------------------------------------------- + +@pytest.mark.parametrize("relpath,limit,warn_at", BUDGET_TARGETS) +def test_main_enforces_the_line_budget_of_each_tracked_doc(tree, capsys, relpath, limit, warn_at): + write(tree.ROOT, relpath, "# Doc\n" + "line\n" * (limit + 5)) + + assert run(tree) == 1 + out = capsys.readouterr().out + assert relpath.rsplit("/", 1)[-1] in out + assert f"exceeds {limit} lines" in out + + +@pytest.mark.parametrize("relpath,limit,warn_at", BUDGET_TARGETS) +def test_main_accepts_a_doc_exactly_at_its_hard_budget(tree, capsys, relpath, limit, warn_at): + # The hard limit is inclusive: check_budget errors only on `> max_lines`, + # so a doc of exactly `limit` lines must not fail the gate. It is still + # over the warning threshold, so only the error path is asserted here. + write(tree.ROOT, relpath, "line\n" * limit) + + assert run(tree) == 0 + out = capsys.readouterr().out + assert f"exceeds {limit} lines" not in out + assert "Docs checks passed." in out + + +@pytest.mark.parametrize("relpath,limit,warn_at", BUDGET_TARGETS) +def test_main_warns_between_the_warning_threshold_and_the_hard_limit(tree, capsys, relpath, limit, warn_at): + write(tree.ROOT, relpath, "line\n" * (warn_at + 1)) + + assert run(tree) == 0 + out = capsys.readouterr().out + assert f"exceeds {warn_at} lines" in out + assert "Errors:" not in out + + +@pytest.mark.parametrize("relpath,limit,warn_at", BUDGET_TARGETS) +def test_main_is_silent_at_the_warning_threshold(tree, capsys, relpath, limit, warn_at): + write(tree.ROOT, relpath, "line\n" * warn_at) + + assert run(tree) == 0 + out = capsys.readouterr().out + assert relpath.rsplit("/", 1)[-1] not in out + assert "Docs checks passed." in out + + +# --- stale flags on top-level docs ---------------------------------------- + +@pytest.mark.parametrize("relpath", ["AGENTS.md", "README.md", "CONTRIBUTING.md"]) +def test_main_rejects_stale_markers_in_top_level_docs(tree, capsys, relpath): + write(tree.ROOT, relpath, "# Doc\n\nTODO: finish this section\n") + + assert run(tree) == 1 + assert "contains TODO/FIXME/XXX/HACK" in capsys.readouterr().out + + +@pytest.mark.parametrize("relpath", ["AGENTS.md", "README.md", "CONTRIBUTING.md"]) +def test_main_rejects_draft_markers_in_top_level_docs(tree, capsys, relpath): + write(tree.ROOT, relpath, "# Doc\n\nThis is a draft document.\n") + + assert run(tree) == 1 + assert "contains 'draft' marker" in capsys.readouterr().out + + +def test_main_allows_draft_wording_in_the_exempt_planning_docs(tree, capsys): + # check_stale_flags exempts MVP_1_0_READINESS.md and + # DOCUMENTATION_OVERHAUL_PLAN.md from the draft rule by filename. + write(tree.ROOT, "docs/MVP_1_0_READINESS.md", "# Readiness\n\nStill a draft plan.\n") + + assert run(tree) == 0 + assert "draft" not in capsys.readouterr().out + + +# --- internal links -------------------------------------------------------- + +def test_main_rejects_a_broken_link_in_a_skill(tree, capsys): + write(tree.SKILLS_DIR, "linky.md", + skill_text("linky", body="See [gone](./nowhere.md).\n")) + + assert run(tree) == 1 + assert "broken internal link" in capsys.readouterr().out + + +def test_main_rejects_a_broken_link_in_a_top_level_doc(tree, capsys): + write(tree.ROOT, "README.md", "# Doc\n\nSee [gone](docs/nowhere.md).\n") + + assert run(tree) == 1 + assert "broken internal link" in capsys.readouterr().out + + +def test_main_accepts_a_link_that_resolves_to_a_tracked_markdown_file(tree, capsys): + write(tree.ROOT, "README.md", "# Doc\n\nSee [agents](AGENTS.md).\n") + + assert run(tree) == 0 + assert "Docs checks passed." in capsys.readouterr().out + + +def test_main_accepts_external_and_anchor_links(tree, capsys): + write(tree.ROOT, "README.md", + "# Doc\n\n[web](https://example.com) [mail](mailto:a@b.c) [anchor](#section)\n") + + assert run(tree) == 0 + assert "Docs checks passed." in capsys.readouterr().out From d8cfa658669486e824c37b10a65bfc8a63689324 Mon Sep 17 00:00:00 2001 From: "kubestellar-hive[bot]" <280983584+kubestellar-hive[bot]@users.noreply.github.com> Date: Sun, 20 Sep 2026 06:00:02 -0400 Subject: [PATCH 17/42] =?UTF-8?q?test:=20behavioral=20coverage=20for=20fil?= =?UTF-8?q?es/bin/bluefin-kubestellar=20=E2=80=94=20tests/unit/bluefin-kub?= =?UTF-8?q?estellar=5Ftest.bats=20(#171)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Assisted-by: Claude Opus 4.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- tests/unit/bluefin-kubestellar_test.bats | 386 ++++++++++++++++++++++- 1 file changed, 380 insertions(+), 6 deletions(-) diff --git a/tests/unit/bluefin-kubestellar_test.bats b/tests/unit/bluefin-kubestellar_test.bats index 4eebeec7..b7cdb299 100755 --- a/tests/unit/bluefin-kubestellar_test.bats +++ b/tests/unit/bluefin-kubestellar_test.bats @@ -1,17 +1,99 @@ #!/usr/bin/env bats -# Tests for files/bin/bluefin-kubestellar single-command launcher +# Behavioral tests for files/bin/bluefin-kubestellar single-command launcher. +# +# Every test runs hermetically: XDG_STATE_HOME points at a per-test temp dir and +# curl/kc-agent/brew resolve from a stub bin directory prepended to PATH, so no +# test touches the real host state dir, the network, or Homebrew. setup() { REPO_ROOT="$(cd "$BATS_TEST_DIRNAME/../.." && pwd)" SCRIPT="$REPO_ROOT/files/bin/bluefin-kubestellar" + + export XDG_STATE_HOME="$BATS_TEST_TMPDIR/state" + STATE_DIR="$XDG_STATE_HOME/bluefin-server" + PID_FILE="$STATE_DIR/kc-agent.pid" + LOG_FILE="$STATE_DIR/kc-agent.log" + + STUB_BIN="$BATS_TEST_TMPDIR/bin" + STUB_LOG="$BATS_TEST_TMPDIR/stub.log" + mkdir -p "$STUB_BIN" + export PATH="$STUB_BIN:$PATH" + export STUB_LOG + + # Default: the health endpoint always fails, so nothing is assumed running. + stub_curl_unhealthy +} + +# Writes a stub that records its argv to $STUB_LOG and exits with $2. +make_stub() { + local name="$1" exit_code="$2" + cat > "$STUB_BIN/$name" <> "\$STUB_LOG" +exit $exit_code +EOF + chmod +x "$STUB_BIN/$name" +} + +stub_curl_healthy() { make_stub curl 0; } +stub_curl_unhealthy() { make_stub curl 7; } + +# curl that fails the pre-flight probe once, then reports healthy — the shape a +# real background start sees. +stub_curl_healthy_after_first_probe() { + cat > "$STUB_BIN/curl" <<'EOF' +#!/usr/bin/env bash +echo "curl $*" >> "$STUB_LOG" +marker="$(dirname "$0")/.probed" +if [ -e "$marker" ]; then exit 0; fi +touch "$marker" +exit 7 +EOF + chmod +x "$STUB_BIN/curl" +} + +# kc-agent that stays alive until killed, so PID bookkeeping is observable. +stub_kc_agent_running() { + cat > "$STUB_BIN/kc-agent" <<'EOF' +#!/usr/bin/env bash +echo "kc-agent $*" >> "$STUB_LOG" +exec sleep 30 +EOF + chmod +x "$STUB_BIN/kc-agent" +} + +# kc-agent that exits successfully at once — for foreground runs, which exec it. +stub_kc_agent_foreground() { + make_stub kc-agent 0 +} + +# kc-agent that dies immediately with diagnostics on stdout. +stub_kc_agent_crashing() { + cat > "$STUB_BIN/kc-agent" <<'EOF' +#!/usr/bin/env bash +echo "kc-agent $*" >> "$STUB_LOG" +echo "fatal: bind: address already in use" +exit 9 +EOF + chmod +x "$STUB_BIN/kc-agent" +} + +# Runs the script with a PATH holding only the stub dir plus coreutils, so a +# real kc-agent or brew on the runner cannot leak into the test. +run_isolated() { + run env PATH="$STUB_BIN:/usr/bin:/bin" "$SCRIPT" "$@" } +# ── packaging ──────────────────────────────────────────────────────────────── + @test "bluefin-kubestellar exists and is executable" { [ -f "$SCRIPT" ] [ -x "$SCRIPT" ] } -@test "bluefin-kubestellar help displays usage options" { +# ── argument parsing ───────────────────────────────────────────────────────── + +@test "help displays usage options" { run "$SCRIPT" help [ "$status" -eq 0 ] [[ "$output" =~ "Usage:" ]] @@ -19,14 +101,306 @@ setup() { [[ "$output" =~ "--foreground" ]] } -@test "bluefin-kubestellar rejects unknown command" { +@test "-h and --help print usage without starting kc-agent" { + for flag in -h --help; do + run "$SCRIPT" "$flag" + [ "$status" -eq 0 ] + [[ "$output" =~ "Usage:" ]] + done + [ ! -f "$PID_FILE" ] +} + +@test "rejects unknown command" { run "$SCRIPT" invalid-cmd [ "$status" -ne 0 ] [[ "$output" =~ "Unknown option or command" ]] } -@test "bluefin-kubestellar status exits cleanly when agent is not running" { +@test "unknown option prints usage to stderr" { + run "$SCRIPT" --bogus + [ "$status" -eq 1 ] + [[ "$output" =~ "Unknown option or command: --bogus" ]] + [[ "$output" =~ "Usage:" ]] +} + +@test "--origin without a value is rejected" { + run "$SCRIPT" --origin + [ "$status" -eq 1 ] + [[ "$output" =~ "--origin requires an argument" ]] +} + +@test "--port without a value is rejected" { + run "$SCRIPT" --port + [ "$status" -eq 1 ] + [[ "$output" =~ "--port requires an argument" ]] +} + +@test "a bare http(s) URL is accepted as the origin" { + stub_kc_agent_foreground + run_isolated --foreground https://console.example.test:8080 + [ "$status" -eq 0 ] + [[ "$output" =~ "Allowed origins: https://console.example.test:8080" ]] +} + +@test "--origin= and -o select the same origin" { + stub_kc_agent_foreground + run_isolated --foreground --origin=http://a.test:8080,http://b.test:8080 + [ "$status" -eq 0 ] + [[ "$output" =~ "Allowed origins: http://a.test:8080,http://b.test:8080" ]] + + run_isolated --foreground -o http://a.test:8080,http://b.test:8080 + [ "$status" -eq 0 ] + [[ "$output" =~ "Allowed origins: http://a.test:8080,http://b.test:8080" ]] +} + +@test "a command word after options still selects the command" { + run "$SCRIPT" --port 9000 help + [ "$status" -eq 0 ] + [[ "$output" =~ "Usage:" ]] +} + +# ── start ──────────────────────────────────────────────────────────────────── + +@test "start defaults to the localhost console origins" { + stub_kc_agent_foreground + run_isolated --foreground + [ "$status" -eq 0 ] + [[ "$output" =~ "Allowed origins: http://localhost:8080,http://127.0.0.1:8080" ]] +} + +@test "foreground start execs kc-agent with -allowed-origins" { + stub_kc_agent_foreground + run_isolated -f --origin http://console.test:8080 + [ "$status" -eq 0 ] + grep -q -- "kc-agent -allowed-origins http://console.test:8080" "$STUB_LOG" +} + +@test "foreground start disables in-cluster Kagenti DNS by default" { + stub_kc_agent_foreground + run_isolated --foreground + [ "$status" -eq 0 ] + [[ "$output" =~ "KAGENTI_CONTROLLER_URL: none" ]] +} + +@test "an inherited KAGENTI_CONTROLLER_URL is preserved" { + stub_kc_agent_foreground + run env PATH="$STUB_BIN:/usr/bin:/bin" KAGENTI_CONTROLLER_URL=http://kagenti.test \ + "$SCRIPT" --foreground + [ "$status" -eq 0 ] + [[ "$output" =~ "KAGENTI_CONTROLLER_URL: http://kagenti.test" ]] +} + +@test "start is a no-op when the agent is already healthy" { + stub_curl_healthy + stub_kc_agent_running + run_isolated + [ "$status" -eq 0 ] + [[ "$output" =~ "already running and healthy" ]] + # The early exit must not spawn kc-agent. + ! grep -q "^kc-agent " "$STUB_LOG" +} + +@test "foreground start ignores the already-healthy short circuit" { + stub_curl_healthy + stub_kc_agent_foreground + run_isolated --foreground + [ "$status" -eq 0 ] + grep -q "^kc-agent " "$STUB_LOG" +} + +@test "the start health probe defaults to port 8585 and honours --port" { + stub_curl_healthy + run_isolated --port 9999 + [ "$status" -eq 0 ] + [[ "$output" =~ "http://127.0.0.1:9999/health" ]] + + run_isolated + [ "$status" -eq 0 ] + [[ "$output" =~ "http://127.0.0.1:8585/health" ]] +} + +@test "--no-install fails closed when kc-agent is missing" { + run_isolated --no-install + [ "$status" -eq 1 ] + [[ "$output" =~ "kc-agent is not installed and cannot be auto-installed" ]] + [[ "$output" =~ "brew tap kubestellar/tap" ]] +} + +@test "missing kc-agent is installed from kubestellar/tap via Homebrew" { + # brew install must materialize kc-agent for the run to proceed. + cat > "$STUB_BIN/brew" <<'EOF' +#!/usr/bin/env bash +echo "brew $*" >> "$STUB_LOG" +if [ "$1" = "install" ]; then + cat > "$(dirname "$0")/kc-agent" <<'AGENT' +#!/usr/bin/env bash +echo "kc-agent $*" >> "$STUB_LOG" +AGENT + chmod +x "$(dirname "$0")/kc-agent" +fi +EOF + chmod +x "$STUB_BIN/brew" + + run_isolated --foreground + [ "$status" -eq 0 ] + grep -q "brew tap kubestellar/tap" "$STUB_LOG" + grep -q "brew install kc-agent" "$STUB_LOG" + grep -q "^kc-agent " "$STUB_LOG" +} + +@test "background start records the PID and reports healthy" { + stub_kc_agent_running + stub_curl_healthy_after_first_probe + + run_isolated + [ "$status" -eq 0 ] + [[ "$output" =~ "kc-agent is healthy and connected" ]] + [ -f "$PID_FILE" ] + kill -0 "$(cat "$PID_FILE")" + kill "$(cat "$PID_FILE")" 2>/dev/null || true +} + +@test "background start writes kc-agent output to the log file" { + stub_kc_agent_running + stub_curl_healthy_after_first_probe + + run_isolated + [ "$status" -eq 0 ] + [ -f "$LOG_FILE" ] + [[ "$output" =~ "Log file: $LOG_FILE" ]] + kill "$(cat "$PID_FILE")" 2>/dev/null || true +} + +@test "a kc-agent that exits immediately fails the start and clears the PID file" { + stub_kc_agent_crashing + run_isolated + [ "$status" -eq 1 ] + [[ "$output" =~ "exited unexpectedly" ]] + [[ "$output" =~ "address already in use" ]] + [ ! -f "$PID_FILE" ] +} + +@test "background start replaces a live PID from a previous run" { + stub_kc_agent_running + stub_curl_healthy_after_first_probe + mkdir -p "$STATE_DIR" + sleep 30 & + OLD_PID=$! + echo "$OLD_PID" > "$PID_FILE" + + run_isolated + [ "$status" -eq 0 ] + NEW_PID="$(cat "$PID_FILE")" + [ "$NEW_PID" != "$OLD_PID" ] + kill "$NEW_PID" 2>/dev/null || true + # Final command: its status gates the test, so a surviving old process fails. + ! kill -0 "$OLD_PID" 2>/dev/null +} + +# ── stop ───────────────────────────────────────────────────────────────────── + +@test "stop reports when no PID file exists" { + run "$SCRIPT" stop + [ "$status" -eq 0 ] + [[ "$output" =~ "No active kc-agent PID file found" ]] +} + +@test "stop terminates a live agent and removes the PID file" { + mkdir -p "$STATE_DIR" + sleep 30 & + PID=$! + echo "$PID" > "$PID_FILE" + + run "$SCRIPT" stop + [ "$status" -eq 0 ] + [[ "$output" =~ "Stopped kc-agent (PID: $PID)" ]] + [ ! -f "$PID_FILE" ] + ! kill -0 "$PID" 2>/dev/null +} + +@test "stop clears a stale PID file without an error" { + mkdir -p "$STATE_DIR" + sleep 30 & + PID=$! + kill "$PID" 2>/dev/null || true + wait "$PID" 2>/dev/null || true + echo "$PID" > "$PID_FILE" + + run "$SCRIPT" stop + [ "$status" -eq 0 ] + [[ "$output" =~ "was not running" ]] + [ ! -f "$PID_FILE" ] +} + +# ── status ─────────────────────────────────────────────────────────────────── + +@test "status exits 3 when nothing is running" { + run "$SCRIPT" status + [ "$status" -eq 3 ] + [[ "$output" =~ "kc-agent is not running" ]] +} + +@test "status exits 0 and reports the PID when the health probe succeeds" { + stub_curl_healthy + mkdir -p "$STATE_DIR" + echo 4242 > "$PID_FILE" + + run "$SCRIPT" status + [ "$status" -eq 0 ] + [[ "$output" =~ "running and healthy" ]] + [[ "$output" =~ "Process PID: 4242" ]] +} + +@test "status probes the health endpoint on --port" { + stub_curl_healthy + run "$SCRIPT" status --port 9100 + [ "$status" -eq 0 ] + [[ "$output" =~ "http://127.0.0.1:9100/health" ]] +} + +@test "status exits 1 when the process is alive but unhealthy" { + mkdir -p "$STATE_DIR" + sleep 30 & + PID=$! + echo "$PID" > "$PID_FILE" + + run "$SCRIPT" status + [ "$status" -eq 1 ] + [[ "$output" =~ "is running but" ]] + [[ "$output" =~ "not responding" ]] + kill "$PID" 2>/dev/null || true +} + +@test "status exits 3 for a stale PID file with no live process" { + mkdir -p "$STATE_DIR" + sleep 30 & + PID=$! + kill "$PID" 2>/dev/null || true + wait "$PID" 2>/dev/null || true + echo "$PID" > "$PID_FILE" + run "$SCRIPT" status - # Exit code 3 signifies not running - [ "$status" -eq 3 ] || [ "$status" -eq 0 ] + [ "$status" -eq 3 ] + [[ "$output" =~ "kc-agent is not running" ]] +} + +# ── logs ───────────────────────────────────────────────────────────────────── + +@test "logs reports the missing log file path" { + run "$SCRIPT" logs + [ "$status" -eq 0 ] + [[ "$output" =~ "No log file found at" ]] + [[ "$output" =~ "kc-agent.log" ]] +} + +@test "logs prints the tail of the log file" { + mkdir -p "$STATE_DIR" + for i in $(seq 1 60); do echo "line $i" >> "$LOG_FILE"; done + + run "$SCRIPT" logs + [ "$status" -eq 0 ] + [[ "$output" =~ "line 60" ]] + [[ "$output" =~ "line 11" ]] + # Only the last 50 lines are shown. + [[ ! "$output" =~ "line 10" ]] } From 547f5f7756ef0212f795a1ebacb85c0f318c28eb Mon Sep 17 00:00:00 2001 From: Kyle Rankin Date: Sun, 20 Sep 2026 03:00:05 -0700 Subject: [PATCH 18/42] test(build-depends): lock in os-countme curl+jq FSDK paths (#122) Assisted-by: Claude Opus 4.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- tests/unit/test_build_depends.py | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/tests/unit/test_build_depends.py b/tests/unit/test_build_depends.py index b2aa04ee..4cc86f2c 100644 --- a/tests/unit/test_build_depends.py +++ b/tests/unit/test_build_depends.py @@ -117,6 +117,30 @@ def test_installer_stack_includes_uutils_and_dbus(): ) +def test_os_countme_depends_on_curl_and_jq(): + """os-countme.bst must ship curl and jq through the freedesktop-sdk junction. + + Regression test for projectbluefin/server#96: the curl dependency was + inferred rather than verified, so a wrong path would fail to resolve and + the minimal image (which ships neither curl nor jq) would not build. + Confirmed that the pinned freedesktop-sdk ref (freedesktop-sdk-26.08.0, + elements/freedesktop-sdk.bst) ships both elements/components/curl.bst and + elements/components/jq.bst, so the dependency must stay on this exact path. + """ + countme = ELEMENTS_DIR / "bluefin-server" / "os-countme.bst" + data = yaml.safe_load(countme.read_text(encoding="utf-8")) + depends = data.get("depends", []) + + assert "freedesktop-sdk.bst:components/curl.bst" in depends, ( + "os-countme.bst must include freedesktop-sdk.bst:components/curl.bst " + "(projectbluefin/server#96)" + ) + assert "freedesktop-sdk.bst:components/jq.bst" in depends, ( + "os-countme.bst must include freedesktop-sdk.bst:components/jq.bst " + "(projectbluefin/server#96)" + ) + + def test_os_stack_includes_bash(): """Bluefin Server OS must include bash for login and interactive access.""" os_stack = ELEMENTS_DIR / "bluefin-server" / "os-stack.bst" From 115c0da780f2986953eb87eb351ba85dd59d6c44 Mon Sep 17 00:00:00 2001 From: "kubestellar-hive[bot]" <280983584+kubestellar-hive[bot]@users.noreply.github.com> Date: Sun, 20 Sep 2026 06:01:15 -0400 Subject: [PATCH 19/42] =?UTF-8?q?test:=20files/=20payload=20reachability?= =?UTF-8?q?=20gate=20=E2=80=94=20tests/unit/test=5Ffiles=5Fpayload=5Freach?= =?UTF-8?q?ability.py=20(#155)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Assisted-by: Claude Opus 4.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- tests/unit/test_files_payload_reachability.py | 180 ++++++++++++++++++ 1 file changed, 180 insertions(+) create mode 100644 tests/unit/test_files_payload_reachability.py diff --git a/tests/unit/test_files_payload_reachability.py b/tests/unit/test_files_payload_reachability.py new file mode 100644 index 00000000..2423587a --- /dev/null +++ b/tests/unit/test_files_payload_reachability.py @@ -0,0 +1,180 @@ +"""Drift gate: every path under ``files/`` is image payload or declared host tooling. + +``files/`` is the repository's image-payload tree. A file only reaches an image +if some element stages it with a ``kind: local`` source, e.g.:: + + sources: + - kind: local + path: files/os/sysupdate.d + +Nothing else pulls ``files/`` into the build graph, so a directory that no +element names is invisible to ``just validate`` (which only runs +``bst show --deps all`` on the three OCI targets) and to the image build. It is +also invisible to the unit suite, because bats tests execute helper scripts +straight out of the checkout whether or not they ship. + +That gap is not hypothetical: ``files/bin/system-container`` is documented in +``docs/skills/system-containers.md`` as "shipped in the OS image" at +``/usr/bin/system-container`` and has bats coverage, yet no element stages it — +see issue #154. + +This module enforces both directions of the contract: + +* every ``path:`` an element declares still exists on disk, so renaming a + payload directory cannot silently drop it out of the image; and +* every file under ``files/`` is staged, or is declared host-side tooling, or is + an explicitly recorded waiver. + +Staging is matched by declaration, not by graph reachability: a path named by an +element that no OCI target depends on still counts as staged here. + +``KNOWN_UNSTAGED`` is shrink-only: staging a waived path fails the gate until +the waiver is deleted, so the record cannot outlive the bug it describes. +""" + +from pathlib import Path + +import pytest +import yaml + +ROOT = Path(__file__).resolve().parents[2] +ELEMENTS_DIR = ROOT / "elements" +FILES_DIR = ROOT / "files" + +# Paths under files/ that are host-side tooling, executed from a repository +# checkout and deliberately absent from every image. +HOST_TOOLING = { + # Host developer CLI: Justfile `install-vm` and + # scripts/lima-e2e-kubestellar-test.sh run it from the checkout. + "files/bin/bluefin-kubestellar", + # limactl VM template consumed by Justfile `test-e2e-lima`. + "files/lima", +} + +# Payload that claims to ship but is staged by no element. Each entry must name +# the issue tracking its resolution. Shrink this set; never grow it. +KNOWN_UNSTAGED = { + # docs/skills/system-containers.md promises /usr/bin/system-container in the + # OS image. No element stages it. Tracked by issue #154 — fixing that issue + # (staging it, or correcting the docs) must remove this entry. + "files/bin/system-container", +} + + +def _element_files(): + return sorted(ELEMENTS_DIR.rglob("*.bst")) + + +def _local_source_paths(document): + """Yield every ``path:`` of a ``kind: local`` source in a parsed element.""" + if not isinstance(document, dict): + return + for source in document.get("sources") or []: + if isinstance(source, dict) and source.get("kind") == "local": + path = source.get("path") + if isinstance(path, str): + yield path + + +def _declared_paths(): + """Map each declared ``kind: local`` path to the elements declaring it.""" + declared = {} + for element in _element_files(): + document = yaml.safe_load(element.read_text()) + for path in _local_source_paths(document): + rel = element.relative_to(ROOT).as_posix() + declared.setdefault(path.rstrip("/"), []).append(rel) + return declared + + +def _staged_paths(): + """Declared paths that live under ``files/``, as repo-relative strings.""" + return {path for path in _declared_paths() if path == "files" or path.startswith("files/")} + + +def _is_staged(rel_path, staged): + """True when ``rel_path`` is a declared path or sits under one.""" + candidate = Path(rel_path) + return any( + candidate == Path(path) or Path(path) in candidate.parents for path in staged + ) + + +def _is_host_tooling(rel_path): + candidate = Path(rel_path) + return any( + candidate == Path(path) or Path(path) in candidate.parents + for path in HOST_TOOLING + ) + + +def _payload_files(): + return sorted( + p.relative_to(ROOT).as_posix() for p in FILES_DIR.rglob("*") if p.is_file() + ) + + +def test_at_least_one_element_stages_payload(): + """Guards the gate itself: a parser regression must not silently pass.""" + staged = _staged_paths() + assert staged, ( + "no element declares a kind: local source under files/ — either the " + "payload wiring was removed or this gate stopped parsing elements" + ) + + +@pytest.mark.parametrize("declared", sorted(_declared_paths())) +def test_declared_source_paths_exist(declared): + """A stale ``path:`` silently drops payload out of the image.""" + owners = ", ".join(_declared_paths()[declared]) + assert (ROOT / declared).exists(), ( + f"{owners} declares a kind: local source path that does not exist: " + f"{declared}. Renaming payload requires updating the element that " + f"stages it." + ) + + +def test_every_payload_file_is_staged_or_declared(): + """No file under files/ may be unreachable without an explicit declaration.""" + staged = _staged_paths() + orphans = [ + rel + for rel in _payload_files() + if not _is_staged(rel, staged) + and not _is_host_tooling(rel) + and rel not in KNOWN_UNSTAGED + ] + assert not orphans, ( + "files/ paths reach no image and are not declared host tooling:\n " + + "\n ".join(orphans) + + "\n\nStage them with a kind: local source on an element that " + "os-stack.bst, installer-stack.bst, or an oci/ target depends on; or " + "add them to HOST_TOOLING if they are host-side only." + ) + + +def test_host_tooling_declarations_are_not_stale(): + staged = _staged_paths() + for declared in sorted(HOST_TOOLING): + assert (ROOT / declared).exists(), ( + f"HOST_TOOLING names {declared}, which no longer exists — drop the " + f"declaration." + ) + assert not _is_staged(declared, staged), ( + f"{declared} is declared host tooling but an element now stages it " + f"into an image. Remove it from HOST_TOOLING." + ) + + +def test_known_unstaged_waivers_are_still_unstaged(): + """Shrink-only: a waiver must be deleted once the path actually ships.""" + staged = _staged_paths() + for waived in sorted(KNOWN_UNSTAGED): + assert (ROOT / waived).exists(), ( + f"KNOWN_UNSTAGED names {waived}, which no longer exists — drop the " + f"waiver." + ) + assert not _is_staged(waived, staged), ( + f"{waived} is now staged by an element. Remove it from " + f"KNOWN_UNSTAGED so the gate protects it." + ) From fc1d16418fc697ae2ba35114b91933e854db8db3 Mon Sep 17 00:00:00 2001 From: Bob Killen Date: Sun, 20 Sep 2026 05:01:59 -0500 Subject: [PATCH 20/42] feat(arch): produce Flatcar-to-FSDK version parity matrix (#142) (#184) Assisted-by: Claude Opus 4.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- AGENTS.md | 1 + docs/skills/flatcar-parity-matrix.md | 83 +++ docs/skills/index.md | 1 + scripts/generate-parity-matrix.py | 657 ++++++++++++++++++++++ tests/unit/test_generate_parity_matrix.py | 165 ++++++ 5 files changed, 907 insertions(+) create mode 100644 docs/skills/flatcar-parity-matrix.md create mode 100755 scripts/generate-parity-matrix.py create mode 100644 tests/unit/test_generate_parity_matrix.py diff --git a/AGENTS.md b/AGENTS.md index 458fbf36..a79d0de0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -59,6 +59,7 @@ All local `just` targets run BuildStream inside the FSDK `bst2` container via `j | Work with `systemd-sysext` / `systemd-confext` | [`docs/skills/systemd-sysext-extensions.md`](docs/skills/systemd-sysext-extensions.md) | | Build or ship the k0s sysext | [`docs/skills/k0s-sysext.md`](docs/skills/k0s-sysext.md), [`docs/skills/k0s-sysext-ops.md`](docs/skills/k0s-sysext-ops.md) | | Update the FSDK pin / versioning | [`docs/skills/bump-fsdk-version.md`](docs/skills/bump-fsdk-version.md) | +| Flatcar version parity matrix / audit | [`docs/skills/flatcar-parity-matrix.md`](docs/skills/flatcar-parity-matrix.md) | | CI workflows, action SHA pinning | [`docs/skills/ci-tooling.md`](docs/skills/ci-tooling.md) | | Release signing / sysupdate trust | [`docs/skills/systemd-sysupdate-verification.md`](docs/skills/systemd-sysupdate-verification.md) | | Credential sealing with TPM2 | [`docs/skills/tpm2-credential-sealing.md`](docs/skills/tpm2-credential-sealing.md) | diff --git a/docs/skills/flatcar-parity-matrix.md b/docs/skills/flatcar-parity-matrix.md new file mode 100644 index 00000000..dc89c42e --- /dev/null +++ b/docs/skills/flatcar-parity-matrix.md @@ -0,0 +1,83 @@ +--- +name: flatcar-parity-matrix +description: | + Flatcar-to-FSDK version parity matrix for Bluefin Server (issue #142). Tracks component + versions, gaps, element paths, and substitution order against Flatcar 4593.2.5. +metadata: + type: reference + status: stable + last_updated: "2026-09-18" +--- +# Flatcar-to-FSDK Parity Matrix + +**Flatcar 4593.2.5 vs freedesktop-sdk 26.08 — version audit (design phase 2, issue #142).** Generated by `scripts/generate-parity-matrix.py` from pinned upstream release artifacts; do not edit by hand — re-run the generator. + +| Component | Flatcar version | FSDK 26.08 version | Gap | Element path | Ordering | +|---|---|---|---|---|---| +| glibc | 2.41-r6 | 2.44-23 | fsdk-newer | `bootstrap/glibc.bst` | load-bearing | +| kernel | 4593.2.5 (6.12.102-flatcar) | n/a | n/a | `flatcar/flatcar-kernel.bst` | load-bearing | +| systemd | 257.9 | 261.2 | fsdk-newer | `components/systemd.bst` | load-bearing | +| bash | 5.3_p3-r3 | 5.3-16 | none | `bootstrap/bash.bst` | important | +| coreutils | 9.8-r1 | 9.11 | fsdk-newer | `bootstrap/coreutils.bst` | important | +| curl | 8.16.0-r1 | 8.21.0 | fsdk-newer | `components/curl.bst` | important | +| dbus | 1.16.2 | 1.16.2 | none | `components/dbus.bst` | important | +| glib | 2.84.4 | 2.88.3 | fsdk-newer | `components/glib.bst` | important | +| gnupg | 2.5.16 | 2.4.9 | flatcar-newer | `components/gnupg.bst` | important | +| kmod | 34.2 | 34.2 | none | `components/kmod.bst` | important | +| libcap | 2.76 | 2.78 | fsdk-newer | `components/libcap.bst` | important | +| libffi | 3.5.2 | 3.8.0 | fsdk-newer | `components/libffi.bst` | important | +| openssh | 10.4_p1-r1 | 10.5.P1 | fsdk-newer | `components/openssh.bst` | important | +| openssl | 3.5.5 | 3.5.8 | fsdk-newer | `components/openssl.bst` | important | +| shadow | 4.14.8-r1 | 4.20.2 | fsdk-newer | `components/shadow.bst` | important | +| util-linux | 2.41.2 | 2.42.2 | fsdk-newer | `components/util-linux.bst` | important | +| zstd | 1.5.7-r1 | 1.5.7 | none | `components/zstd.bst` | important | +| ca-certificates | 3.126 | 2010.63-3.fc14-175 | different-scheme | `components/ca-certificates.bst` | deferred | +| podman | 5.5.2 | 6.1.0 | fsdk-newer | `components/podman.bst` | deferred | +| xfsprogs | 6.16.0 | 7.1.1 | fsdk-newer | `components/xfsprogs.bst` | deferred | + +## Gap Definitions + +- `none` — FSDK already pins Flatcar's upstream version; no substitution required. +- `fsdk-newer` — FSDK pins a newer upstream release than Flatcar; substitute by pinning or backporting the Flatcar version in FSDK elements. +- `flatcar-newer` — Flatcar pins a newer upstream release than FSDK. +- `different-scheme` — Component version strings follow different packaging schemes and cannot be ordered numerically (e.g. Mozilla NSS certdata vs Fedora RPM). +- `n/a` — FSDK does not provide this component; imported whole as a reference. + +## Ordering Guidance + +- **load-bearing** — Boot-critical components (glibc, kernel, systemd). Must be substituted first because all subsequent layers depend on them. +- **important** — Base userspace runtime and installer dependencies (bash, coreutils, curl, dbus, glib, gnupg, kmod, libcap, libffi, openssh, openssl, shadow, util-linux, zstd). +- **deferred** — Optional payloads, sysext extensions, or filesystem utilities (ca-certificates, podman, xfsprogs). + +## Source Citations + +- Flatcar release 4593.2.5 artifacts fetched from `https://flatcar.cdn.cncf.io/stable/amd64-usr/4593.2.5/` with SHA256 checksums pinned in `scripts/generate-parity-matrix.py`: + - `version.txt` (`6e86c457...`): release identifier and build ID. + - `flatcar_production_image_packages.txt` (`58a43787...`): installed Portage atoms and versions. + - `flatcar-podman_packages.txt` (`befde0ac...`): container runtime sysext packages. +- FSDK 26.08 source elements: pinned junction ref `freedesktop-sdk-26.08.0` in `elements/freedesktop-sdk.bst`. + +## Downstream Substitution Tickets + +The following substitution tickets are derived directly from the matrix ordering: + +1. **Load-bearing (phase 6a)** + - `subst(kernel)`: reference import `flatcar/flatcar-kernel.bst` (6.12.102-flatcar) + - `subst(glibc)`: pin glibc 2.41 in `bootstrap/glibc.bst` + - `subst(systemd)`: pin systemd 257 in `components/systemd.bst` +2. **Important base userspace (phase 6b)** + - `subst(coreutils)`: pin coreutils 9.8 in `bootstrap/coreutils.bst` + - `subst(curl)`: pin curl 8.16.0 in `components/curl.bst` + - `subst(glib)`: pin glib 2.84.4 in `components/glib.bst` + - `subst(gnupg)`: pin gnupg 2.5.16 in `components/gnupg.bst` + - `subst(libcap)`: pin libcap 2.76 in `components/libcap.bst` + - `subst(libffi)`: pin libffi 3.5.2 in `components/libffi.bst` + - `subst(openssh)`: pin openssh 10.4 in `components/openssh.bst` + - `subst(openssl)`: pin openssl 3.5.5 in `components/openssl.bst` + - `subst(shadow)`: pin shadow 4.14.8 in `components/shadow.bst` + - `subst(util-linux)`: pin util-linux 2.41.2 in `components/util-linux.bst` + - Version matches (verification only): `bash` (5.3), `dbus` (1.16.2), `kmod` (34.2), `zstd` (1.5.7) +3. **Deferred (phase 6c)** + - `subst(ca-certificates)`: evaluate NSS certdata 3.126 vs Fedora packaging + - `subst(podman)`: delivery via sysext matching Flatcar podman 5.5.2 + - `subst(xfsprogs)`: pin xfsprogs 6.16.0 in `components/xfsprogs.bst` diff --git a/docs/skills/index.md b/docs/skills/index.md index 02c5b0a3..c9322b90 100644 --- a/docs/skills/index.md +++ b/docs/skills/index.md @@ -29,6 +29,7 @@ This is the lazy-load routing table for agent skills. Keep this file in memory w | [`ddi-installer-build.md`](ddi-installer-build.md) | Building the installer or DDI on the cluster | Cluster build pipeline and local installer/DDI build. | | [`ddi-installer.md`](ddi-installer.md) | Installer boot flow, `systemd-sysinstall`, `systemd-repart` | High-level DDI install architecture and local smoke test. | | [`factory-integration.md`](factory-integration.md) | Lab integration, boot-test workflow, factory role | How Bluefin Server is consumed by the CI lab. | +| [`flatcar-parity-matrix.md`](flatcar-parity-matrix.md) | Flatcar version audit, component parity, substitution order | Version parity matrix and gap audit against Flatcar 4593.2.5. | | [`gap-analysis-distros.md`](gap-analysis-distros.md) | Comparing Bluefin Server to other server OSes | Source-verified comparison to Ubuntu, Talos, Flatcar, FCOS. | | [`k0s-sysext-ops.md`](k0s-sysext-ops.md) | Operating k0s on Bluefin Server | Runtime operation and reboot coordination for k0s. | | [`k0s-sysext.md`](k0s-sysext.md) | Building the k0s sysext | BuildStream element and publish steps for the k0s sysext. | diff --git a/scripts/generate-parity-matrix.py b/scripts/generate-parity-matrix.py new file mode 100755 index 00000000..47cc179c --- /dev/null +++ b/scripts/generate-parity-matrix.py @@ -0,0 +1,657 @@ +#!/usr/bin/env python3 +"""Generate the Flatcar-to-FSDK version parity matrix (issue #142). + +Bluefin Server composes its OS payload from freedesktop-sdk 26.08 components +while its kernel and reference binaries derive from Flatcar Container Linux +(pinned at 4593.2.5 in include/flatcar.yml). Phase 2 of the Flatcar version +parity design (issue #142) requires an authoritative parity matrix: for each +in-scope component, record what version Flatcar ships, what version FSDK 26.08 +pins, the version gap, and substitution priority. + +This script generates that matrix into docs/skills/flatcar-parity-matrix.md +from pinned upstream artifacts: + - version.txt (FLATCAR_VERSION and build ID) + - flatcar_production_image_packages.txt (base system portage atoms and versions) + - flatcar-podman_packages.txt (Flatcar podman sysext package atom and version) + - elements/freedesktop-sdk.bst (junction ref to FSDK 26.08) + +To ensure reproducibility without committing large vendored binaries, upstream +artifacts are verified against pinned SHA256 checksums and cached in +.cache/flatcar// (which is gitignored). +""" + +import argparse +import hashlib +import json +import re +import sys +import urllib.request +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +FLATCAR_INCLUDE = ROOT / "include" / "flatcar.yml" +FSDK_JUNCTION = ROOT / "elements" / "freedesktop-sdk.bst" +DEFAULT_OUTPUT = ROOT / "docs" / "skills" / "flatcar-parity-matrix.md" +DEFAULT_CACHE_DIR = ROOT / ".cache" / "flatcar" + +FLATCAR_BASE_URL = "https://flatcar.cdn.cncf.io/stable" + +# Pinned SHA256 checksums for upstream Flatcar 4593.2.5 artifacts. +PINNED_ARTIFACTS = { + "4593.2.5": { + "amd64-usr": { + "version.txt": "6e86c457e9c3a622bbf1bd91874d16b121585fbec01813275c031ff52bbd227c", + "flatcar_production_image_packages.txt": "58a437870d44c9bef66cc7b8186859de0071a9286a896535fff8e8e908aaedc2", + "flatcar-podman_packages.txt": "befde0acac87cc8e6e24b4c1863e0ef03d689bbf6d2900b93bbc9f0a766ad7b1", + } + } +} + +# The components in scope for the OS payload substitution audit. +# Derived from the design document ("Overlay: what Flatcar displaces" + version anchors). +IN_SCOPE_COMPONENTS = [ + { + "component": "glibc", + "atom": "sys-libs/glibc", + "fsdk_version": "2.44-23", + "fsdk_element": "bootstrap/glibc.bst", + "fsdk_source": "bootstrap/glibc-source.yml", + "priority": "load-bearing", + }, + { + "component": "kernel", + "atom": None, + "fsdk_version": "n/a", + "fsdk_element": "flatcar/flatcar-kernel.bst", + "fsdk_source": "imported, not FSDK-built", + "priority": "load-bearing", + }, + { + "component": "systemd", + "atom": "sys-apps/systemd", + "fsdk_version": "261.2", + "fsdk_element": "components/systemd.bst", + "fsdk_source": "include/systemd.yml", + "priority": "load-bearing", + }, + { + "component": "bash", + "atom": "app-shells/bash", + "fsdk_version": "5.3-16", + "fsdk_element": "bootstrap/bash.bst", + "fsdk_source": "bootstrap/bash-source.yml", + "priority": "important", + }, + { + "component": "coreutils", + "atom": "sys-apps/coreutils", + "fsdk_version": "9.11", + "fsdk_element": "bootstrap/coreutils.bst", + "fsdk_source": "bootstrap/coreutils-source.yml", + "priority": "important", + }, + { + "component": "curl", + "atom": "net-misc/curl", + "fsdk_version": "8.21.0", + "fsdk_element": "components/curl.bst", + "fsdk_source": "components/curl.bst", + "priority": "important", + }, + { + "component": "dbus", + "atom": "sys-apps/dbus", + "fsdk_version": "1.16.2", + "fsdk_element": "components/dbus.bst", + "fsdk_source": "components/dbus.bst", + "priority": "important", + }, + { + "component": "glib", + "atom": "dev-libs/glib", + "fsdk_version": "2.88.3", + "fsdk_element": "components/glib.bst", + "fsdk_source": "components/glib.bst", + "priority": "important", + }, + { + "component": "gnupg", + "atom": "app-crypt/gnupg", + "fsdk_version": "2.4.9", + "fsdk_element": "components/gnupg.bst", + "fsdk_source": "components/gnupg.bst", + "priority": "important", + }, + { + "component": "kmod", + "atom": "sys-apps/kmod", + "fsdk_version": "34.2", + "fsdk_element": "components/kmod.bst", + "fsdk_source": "components/kmod.bst", + "priority": "important", + }, + { + "component": "libcap", + "atom": "sys-libs/libcap", + "fsdk_version": "2.78", + "fsdk_element": "components/libcap.bst", + "fsdk_source": "components/libcap.bst", + "priority": "important", + }, + { + "component": "libffi", + "atom": "dev-libs/libffi", + "fsdk_version": "3.8.0", + "fsdk_element": "components/libffi.bst", + "fsdk_source": "components/libffi.bst", + "priority": "important", + }, + { + "component": "openssh", + "atom": "net-misc/openssh", + "fsdk_version": "10.5.P1", + "fsdk_element": "components/openssh.bst", + "fsdk_source": "components/openssh.bst", + "priority": "important", + }, + { + "component": "openssl", + "atom": "dev-libs/openssl", + "fsdk_version": "3.5.8", + "fsdk_element": "components/openssl.bst", + "fsdk_source": "components/openssl.bst", + "priority": "important", + }, + { + "component": "shadow", + "atom": "sys-apps/shadow", + "fsdk_version": "4.20.2", + "fsdk_element": "components/shadow.bst", + "fsdk_source": "components/shadow.bst", + "priority": "important", + }, + { + "component": "util-linux", + "atom": "sys-apps/util-linux", + "fsdk_version": "2.42.2", + "fsdk_element": "components/util-linux.bst", + "fsdk_source": "components/util-linux.bst", + "priority": "important", + }, + { + "component": "zstd", + "atom": "app-arch/zstd", + "fsdk_version": "1.5.7", + "fsdk_element": "components/zstd.bst", + "fsdk_source": "components/zstd.bst", + "priority": "important", + }, + { + "component": "ca-certificates", + "atom": "app-misc/ca-certificates", + "fsdk_version": "2010.63-3.fc14-175", + "fsdk_element": "components/ca-certificates.bst", + "fsdk_source": "components/ca-certificates.bst", + "priority": "deferred", + "gap_override": "different-scheme", + }, + { + "component": "podman", + "atom": "app-containers/podman", + "fsdk_version": "6.1.0", + "fsdk_element": "components/podman.bst", + "fsdk_source": "components/podman.bst", + "priority": "deferred", + "sysext": "flatcar-podman.raw", + }, + { + "component": "xfsprogs", + "atom": "sys-fs/xfsprogs", + "fsdk_version": "7.1.1", + "fsdk_element": "components/xfsprogs.bst", + "fsdk_source": "components/xfsprogs.bst", + "priority": "deferred", + }, +] + +PRIORITY_ORDER = {"load-bearing": 0, "important": 1, "deferred": 2} + + +def read_text(path): + if not path.is_file(): + sys.exit(f"ERROR: expected file not found: {path}") + return path.read_text(encoding="utf-8") + + +def get_flatcar_pinned_version(): + """Read flatcar-version from include/flatcar.yml.""" + content = read_text(FLATCAR_INCLUDE) + match = re.search(r"^\s*flatcar-version:\s*[\"']?([0-9.]+)[\"']?\s*$", content, re.MULTILINE) + if not match: + sys.exit("ERROR: include/flatcar.yml does not declare 'flatcar-version:'") + return match.group(1) + + +def get_flatcar_pinned_kver(): + """Read flatcar-kver from include/flatcar.yml.""" + content = read_text(FLATCAR_INCLUDE) + match = re.search(r"^\s*flatcar-kver:\s*[\"']?([^\s\"']+)[\"']?\s*$", content, re.MULTILINE) + if not match: + sys.exit("ERROR: include/flatcar.yml does not declare 'flatcar-kver:'") + return match.group(1) + + +def check_fsdk_junction_ref(): + """Verify that elements/freedesktop-sdk.bst pins freedesktop-sdk-26.08.*.""" + content = read_text(FSDK_JUNCTION) + match = re.search(r"freedesktop-sdk-(26\.08\.[0-9]+)", content) + if not match: + sys.exit("ERROR: elements/freedesktop-sdk.bst does not pin freedesktop-sdk-26.08.*") + return match.group(1) + + +def verify_sha256(data, expected_sha): + actual = hashlib.sha256(data).hexdigest() + return actual == expected_sha, actual + + +def fetch_or_load_artifact(filename, expected_sha, cache_dir, version, board="amd64-usr"): + """Load artifact from cache or fetch from Flatcar CDN if missing/checksum mismatch.""" + path = cache_dir / filename + if path.is_file(): + valid, _ = verify_sha256(path.read_bytes(), expected_sha) + if valid: + return path.read_text(encoding="utf-8") + + # Download from CDN + url = f"{FLATCAR_BASE_URL}/{board}/{version}/{filename}" + req = urllib.request.Request(url, headers={"User-Agent": "curl/7.88.1 (bluefin-server parity generator)"}) + try: + with urllib.request.urlopen(req) as resp: + data = resp.read() + except Exception as exc: + sys.exit(f"ERROR: failed to fetch {url}: {exc}") + + valid, actual_sha = verify_sha256(data, expected_sha) + if not valid: + sys.exit( + f"ERROR: checksum mismatch for {filename} from {url}:\n" + f" expected: {expected_sha}\n" + f" got : {actual_sha}" + ) + + cache_dir.mkdir(parents=True, exist_ok=True) + path.write_bytes(data) + return data.decode("utf-8") + + +def parse_packages_manifest(content): + """Parse flatcar_production_image_packages.txt (or sysext packages file).""" + packages = {} + pattern = re.compile(r"^([a-z0-9+._-]+/[a-z0-9+._-]+?)-([0-9]+.*)$") + for line in content.splitlines(): + line = line.strip() + if not line or line.startswith("#"): + continue + pkg_part = line.split("::")[0].strip() + m = pattern.match(pkg_part) + if m: + atom = m.group(1) + version = m.group(2) + packages[atom] = version + return packages + + +def parse_spdx_sbom(content): + """Parse SPDX SBOM JSON if present, returning {atom: version}.""" + sbom = json.loads(content) + packages = {} + for pkg in sbom.get("packages", []): + locator = "" + for ref in pkg.get("externalRefs", []) or []: + ref_loc = (ref.get("externalReference") or ref).get("referenceLocator", "") + if ref_loc.startswith("pkg:gentoo/"): + locator = ref_loc[len("pkg:gentoo/"):] + break + atom = locator.split("@")[0] if locator else pkg.get("name", "") + version = pkg.get("versionInfo") + if atom and version: + packages[atom] = version + return packages + + +def parse_version_prefix(text): + """Extract numeric components for version comparison.""" + if not text: + return None + s = re.sub(r"[-_](?:r|p|pre|rc|beta|alpha|post)\d*", ".", text, flags=re.I) + m = re.match(r"\s*([0-9]+(?:\.[0-9]+)*)", s) + if not m: + return None + return [int(x) for x in m.group(1).split(".")] + + +def compare_versions(v_fcar, v_fsdk): + """Compare Flatcar version against FSDK version. + + Returns -1 if v_fcar < v_fsdk (fsdk is newer), + 0 if equal (none), + 1 if v_fcar > v_fsdk (flatcar is newer), + None if uncomparable. + """ + if not v_fcar or not v_fsdk: + return None + p_fcar = parse_version_prefix(v_fcar) + p_fsdk = parse_version_prefix(v_fsdk) + if p_fcar is None or p_fsdk is None: + return None + max_len = max(len(p_fcar), len(p_fsdk)) + p_fcar += [0] * (max_len - len(p_fcar)) + p_fsdk += [0] * (max_len - len(p_fsdk)) + if p_fcar == p_fsdk: + return 0 + return -1 if p_fcar < p_fsdk else 1 + + +def compute_gap(component_spec, flatcar_ver, fsdk_ver): + """Calculate the version gap between Flatcar and FSDK.""" + if "gap_override" in component_spec: + return component_spec["gap_override"] + if fsdk_ver == "n/a" or flatcar_ver == "n/a": + return "n/a" + cmp_res = compare_versions(flatcar_ver, fsdk_ver) + if cmp_res is None: + return "different-scheme" + if cmp_res == 0: + return "none" + return "fsdk-newer" if cmp_res < 0 else "flatcar-newer" + + +def collect_flatcar_versions(flatcar_dir=None, flatcar_version="4593.2.5", board="amd64-usr"): + """Load package versions from flatcar_dir or download via CDN with SHA256 pin verification.""" + packages = {} + sources = {} + + if flatcar_dir and Path(flatcar_dir).is_dir(): + d = Path(flatcar_dir) + # Check for version.txt + v_files = sorted(d.glob("**/version.txt")) + if not v_files: + sys.exit(f"ERROR: no version.txt found in {flatcar_dir}") + v_txt = read_text(v_files[0]) + m = re.search(r"FLATCAR_VERSION=([0-9.]+)", v_txt) + if m: + flatcar_version = m.group(1) + + # Check for SBOM + sbom_files = sorted(d.glob("**/flatcar_production_image_sbom.json")) + if sbom_files: + sbom_pkgs = parse_spdx_sbom(read_text(sbom_files[0])) + packages.update(sbom_pkgs) + for atom in sbom_pkgs: + sources[atom] = "flatcar_production_image_sbom.json" + + # Check for packages manifest + pkg_files = sorted(d.glob("**/flatcar_production_image_packages.txt")) + if pkg_files: + manifest_pkgs = parse_packages_manifest(read_text(pkg_files[0])) + for atom, ver in manifest_pkgs.items(): + if atom not in packages: + packages[atom] = ver + sources[atom] = "flatcar_production_image_packages.txt" + + # Check for podman packages + podman_pkg_files = sorted(d.glob("**/flatcar-podman_packages.txt")) + if podman_pkg_files: + podman_pkgs = parse_packages_manifest(read_text(podman_pkg_files[0])) + for atom, ver in podman_pkgs.items(): + packages[atom] = ver + sources[atom] = "flatcar-podman_packages.txt" + + return flatcar_version, packages, sources + + # Cache / CDN fetch path + cache_dir = DEFAULT_CACHE_DIR / flatcar_version + pins = PINNED_ARTIFACTS.get(flatcar_version, {}).get(board, {}) + if not pins: + sys.exit(f"ERROR: no pinned artifacts for Flatcar {flatcar_version} ({board})") + + # Fetch version.txt + v_txt = fetch_or_load_artifact("version.txt", pins["version.txt"], cache_dir, flatcar_version, board) + m = re.search(r"FLATCAR_VERSION=([0-9.]+)", v_txt) + if m: + flatcar_version = m.group(1) + + # Fetch base packages manifest + pkg_txt = fetch_or_load_artifact( + "flatcar_production_image_packages.txt", + pins["flatcar_production_image_packages.txt"], + cache_dir, + flatcar_version, + board, + ) + manifest_pkgs = parse_packages_manifest(pkg_txt) + for atom, ver in manifest_pkgs.items(): + packages[atom] = ver + sources[atom] = "flatcar_production_image_packages.txt" + + # Fetch podman packages manifest + podman_txt = fetch_or_load_artifact( + "flatcar-podman_packages.txt", + pins["flatcar-podman_packages.txt"], + cache_dir, + flatcar_version, + board, + ) + podman_pkgs = parse_packages_manifest(podman_txt) + for atom, ver in podman_pkgs.items(): + packages[atom] = ver + sources[atom] = "flatcar-podman_packages.txt" + + return flatcar_version, packages, sources + + +def clean_ticket_version(comp, v): + """Normalize version string for downstream ticket description.""" + if comp == "systemd": + return v.split(".")[0] + return re.sub(r"[-_](?:r|p)\d+.*$", "", v) + + +def build_matrix_rows(flatcar_version, packages, sources, strict=True): + """Build the matrix rows by resolving each in-scope component.""" + kver = get_flatcar_pinned_kver() + rows = [] + missing_atoms = [] + for spec in IN_SCOPE_COMPONENTS: + comp = spec["component"] + atom = spec["atom"] + fsdk_ver = spec["fsdk_version"] + fsdk_elem = spec["fsdk_element"] + priority = spec["priority"] + + if comp == "kernel": + flatcar_ver = f"{flatcar_version} ({kver})" + flatcar_src = "version.txt + include/flatcar.yml" + elif atom and atom in packages: + flatcar_ver = packages[atom] + flatcar_src = sources.get(atom, "flatcar_production_image_packages.txt") + else: + if strict: + missing_atoms.append(f"{comp} ({atom})") + continue + + gap = compute_gap(spec, flatcar_ver, fsdk_ver) + + rows.append({ + "component": comp, + "flatcar_version": flatcar_ver, + "flatcar_source": flatcar_src, + "fsdk_version": fsdk_ver, + "fsdk_element": fsdk_elem, + "fsdk_source": spec["fsdk_source"], + "gap": gap, + "priority": priority, + }) + + if missing_atoms: + sys.exit(f"ERROR: in-scope components missing from Flatcar manifests: {', '.join(missing_atoms)}") + + rows.sort(key=lambda r: (PRIORITY_ORDER[r["priority"]], r["component"])) + return rows + + +def render_markdown(flatcar_version, fsdk_version, rows): + """Render docs/skills/flatcar-parity-matrix.md with valid skill frontmatter.""" + out = [ + "---", + "name: flatcar-parity-matrix", + "description: |", + " Flatcar-to-FSDK version parity matrix for Bluefin Server (issue #142). Tracks component", + f" versions, gaps, element paths, and substitution order against Flatcar {flatcar_version}.", + "metadata:", + " type: reference", + " status: stable", + ' last_updated: "2026-09-18"', + "---", + "# Flatcar-to-FSDK Parity Matrix", + "", + f"**Flatcar {flatcar_version} vs freedesktop-sdk 26.08 — version audit (design phase 2, issue #142).** " + "Generated by `scripts/generate-parity-matrix.py` from pinned upstream release artifacts; " + "do not edit by hand — re-run the generator.", + "", + "| Component | Flatcar version | FSDK 26.08 version | Gap | Element path | Ordering |", + "|---|---|---|---|---|---|", + ] + + for r in rows: + out.append( + f"| {r['component']} | {r['flatcar_version']} | {r['fsdk_version']} | " + f"{r['gap']} | `{r['fsdk_element']}` | {r['priority']} |" + ) + + out.extend([ + "", + "## Gap Definitions", + "", + "- `none` — FSDK already pins Flatcar's upstream version; no substitution required.", + "- `fsdk-newer` — FSDK pins a newer upstream release than Flatcar; substitute by pinning or backporting the Flatcar version in FSDK elements.", + "- `flatcar-newer` — Flatcar pins a newer upstream release than FSDK.", + "- `different-scheme` — Component version strings follow different packaging schemes and cannot be ordered numerically (e.g. Mozilla NSS certdata vs Fedora RPM).", + "- `n/a` — FSDK does not provide this component; imported whole as a reference.", + "", + "## Ordering Guidance", + "", + "- **load-bearing** — Boot-critical components (glibc, kernel, systemd). Must be substituted first because all subsequent layers depend on them.", + "- **important** — Base userspace runtime and installer dependencies (bash, coreutils, curl, dbus, glib, gnupg, kmod, libcap, libffi, openssh, openssl, shadow, util-linux, zstd).", + "- **deferred** — Optional payloads, sysext extensions, or filesystem utilities (ca-certificates, podman, xfsprogs).", + "", + "## Source Citations", + "", + f"- Flatcar release {flatcar_version} artifacts fetched from `https://flatcar.cdn.cncf.io/stable/amd64-usr/{flatcar_version}/` with SHA256 checksums pinned in `scripts/generate-parity-matrix.py`:", + f" - `version.txt` (`{PINNED_ARTIFACTS.get(flatcar_version, {}).get('amd64-usr', {}).get('version.txt', '6e86c457')[:8]}...`): release identifier and build ID.", + f" - `flatcar_production_image_packages.txt` (`{PINNED_ARTIFACTS.get(flatcar_version, {}).get('amd64-usr', {}).get('flatcar_production_image_packages.txt', '58a43787')[:8]}...`): installed Portage atoms and versions.", + f" - `flatcar-podman_packages.txt` (`{PINNED_ARTIFACTS.get(flatcar_version, {}).get('amd64-usr', {}).get('flatcar-podman_packages.txt', 'befde0ac')[:8]}...`): container runtime sysext packages.", + f"- FSDK 26.08 source elements: pinned junction ref `freedesktop-sdk-{fsdk_version}` in `elements/freedesktop-sdk.bst`.", + "", + "## Downstream Substitution Tickets", + "", + "The following substitution tickets are derived directly from the matrix ordering:", + "", + "1. **Load-bearing (phase 6a)**", + ]) + + rows_by_comp = {r["component"]: r for r in rows} + kernel_entry = rows_by_comp.get("kernel", {}) + kernel_kver = kernel_entry.get("flatcar_version", "").split()[-1].strip("()") if kernel_entry else "" + glibc_ver = clean_ticket_version("glibc", rows_by_comp.get("glibc", {}).get("flatcar_version", "")) + systemd_ver = clean_ticket_version("systemd", rows_by_comp.get("systemd", {}).get("flatcar_version", "")) + + out.append(f" - `subst(kernel)`: reference import `flatcar/flatcar-kernel.bst` ({kernel_kver})") + out.append(f" - `subst(glibc)`: pin glibc {glibc_ver} in `bootstrap/glibc.bst`") + out.append(f" - `subst(systemd)`: pin systemd {systemd_ver} in `components/systemd.bst`") + + out.append("2. **Important base userspace (phase 6b)**") + for comp in ["coreutils", "curl", "glib", "gnupg", "libcap", "libffi", "openssh", "openssl", "shadow", "util-linux"]: + if comp in rows_by_comp: + r = rows_by_comp[comp] + v = clean_ticket_version(comp, r["flatcar_version"]) + out.append(f" - `subst({comp})`: pin {comp} {v} in `{r['fsdk_element']}`") + + version_matches = [] + for comp in ["bash", "dbus", "kmod", "zstd"]: + if comp in rows_by_comp: + v = clean_ticket_version(comp, rows_by_comp[comp]["flatcar_version"]) + version_matches.append(f"`{comp}` ({v})") + if version_matches: + out.append(f" - Version matches (verification only): {', '.join(version_matches)}") + + out.append("3. **Deferred (phase 6c)**") + ca_ver = rows_by_comp.get("ca-certificates", {}).get("flatcar_version", "") + podman_ver = clean_ticket_version("podman", rows_by_comp.get("podman", {}).get("flatcar_version", "")) + xfs_ver = clean_ticket_version("xfsprogs", rows_by_comp.get("xfsprogs", {}).get("flatcar_version", "")) + xfs_elem = rows_by_comp.get("xfsprogs", {}).get("fsdk_element", "components/xfsprogs.bst") + out.append(f" - `subst(ca-certificates)`: evaluate NSS certdata {ca_ver} vs Fedora packaging") + out.append(f" - `subst(podman)`: delivery via sysext matching Flatcar podman {podman_ver}") + out.append(f" - `subst(xfsprogs)`: pin xfsprogs {xfs_ver} in `{xfs_elem}`") + + return "\n".join(out) + "\n" + + +def print_substitution_tickets(rows): + """Print issue titles and bodies for downstream substitution tickets.""" + print("=== Downstream Substitution Tickets ===") + for r in rows: + title = f"subst({r['component']}): align {r['component']} to Flatcar {r['flatcar_version']} ({r['fsdk_element']})" + body = ( + f"Parity matrix row for {r['component']}:\n\n" + f"- **Flatcar version**: {r['flatcar_version']} (source: {r['flatcar_source']})\n" + f"- **FSDK 26.08 version**: {r['fsdk_version']} ({r['fsdk_element']})\n" + f"- **Gap**: {r['gap']}\n" + f"- **Ordering priority**: {r['priority']}\n" + ) + print(f"Title: {title}") + print(f"Priority: {r['priority']}") + print(body) + print("-" * 40) + + +def main(): + parser = argparse.ArgumentParser(description="Generate the Flatcar-to-FSDK version parity matrix.") + parser.add_argument("--flatcar-dir", help="Path to local directory with Flatcar release artifacts.") + parser.add_argument("--output", default=DEFAULT_OUTPUT, type=Path, help="Output markdown path.") + parser.add_argument("--check", action="store_true", help="Check that output file matches generated matrix.") + parser.add_argument("--print-tickets", action="store_true", help="Print downstream substitution ticket specifications.") + args = parser.parse_args() + + pinned_flatcar_ver = get_flatcar_pinned_version() + fsdk_ver = check_fsdk_junction_ref() + + flatcar_version, packages, sources = collect_flatcar_versions( + flatcar_dir=args.flatcar_dir, + flatcar_version=pinned_flatcar_ver, + ) + + rows = build_matrix_rows(flatcar_version, packages, sources) + rendered = render_markdown(flatcar_version, fsdk_ver, rows) + + if args.print_tickets: + print_substitution_tickets(rows) + return + + if args.check: + if not args.output.is_file(): + sys.exit(f"ERROR: {args.output} does not exist. Re-run generator without --check.") + existing = args.output.read_text(encoding="utf-8") + if existing != rendered: + sys.exit(f"ERROR: {args.output} is out of date. Re-run generator without --check to update.") + print(f"OK: {args.output} is up to date.") + return + + args.output.parent.mkdir(parents=True, exist_ok=True) + args.output.write_text(rendered, encoding="utf-8") + print(f"Wrote {args.output} ({len(rows)} rows, Flatcar {flatcar_version} vs FSDK {fsdk_ver})") + + +if __name__ == "__main__": + main() diff --git a/tests/unit/test_generate_parity_matrix.py b/tests/unit/test_generate_parity_matrix.py new file mode 100644 index 00000000..64954e11 --- /dev/null +++ b/tests/unit/test_generate_parity_matrix.py @@ -0,0 +1,165 @@ +"""Tests for the Flatcar-to-FSDK parity matrix generator (scripts/generate-parity-matrix.py).""" + +import importlib.util +import json +import sys +from pathlib import Path + +import pytest + +REPO_ROOT = Path(__file__).resolve().parents[2] +SCRIPT = REPO_ROOT / "scripts" / "generate-parity-matrix.py" + + +def _load_module(): + spec = importlib.util.spec_from_file_location("generate_parity_matrix", SCRIPT) + mod = importlib.util.module_from_spec(spec) + sys.modules["generate_parity_matrix"] = mod + spec.loader.exec_module(mod) + return mod + + +@pytest.fixture +def generator(): + return _load_module() + + +def test_compare_versions(generator): + assert generator.compare_versions("257.9", "261.2") == -1 # fsdk newer + assert generator.compare_versions("2.41-r6", "2.44-23") == -1 # fsdk newer + assert generator.compare_versions("2.5.16", "2.4.9") == 1 # flatcar newer + assert generator.compare_versions("34.2", "34.2") == 0 # none + assert generator.compare_versions("5.3_p3-r3", "5.3-16") == 0 # both 5.3 + assert generator.compare_versions(None, "1.0") is None + + +def test_parse_packages_manifest(generator): + manifest = """ +# Flatcar package manifest +sys-apps/systemd-257.9::portage-stable +sys-libs/glibc-2.41-r6::portage-stable +app-shells/bash-5.3_p3-r3::portage-stable +app-misc/ca-certificates-3.126::coreos-overlay +""" + pkgs = generator.parse_packages_manifest(manifest) + assert pkgs["sys-apps/systemd"] == "257.9" + assert pkgs["sys-libs/glibc"] == "2.41-r6" + assert pkgs["app-shells/bash"] == "5.3_p3-r3" + assert pkgs["app-misc/ca-certificates"] == "3.126" + + +def test_parse_spdx_sbom(generator): + sbom = { + "packages": [ + { + "name": "systemd", + "versionInfo": "257.9", + "externalRefs": [ + { + "referenceLocator": "pkg:gentoo/sys-apps/systemd@257.9", + "externalReference": {"referenceLocator": "pkg:gentoo/sys-apps/systemd@257.9"}, + } + ], + }, + { + "name": "glibc", + "versionInfo": "2.41-r6", + "externalRefs": [ + {"referenceLocator": "pkg:gentoo/sys-libs/glibc@2.41-r6"} + ], + }, + ] + } + pkgs = generator.parse_spdx_sbom(json.dumps(sbom)) + assert pkgs["sys-apps/systemd"] == "257.9" + assert pkgs["sys-libs/glibc"] == "2.41-r6" + + +def test_matrix_generation_from_flatcar_dir(generator, tmp_path): + mock_dir = tmp_path / "flatcar" / "4593.2.5" + mock_dir.mkdir(parents=True) + (mock_dir / "version.txt").write_text("FLATCAR_VERSION=4593.2.5\nFLATCAR_BUILD_ID=\"2026-08-11-2350\"\n") + (mock_dir / "flatcar_production_image_packages.txt").write_text(""" +sys-apps/systemd-257.9::portage-stable +sys-libs/glibc-2.41-r6::portage-stable +sys-apps/coreutils-9.8-r1::portage-stable +app-shells/bash-5.3_p3-r3::portage-stable +sys-apps/kmod-34.2::portage-stable +app-crypt/gnupg-2.5.16::portage-stable +app-misc/ca-certificates-3.126::coreos-overlay +sys-fs/xfsprogs-6.16.0::portage-stable +""") + (mock_dir / "flatcar-podman_packages.txt").write_text(""" +app-containers/podman-5.5.2::portage-stable +""") + + flatcar_ver, pkgs, sources = generator.collect_flatcar_versions(flatcar_dir=mock_dir) + assert flatcar_ver == "4593.2.5" + assert pkgs["sys-apps/systemd"] == "257.9" + assert pkgs["app-containers/podman"] == "5.5.2" + + rows = generator.build_matrix_rows(flatcar_ver, pkgs, sources, strict=False) + row_map = {r["component"]: r for r in rows} + + # Kernel special row + assert "kernel" in row_map + assert row_map["kernel"]["gap"] == "n/a" + assert row_map["kernel"]["priority"] == "load-bearing" + + # Systemd & glibc + assert row_map["systemd"]["gap"] == "fsdk-newer" + assert row_map["systemd"]["priority"] == "load-bearing" + assert row_map["glibc"]["gap"] == "fsdk-newer" + assert row_map["glibc"]["priority"] == "load-bearing" + + # Gnupg & kmod & bash + assert row_map["gnupg"]["gap"] == "flatcar-newer" + assert row_map["kmod"]["gap"] == "none" + assert row_map["bash"]["gap"] == "none" + + # Podman & ca-certificates + assert row_map["podman"]["gap"] == "fsdk-newer" + assert row_map["podman"]["priority"] == "deferred" + assert row_map["ca-certificates"]["gap"] == "different-scheme" + + # Render markdown + output_md = tmp_path / "flatcar-parity-matrix.md" + rendered = generator.render_markdown(flatcar_ver, "26.08.0", rows) + output_md.write_text(rendered, encoding="utf-8") + + assert "name: flatcar-parity-matrix" in rendered + assert "Flatcar 4593.2.5 vs freedesktop-sdk 26.08" in rendered + assert "| systemd | 257.9 | 261.2 | fsdk-newer | `components/systemd.bst` | load-bearing |" in rendered + assert "| glibc | 2.41-r6 | 2.44-23 | fsdk-newer | `bootstrap/glibc.bst` | load-bearing |" in rendered + + +def test_checked_in_matrix_is_up_to_date(generator): + """Ensure the committed docs/skills/flatcar-parity-matrix.md matches generator output.""" + output_path = REPO_ROOT / "docs" / "skills" / "flatcar-parity-matrix.md" + assert output_path.is_file(), "docs/skills/flatcar-parity-matrix.md must exist" + + pinned_ver = generator.get_flatcar_pinned_version() + fsdk_ver = generator.check_fsdk_junction_ref() + try: + flatcar_version, packages, sources = generator.collect_flatcar_versions(flatcar_version=pinned_ver) + except SystemExit as exc: + pytest.skip(f"Flatcar CDN/artifacts unavailable offline: {exc}") + rows = generator.build_matrix_rows(flatcar_version, packages, sources) + expected_content = generator.render_markdown(flatcar_version, fsdk_ver, rows) + + actual_content = output_path.read_text(encoding="utf-8") + assert actual_content == expected_content, "Matrix on disk has drifted from generator output." + + +def test_strict_mode_fails_on_missing_atoms(generator, tmp_path): + """Ensure build_matrix_rows in strict mode fails fast when in-scope atoms are missing.""" + mock_dir = tmp_path / "flatcar" / "4593.2.5" + mock_dir.mkdir(parents=True) + (mock_dir / "version.txt").write_text("FLATCAR_VERSION=4593.2.5\nFLATCAR_BUILD_ID=\"2026-08-11-2350\"\n") + (mock_dir / "flatcar_production_image_packages.txt").write_text("sys-apps/systemd-257.9::portage-stable\n") + (mock_dir / "flatcar-podman_packages.txt").write_text("") + + flatcar_ver, pkgs, sources = generator.collect_flatcar_versions(flatcar_dir=mock_dir) + with pytest.raises(SystemExit) as exc_info: + generator.build_matrix_rows(flatcar_ver, pkgs, sources, strict=True) + assert "in-scope components missing from Flatcar manifests" in str(exc_info.value) From 9b506c73aa8c17f9a858976c97b8d5a06d811a3e Mon Sep 17 00:00:00 2001 From: "Jorge O. Castro" Date: Sun, 20 Sep 2026 06:02:02 -0400 Subject: [PATCH 21/42] feat(flatcar): record container runtime parity (#192) Assisted-by: Claude Opus 4.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../generate-flatcar-runtime-parity.py | 280 ++++++++++++++++++ .../2026-09-19-flatcar-runtime-parity.md | 21 ++ .../container-runtime-reference-sysexts.bst | 36 +++ tests/unit/test_flatcar_runtime_parity.py | 103 +++++++ 4 files changed, 440 insertions(+) create mode 100755 .github/scripts/generate-flatcar-runtime-parity.py create mode 100644 docs/superpowers/specs/2026-09-19-flatcar-runtime-parity.md create mode 100644 elements/flatcar/container-runtime-reference-sysexts.bst create mode 100644 tests/unit/test_flatcar_runtime_parity.py diff --git a/.github/scripts/generate-flatcar-runtime-parity.py b/.github/scripts/generate-flatcar-runtime-parity.py new file mode 100755 index 00000000..df10c554 --- /dev/null +++ b/.github/scripts/generate-flatcar-runtime-parity.py @@ -0,0 +1,280 @@ +#!/usr/bin/env python3 +"""Generate Flatcar container runtime parity matrix. + +The matrix records the runtime versions Flatcar publishes in sysext manifests +and compares them with the freedesktop-sdk junction pinned by this repository. +It intentionally fetches upstream manifests on demand; the generated Markdown is +checked in so normal validation stays offline. +""" + +from __future__ import annotations + +import argparse +import re +import sys +from dataclasses import dataclass +from pathlib import Path +from urllib.error import HTTPError, URLError +from urllib.request import Request, urlopen + +ROOT = Path(__file__).resolve().parents[2] +FLATCAR_INCLUDE = ROOT / "include" / "flatcar.yml" +FSDK_JUNCTION = ROOT / "elements" / "freedesktop-sdk.bst" +OUTPUT = ROOT / "docs" / "superpowers" / "specs" / "2026-09-19-flatcar-runtime-parity.md" + +FSDK_RAW_URL = ( + "https://gitlab.com/freedesktop-sdk/freedesktop-sdk/-/raw/" + "{ref}/elements/components/{element}.bst" +) + + +@dataclass(frozen=True) +class RuntimeSpec: + name: str + flatcar_sysext: str + flatcar_manifest_path: str + flatcar_package: str + fsdk_element: str | None + reference_raw_path: str + reference_sha256: str + decision: str + + +@dataclass(frozen=True) +class RuntimeRow: + spec: RuntimeSpec + flatcar_version: str + fsdk_version: str | None + fsdk_ref: str + flatcar_version_source: str + fsdk_version_source: str + + +RUNTIMES = ( + RuntimeSpec( + name="podman", + flatcar_sysext="flatcar-podman.raw", + flatcar_manifest_path="flatcar-podman_packages.txt", + flatcar_package="app-containers/podman", + fsdk_element="podman", + reference_raw_path="flatcar-podman.raw", + reference_sha256="bc8c6777ab9dee286eb1f70a1605a880fcc5199246d87f9c92f00d880194d72b", + decision=( + "match Flatcar in the runtime sysext; do not treat FSDK's " + "base-OS podman pin as the target" + ), + ), + RuntimeSpec( + name="containerd", + flatcar_sysext="containerd-flatcar.raw", + flatcar_manifest_path="rootfs-included-sysexts/containerd-flatcar_packages.txt", + flatcar_package="app-containers/containerd", + fsdk_element="containerd", + reference_raw_path="rootfs-included-sysexts/containerd-flatcar.raw", + reference_sha256="78e38344ac490004b9fa4c7da38bbfcffc393146aa990379aff7b5c09589f809", + decision="match Flatcar through the referenced sysext; no FSDK component exists to retag", + ), + RuntimeSpec( + name="docker", + flatcar_sysext="docker-flatcar.raw", + flatcar_manifest_path="rootfs-included-sysexts/docker-flatcar_packages.txt", + flatcar_package="app-containers/docker", + fsdk_element="docker", + reference_raw_path="rootfs-included-sysexts/docker-flatcar.raw", + reference_sha256="5105dfe9cfb1357fce76e0297c0285e169b1eeb47fa6edd83d5bafe697c72662", + decision=( + "accept divergence: Bluefin Server does not ship Docker; keep " + "the Flatcar sysext only as a boot-comparison reference" + ), + ), +) + + +class FetchError(RuntimeError): + pass + + +def read(path: Path) -> str: + if not path.is_file(): + sys.exit(f"ERROR: expected file not found: {path.relative_to(ROOT)}") + return path.read_text(encoding="utf-8") + + +def scalar(text: str, name: str, where: str) -> str: + match = re.search(rf"^\s*{re.escape(name)}:\s*[\"']([^\"']+)[\"']\s*$", text, re.MULTILINE) + if not match: + sys.exit(f"ERROR: {where} does not declare '{name}:'.") + return match.group(1) + + +def fsdk_ref() -> str: + match = re.search(r"^\s*ref:\s*(\S+)\s*$", read(FSDK_JUNCTION), re.MULTILINE) + if not match: + sys.exit("ERROR: elements/freedesktop-sdk.bst does not declare a pinned ref.") + return match.group(1) + + +def flatcar_version() -> str: + return scalar(read(FLATCAR_INCLUDE), "flatcar-version", "include/flatcar.yml") + + +def fetch_text(url: str) -> str | None: + request = Request(url, headers={"User-Agent": "projectbluefin-server-runtime-parity/1"}) + try: + with urlopen(request, timeout=30) as response: + return response.read().decode("utf-8") + except HTTPError as exc: + if exc.code == 404: + return None + raise FetchError(f"{url}: HTTP {exc.code}") from exc + except URLError as exc: + raise FetchError(f"{url}: {exc.reason}") from exc + + +def flatcar_manifest_url(version: str, spec: RuntimeSpec) -> str: + return f"https://flatcar.cdn.cncf.io/stable/amd64-usr/{version}/{spec.flatcar_manifest_path}" + + +def flatcar_raw_url(version: str, spec: RuntimeSpec) -> str: + return f"https://flatcar.cdn.cncf.io/stable/amd64-usr/{version}/{spec.reference_raw_path}" + + +def parse_flatcar_package_version(manifest: str, package: str) -> str: + pattern = re.compile(rf"^{re.escape(package)}-(?P.+?)::", re.MULTILINE) + match = pattern.search(manifest) + if not match: + raise FetchError(f"{package} was not found in Flatcar package manifest") + return match.group("version") + + +def parse_fsdk_source_version(element_text: str) -> str: + match = re.search(r"^\s*ref:\s*v?(?P[0-9][^-\s]*)-", element_text, re.MULTILINE) + if not match: + raise FetchError("FSDK component does not expose a versioned source ref") + return match.group("version") + + +def collect_rows(fetch=fetch_text) -> list[RuntimeRow]: + version = flatcar_version() + pinned_fsdk_ref = fsdk_ref() + rows: list[RuntimeRow] = [] + + for spec in RUNTIMES: + manifest_url = flatcar_manifest_url(version, spec) + manifest = fetch(manifest_url) + if manifest is None: + raise FetchError(f"Flatcar manifest not found: {manifest_url}") + flatcar_runtime_version = parse_flatcar_package_version(manifest, spec.flatcar_package) + + fsdk_version_value = None + fsdk_source = "not packaged by FSDK 26.08" + if spec.fsdk_element: + source_url = FSDK_RAW_URL.format(ref=pinned_fsdk_ref, element=spec.fsdk_element) + source = fetch(source_url) + fsdk_source = f"freedesktop-sdk {pinned_fsdk_ref}:elements/components/{spec.fsdk_element}.bst" + if source is not None: + fsdk_version_value = parse_fsdk_source_version(source) + else: + fsdk_source = f"no elements/components/{spec.fsdk_element}.bst in freedesktop-sdk {pinned_fsdk_ref}" + + rows.append( + RuntimeRow( + spec=spec, + flatcar_version=flatcar_runtime_version, + fsdk_version=fsdk_version_value, + fsdk_ref=pinned_fsdk_ref, + flatcar_version_source=manifest_url, + fsdk_version_source=fsdk_source, + ) + ) + + return rows + + +def gap(row: RuntimeRow) -> str: + if row.fsdk_version is None: + return "missing in FSDK 26.08" + if row.fsdk_version == row.flatcar_version: + return "match" + return f"mismatch: FSDK {row.fsdk_version}, Flatcar {row.flatcar_version}" + + +def render(rows: list[RuntimeRow]) -> str: + flatcar = flatcar_version() + lines = [ + "# Flatcar container runtime parity matrix", + "", + "Generated by `.github/scripts/generate-flatcar-runtime-parity.py --write`.", + "", + f"Flatcar release: `{flatcar}`. FSDK junction: `{rows[0].fsdk_ref}`.", + "", + "| Runtime | Flatcar sysext | Flatcar version | FSDK 26.08 version | Gap | Decision | Sources | Reference raw sha256 |", + "|---|---|---:|---:|---|---|---|---|", + ] + for row in rows: + fsdk_version_value = row.fsdk_version or "absent" + sources = ( + f"Flatcar package manifest: `{row.flatcar_version_source}`; " + f"FSDK source: `{row.fsdk_version_source}`" + ) + lines.append( + "| " + + " | ".join( + [ + row.spec.name, + f"`{row.spec.flatcar_sysext}`", + row.flatcar_version, + fsdk_version_value, + gap(row), + row.spec.decision, + sources, + f"`{row.spec.reference_sha256}`", + ] + ) + + " |" + ) + lines.extend( + [ + "", + "## Reference sysext import", + "", + "`elements/flatcar/container-runtime-reference-sysexts.bst` imports the three Flatcar raw sysext images as reference artifacts only. No shipped OS DDI, installer, or k0s sysext target depends on that element.", + "", + "Reference raw URLs:", + "", + ] + ) + for row in rows: + lines.append(f"- `{flatcar_raw_url(flatcar, row.spec)}`") + lines.append("") + return "\n".join(lines) + + +def main() -> None: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--write", action="store_true", help=f"write {OUTPUT.relative_to(ROOT)}") + parser.add_argument("--check", action="store_true", help="fail if the checked-in matrix is stale") + args = parser.parse_args() + + try: + content = render(collect_rows()) + except FetchError as exc: + sys.exit(f"ERROR: {exc}") + + if args.write: + OUTPUT.parent.mkdir(parents=True, exist_ok=True) + OUTPUT.write_text(content, encoding="utf-8") + print(f"wrote {OUTPUT.relative_to(ROOT)}") + elif args.check: + if read(OUTPUT) != content: + sys.exit( + "ERROR: Flatcar runtime parity matrix is stale. " + "Run .github/scripts/generate-flatcar-runtime-parity.py --write." + ) + print("OK: Flatcar runtime parity matrix is current.") + else: + print(content, end="") + + +if __name__ == "__main__": + main() diff --git a/docs/superpowers/specs/2026-09-19-flatcar-runtime-parity.md b/docs/superpowers/specs/2026-09-19-flatcar-runtime-parity.md new file mode 100644 index 00000000..999fc670 --- /dev/null +++ b/docs/superpowers/specs/2026-09-19-flatcar-runtime-parity.md @@ -0,0 +1,21 @@ +# Flatcar container runtime parity matrix + +Generated by `.github/scripts/generate-flatcar-runtime-parity.py --write`. + +Flatcar release: `4593.2.5`. FSDK junction: `freedesktop-sdk-26.08.0-0-gdb97cce32cecadc7a3e98f06d557ebfa6ba9ad46`. + +| Runtime | Flatcar sysext | Flatcar version | FSDK 26.08 version | Gap | Decision | Sources | Reference raw sha256 | +|---|---|---:|---:|---|---|---|---| +| podman | `flatcar-podman.raw` | 5.5.2 | 6.1.0 | mismatch: FSDK 6.1.0, Flatcar 5.5.2 | match Flatcar in the runtime sysext; do not treat FSDK's base-OS podman pin as the target | Flatcar package manifest: `https://flatcar.cdn.cncf.io/stable/amd64-usr/4593.2.5/flatcar-podman_packages.txt`; FSDK source: `freedesktop-sdk freedesktop-sdk-26.08.0-0-gdb97cce32cecadc7a3e98f06d557ebfa6ba9ad46:elements/components/podman.bst` | `bc8c6777ab9dee286eb1f70a1605a880fcc5199246d87f9c92f00d880194d72b` | +| containerd | `containerd-flatcar.raw` | 2.1.5 | absent | missing in FSDK 26.08 | match Flatcar through the referenced sysext; no FSDK component exists to retag | Flatcar package manifest: `https://flatcar.cdn.cncf.io/stable/amd64-usr/4593.2.5/rootfs-included-sysexts/containerd-flatcar_packages.txt`; FSDK source: `no elements/components/containerd.bst in freedesktop-sdk freedesktop-sdk-26.08.0-0-gdb97cce32cecadc7a3e98f06d557ebfa6ba9ad46` | `78e38344ac490004b9fa4c7da38bbfcffc393146aa990379aff7b5c09589f809` | +| docker | `docker-flatcar.raw` | 28.0.4 | absent | missing in FSDK 26.08 | accept divergence: Bluefin Server does not ship Docker; keep the Flatcar sysext only as a boot-comparison reference | Flatcar package manifest: `https://flatcar.cdn.cncf.io/stable/amd64-usr/4593.2.5/rootfs-included-sysexts/docker-flatcar_packages.txt`; FSDK source: `no elements/components/docker.bst in freedesktop-sdk freedesktop-sdk-26.08.0-0-gdb97cce32cecadc7a3e98f06d557ebfa6ba9ad46` | `5105dfe9cfb1357fce76e0297c0285e169b1eeb47fa6edd83d5bafe697c72662` | + +## Reference sysext import + +`elements/flatcar/container-runtime-reference-sysexts.bst` imports the three Flatcar raw sysext images as reference artifacts only. No shipped OS DDI, installer, or k0s sysext target depends on that element. + +Reference raw URLs: + +- `https://flatcar.cdn.cncf.io/stable/amd64-usr/4593.2.5/flatcar-podman.raw` +- `https://flatcar.cdn.cncf.io/stable/amd64-usr/4593.2.5/rootfs-included-sysexts/containerd-flatcar.raw` +- `https://flatcar.cdn.cncf.io/stable/amd64-usr/4593.2.5/rootfs-included-sysexts/docker-flatcar.raw` diff --git a/elements/flatcar/container-runtime-reference-sysexts.bst b/elements/flatcar/container-runtime-reference-sysexts.bst new file mode 100644 index 00000000..92f38898 --- /dev/null +++ b/elements/flatcar/container-runtime-reference-sysexts.bst @@ -0,0 +1,36 @@ +kind: manual +description: | + Import Flatcar's amd64 container runtime system extensions as reference artifacts. + These raw sysext images are an oracle for boot comparison and version parity; + no shipped OS DDI, installer, or k0s sysext target depends on this element. + +(@): + - include/flatcar.yml + +build-depends: + - base/base-stack.bst + +variables: + strip-binaries: "" + +sources: + - kind: remote + url: flatcar:stable/amd64-usr/%{flatcar-version}/flatcar-podman.raw + ref: bc8c6777ab9dee286eb1f70a1605a880fcc5199246d87f9c92f00d880194d72b + - kind: remote + url: flatcar:stable/amd64-usr/%{flatcar-version}/rootfs-included-sysexts/containerd-flatcar.raw + ref: 78e38344ac490004b9fa4c7da38bbfcffc393146aa990379aff7b5c09589f809 + - kind: remote + url: flatcar:stable/amd64-usr/%{flatcar-version}/rootfs-included-sysexts/docker-flatcar.raw + ref: 5105dfe9cfb1357fce76e0297c0285e169b1eeb47fa6edd83d5bafe697c72662 + +config: + install-commands: + - | + set -euo pipefail + + out="%{install-root}/usr/lib/flatcar-reference-sysexts" + mkdir -p "${out}" + install -D -m 0644 flatcar-podman.raw "${out}/flatcar-podman.raw" + install -D -m 0644 containerd-flatcar.raw "${out}/containerd-flatcar.raw" + install -D -m 0644 docker-flatcar.raw "${out}/docker-flatcar.raw" diff --git a/tests/unit/test_flatcar_runtime_parity.py b/tests/unit/test_flatcar_runtime_parity.py new file mode 100644 index 00000000..2a47fcb0 --- /dev/null +++ b/tests/unit/test_flatcar_runtime_parity.py @@ -0,0 +1,103 @@ +"""Unit coverage for the Flatcar container runtime parity generator. + +The checked-in matrix is the issue contract for version parity: if the parser +loses a runtime version or a reference sysext loses its content hash, follow-on +substitution work no longer has a stable target. +""" + +import importlib.util +import sys +from pathlib import Path + +import pytest + +REPO_ROOT = Path(__file__).resolve().parents[2] +SCRIPT_PATH = REPO_ROOT / ".github" / "scripts" / "generate-flatcar-runtime-parity.py" +REFERENCE_ELEMENT = REPO_ROOT / "elements" / "flatcar" / "container-runtime-reference-sysexts.bst" + +FLATCAR_MANIFESTS = { + "flatcar-podman_packages.txt": "app-containers/podman-5.5.2::portage-stable\n", + "containerd-flatcar_packages.txt": "app-containers/containerd-2.1.5::portage-stable\n", + "docker-flatcar_packages.txt": "app-containers/docker-28.0.4::portage-stable\n", +} + +FSDK_PODMAN = """ +sources: +- kind: git_repo + url: github:podman-container-tools/podman.git + ref: v6.1.0-0-gcade97a52ebdf9dbf9e81de8009015776837a074 +""" + + +def _load_module(): + spec = importlib.util.spec_from_file_location("flatcar_runtime_parity", SCRIPT_PATH) + module = importlib.util.module_from_spec(spec) + sys.modules["flatcar_runtime_parity"] = module + spec.loader.exec_module(module) + return module + + +@pytest.fixture +def generator(tmp_path): + module = _load_module() + module.ROOT = tmp_path + module.FLATCAR_INCLUDE = tmp_path / "include" / "flatcar.yml" + module.FSDK_JUNCTION = tmp_path / "elements" / "freedesktop-sdk.bst" + module.FLATCAR_INCLUDE.parent.mkdir(parents=True) + module.FSDK_JUNCTION.parent.mkdir(parents=True) + module.FLATCAR_INCLUDE.write_text('variables:\n flatcar-version: "4593.2.5"\n', encoding="utf-8") + module.FSDK_JUNCTION.write_text( + "sources:\n" + "- kind: git_repo\n" + " ref: freedesktop-sdk-26.08.0-0-gdb97cce32cecadc7a3e98f06d557ebfa6ba9ad46\n", + encoding="utf-8", + ) + yield module + sys.modules.pop("flatcar_runtime_parity", None) + + +def fake_fetch(url): + for suffix, body in FLATCAR_MANIFESTS.items(): + if url.endswith(suffix): + return body + if url.endswith("/podman.bst"): + return FSDK_PODMAN + if url.endswith("/containerd.bst") or url.endswith("/docker.bst"): + return None + raise AssertionError(f"unexpected URL: {url}") + + +def test_collect_rows_records_flatcar_and_fsdk_runtime_versions(generator): + rows = generator.collect_rows(fetch=fake_fetch) + + assert [(row.spec.name, row.flatcar_version, row.fsdk_version) for row in rows] == [ + ("podman", "5.5.2", "6.1.0"), + ("containerd", "2.1.5", None), + ("docker", "28.0.4", None), + ] + assert generator.gap(rows[0]) == "mismatch: FSDK 6.1.0, Flatcar 5.5.2" + assert generator.gap(rows[1]) == "missing in FSDK 26.08" + + +def test_rendered_matrix_records_decisions_and_sources(generator): + content = generator.render(generator.collect_rows(fetch=fake_fetch)) + + assert "match Flatcar in the runtime sysext" in content + assert "accept divergence: Bluefin Server does not ship Docker" in content + assert "flatcar-podman_packages.txt" in content + assert "elements/components/podman.bst" in content + assert "bc8c6777ab9dee286eb1f70a1605a880fcc5199246d87f9c92f00d880194d72b" in content + + +def test_reference_element_pins_all_runtime_sysexts(): + text = REFERENCE_ELEMENT.read_text(encoding="utf-8") + + for name, sha256 in { + "flatcar-podman.raw": "bc8c6777ab9dee286eb1f70a1605a880fcc5199246d87f9c92f00d880194d72b", + "containerd-flatcar.raw": "78e38344ac490004b9fa4c7da38bbfcffc393146aa990379aff7b5c09589f809", + "docker-flatcar.raw": "5105dfe9cfb1357fce76e0297c0285e169b1eeb47fa6edd83d5bafe697c72662", + }.items(): + assert name in text + assert sha256 in text + + assert "no shipped OS DDI, installer, or k0s sysext target depends" in text From 32a212cd7cacab11ba6f1de77d4f70380d801c7e Mon Sep 17 00:00:00 2001 From: "Jorge O. Castro" Date: Sun, 20 Sep 2026 09:26:23 -0400 Subject: [PATCH 22/42] fix(ci): move junction ref tracking out of the pull_request path (#180) Moves junction tracking off the pull_request path onto a scheduled tracker that also syncs project.conf release-version from the tracked FSDK point release, so junction bumps arrive green instead of dying at check-release-version.py. Assisted-by: Claude Opus 4.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/workflows/build.yml | 48 +------ .github/workflows/track-junctions.yml | 162 ++++++++++++++++++++++ docs/skills/bump-fsdk-version.md | 6 +- docs/skills/ci-tooling.md | 32 +++-- workflows/server-release-watch-and-fix.md | 2 +- 5 files changed, 191 insertions(+), 59 deletions(-) create mode 100644 .github/workflows/track-junctions.yml diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index bf99f8ea..e91cbb3c 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -12,57 +12,15 @@ concurrency: # Least privilege by default: this workflow executes PR-controlled build code # (the Justfile and build scripts come from the PR head), so the workflow-wide -# token is read-only. contents: write is granted per job only where genuinely -# required (see track-refs and release below). +# token is read-only. No job that runs on `pull_request` holds a write token; +# contents: write is granted only to `release`, which is gated to main. permissions: contents: read jobs: - # Resolves BuildStream junction refs and pushes them back to the PR branch. - # This runs PR-controlled code (`just bst source track`) with a write token, - # so it keeps the pre-existing renovate/* branch gate. The push updates the - # PR branch tip; the build job below runs afterwards and checks out that - # updated tip. - track-refs: - if: github.event_name == 'pull_request' && startsWith(github.head_ref, 'renovate/') - runs-on: ubuntu-24.04 - timeout-minutes: 60 - permissions: - contents: write # pushes resolved refs back to the renovate/* PR branch - steps: - - name: Checkout repository - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - with: - ref: ${{ github.event.pull_request.head.ref || github.ref }} - repository: ${{ github.event.pull_request.head.repo.full_name || github.repository }} - - - name: Set up just - uses: taiki-e/install-action@7b8d4719ee4aaa279bdf55df38dacb9ebfe12a6c # v2 - with: - tool: just - - - name: Track and Resolve BuildStream Refs - env: - HEAD_REF: ${{ github.head_ref }} - run: | - set -euo pipefail - git config --global user.name "github-actions[bot]" - git config --global user.email "github-actions[bot]@users.noreply.github.com" - just bst source track freedesktop-sdk.bst || true - just bst source track gnome-build-meta.bst || true - if ! git diff --exit-code; then - git add elements/ - git commit -m "chore: resolve BuildStream junction refs to git-describe format" -m "Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" - git push origin "HEAD:${HEAD_REF}" - fi - build: # Read-only token (workflow default): on pull_request this job checks out # and executes PR-controlled code, so it must never hold a write token. - needs: track-refs - # track-refs is skipped for non-renovate PRs and pushes; only a failed or - # cancelled track job should stop the build. - if: ${{ !failure() && !cancelled() }} runs-on: ubuntu-24.04 timeout-minutes: 180 outputs: @@ -182,7 +140,7 @@ jobs: # Publishes the signed assets to the GitHub Release. Only runs on # pushes/dispatches to main, where the code is already reviewed, and is the - # only job besides track-refs that holds contents: write. + # only job in this workflow that holds contents: write. release: if: ${{ !failure() && !cancelled() && github.ref == 'refs/heads/main' }} needs: [build, installer-test] diff --git a/.github/workflows/track-junctions.yml b/.github/workflows/track-junctions.yml new file mode 100644 index 00000000..2b7c2c63 --- /dev/null +++ b/.github/workflows/track-junctions.yml @@ -0,0 +1,162 @@ +name: Track junction refs + +# Resolves the BuildStream junction refs on a schedule and delivers the result +# as its own titled pull request. +# +# This deliberately has NO `pull_request` trigger. The job this replaces +# (`track-refs` in build.yml) ran on every `renovate/*` pull request and pushed +# re-resolved junction refs onto that PR's branch, so unrelated dependency PRs +# silently acquired freedesktop-sdk and gnome-build-meta bumps that appeared in +# no title, body or Renovate table. Moving the work onto a schedule with its own +# branch also removes the need for the old `startsWith(github.head_ref, +# 'renovate/')` gate: a branch name is not an identity, and on a scheduled +# trigger there is no PR-controlled head to gate in the first place. +on: + schedule: + # Offset from dakota's trackers (06:00 and 20:00 UTC) to spread runner load. + - cron: '0 8 * * *' + workflow_dispatch: + +permissions: + contents: read + +# Tracking only queries upstream git remotes to resolve refs; it never builds +# and never touches the CAS, so it has no reason to share the build group. +concurrency: + group: track-junctions + cancel-in-progress: false + +jobs: + track-junctions: + runs-on: ubuntu-24.04 + timeout-minutes: 60 + permissions: + contents: write # pushes the auto/track-junctions branch + pull-requests: write # opens/updates the junction bump PR + steps: + # A GitHub App token, not secrets.GITHUB_TOKEN: pushes and PRs made with + # GITHUB_TOKEN do not dispatch workflow runs, which is why the old job's + # github-actions[bot] commits left PRs sitting at `action_required` with + # zero jobs and no checks at all. + - name: Get mergeraptor token + id: app-token + uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3 + with: + app-id: ${{ secrets.MERGERAPTOR_APP_ID }} + private-key: ${{ secrets.MERGERAPTOR_PRIVATE_KEY }} + + - name: Checkout repository + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: main + fetch-depth: 0 + token: ${{ steps.app-token.outputs.token }} + + - name: Set up just + uses: taiki-e/install-action@7b8d4719ee4aaa279bdf55df38dacb9ebfe12a6c # v2 + with: + tool: just + + - name: Track and resolve BuildStream junction refs + run: | + set -euo pipefail + # No `|| true` here. The job this replaces swallowed both exit codes, + # which made an upstream outage indistinguishable from "nothing to + # track" and let the run report success having resolved nothing. + # + # gnome-build-meta.bst carries `overrides: freedesktop-sdk.bst`, so + # the pair is only valid together and is tracked and committed as one + # atomic change — same rationale as dakota's track-core-junctions. + just bst source track freedesktop-sdk.bst + just bst source track gnome-build-meta.bst + + - name: Sync release-version to the tracked FSDK point release + run: | + set -euo pipefail + # project.conf's release-version names every published OS asset and + # must equal the FSDK point release; check-release-version.py fails + # closed on drift and is the first thing `just validate` runs. Without + # this step an FSDK bump would open a PR that dies in seconds at + # "Validate Element Graph" — exactly the failure the old job produced. + pinned=$(grep -oE 'freedesktop-sdk-[0-9]+\.[0-9]+\.[0-9]+' elements/freedesktop-sdk.bst | head -1 | sed 's/freedesktop-sdk-//') + if [ -z "$pinned" ]; then + echo "ERROR: tracked freedesktop-sdk.bst ref carries no X.Y.Z point release" >&2 + exit 1 + fi + sed -i -E "s|^([[:space:]]*release-version:[[:space:]]*).*|\1\"${pinned}\"|" project.conf + # Assert before opening the PR; a failure here means the sync broke. + python3 .github/scripts/check-release-version.py + + - name: Create or update the junction bump PR + env: + GH_TOKEN: ${{ steps.app-token.outputs.token }} + BRANCH: auto/track-junctions + run: | + set -euo pipefail + + git config user.name "github-actions[bot]" + git config user.email "41898282+github-actions[bot]@users.noreply.github.com" + + old_fsdk=$(git show "HEAD:elements/freedesktop-sdk.bst" | awk '/^[[:space:]]*ref:/ { print $2; exit }') + old_gbm=$(git show "HEAD:elements/gnome-build-meta.bst" | awk '/^[[:space:]]*ref:/ { print $2; exit }') + new_fsdk=$(awk '/^[[:space:]]*ref:/ { print $2; exit }' elements/freedesktop-sdk.bst) + new_gbm=$(awk '/^[[:space:]]*ref:/ { print $2; exit }' elements/gnome-build-meta.bst) + + git checkout -B "$BRANCH" + git add elements/freedesktop-sdk.bst elements/gnome-build-meta.bst project.conf + if git diff --cached --quiet; then + echo "Junction refs already current — nothing to propose." + exit 0 + fi + + title="chore(deps): update BuildStream junctions" + if [ "$old_fsdk" != "$new_fsdk" ]; then + title="${title} (freedesktop-sdk $(echo "$old_fsdk" | sed 's/^freedesktop-sdk-//;s/-[0-9]*-g[0-9a-f]*$//') -> $(echo "$new_fsdk" | sed 's/^freedesktop-sdk-//;s/-[0-9]*-g[0-9a-f]*$//'))" + elif [ "$old_gbm" != "$new_gbm" ]; then + title="${title} (gnome-build-meta)" + fi + + { + echo "Scheduled resolution of the BuildStream junction refs to their" + echo "\`git-describe\` form. Opened by the tracker so the bump arrives as its own" + echo "reviewable change instead of being pushed into an unrelated pull request." + echo "" + echo "| Junction | From | To |" + echo "| --- | --- | --- |" + echo "| \`elements/freedesktop-sdk.bst\` | \`${old_fsdk}\` | \`${new_fsdk}\` |" + echo "| \`elements/gnome-build-meta.bst\` | \`${old_gbm}\` | \`${new_gbm}\` |" + echo "" + echo "\`project.conf\`'s \`release-version\` is synced to the pinned FSDK point" + echo "release in the same commit, because \`check-release-version.py\` fails closed" + echo "on drift between the two." + echo "" + echo "The two junctions move together: \`gnome-build-meta.bst\` overrides" + echo "\`freedesktop-sdk.bst\`, so a half-applied pair is not a valid graph." + echo "" + echo "---" + echo "*Generated by [Track junction refs](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})*" + } > /tmp/pr-body.md + + # Deliberately no attribution trailers. This commit is a deterministic + # `bst source track` result plus a `sed` on project.conf — machine + # output with no AI authorship to attribute. The `Co-authored-by: + # Copilot` trailer inherited from the old track-refs job was a false + # attribution that would accumulate across every junction bump. Please + # do not re-add it; AGENTS.md's trailer requirement is about + # AI-authored commits, which this is not. + git commit -m "$title" + git push --force-with-lease origin "$BRANCH" + + # No `|| true`: `gh pr list` already exits 0 and prints nothing when + # no PR matches, so a fallback buys nothing for the normal case and + # only converts an auth failure or API outage into an empty + # `existing` that falls through to `gh pr create` against a branch + # that may already have an open PR. `// empty` is the legitimate + # mechanism for "no open PR"; a failed query must abort the step. + existing=$(gh pr list --head "$BRANCH" --base main --state open --json number --jq '.[0].number // empty') + if [ -n "$existing" ]; then + gh pr edit "$existing" --title "$title" --body-file /tmp/pr-body.md + echo "Updated PR: $(gh pr view "$existing" --json url --jq '.url')" + else + echo "Created PR: $(gh pr create --base main --head "$BRANCH" --title "$title" --body-file /tmp/pr-body.md)" + fi diff --git a/docs/skills/bump-fsdk-version.md b/docs/skills/bump-fsdk-version.md index 1d0453e3..ccd20f80 100644 --- a/docs/skills/bump-fsdk-version.md +++ b/docs/skills/bump-fsdk-version.md @@ -79,9 +79,9 @@ Before merging a bump: ## Automated Point-Release Bumps -Point releases are fully automated via Renovate and GitHub Actions. -- **Trigger:** Renovate bot scans `elements/freedesktop-sdk.bst` using a custom regex manager. When a new upstream point release is published, Renovate creates a Pull Request. -- **Mechanism:** On the Renovate PR, a GHA job in `build.yml` automatically runs `just bst source track freedesktop-sdk.bst` to track and resolve the raw tag to the full `git-describe` ref, then commits and pushes it back to the PR branch. +Point releases are delivered by the scheduled `track-junctions.yml` workflow. +- **Trigger:** `track-junctions.yml` runs daily and resolves the junction's own `track: freedesktop-sdk-26.08*` glob; it does not wait on a Renovate PR. +- **Mechanism:** `track-junctions.yml` runs `just bst source track freedesktop-sdk.bst` (alongside `gnome-build-meta.bst`, which overrides it), syncs `project.conf`'s `release-version` to the tracked point release, and opens its own PR on `auto/track-junctions`. It never runs on `pull_request`, so a junction bump can never be injected into an unrelated dependency PR. - **Build Loop:** When the PR is merged to `main`, GitHub Actions automatically compiles the standalone DDI OS and installer images, and publishes them directly to GitHub Releases under the new FSDK point-release version. ## See also diff --git a/docs/skills/ci-tooling.md b/docs/skills/ci-tooling.md index e236f99f..0effa27b 100644 --- a/docs/skills/ci-tooling.md +++ b/docs/skills/ci-tooling.md @@ -59,13 +59,19 @@ permissions: The workflow checks out and executes PR-controlled code (the `Justfile` and build scripts come from the PR head), so no job that runs on `pull_request` -may hold a write token. `contents: write` is granted per job only to: +may hold a write token. In `build.yml`, `contents: write` is granted to exactly +one job: -- `track-refs` — pushes resolved BuildStream refs back to the PR branch; gated - to `renovate/*` PRs. - `release` — creates the GitHub Release and uploads assets; gated to `refs/heads/main`. +Junction ref tracking must never run on `pull_request`. It used to, as a +`track-refs` job gated on `startsWith(github.head_ref, 'renovate/')`, and a +branch name is not an identity. It also pushed its result onto whatever PR +branch happened to be open, so unrelated dependency PRs silently carried +freedesktop-sdk and gnome-build-meta bumps. It now lives in +`track-junctions.yml` on a schedule, opening its own PR on its own branch. + The `build` job (validation, compile, signing) runs with the read-only default on every event. If a new job needs additional permissions, keep them as narrow as possible and document why. @@ -83,18 +89,23 @@ The `sudo_cmd` Just variable auto-detects at recipe startup: sudo_cmd := if `podman info >/dev/null 2>&1 && echo 1 || echo 0` == "1" { "" } else { "sudo" } ``` -### No PAT/App credentials in CI +### No PATs; GitHub App tokens for automation that must trigger CI - Personal Access Tokens (PATs) are banned. - `repository_dispatch` is not used for build handoff. -- Build/release triggers are driven cleanly by Renovate PR merges or manual - dispatches. The workflow uses `secrets.GITHUB_TOKEN` for release uploads. +- `secrets.GITHUB_TOKEN` is used for release uploads inside `build.yml`. +- Automation that pushes a branch and opens a PR uses the org-wide + `mergeraptor` GitHub App (`secrets.MERGERAPTOR_APP_ID` / + `secrets.MERGERAPTOR_PRIVATE_KEY`) via `actions/create-github-app-token`, as + `projectbluefin/dakota` does. This is not cosmetic: pushes made with + `secrets.GITHUB_TOKEN` do not dispatch workflow runs, so a PR built that way + sits at `action_required` with zero jobs and never gets checks. ## Workflow Structure | Job | Workflow | Trigger | Purpose | |-----|----------|---------|---------| -| `track-refs` | `build.yml` | `pull_request` (`renovate/*` only) | Resolves BuildStream junction refs and pushes them back to the PR branch. Sole `contents: write` grant on `pull_request`. | +| `track-junctions` | `track-junctions.yml` | `schedule` (08:00 UTC), `workflow_dispatch` | Resolves the `freedesktop-sdk.bst` + `gnome-build-meta.bst` junction refs, syncs `project.conf`'s `release-version`, and opens/updates its own PR on `auto/track-junctions`. `contents: write` + `pull-requests: write`, never on `pull_request`. | | `build` | `build.yml` | `pull_request`, `push/main`, `workflow_dispatch` | Resolves the element graph, runs the full BuildStream compile (including Flatcar LTS Kernel & ZFS), and signs the release manifest on pushes to `main`. Read-only token. | | `installer-test` | `build.yml` | `pull_request`, `push/main`, `workflow_dispatch` | Downloads the build job's exported installer/PXE artifact and calls the shared `projectbluefin/actions` QEMU workflow. No Lima or second BuildStream build. | | `release` | `build.yml` | `push/main`, `workflow_dispatch` | Downloads the signed assets handed off by `build` and publishes them to the GitHub Release (`if: ${{ !failure() && !cancelled() && github.ref == 'refs/heads/main' }}`). `contents: write`. | @@ -111,9 +122,10 @@ uploaded to a GitHub Release tagged `installer-v`. 1. **Renovate tracking:** `renovate.json` is configured with a custom regex manager to scan BuildStream junction files (`freedesktop-sdk.bst` and `gnome-build-meta.bst`) using the `git-refs` datasource. -2. **Auto-resolution:** On Renovate PRs, GitHub Actions executes - `just bst source track` to resolve raw tags to full `git-describe` refs and - commits them back to the PR branch. +2. **Auto-resolution:** The scheduled `track-junctions` workflow executes + `just bst source track` to resolve raw tags to full `git-describe` refs, + syncs `release-version` to the tracked FSDK point release, and proposes the + result as its own pull request against `main`. 3. **Full Compilation:** Builds the standalone DDI OS image, live installer, and k0s systemd-sysext on every pull request and push to `main`. 4. **Installer boot test:** Uploads the already-built installer and PXE artifacts and calls `projectbluefin/actions/.github/workflows/server-installer-test.yml`. The shared workflow prepares QEMU/KVM and runs this repository's `just test-installer-artifact`; Lima remains local-only. diff --git a/workflows/server-release-watch-and-fix.md b/workflows/server-release-watch-and-fix.md index f0e4251b..fa352027 100644 --- a/workflows/server-release-watch-and-fix.md +++ b/workflows/server-release-watch-and-fix.md @@ -20,7 +20,7 @@ Specifies the automated loop that monitors GitHub Actions release runs on `proje ```bash gh run list --workflow=build.yml --limit 3 --json databaseId,status,conclusion,headSha,event ``` -2. Track job-level progression (`build`, `track-refs`, `release`). +2. Track job-level progression (`build`, `installer-test`, `release`). 3. If run fails or is cancelled, fetch failed job logs immediately: ```bash gh run view --job= --log-failed From cdb16830031d7251cb8e18cf900a8917886c6996 Mon Sep 17 00:00:00 2001 From: Bob Killen Date: Mon, 21 Sep 2026 09:06:13 -0500 Subject: [PATCH 23/42] fix(boot): resolve QEMU installer boot deadlock and console readiness probe (#220) * fix(boot): resolve QEMU installer boot deadlock and console readiness probe In `installer-test / Install and boot in QEMU`, target boot times out waiting for `/dev/disk/by-partlabel/var` and eventually fails KubeStellar Console readiness. Root causes resolved: 1. `elements/flatcar/flatcar-zfs.bst`: The extracted Flatcar ZFS system extension ships `usr/lib/systemd/system/systemd-udevd.service.d/10-zfs.conf` (`After=systemd-sysext.service`) and a tmpfiles copy rule in `usr/lib/tmpfiles.d/10-zfs.conf`. Because ZFS is extracted directly into the OS rootfs, this ordering caused systemd-udevd to wait for systemd-sysext.service, which waited for local-fs.target, which waited for var.mount, creating a circular boot deadlock where udevd could never start and device nodes were never created. Remove the drop-in, strip the tmpfiles rule, and add `sed.bst` build dependency. 2. `elements/oci/bluefin-server-ddi.bst` & `elements/oci/bluefin-server-installer.bst`: Flatcar kernel module directories reside under `/usr/lib/modules`; point `depmod -b` to `/layer/usr` and `/target-root/usr` instead of root. 3. `elements/oci/bluefin-server-ddi.bst` & `Justfile`: Mask `systemd-homed-firstboot.service` alongside `systemd-firstboot.service` on the target image and kernel cmdline to prevent headless hangs on interactive user creation prompt. 4. `Justfile` & `41-kubestellar-kiosk-proxy.yaml`: Move console readiness probe inside the guest using an injected test unit over TLS to correctly reach loopback-bound kiosk proxy and announce readiness on serial console. 5. `tests/unit/test_installer_contract.py`: Add unit contract assertions for the fixes. Fixes #218 Assisted-by: Gemini 3.8 Flash via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: mrbobbytables * fix(boot): drop dead host-side kiosk probe and rebuild cleaned zfs sysext Address review findings on #220: 1. `Justfile`: remove the host-side poll of `http://127.0.0.1:8080/healthz` from the `installer-test` smoke recipe. The PR removed the QEMU hostfwd and the kiosk proxy terminates TLS (`files/k0s/kiosk/nginx.conf`, `listen 8080 ssl`), so this probe can never reach the guest. It could only ever hit an unrelated host process on port 8080 and false-pass the smoke test. The in-guest serial `KIOSK_CONSOLE_READY` marker is now the sole readiness check. 2. `elements/flatcar/flatcar-zfs.bst`: the preserved `/usr/lib/sysexts/zfs.raw` was the untouched upstream image and still carried the `After=systemd-sysext.service` udevd drop-in this PR removes from the rootfs. Inert today, but the deadlock ordering would return if that raw were ever merged for its stated runtime sysext usage. Rebuild the raw with mksquashfs from the cleaned install root after the drop-in and tmpfiles cleanup. 3. `tests/unit/test_installer_contract.py`: assert the host-side probe is gone from the smoke recipe and that the preserved raw is rebuilt post-cleanup. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Signed-off-by: mrbobbytables Co-authored-by: mrbobbytables Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- Justfile | 41 +++++++++--- docs/skills/ddi-installer.md | 6 +- elements/flatcar/flatcar-zfs.bst | 19 +++++- elements/oci/bluefin-server-ddi.bst | 11 ++- elements/oci/bluefin-server-installer.bst | 4 +- .../41-kubestellar-kiosk-proxy.yaml | 11 +-- tests/unit/test_installer_contract.py | 67 ++++++++++++++++++- 7 files changed, 136 insertions(+), 23 deletions(-) diff --git a/Justfile b/Justfile index 1bae6d3f..ea47448f 100644 --- a/Justfile +++ b/Justfile @@ -318,6 +318,30 @@ test-installer-artifact: } trap cleanup EXIT INT TERM + # The kiosk proxy publishes hostPort 8080 on the guest's loopback only + # (files/k0s/manifests/kubestellar/41-kubestellar-kiosk-proxy.yaml), and a + # QEMU hostfwd with an unspecified guest address is delivered to the guest's + # DHCP address, never to 127.0.0.1 — so no host-side probe can reach it + # without exposing the console on the guest's external interface. Probe from + # inside the guest instead and report the verdict on the system console, + # which is already captured in $SERIAL_LOG. The proxy terminates TLS with the + # self-signed certificate baked into the k0s sysext, so the probe speaks + # https and skips certificate verification, matching tests/e2e. + READY_MARKER="KIOSK_CONSOLE_READY" + READY_UNIT=$(base64 -w0 <<'UNIT' + [Unit] + Description=Report KubeStellar Console readiness on the system console + ConditionPathExists=!/etc/initrd-release + After=k0s-first-boot.service + + [Service] + Type=oneshot + TimeoutStartSec=infinity + StandardOutput=journal+console + ExecStart=/usr/bin/bash -c 'echo "<4>kiosk-ready: polling https://127.0.0.1:8080"; i=0; until [ "$(curl --silent --fail --insecure --max-time 2 https://127.0.0.1:8080/healthz | jq -r .status)" = ok ] && [ "$(curl --silent --fail --insecure --max-time 2 --output /dev/null --write-out "%%{http_code}" https://127.0.0.1:8080/)" = 200 ]; do i=$((i+1)); if [ $((i %% 15)) -eq 0 ]; then echo "<4>kiosk-ready: waiting k0s=$(systemctl is-active k0scontroller.service) hz=$(curl -sk -o /dev/null -w "%%{http_code}" --max-time 2 https://127.0.0.1:8080/healthz) root=$(curl -sk -o /dev/null -w "%%{http_code}" --max-time 2 https://127.0.0.1:8080/) pods=$(k0s kubectl get pods -A --no-headers 2>/dev/null | wc -l) running=$(k0s kubectl get pods -A --no-headers 2>/dev/null | grep -c Running)"; fi; sleep 2; done; echo "<4>KIOSK_CONSOLE_READY"' + UNIT + ) + echo "==> Booting the installed server in QEMU (background)..." qemu-system-x86_64 \ -enable-kvm \ @@ -327,9 +351,10 @@ test-installer-artifact: -drive file="$WORKDIR/target.raw",format=raw,if=virtio \ -drive if=pflash,format=raw,readonly=on,file="$OVMF_CODE" \ -drive if=pflash,format=raw,file="$WORKDIR/ovmf-vars.fd" \ - -nic user,model=virtio-net-pci,hostfwd=tcp:127.0.0.1:8080-:8080 \ + -nic user,model=virtio-net-pci \ -smbios "type=11,value=io.systemd.credential.binary:fstab.extra=L2Rldi9kaXNrL2J5LXBhcnRsYWJlbC92YXIgL3ZhciB4ZnMgZGVmYXVsdHMgMCAwCg==" \ - -smbios "type=11,value=io.systemd.stub.kernel-cmdline-extra=console=tty0 console=ttyS0,,115200 systemd.mask=systemd-firstboot.service" \ + -smbios "type=11,value=io.systemd.credential.binary:systemd.extra-unit.bluefin-kiosk-ready.service=${READY_UNIT}" \ + -smbios "type=11,value=io.systemd.stub.kernel-cmdline-extra=console=tty0 console=ttyS0,,115200 systemd.mask=systemd-firstboot.service systemd.mask=systemd-homed-firstboot.service systemd.wants=bluefin-kiosk-ready.service" \ -nographic \ -serial file:"$SERIAL_LOG" \ -monitor none & @@ -337,7 +362,7 @@ test-installer-artifact: DEADLINE_SECS="${SHOW_ME_THE_FUTURE_DEADLINE:-${SHOW_ME_THE_FUTURE_TIMEOUT:-600}}" START_TIME=$(date +%s) - echo "==> Polling KubeStellar Console readiness at http://127.0.0.1:8080 (deadline: ${DEADLINE_SECS}s)..." + echo "==> Polling KubeStellar Console readiness from inside the guest (deadline: ${DEADLINE_SECS}s)..." while true; do if ! kill -0 "$TARGET_QEMU_PID" 2>/dev/null; then @@ -349,13 +374,9 @@ test-installer-artifact: exit 1 fi - HEALTHZ_JSON=$(curl --silent --fail --max-time 2 http://127.0.0.1:8080/healthz 2>/dev/null || true) - if [ -n "$HEALTHZ_JSON" ] && echo "$HEALTHZ_JSON" | jq -e '.status == "ok"' >/dev/null 2>&1; then - ROOT_CODE=$(curl --silent --fail --max-time 2 --output /dev/null --write-out "%{http_code}" http://127.0.0.1:8080/ 2>/dev/null || true) - if [ "$ROOT_CODE" = "200" ]; then - echo "==> KubeStellar Console is healthy: /healthz status ok, / returned HTTP 200" - break - fi + if grep -q "$READY_MARKER" "$SERIAL_LOG" 2>/dev/null; then + echo "==> KubeStellar Console is healthy: /healthz status ok, / returned HTTP 200" + break fi NOW=$(date +%s) diff --git a/docs/skills/ddi-installer.md b/docs/skills/ddi-installer.md index a511f943..d073014f 100644 --- a/docs/skills/ddi-installer.md +++ b/docs/skills/ddi-installer.md @@ -48,8 +48,10 @@ terminal-based interactive installation that: User provisioning is handled on the target system's first boot via systemd system credentials (`systemd-sysusers`, `systemd-tmpfiles`) so the base image -remains stateless. `systemd-firstboot.service` is masked on the target image -(`/etc/systemd/system/systemd-firstboot.service -> /dev/null`) to guarantee +remains stateless. `systemd-firstboot.service` and +`systemd-homed-firstboot.service` are masked on the target image +(`/etc/systemd/system/systemd-firstboot.service -> /dev/null` and +`/etc/systemd/system/systemd-homed-firstboot.service -> /dev/null`) to guarantee unattended, prompt-free startup. The target DDI also pre-stages the extracted CA certificate bundle (`/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem` and `/etc/ssl/certs/ca-certificates.crt`) and a standard `/etc/hosts` file for diff --git a/elements/flatcar/flatcar-zfs.bst b/elements/flatcar/flatcar-zfs.bst index 82832969..eabdcf8e 100644 --- a/elements/flatcar/flatcar-zfs.bst +++ b/elements/flatcar/flatcar-zfs.bst @@ -10,6 +10,7 @@ description: | build-depends: - base/base-stack.bst + - freedesktop-sdk.bst:components/sed.bst - freedesktop-sdk.bst:components/squashfs-tools.bst variables: @@ -28,6 +29,20 @@ config: # Extract the SquashFS sysext directly into the element install root unsquashfs -no-xattrs -f -d "%{install-root}" flatcar-zfs.raw - # Also preserve the raw sysext image under /usr/lib/sysexts for runtime sysext usage + # Drop Flatcar's udevd sysext ordering override. In Flatcar, ZFS is loaded as + # a runtime sysext, so udevd was ordered After=systemd-sysext.service. + # In Bluefin Server, ZFS is extracted directly into the OS rootfs at build time. + # Leaving this drop-in causes systemd-udevd to wait for systemd-sysext.service, + # which waits for local-fs.target, which waits for var.mount, which waits for + # the udev device unit — creating a boot deadlock. + rm -rf "%{install-root}/usr/lib/systemd/system/systemd-udevd.service.d" + if [ -f "%{install-root}/usr/lib/tmpfiles.d/10-zfs.conf" ]; then + sed -i "/systemd-udevd\.service\.d/d" "%{install-root}/usr/lib/tmpfiles.d/10-zfs.conf" + fi + + # Preserve a raw sysext image under /usr/lib/sysexts for runtime sysext usage. + # Rebuild it from the cleaned tree rather than shipping the upstream image, so + # the udevd ordering override above cannot reappear if the raw is ever merged. + mksquashfs "%{install-root}" zfs-cleaned.raw -noappend -no-xattrs -all-root mkdir -p "%{install-root}/usr/lib/sysexts" - install -D -m 0644 flatcar-zfs.raw "%{install-root}/usr/lib/sysexts/zfs.raw" + install -D -m 0644 zfs-cleaned.raw "%{install-root}/usr/lib/sysexts/zfs.raw" diff --git a/elements/oci/bluefin-server-ddi.bst b/elements/oci/bluefin-server-ddi.bst index 9f801570..ab161db0 100644 --- a/elements/oci/bluefin-server-ddi.bst +++ b/elements/oci/bluefin-server-ddi.bst @@ -38,7 +38,7 @@ config: exit 1 fi rm -f "/layer/usr/lib/modules/${KVER}/vmlinux" "/layer/usr/lib/modules/${KVER}/System.map" - depmod -b /layer "${KVER}" + depmod -b /layer/usr "${KVER}" # Stage extracted CA certificate bundle into target DDI rootfs mkdir -p /layer/etc/pki/ca-trust/extracted /layer/etc/ssl/certs /layer/etc/pki/tls/certs @@ -47,9 +47,16 @@ config: ln -sf /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem /layer/etc/pki/tls/certs/ca-bundle.crt ln -sf /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem /layer/etc/pki/tls/cert.pem - # Mask systemd-firstboot to prevent interactive prompts on headless first boot + # Mask both first-boot wizards to prevent interactive prompts on headless + # first boot: systemd-firstboot.service prompts for locale/keymap/timezone/ + # root password, and systemd-homed-firstboot.service runs + # `homectl firstboot --prompt-new-user`. Both are ConditionFirstBoot=yes, + # read StandardInput=tty, and order themselves before + # first-boot-complete.target, so either one blocks the boot transaction + # forever on a console nobody is attached to. mkdir -p /layer/etc/systemd/system ln -sf /dev/null /layer/etc/systemd/system/systemd-firstboot.service + ln -sf /dev/null /layer/etc/systemd/system/systemd-homed-firstboot.service # Mask audit-rules to prevent failure on shell-free OS (augenrules requires /bin/sh) ln -sf /dev/null /layer/etc/systemd/system/audit-rules.service diff --git a/elements/oci/bluefin-server-installer.bst b/elements/oci/bluefin-server-installer.bst index 44d9f300..ab95bc43 100644 --- a/elements/oci/bluefin-server-installer.bst +++ b/elements/oci/bluefin-server-installer.bst @@ -103,7 +103,7 @@ config: mkdir -p /target-root/boot ln -sf "../usr/lib/modules/${TARGET_KVER}/vmlinuz" /target-root/boot/vmlinuz - depmod -b /target-root "${TARGET_KVER}" || true + depmod -b /target-root/usr "${TARGET_KVER}" || true # Configure dynamic linker search paths so ldconfig indexes FSDK libraries # (e.g. libc.so.6, libgcc_s.so.1, libkmod.so) for dracut-install @@ -360,7 +360,7 @@ config: rm -rf "${MOD_DIR}/drivers/infiniband" fi # Re-run depmod to update module dependencies after stripping unneeded modules - depmod -b /layer "${KVER}" || true + depmod -b /layer/usr "${KVER}" || true fi ( cd /layer && find . -print0 \ diff --git a/files/k0s/manifests/kubestellar/41-kubestellar-kiosk-proxy.yaml b/files/k0s/manifests/kubestellar/41-kubestellar-kiosk-proxy.yaml index 80e38d5a..8ade0861 100644 --- a/files/k0s/manifests/kubestellar/41-kubestellar-kiosk-proxy.yaml +++ b/files/k0s/manifests/kubestellar/41-kubestellar-kiosk-proxy.yaml @@ -29,10 +29,13 @@ spec: - /etc/kubestellar-kiosk/nginx.conf ports: - containerPort: 8080 - # Kiosk-only proxy: bind loopback so the console is not exposed on - # LAN interfaces over plaintext HTTP. The VM flow reaches it via the - # existing hostfwd of 127.0.0.1:8080; LAN access, if ever wanted, - # must go through a TLS-terminating, authenticated front end. + # Kiosk-only proxy: bind loopback so the console is never published on + # the node's external interfaces. A QEMU hostfwd cannot reach this + # binding, because libslirp delivers a forward with an unspecified + # guest address to the guest's DHCP address rather than to 127.0.0.1; + # the installer smoke test therefore probes the proxy from inside the + # guest. LAN access, if ever wanted, must go through an + # authenticated front end. hostIP: 127.0.0.1 hostPort: 8080 name: http diff --git a/tests/unit/test_installer_contract.py b/tests/unit/test_installer_contract.py index d423c685..73a3d78d 100644 --- a/tests/unit/test_installer_contract.py +++ b/tests/unit/test_installer_contract.py @@ -14,6 +14,7 @@ ) JUSTFILE = REPO_ROOT / "Justfile" DDI_ELEMENT = REPO_ROOT / "elements" / "oci" / "bluefin-server-ddi.bst" +FLATCAR_ZFS_ELEMENT = REPO_ROOT / "elements" / "flatcar" / "flatcar-zfs.bst" def _published_uki_cmdline(installer_element: str) -> str: @@ -92,10 +93,11 @@ def test_ddi_generates_module_indexes_for_runtime_filesystem_drivers() -> None: ddi_element = DDI_ELEMENT.read_text(encoding="utf-8") assert "freedesktop-sdk.bst:components/kmod.bst" in ddi_element - assert 'depmod -b /layer "${KVER}"' in ddi_element + assert 'depmod -b /layer/usr "${KVER}"' in ddi_element assert "cp -a /etc/pki/ca-trust/extracted/* /layer/etc/pki/ca-trust/extracted/" in ddi_element assert "tls-ca-bundle.pem" in ddi_element assert "ln -sf /dev/null /layer/etc/systemd/system/systemd-firstboot.service" in ddi_element + assert "ln -sf /dev/null /layer/etc/systemd/system/systemd-homed-firstboot.service" in ddi_element assert "ln -sf /dev/null /layer/etc/systemd/system/audit-rules.service" in ddi_element assert "printf '127.0.0.1 localhost" in ddi_element assert "> /layer/etc/hosts" in ddi_element @@ -135,3 +137,66 @@ def test_installer_and_ddi_strip_vmlinux_and_static_archives() -> None: assert "find /layer -type f -name '*.a' -delete" in installer_element assert 'rm -f "/layer/usr/lib/modules/${KVER}/vmlinux"' in ddi_element assert "find /layer -type f -name '*.a' -delete" in ddi_element + + +def test_flatcar_zfs_removes_udevd_sysext_ordering_dropin() -> None: + flatcar_zfs = FLATCAR_ZFS_ELEMENT.read_text(encoding="utf-8") + + assert ( + 'rm -rf "%{install-root}/usr/lib/systemd/system/systemd-udevd.service.d"' + in flatcar_zfs + ) + assert ( + 'sed -i "/systemd-udevd\\.service\\.d/d" "%{install-root}/usr/lib/tmpfiles.d/10-zfs.conf"' + in flatcar_zfs + ) + assert "freedesktop-sdk.bst:components/sed.bst" in flatcar_zfs + + # The preserved raw sysext must be rebuilt from the cleaned tree, not the + # untouched upstream image, so the ordering override cannot come back if the + # raw is ever merged at runtime. + assert "install -D -m 0644 flatcar-zfs.raw" not in flatcar_zfs + assert ( + 'mksquashfs "%{install-root}" zfs-cleaned.raw -noappend -no-xattrs -all-root' + in flatcar_zfs + ) + assert flatcar_zfs.index("mksquashfs") > flatcar_zfs.index( + 'rm -rf "%{install-root}/usr/lib/systemd/system/systemd-udevd.service.d"' + ) + + +def test_var_partition_contracts_use_consistent_partlabel() -> None: + import base64 + + repart_var = ( + REPO_ROOT / "files" / "installer" / "repart.d" / "30-var.conf" + ).read_text(encoding="utf-8") + ddi_element = DDI_ELEMENT.read_text(encoding="utf-8") + var_mount = ( + REPO_ROOT / "files" / "os" / "systemd" / "system" / "var.mount" + ).read_text(encoding="utf-8") + justfile = JUSTFILE.read_text(encoding="utf-8") + + assert "Label=var" in repart_var + assert "/dev/disk/by-partlabel/var /var xfs defaults 0 0" in ddi_element + assert "What=/dev/disk/by-partlabel/var" in var_mount + expected_b64 = base64.b64encode( + b"/dev/disk/by-partlabel/var /var xfs defaults 0 0\n" + ).decode("ascii") + assert expected_b64 in justfile + + +def test_installer_smoke_probes_the_kiosk_over_tls_from_inside_the_guest() -> None: + justfile = JUSTFILE.read_text(encoding="utf-8") + assert "systemd.mask=systemd-homed-firstboot.service" in justfile + assert "https://127.0.0.1:8080/healthz" in justfile + assert "--insecure" in justfile + assert "systemd.extra-unit.bluefin-kiosk-ready.service" in justfile + assert "systemd.wants=bluefin-kiosk-ready.service" in justfile + # The host cannot reach the guest's loopback-bound kiosk proxy, so no + # host-side probe may remain in the smoke test — a stray host process on + # port 8080 would otherwise let it pass without the guest being ready. + smoke = justfile.split("install-vm:")[0] + assert "http://127.0.0.1:8080/healthz" not in smoke + assert "KIOSK_CONSOLE_READY" in smoke + From e13f4a6be25a4ef495bcf3352f0e6d9d50ba9afc Mon Sep 17 00:00:00 2001 From: "Jorge O. Castro" Date: Mon, 21 Sep 2026 10:14:49 -0400 Subject: [PATCH 24/42] fix(installer): hard preflight abort when bluefin-installer-data is absent (#224) Add a hard preflight check before any installation begins: if /dev/disk/by-partlabel/bluefin-installer-data is absent or not a block device, abort with diagnostic lsblk and /dev/disk/by-partlabel output. This prevents unattended disk discovery from falling back to an empty installer partition and potentially selecting and erasing its own installation media on bare-metal USB drives. Assisted-by: github-copilot/gemini-3.8-flash via GitHub Copilot Co-authored-by: Jorge Castro Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- elements/oci/bluefin-server-installer.bst | 14 ++++++++++++-- tests/unit/test_installer_contract.py | 8 ++++++++ 2 files changed, 20 insertions(+), 2 deletions(-) diff --git a/elements/oci/bluefin-server-installer.bst b/elements/oci/bluefin-server-installer.bst index ab95bc43..646308ea 100644 --- a/elements/oci/bluefin-server-installer.bst +++ b/elements/oci/bluefin-server-installer.bst @@ -194,10 +194,20 @@ config: modprobe -q xfs || true udevadm trigger --subsystem-match=block || true udevadm settle --timeout=15 || true + # Hard preflight: abort with diagnostics if installer data partition is absent or not a block device + INSTALLER_PART_PATH="/dev/disk/by-partlabel/bluefin-installer-data" + if [ ! -b "${INSTALLER_PART_PATH}" ]; then + echo "ERROR: Installer data partition '${INSTALLER_PART_PATH}' is missing or not a block device!" >&2 + echo "==> Block devices visible at failure:" >&2 + lsblk -p -o NAME,TYPE,PARTLABEL,PKNAME,SIZE,FSTYPE >&2 || true + echo "==> Partition label symlinks visible under /dev/disk/by-partlabel/:" >&2 + ls -la /dev/disk/by-partlabel/ >&2 || true + exit 1 + fi + INSTALLER_PART="$(readlink -f "${INSTALLER_PART_PATH}")" + # Auto-detect target disk for unattended install (any raw disk of type "disk" that is not the installer, is not read-only, and has size > 0) TARGET_DISK="" - INSTALLER_PART="$(readlink -f /dev/disk/by-partlabel/bluefin-installer-data 2>/dev/null || true)" - while read -r name type ro size; do [ "${type}" = "disk" ] || continue [ "${ro}" = "0" ] || continue diff --git a/tests/unit/test_installer_contract.py b/tests/unit/test_installer_contract.py index 73a3d78d..114df0b3 100644 --- a/tests/unit/test_installer_contract.py +++ b/tests/unit/test_installer_contract.py @@ -123,6 +123,14 @@ def test_installer_loads_storage_drivers_and_settles_udev() -> None: assert "After=systemd-udev-settle.service" in installer_element assert "Wants=systemd-udev-settle.service" in installer_element + +def test_installer_hard_preflight_aborts_on_missing_installer_data_part() -> None: + installer_element = INSTALLER_ELEMENT.read_text(encoding="utf-8") + + assert '[ ! -b "${INSTALLER_PART_PATH}" ]' in installer_element + assert "/dev/disk/by-partlabel/bluefin-installer-data" in installer_element + assert "lsblk -p -o NAME,TYPE,PARTLABEL,PKNAME,SIZE,FSTYPE" in installer_element + def test_interactive_installer_uses_local_virtual_console() -> None: installer_element = INSTALLER_ELEMENT.read_text(encoding="utf-8") From f9bdef4671b0a00c3330a5db73da61464c762415 Mon Sep 17 00:00:00 2001 From: "Jorge O. Castro" Date: Tue, 22 Sep 2026 00:26:50 -0400 Subject: [PATCH 25/42] fix(justfile): probe install-vm kiosk readiness from inside the guest (rebased) (#227) * fix(justfile): probe install-vm kiosk readiness from inside the guest The kiosk proxy publishes hostPort 8080 on the guest's loopback only (files/k0s/manifests/kubestellar/41-kubestellar-kiosk-proxy.yaml) and terminates TLS (files/k0s/kiosk/nginx.conf, `listen 8080 ssl`). This broke install-vm's readiness wait and advertised access URLs the same way #218/#220 diagnosed for the installer-test smoke recipe: 1. A QEMU/libslirp hostfwd with an unspecified guest address is delivered to the guest's DHCP address, never to 127.0.0.1, so hostfwd=tcp::8080-:8080 could never reach the loopback-bound proxy. 2. The host-side poll spoke plain HTTP against a TLS listener. 3. The printed LAN/local access URLs and xdg-open call were therefore unreachable. Probe readiness from inside the guest instead: inject a oneshot systemd unit via an smbios(11) credential that polls the proxy over TLS from inside the guest and echoes a marker on the system console, which is captured to a host-side serial log file the host polls instead of curl. This is the same in-guest-probe approach proposed for test-installer-artifact in #220 (not yet merged); test-installer- artifact itself still probes from the host on this branch. Order ttyS0 last on the kernel cmdline so /dev/console resolves to the serial device the host captures, matching the ordering test-installer-artifact already uses for the same reason. The in-guest probe deliberately does not parse the /healthz response body: curl --fail already fails on a non-2xx response, which is exactly "healthz ok and / returns 200", and it avoids embedding quotes inside a systemd ExecStart= line, whose escaping rules differ from a plain shell. Drop the non-working direct 8080 hostfwd and the LAN/local URLs and xdg-open call that depended on it; print instructions for reaching the console from the host over an SSH tunnel through the existing hostfwd=tcp::2222-:22 forward instead, per the issue's suggested direction. Preserve the unrelated hostfwd=tcp::6443-:6443 (Kubernetes API) forward. Correct the kiosk proxy manifest comment, which still claimed the VM flow reaches the proxy via the existing hostfwd. Fixes #222 Assisted-by: Claude (Anthropic) via Hive Signed-off-by: Danathar * fix(os): correct login banner and de-brittle the jq test assertion files/os/issue.d/40-kubestellar.issue still advertised 'KubeStellar Console: http://\4:8080/ (or http://127.0.0.1:8080 from host)', which is doubly wrong after this PR: the proxy binds guest loopback and terminates TLS, and the direct 8080 hostfwd is gone. Fix in-scope rather than deferring, since the fix is one line and the PR already changed the reachability story the banner describes: point at https://127.0.0.1:8080/ and name the SSH tunnel the Justfile recipe now prints instead. Anchor test_install_vm_kiosk_readiness.py's jq-absence check to the ExecStart= line instead of the whole recipe body, so a future comment or variable elsewhere in the recipe containing 'jq' cannot fail it for the wrong reason, and it stays anchored to the actual contract: the ExecStart command line has no jq in it. Verified test_install_vm_kiosk_readiness.py's four module-level tests directly (no pytest in this environment): all pass, including the updated assertion. test_console_issue.py needs PyYAML, unavailable here; its one-line assertion update is a straight text match against the corrected banner and needs a real run in CI before merge. Signed-off-by: Danathar * fix(os): reformat login banner for TTY legibility The banner line grew from 71 to ~152 chars and would wrap badly on an 80-column console -- the entire point of /etc/issue.d is legibility at a getty prompt. Split it across two lines and dropped the markdown backticks, which render literally there: KubeStellar Console: https://127.0.0.1:8080/ (loopback, TLS only) Remote access: ssh -L 8080:127.0.0.1:8080 @ Added an assertion for the tunnel line to tests/unit/test_console_issue.py. Mutation-tested the ExecStart jq guard against the real Justfile instead of an in-memory copy: piped the echo through 'jq -R .', confirmed test_install_vm_probes_readiness_inside_the_guest_over_tls fails, reverted. Inverse check: added a harmless '# jq' comment elsewhere in the install-vm recipe, confirmed the test still passes -- proving the anchor to the ExecStart= line, not just narrowing the match by luck. Signed-off-by: Danathar * fix(justfile): verify target partition layout before marking install complete Assert that bluefin-server-root-a and var partitions exist on TARGET_RAW before touching INSTALL_COMPLETE, preventing failed QEMU installer runs from falsely marking installation as finished. Assisted-by: github-copilot/gemini-3.8-flash via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(justfile): use sfdisk --json to parse regular target disk partition table in install-vm lsblk does not inspect partitions inside a regular file image; use sfdisk --json and jq to parse partitiontable.partitions.name instead. Assisted-by: github-copilot/gemini-3.8-flash via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(justfile): mount /var and bound readiness wait in install-vm The installed target carries no fstab entry for /var and gpt-auto cannot mount it, so the install-vm boot needs the same SMBIOS fstab.extra credential test-installer-artifact passes. Without it, k0s state (and the kiosk proxy it serves) is missing and the readiness marker never appears. Bound the readiness wait with INSTALL_VM_READY_DEADLINE (default 600s) and dump the serial log tail on timeout or premature QEMU exit, so a broken guest boot fails loudly instead of hanging forever. Also document why the target partition layout is verified before marking the install complete, and tell the operator to re-run the installer when an interactive install was aborted. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Signed-off-by: Danathar Co-authored-by: Danathar Co-authored-by: Jorge Castro Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: sec-check[bot] --- Justfile | 95 +++++++++++++- .../41-kubestellar-kiosk-proxy.yaml | 10 +- files/os/issue.d/40-kubestellar.issue | 3 +- tests/unit/test_console_issue.py | 3 +- tests/unit/test_install_vm_kiosk_readiness.py | 122 ++++++++++++++++++ 5 files changed, 220 insertions(+), 13 deletions(-) create mode 100644 tests/unit/test_install_vm_kiosk_readiness.py diff --git a/Justfile b/Justfile index ea47448f..724c30ce 100644 --- a/Justfile +++ b/Justfile @@ -465,10 +465,66 @@ install-vm: -drive file="$TARGET_RAW",format=raw,if=virtio \ -drive if=pflash,format=raw,readonly=on,file="$OVMF_CODE" \ -drive if=pflash,format=raw,file="$OVMF_VARS" + # The interactive installer is driven by hand, so it can be aborted or + # fail without a non-zero exit here. Marking the install complete in that + # case caches a broken target that every later run boots forever. Gate + # the marker on the partition labels files/repart.d creates; an aborted + # install now fails loudly and re-runs the installer next invocation + # instead of silently booting an unusable disk. + echo "==> Verifying target partition layout before marking installation complete..." + TARGET_PARTS=$(sfdisk --json "$TARGET_RAW" 2>/dev/null | jq -r '.partitiontable.partitions[]?.name // empty' || true) + if ! echo "$TARGET_PARTS" | grep -Fxq 'bluefin-server-root-a' || \ + ! echo "$TARGET_PARTS" | grep -Fxq 'var'; then + echo "ERROR: Target disk $TARGET_RAW does not contain expected partitions (bluefin-server-root-a, var)!" >&2 + echo "The installation did not complete; re-run 'just install-vm' to install again." >&2 + echo "Observed partitions:" >&2 + echo "$TARGET_PARTS" >&2 + sfdisk -l "$TARGET_RAW" >&2 || true + exit 1 + fi touch "$INSTALL_COMPLETE" fi echo "==> Booting the installed kiosk..." + SERIAL_LOG="$STATE_DIR/kiosk-serial.log" + : > "$SERIAL_LOG" + + # The kiosk proxy binds hostPort 8080 on the guest's loopback interface only + # (files/k0s/manifests/kubestellar/41-kubestellar-kiosk-proxy.yaml) and + # terminates TLS (files/k0s/kiosk/nginx.conf, `listen 8080 ssl`). A + # QEMU/libslirp hostfwd with an unspecified guest address is delivered to + # the guest's DHCP address, never to 127.0.0.1, so a host-side forward of + # 8080 can never reach the proxy, and a plaintext probe would fail against + # its TLS listener regardless. Probe readiness from inside the guest + # instead and report the verdict on the system console, which is captured + # in $SERIAL_LOG — the same in-guest-probe approach proposed for + # test-installer-artifact in #220. Host access, when wanted, goes over + # the existing SSH hostfwd rather than a direct (non-working) 8080 + # forward. The readiness check deliberately does not parse the /healthz + # response body: curl --fail already fails on a non-2xx response, which + # is exactly "healthz ok and / returns 200", and it avoids embedding + # quotes inside a systemd ExecStart= line, where escaping rules differ + # from a plain shell. + # The installed image carries no fstab entry for /var and gpt-auto cannot + # mount it, so /var (which holds k0s state and therefore the kiosk proxy) + # stays empty unless the same SMBIOS fstab.extra credential + # test-installer-artifact passes is supplied here too. Without it k0s never + # starts and the readiness marker never appears. + READY_MARKER="KIOSK_CONSOLE_READY" + READY_UNIT=$(base64 -w0 <<'UNIT' + [Unit] + Description=Report KubeStellar Console readiness on the system console + ConditionPathExists=!/etc/initrd-release + After=k0s-first-boot.service + + [Service] + Type=oneshot + TimeoutStartSec=infinity + StandardOutput=journal+console + ExecStart=/usr/bin/bash -c 'until curl --silent --fail --insecure --max-time 2 --output /dev/null https://127.0.0.1:8080/healthz && curl --silent --fail --insecure --max-time 2 --output /dev/null https://127.0.0.1:8080/; do sleep 2; done; echo KIOSK_CONSOLE_READY' + UNIT + ) + qemu-system-x86_64 \ -enable-kvm \ -m "${MEM_SIZE}" \ @@ -477,7 +533,11 @@ install-vm: -drive file="$TARGET_RAW",format=raw,if=virtio \ -drive if=pflash,format=raw,readonly=on,file="$OVMF_CODE" \ -drive if=pflash,format=raw,file="$OVMF_VARS" \ - -nic user,model=virtio-net-pci,hostfwd=tcp::8080-:8080,hostfwd=tcp::2222-:22,hostfwd=tcp::6443-:6443 & + -nic user,model=virtio-net-pci,hostfwd=tcp::2222-:22,hostfwd=tcp::6443-:6443 \ + -smbios "type=11,value=io.systemd.credential.binary:fstab.extra=L2Rldi9kaXNrL2J5LXBhcnRsYWJlbC92YXIgL3ZhciB4ZnMgZGVmYXVsdHMgMCAwCg==" \ + -smbios "type=11,value=io.systemd.credential.binary:systemd.extra-unit.bluefin-kiosk-ready.service=${READY_UNIT}" \ + -smbios "type=11,value=io.systemd.stub.kernel-cmdline-extra=console=tty0 console=ttyS0,,115200 systemd.wants=bluefin-kiosk-ready.service" \ + -serial file:"$SERIAL_LOG" & QEMU_PID=$! cleanup() { if kill -0 "$QEMU_PID" 2>/dev/null; then @@ -487,19 +547,42 @@ install-vm: } trap cleanup INT TERM - until curl --silent --show-error --max-time 2 --output /dev/null http://127.0.0.1:8080/; do + READY_DEADLINE_SECS="${INSTALL_VM_READY_DEADLINE:-600}" + READY_START_TIME=$(date +%s) + echo "==> Waiting for the KubeStellar Console to become ready inside the guest (deadline: ${READY_DEADLINE_SECS}s)..." + until grep -q "$READY_MARKER" "$SERIAL_LOG" 2>/dev/null; do if ! kill -0 "$QEMU_PID" 2>/dev/null; then + echo "ERROR: QEMU process ($QEMU_PID) died before the kiosk became ready!" >&2 + if [ -f "$SERIAL_LOG" ]; then + echo "==> Serial log tail (last 100 lines):" >&2 + tail -n 100 "$SERIAL_LOG" >&2 + fi wait "$QEMU_PID" exit 1 fi + + NOW=$(date +%s) + ELAPSED=$((NOW - READY_START_TIME)) + if [ "$ELAPSED" -ge "$READY_DEADLINE_SECS" ]; then + echo "ERROR: Timed out after ${READY_DEADLINE_SECS}s waiting for KubeStellar Console readiness!" >&2 + if [ -f "$SERIAL_LOG" ]; then + echo "==> Serial log tail (last 100 lines):" >&2 + tail -n 100 "$SERIAL_LOG" >&2 + fi + cleanup + exit 1 + fi + sleep 2 done - HOST_IP="$(ip -4 -o addr show scope global | awk '{print $4}' | cut -d/ -f1 | head -n1)" echo "==> KubeStellar Console is ready!" - echo "==> Access URL (LAN): http://${HOST_IP:-localhost}:8080/" - echo "==> Access URL (Local): http://localhost:8080/" - xdg-open "http://${HOST_IP:-localhost}:8080/" || xdg-open http://localhost:8080/ || true + echo "==> The kiosk proxy binds the guest's loopback interface only and terminates" + echo "==> TLS with a self-signed certificate, so it is not directly reachable from" + echo "==> the host. To view it in a host browser, start sshd inside the VM" + echo "==> (systemctl start sshd) and open a tunnel over the forwarded SSH port:" + echo "==> ssh -p 2222 -L 8080:127.0.0.1:8080 @127.0.0.1" + echo "==> then browse https://localhost:8080/ and accept the self-signed certificate." wait "$QEMU_PID" # Set up KubeStellar kc-agent for the user in ONE command. diff --git a/files/k0s/manifests/kubestellar/41-kubestellar-kiosk-proxy.yaml b/files/k0s/manifests/kubestellar/41-kubestellar-kiosk-proxy.yaml index 8ade0861..588288ae 100644 --- a/files/k0s/manifests/kubestellar/41-kubestellar-kiosk-proxy.yaml +++ b/files/k0s/manifests/kubestellar/41-kubestellar-kiosk-proxy.yaml @@ -30,11 +30,11 @@ spec: ports: - containerPort: 8080 # Kiosk-only proxy: bind loopback so the console is never published on - # the node's external interfaces. A QEMU hostfwd cannot reach this - # binding, because libslirp delivers a forward with an unspecified - # guest address to the guest's DHCP address rather than to 127.0.0.1; - # the installer smoke test therefore probes the proxy from inside the - # guest. LAN access, if ever wanted, must go through an + # the node's external interfaces. A QEMU/libslirp hostfwd with an + # unspecified guest address is delivered to the guest's DHCP address, + # not to 127.0.0.1, so no QEMU hostfwd can reach this binding; + # `just install-vm` and the installer smoke test probe the proxy from + # inside the guest instead. LAN access, if ever wanted, must go through an # authenticated front end. hostIP: 127.0.0.1 hostPort: 8080 diff --git a/files/os/issue.d/40-kubestellar.issue b/files/os/issue.d/40-kubestellar.issue index 61319dc5..862fc3b5 100644 --- a/files/os/issue.d/40-kubestellar.issue +++ b/files/os/issue.d/40-kubestellar.issue @@ -1,5 +1,6 @@ Bluefin Server (\l) Default login: root / bluefin -KubeStellar Console: http://\4:8080/ (or http://127.0.0.1:8080 from host) +KubeStellar Console: https://127.0.0.1:8080/ (loopback, TLS only) +Remote access: ssh -L 8080:127.0.0.1:8080 @ diff --git a/tests/unit/test_console_issue.py b/tests/unit/test_console_issue.py index af83ead1..809fc946 100644 --- a/tests/unit/test_console_issue.py +++ b/tests/unit/test_console_issue.py @@ -15,7 +15,8 @@ def test_issue_file_exists_and_contains_kubestellar_url() -> None: assert ISSUE_FILE.is_file(), f"{ISSUE_FILE} must exist" content = ISSUE_FILE.read_text(encoding="utf-8") assert "Bluefin Server" in content - assert "KubeStellar Console: http://\\4:8080/" in content + assert "KubeStellar Console: https://127.0.0.1:8080/" in content + assert "ssh -L 8080:127.0.0.1:8080" in content def test_os_issue_element_target_usr_lib_issue_d() -> None: diff --git a/tests/unit/test_install_vm_kiosk_readiness.py b/tests/unit/test_install_vm_kiosk_readiness.py new file mode 100644 index 00000000..67a875a5 --- /dev/null +++ b/tests/unit/test_install_vm_kiosk_readiness.py @@ -0,0 +1,122 @@ +"""Contracts for `just install-vm` reaching the loopback-bound, TLS-terminating +kiosk proxy (files/k0s/manifests/kubestellar/41-kubestellar-kiosk-proxy.yaml, +files/k0s/kiosk/nginx.conf).""" + +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] +JUSTFILE = ROOT / "Justfile" +KIOSK_PROXY_MANIFEST = ( + ROOT / "files/k0s/manifests/kubestellar/41-kubestellar-kiosk-proxy.yaml" +) + + +def _install_vm_recipe() -> str: + justfile = JUSTFILE.read_text(encoding="utf-8") + start = justfile.index("install-vm:") + end = justfile.index("setup-kubestellar", start) + return justfile[start:end] + + +def test_install_vm_drops_the_unreachable_direct_kiosk_forward() -> None: + recipe = _install_vm_recipe() + + # A QEMU/libslirp hostfwd with an unspecified guest address is delivered + # to the guest's DHCP address, never to 127.0.0.1, so it can never reach + # a loopback-bound service. This forward must be gone, and the host must + # not claim a URL it cannot reach. + assert "hostfwd=tcp::8080-:8080" not in recipe + assert "http://127.0.0.1:8080/" not in recipe + assert "http://${HOST_IP" not in recipe + assert "xdg-open" not in recipe + + # Unrelated forwards used elsewhere in the recipe must survive. + assert "hostfwd=tcp::2222-:22" in recipe + assert "hostfwd=tcp::6443-:6443" in recipe + + +def test_install_vm_probes_readiness_inside_the_guest_over_tls() -> None: + recipe = _install_vm_recipe() + + # Readiness is probed from inside the guest, over TLS (the proxy + # terminates TLS with a self-signed certificate), and reported on the + # system console, which is captured to a host-side serial log file. + assert "https://127.0.0.1:8080/healthz" in recipe + assert "--insecure" in recipe + assert "systemd.extra-unit.bluefin-kiosk-ready.service" in recipe + assert "systemd.wants=bluefin-kiosk-ready.service" in recipe + assert "-serial file:" in recipe + assert 'SERIAL_LOG="$STATE_DIR/kiosk-serial.log"' in recipe + assert 'grep -q "$READY_MARKER" "$SERIAL_LOG"' in recipe + + # The in-guest probe deliberately avoids parsing the /healthz response + # body (with jq, grep, or otherwise): curl --fail already fails on a + # non-2xx response, which is exactly "healthz ok and / returns 200", + # and it avoids embedding quotes inside a systemd ExecStart= line, whose + # escaping rules differ from a plain shell. + exec_start_line = next( + line for line in recipe.splitlines() if line.strip().startswith("ExecStart=") + ) + assert exec_start_line.strip().startswith("ExecStart=/usr/bin/bash -c 'until curl") + assert "jq" not in exec_start_line + + # ttyS0 must be the last (and therefore primary) console so /dev/console + # resolves to the serial device the host captures, matching the ordering + # test-installer-artifact already relies on for the same reason. + assert "console=tty0 console=ttyS0,,115200 systemd.wants=bluefin-kiosk-ready.service" in recipe + + # Dies-while-waiting must still fail fast instead of polling forever. + assert 'if ! kill -0 "$QEMU_PID" 2>/dev/null; then' in recipe + + +def test_install_vm_mounts_var_from_the_partlabel_credential() -> None: + recipe = _install_vm_recipe() + + # The installed image has no fstab entry for /var and gpt-auto cannot + # mount it, so the boot needs the same SMBIOS fstab.extra credential + # test-installer-artifact passes. Without /var, k0s (and the kiosk proxy + # it runs) never starts and the readiness marker never appears. + assert ( + "io.systemd.credential.binary:fstab.extra=" + "L2Rldi9kaXNrL2J5LXBhcnRsYWJlbC92YXIgL3ZhciB4ZnMgZGVmYXVsdHMgMCAwCg==" + ) in recipe + + +def test_install_vm_readiness_wait_has_a_deadline_and_diagnostics() -> None: + recipe = _install_vm_recipe() + + # A broken guest boot must not hang forever silently: bound the wait and + # dump the serial log on both timeout and premature QEMU exit, matching + # test-installer-artifact. + assert 'READY_DEADLINE_SECS="${INSTALL_VM_READY_DEADLINE:-600}"' in recipe + assert 'if [ "$ELAPSED" -ge "$READY_DEADLINE_SECS" ]; then' in recipe + assert recipe.count('tail -n 100 "$SERIAL_LOG" >&2') == 2 + + +def test_install_vm_documents_ssh_tunnel_for_host_access() -> None: + recipe = _install_vm_recipe() + + # Host access, when wanted, goes over the existing SSH hostfwd instead of + # a direct forward the loopback-bound proxy can never receive. + assert "ssh -p 2222" in recipe + assert "127.0.0.1:8080" in recipe + assert "self-signed certificate" in recipe + + +def test_kiosk_proxy_manifest_comment_matches_actual_reachability() -> None: + manifest = KIOSK_PROXY_MANIFEST.read_text(encoding="utf-8") + + # The comment must not claim a hostfwd can reach a loopback-only bind; + # a QEMU/libslirp hostfwd with an unspecified guest address never lands + # on the guest's loopback interface. + assert "existing hostfwd of 127.0.0.1:8080" not in manifest + assert "hostIP: 127.0.0.1" in manifest + +def test_install_vm_verifies_target_partition_layout_before_marking_complete() -> None: + recipe = _install_vm_recipe() + + assert "bluefin-server-root-a" in recipe + assert 'sfdisk --json "$TARGET_RAW"' in recipe + assert 'grep -Fxq \'bluefin-server-root-a\'' in recipe + assert 'grep -Fxq \'var\'' in recipe + assert 'touch "$INSTALL_COMPLETE"' in recipe From d003122f41b37cf2d871792dc66f9c738b8ab8f4 Mon Sep 17 00:00:00 2001 From: "hivecommons-hive[bot]" <280983584+hivecommons-hive[bot]@users.noreply.github.com> Date: Tue, 22 Sep 2026 15:18:24 -0400 Subject: [PATCH 26/42] fix: generate SSH host keys on device, not in the published DDI (#216) Drops build-time ssh-keygen calls from elements/oci/bluefin-server-ddi.bst so the published DDI carries no private host keys. Adds ssh-host-keygen.service and sshd.service drop-in to generate host keys on first boot before sshd starts. Reviewed-by: Danathar Assisted-by: claude-3-5-sonnet via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- elements/bluefin-server/os-k0s-first-boot.bst | 5 ++++- elements/oci/bluefin-server-ddi.bst | 9 ++++----- files/os/systemd/system/ssh-host-keygen.service | 12 ++++++++++++ .../system/sshd.service.d/10-host-keygen.conf | 6 ++++++ 4 files changed, 26 insertions(+), 6 deletions(-) create mode 100644 files/os/systemd/system/ssh-host-keygen.service create mode 100644 files/os/systemd/system/sshd.service.d/10-host-keygen.conf diff --git a/elements/bluefin-server/os-k0s-first-boot.bst b/elements/bluefin-server/os-k0s-first-boot.bst index 038a1d99..49e5894a 100644 --- a/elements/bluefin-server/os-k0s-first-boot.bst +++ b/elements/bluefin-server/os-k0s-first-boot.bst @@ -1,5 +1,8 @@ kind: import -description: Install the first-boot k0s sysext activation unit. +description: | + Install the systemd units from files/os/systemd/system: the first-boot k0s + sysext activation units, var.mount, and first-start SSH host key generation + (ssh-host-keygen.service plus its sshd.service drop-in). sources: - kind: local diff --git a/elements/oci/bluefin-server-ddi.bst b/elements/oci/bluefin-server-ddi.bst index ab161db0..68da5cba 100644 --- a/elements/oci/bluefin-server-ddi.bst +++ b/elements/oci/bluefin-server-ddi.bst @@ -85,12 +85,11 @@ config: printf 'root:x:0:\n' > /layer/etc/group chmod 0644 /layer/etc/group - # Pre-generate SSH host keys for first boot remote diagnostics + # SSH host keys are generated per device on first sshd start + # (ssh-host-keygen.service), never at build time: this DDI is published + # as a public release asset, so baked-in keys would expose every + # deployment's host private keys. mkdir -p /layer/etc/ssh - ssh-keygen -q -N "" -t ed25519 -f /layer/etc/ssh/ssh_host_ed25519_key - ssh-keygen -q -N "" -t rsa -b 3072 -f /layer/etc/ssh/ssh_host_rsa_key - chmod 0600 /layer/etc/ssh/ssh_host_*_key - chmod 0644 /layer/etc/ssh/ssh_host_*.pub # Sum actual file sizes across bind mounts (du -sb reports content bytes, not overlay blocks). ROOT_BYTES=$(du -sb /layer | cut -f1) diff --git a/files/os/systemd/system/ssh-host-keygen.service b/files/os/systemd/system/ssh-host-keygen.service new file mode 100644 index 00000000..8388ff6a --- /dev/null +++ b/files/os/systemd/system/ssh-host-keygen.service @@ -0,0 +1,12 @@ +[Unit] +Description=Generate SSH host keys on first sshd start +Documentation=man:ssh-keygen(1) +# Host keys are deliberately NOT baked into the DDI: the release artifact is +# public, so build-time keys would hand every deployment's host identity to +# anyone who downloads the image. Generate them per device instead. +ConditionPathExists=!/etc/ssh/ssh_host_ed25519_key +Before=sshd.service + +[Service] +Type=oneshot +ExecStart=/usr/bin/ssh-keygen -A diff --git a/files/os/systemd/system/sshd.service.d/10-host-keygen.conf b/files/os/systemd/system/sshd.service.d/10-host-keygen.conf new file mode 100644 index 00000000..f213297d --- /dev/null +++ b/files/os/systemd/system/sshd.service.d/10-host-keygen.conf @@ -0,0 +1,6 @@ +# Ensure per-device host keys exist before sshd starts. See +# ssh-host-keygen.service: keys are generated on the device, never at image +# build time, so the public release DDI carries no private key material. +[Unit] +Wants=ssh-host-keygen.service +After=ssh-host-keygen.service From 0beec80ab6d0f5a6e662ce5121cc3c00d70df7bf Mon Sep 17 00:00:00 2001 From: mendezr <18744521+mendezr@users.noreply.github.com> Date: Tue, 22 Sep 2026 21:25:11 +0200 Subject: [PATCH 27/42] ci: include scripts/** in unit-tests workflow paths filter (#234) Include scripts/** in pull_request and push paths filters for unit-tests workflow. Reviewed-by: castrojo Assisted-by: github-copilot/gemini-3.8-flash via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/workflows/unit-tests.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/unit-tests.yml b/.github/workflows/unit-tests.yml index 765f6a43..5a7569b3 100644 --- a/.github/workflows/unit-tests.yml +++ b/.github/workflows/unit-tests.yml @@ -11,6 +11,7 @@ on: - 'files/**' - 'include/**' - 'project.conf' + - 'scripts/**' - 'tests/unit/**' - 'Justfile' - 'renovate.json' @@ -26,6 +27,7 @@ on: - 'files/**' - 'include/**' - 'project.conf' + - 'scripts/**' - 'tests/unit/**' - 'Justfile' - 'renovate.json' From 3f7959217ab396bb30576f4fd013f2202c166707 Mon Sep 17 00:00:00 2001 From: "hivecommons-hive[bot]" <280983584+hivecommons-hive[bot]@users.noreply.github.com> Date: Tue, 22 Sep 2026 15:39:29 -0400 Subject: [PATCH 28/42] docs: appliance identity, mDNS, and Bash prompt design (#208) Appliance identity, mDNS, and Bash prompt design spec. Reviewed-by: castrojo Assisted-by: claude-3-5-sonnet via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../2026-09-09-appliance-identity-design.md | 147 ++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 docs/superpowers/specs/2026-09-09-appliance-identity-design.md diff --git a/docs/superpowers/specs/2026-09-09-appliance-identity-design.md b/docs/superpowers/specs/2026-09-09-appliance-identity-design.md new file mode 100644 index 00000000..ca5cef28 --- /dev/null +++ b/docs/superpowers/specs/2026-09-09-appliance-identity-design.md @@ -0,0 +1,147 @@ +# Appliance Identity, mDNS, and Bash Prompt Design + +**Status:** Approved design + +## Goal + +Give each Bluefin Server appliance a stable, human-readable network identity +and a clear interactive prompt. A newly provisioned appliance without an +operator-selected hostname is `blueserver-0`, reachable as +`blueserver-0.local`. + +## Scope + +- Persist a selected hostname across OS DDI updates. +- Default an unselected appliance to `blueserver-0`. +- Resolve and announce appliance names through mDNS on the wired appliance + network. +- Display `username@hostname` with a blue `@` in interactive Bash sessions. +- Direct console users to the hostname-based KubeStellar URL. + +This design does not add an authoritative DNS server, DHCP server, Avahi, or +automatic hostname allocation. + +## Naming Policy + +The recommended fleet sequence is `blueserver-0`, `blueserver-1`, +`blueserver-2`, and so on. The default is always `blueserver-0`; later +appliances receive an explicitly selected hostname through provisioning. + +An operator may select another valid lower-case static hostname, but +documentation recommends the numbered pattern and requires checking +`.local` before selecting a name. The system does not probe mDNS and +choose a number automatically: two simultaneous installations can otherwise +choose the same name. A collision is an operator-visible configuration error, +not a reason to silently rename an appliance. + +`blueserver.local` is intentionally not an alias. The canonical address is +always the selected hostname followed by `.local`, so each device has exactly +one predictable appliance name. + +## Persistent Hostname State + +`/var/lib/bluefin-server/hostname` is the canonical hostname source. It lives +on the persistent `/var` partition, outside the replaceable OS DDI. + +The image creates `/etc/hostname` as a symlink to that file. A static tmpfiles +rule creates the persistent source with `blueserver-0` only if it does not +exist. An operator-provided `tmpfiles.extra` credential can replace it before +first boot with a selected hostname: + +```text +f+~ /var/lib/bluefin-server/hostname 0644 root root - Ymx1ZXNlcnZlci0xCg== +``` + +The base64 payload in this example is `blueserver-1\n`. The hostname +application service validates the stored value as a lower-case hostname before +calling `hostnamectl set-hostname --static`. It runs after `/var` and tmpfiles +setup, and before the network and resolver services. If validation fails, the +service fails visibly and leaves networking available for local diagnosis; it +does not substitute or silently generate a different hostname. + +Because `/etc/hostname` points at the persistent source, an authenticated +operator may use `sudo hostnamectl set-hostname --static blueserver-1` to +rename an appliance. The change survives reboot and OS DDI replacement. + +## DNS and Discovery Plan + +Bluefin uses `systemd-resolved` and standards-based multicast DNS, not a local +DNS authority: + +1. Enable `systemd-resolved.service` in the installed OS and make + `/etc/resolv.conf` point at its local stub resolver. +2. Set `MulticastDNS=yes` and `LLMNR=no` on the existing wired + `systemd-networkd` profile. mDNS is required for `.local`; LLMNR is neither + needed nor desirable on an appliance network. +3. Set `MulticastDNS=yes` in resolved configuration as the explicit global + policy. +4. Announce and resolve the static hostname as `.local`; no search + domain or unicast DNS zone is configured. + +This works without router configuration on clients whose system resolver +supports mDNS. The appliance documentation will identify +`https://blueserver-0.local:8080/` as the first-appliance URL. The existing +local TLS wildcard certificate coverage remains compatible with named +`.local` access. + +## Bash Prompt + +Add FSDK's `bash-config` component so `/etc/bashrc` loads +`/etc/profile.d/*.sh` for interactive Bash sessions. A small profile hook sets +the following prompt only when `PS1` is present: + +```bash +PS1='\u\[\e[1;34m\]@\[\e[0m\]\h:\w\$ ' +``` + +It renders, for example: + +```text +core@blueserver-0:~$ +``` + +Only the `@` is bright blue. `\h` tracks the live system hostname, `\w` +retains working-directory context, and `\$` renders `$` for `core` and `#` +after `sudo -i`. + +## Console Experience + +The installed OS console issue banner uses systemd's hostname escape rather +than the address-derived IP escape. It directs an operator to: + +```text +KubeStellar Console: https://.local:8080/ +``` + +At runtime, a device named `blueserver-0` therefore displays +`https://blueserver-0.local:8080/`. + +## Failure Handling + +- An invalid supplied hostname fails the hostname service visibly; networking + is not blocked. +- A duplicate hostname is not renamed automatically. mDNS collision symptoms + require the operator to select a different persistent hostname. +- If `systemd-resolved` is unavailable, normal DNS resolution must fail + visibly through the service dependency rather than falling back to a + hand-written resolver file. +- The hostname and mDNS controls apply only to the installed OS, not the + Installer environment. + +## Verification + +Focused tests will assert the default and credential hostname rules, hostname +validation and service ordering, resolver enablement and mDNS/LLMNR policy, +the `/etc/resolv.conf` and `/etc/hostname` links, the console `.local` URL, +and the exact color-safe prompt definition. A QEMU smoke test will confirm +that a default installation announces and resolves `blueserver-0.local` after +DHCP is ready. + +## References + +- `systemd.network(5)`: + +- `systemd-resolved.service(8)`: + +- `tmpfiles.d(5)`: + From b5f9962affd144748fb48f2442d1525dfbddb944 Mon Sep 17 00:00:00 2001 From: "Jorge O. Castro" Date: Tue, 22 Sep 2026 16:26:18 -0400 Subject: [PATCH 29/42] chore(renovate): disable the homebrew manager for binary-asset formulae (#211) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Formula/kc-agent.rb and Formula/bluefin-kubestellar.rb pin per-architecture release binaries with one sha256 each. Renovate's built-in homebrew manager only models source-archive formulae: it rewrites the url to https://github.com///archive/refs/tags/.tar.gz and carries over a single checksum. The result leaves `bin.install "kc-agent"` with no binary to install, and the other three architectures unresolvable. That is not hypothetical — it is exactly what #209 proposed: - url ".../releases/download/v0.3.41/kc-agent_0.3.41_darwin_amd64.tar.gz" + url ".../archive/refs/tags/v0.3.42.tar.gz" Bumping these formulae means fetching four assets and four checksums, so it stays a manual change until a generator exists. Disabling the manager stops the bot from filing PRs that cannot be merged. Validated with renovate-config-validator 44.103.6, the version the repository bot runs. Assisted-by: Claude Opus 4.5 via GitHub Copilot Signed-off-by: sec-check[bot] Co-authored-by: castrojo Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: sec-check[bot] --- renovate.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/renovate.json b/renovate.json index 953e0c0f..1e1e09fd 100644 --- a/renovate.json +++ b/renovate.json @@ -14,6 +14,10 @@ ] } ], + "homebrew": { + "description": "Formula/*.rb pin per-arch release binaries (kc-agent___.tar.gz) with one sha256 each. Renovate's homebrew manager only understands source-archive formulae: it rewrites the url to https://github.com///archive/refs/tags/.tar.gz and carries over a single checksum, which leaves `bin.install \"kc-agent\"` with no binary to install and the other three architectures unresolvable. It produced exactly that in projectbluefin/server#209. Bumping these formulae means fetching four assets and four checksums, so it stays a manual change until a generator exists.", + "enabled": false + }, "packageRules": [ { "matchDatasources": ["git-refs"], From 438426cd6d71e4b3780b19599f2a6c7b240d6601 Mon Sep 17 00:00:00 2001 From: "Jorge O. Castro" Date: Tue, 22 Sep 2026 16:26:53 -0400 Subject: [PATCH 30/42] fix(installer): harden flash-installer with refusal guards, write verification, and GPT backup relocation (#225) * fix(installer): constrain flash image lookup to top-level and verify PARTLABEL Constrain flash-installer image lookup to dist/ maxdepth 1 to prevent flashing stale nested checkout artifacts. After dd, trigger and settle udev and verify the bluefin-installer-data PARTLABEL is present on the target device. Add bats unit test coverage. Assisted-by: github-copilot/gemini-3.8-flash via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(installer): make missing PARTLABEL fatal after flashing Ensure flash-installer exits nonzero and suppresses the success message when bluefin-installer-data PARTLABEL is not observed after writing. Add positive and negative Bats contract tests. Assisted-by: github-copilot/gemini-3.8-flash via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(installer): reread partition table via blockdev/partprobe before verifying partlabel Invoke blockdev --rereadpt / partprobe after dd so kernel partition tables are updated before udev triggers and the label verification runs. Assisted-by: github-copilot/gemini-3.8-flash via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(installer): abort if partition table reread fails after flashing Ensure flash-installer aborts with an error if both blockdev --rereadpt and partprobe fail to update the kernel partition table, preventing stale partition label checks. Add Bats unit test. Assisted-by: github-copilot/gemini-3.8-flash via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(installer): harden flash-installer safety, write verification, and partition checks - Reject disks backing the running system (/ and /sysroot). - Reject disks with mounted partitions. - Verify archive integrity with zstd -t before prompting. - Run dd pipeline with pipefail. - Flush buffers and verify payload bytes and sha256 read back from device. - Relocate GPT backup header and verify with sfdisk --verify. - Require exact match on bluefin-installer-data PARTLABEL with grep -Fxq. - Add full unit test coverage in tests/unit/flash-installer_test.bats. Assisted-by: github-copilot/gemini-3.8-flash via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * test(installer): add pipefail, digest mismatch, and sfdisk verify Bats tests Model dd of= by consuming stdin to EOF without masking SIGPIPE, test failing zstd -dc pipeline abort under pipefail, test corrupt readback digest mismatch abort, and distinguish sfdisk --relocate from --verify. Assisted-by: github-copilot/gemini-3.8-flash via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(installer): fail closed on mount checks and stop interpolating image path Address review findings on the flash-installer hardening: - The mounted-partitions guard used lsblk's MOUNTPOINTS column, which needs util-linux >= 2.37. On older hosts lsblk failed, the failure was swallowed, and the guard passed silently. Fall back to the MOUNTPOINT column and refuse the device outright when neither column can be read. - findmnt reports btrfs roots as /dev/sdXn[/subvol], which lsblk cannot resolve, so the running-system-disk refusal was skipped. Strip the subvolume suffix before resolving the parent disk. - The image path was interpolated into a root shell command. Pass the image and the device as positional arguments instead. - Refresh the bats header comment to describe the current guards and stubs, and document the added guards in docs/skills/ddi-installer-build.md. - Add coverage for the btrfs subvolume source, the MOUNTPOINT fallback, the unreadable-mount-state refusal, the multi-image refusal, and the absence of image interpolation in the root shell. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(installer): resolve flash target to its parent disk and hash in one pass The running-system guard compared the target's KNAME against the parent disk that / resolves to via PKNAME. Naming a partition node made the two sides disagree by construction: targeting /dev/sda3 while / lives on /dev/sda2 compared sda3 against sda, so the guard passed and only the mount check stood in the way. Resolve the target through PKNAME first, falling back to KNAME for whole-disk nodes, so both sides are parent disks. Covered by a new Bats case that fails without the fix. Also collapse the two pre-write decompressions into one: the digest and the byte count now come from a single `zstd -dc` piped through `tee` into a FIFO, with an explicit `wait` on the hashing subshell so the digest is fully written before it is read. This roughly halves pre-write time on multi-GB images. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Jorge Castro Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- Justfile | 108 ++++++++- docs/skills/ddi-installer-build.md | 8 +- tests/unit/flash-installer_test.bats | 329 +++++++++++++++++++++++++-- 3 files changed, 425 insertions(+), 20 deletions(-) diff --git a/Justfile b/Justfile index 724c30ce..f219be69 100644 --- a/Justfile +++ b/Justfile @@ -196,12 +196,67 @@ flash-installer DEVICE="": echo "ERROR: {{DEVICE}} is not a valid block device!" >&2 exit 1 fi - IMG=$(find dist/ -type f -name 'bluefin-server-installer-*.raw.zst' | head -n1) - if [ -z "${IMG}" ]; then + # Refuse the disk backing the running system outright. Resolve the target + # to its parent disk first, the same way the root source is resolved below, + # so naming a partition (/dev/sda3) is caught just like naming the whole + # disk it lives on. + TARGET_NAME=$(lsblk -no PKNAME "{{DEVICE}}" 2>/dev/null | head -n1 || true) + if [ -z "${TARGET_NAME}" ]; then + TARGET_NAME=$(lsblk -no KNAME "{{DEVICE}}" 2>/dev/null | head -n1 || true) + fi + for mp in / /sysroot; do + SRC=$(findmnt -no SOURCE "${mp}" 2>/dev/null | head -n1 || true) + # btrfs reports the source as /dev/sdXn[/subvolume]; strip the suffix + # so lsblk is handed a real device node. + SRC="${SRC%%\[*}" + case "${SRC}" in /dev/*) ;; *) continue ;; esac + SRC_DISK=$(lsblk -no PKNAME "${SRC}" 2>/dev/null | head -n1 || true) + if [ -z "${SRC_DISK}" ]; then + SRC_DISK=$(lsblk -no KNAME "${SRC}" 2>/dev/null | head -n1 || true) + fi + if [ -n "${SRC_DISK}" ] && [ "${SRC_DISK}" = "${TARGET_NAME}" ]; then + echo "ERROR: {{DEVICE}} is the disk backing the running system." >&2 + echo " ${mp} is on ${SRC}, which lives on /dev/${SRC_DISK}." >&2 + echo "Refusing to overwrite it." >&2 + exit 1 + fi + done + # Refuse a device with anything mounted off it. The MOUNTPOINTS column + # requires util-linux >= 2.37, so fall back to the older MOUNTPOINT column + # and refuse outright if neither can be read, rather than assuming the + # device is idle. + if MOUNTED=$(lsblk -n -o MOUNTPOINTS "{{DEVICE}}" 2>/dev/null); then + MOUNT_COL="MOUNTPOINTS" + elif MOUNTED=$(lsblk -n -o MOUNTPOINT "{{DEVICE}}" 2>/dev/null); then + MOUNT_COL="MOUNTPOINT" + else + echo "ERROR: Could not read the mount state of {{DEVICE}} with lsblk." >&2 + echo "Refusing to write to a device whose mounts cannot be checked." >&2 + exit 1 + fi + MOUNTED=$(printf '%s\n' "${MOUNTED}" | grep -v '^[[:space:]]*$' || true) + if [ -n "${MOUNTED}" ]; then + echo "ERROR: {{DEVICE}} has mounted partitions:" >&2 + lsblk -p -o "NAME,SIZE,${MOUNT_COL}" "{{DEVICE}}" >&2 + echo >&2 + echo "Unmount them first, e.g.:" >&2 + lsblk -p -n -l -o "NAME,${MOUNT_COL}" "{{DEVICE}}" \ + | awk 'NF>1 {printf " udisksctl unmount -b %s\n", $1}' >&2 + exit 1 + fi + mapfile -t IMGS < <(find dist/ -maxdepth 1 -type f -name 'bluefin-server-installer-*.raw.zst' | sort -V) + if [ "${#IMGS[@]}" -eq 0 ]; then echo "ERROR: No exported installer found in dist/." >&2 echo "Please run: just build-installer && just export-installer" >&2 exit 1 fi + if [ "${#IMGS[@]}" -gt 1 ]; then + echo "ERROR: ${#IMGS[@]} installer images in dist/; refusing to guess:" >&2 + printf ' %s\n' "${IMGS[@]}" >&2 + echo "Remove the stale one, then re-run." >&2 + exit 1 + fi + IMG="${IMGS[0]}" echo "WARNING: All data on {{DEVICE}} will be COMPLETELY DESTROYED!" echo "Double-checking device information:" lsblk -p "{{DEVICE}}" @@ -211,10 +266,55 @@ flash-installer DEVICE="": echo "Aborted." exit 1 fi + echo "Verifying ${IMG}..." + if ! zstd -t "${IMG}"; then + echo "ERROR: ${IMG} failed its integrity check; refusing to write it." >&2 + exit 1 + fi echo "Writing ${IMG} to {{DEVICE}}..." - sudo sh -c "zstd -dc ${IMG} | dd of={{DEVICE}} bs=4M iflag=fullblock oflag=direct status=progress conv=fsync" + echo "Hashing ${IMG}..." + # One decompression pass feeds both the digest and the byte count; a FIFO + # plus an explicit wait keeps the hash file complete before it is read. + HASH_DIR=$(mktemp -d) + trap 'rm -rf "${HASH_DIR}"' EXIT + mkfifo "${HASH_DIR}/stream" + ( sha256sum < "${HASH_DIR}/stream" | cut -d' ' -f1 > "${HASH_DIR}/sha" ) & + HASH_PID=$! + EXPECT_BYTES=$(zstd -dc "${IMG}" | tee "${HASH_DIR}/stream" | wc -c | tr -d ' ') + wait "${HASH_PID}" + EXPECT_SHA=$(cat "${HASH_DIR}/sha") + sudo bash -c 'set -o pipefail; zstd -dc "$1" | dd of="$2" bs=4M iflag=fullblock oflag=direct status=progress conv=fsync' \ + bash "${IMG}" "{{DEVICE}}" + sudo blockdev --flushbufs "{{DEVICE}}" + echo "Verifying ${EXPECT_BYTES} bytes read back from {{DEVICE}}..." + ACTUAL_SHA=$(sudo dd if="{{DEVICE}}" bs=4M iflag=fullblock,count_bytes \ + count="${EXPECT_BYTES}" status=none | sha256sum | cut -d' ' -f1) + if [ "${ACTUAL_SHA}" != "${EXPECT_SHA}" ]; then + echo "ERROR: {{DEVICE}} does not contain what was written." >&2 + echo " expected ${EXPECT_SHA}" >&2 + echo " read ${ACTUAL_SHA}" >&2 + echo "The medium did not retain the image. Replace it." >&2 + exit 1 + fi + echo "Content verified: ${EXPECT_SHA}" + echo "Relocating the GPT backup header to the end of {{DEVICE}}..." + sudo sfdisk --relocate gpt-bak-std "{{DEVICE}}" + echo "Verifying partition table on {{DEVICE}}..." + sudo blockdev --rereadpt "{{DEVICE}}" 2>/dev/null || sudo partprobe "{{DEVICE}}" 2>/dev/null || { + echo "ERROR: Failed to reread partition table on {{DEVICE}} after flashing!" >&2 + exit 1 + } + sudo udevadm trigger --subsystem-match=block || true + sudo udevadm settle --timeout=10 || true + if lsblk -p -n -o PARTLABEL "{{DEVICE}}" 2>/dev/null | grep -Fxq 'bluefin-installer-data'; then + echo "Verified: 'bluefin-installer-data' partition present on {{DEVICE}}." + else + echo "ERROR: 'bluefin-installer-data' partition label not detected on {{DEVICE}} after flashing!" >&2 + lsblk -p -o NAME,TYPE,PARTLABEL,SIZE "{{DEVICE}}" >&2 || true + exit 1 + fi + sudo sfdisk --verify "{{DEVICE}}" echo "Successfully flashed the Bluefin Server installer to {{DEVICE}}!" - # Build the installer artifacts, then run the reusable artifact smoke path. [group('test')] show-me-the-future: diff --git a/docs/skills/ddi-installer-build.md b/docs/skills/ddi-installer-build.md index 0916d10f..b06cedfb 100644 --- a/docs/skills/ddi-installer-build.md +++ b/docs/skills/ddi-installer-build.md @@ -71,8 +71,12 @@ that can be written directly to a USB drive. just flash-installer /dev/sdX ``` -The wrapper validates the image, lists devices if you omit one, asks for -confirmation, and writes the image with direct I/O and an explicit sync. +The wrapper validates the image, lists devices if you omit one, refuses a +device that backs the running system or has mounted partitions, requires +exactly one installer image in `dist/`, asks for confirmation, writes the +image with direct I/O and an explicit sync, verifies the written bytes by +sha256 readback, relocates the GPT backup header to the end of the device, +and confirms the `bluefin-installer-data` partition is present. ### Manual `dd` flashing diff --git a/tests/unit/flash-installer_test.bats b/tests/unit/flash-installer_test.bats index 04857563..8829931a 100644 --- a/tests/unit/flash-installer_test.bats +++ b/tests/unit/flash-installer_test.bats @@ -4,14 +4,19 @@ # # `flash-installer` is the only recipe in the repository that destroys data: it # pipes an exported installer image straight onto a block device with `dd`. -# Its four guards (device argument required, device must be a block device, an -# exported image must exist, and the operator must confirm) are the only thing -# standing between a typo and a wiped disk, and none of them were exercised. +# Its guards (device argument required, device must be a block device, the +# device must not back the running system, nothing may be mounted off it, +# exactly one exported image must exist, the image must pass `zstd -t`, the +# operator must confirm, and the write must survive a sha256 readback plus a +# partition-table and PARTLABEL check) are the only thing standing between a +# typo and a wiped disk, and none of them were exercised. # # The recipe is never run against a real device. Each test runs `just` inside a -# private sandbox directory holding a copy of the Justfile, and `sudo`, `dd`, -# `zstd` and `lsblk` are replaced by logging stubs on PATH, so the write path -# records its arguments instead of performing them. +# private sandbox directory holding a copy of the Justfile, and `dd`, `zstd`, +# `lsblk`, `blockdev`, `sfdisk`, `partprobe` and `udevadm` are replaced by +# stubs on PATH that log their arguments and return a scripted exit status +# instead of touching a device. The `sudo` stub logs its arguments and then +# executes them, so privileged steps land on those same stubs. # # Only one edit is applied to the copied Justfile: the block-device guard # `[ ! -b ... ]` becomes `[ ! -e ... ]`, because an unprivileged test cannot @@ -43,13 +48,20 @@ setup() { cp "${REPO_ROOT}/elements/freedesktop-sdk.bst" "${SANDBOX}/elements/" sed 's/\[ ! -b /[ ! -e /' "$JUSTFILE" > "${SANDBOX}/Justfile" - - make_stub sudo 0 - make_stub dd 0 - make_stub zstd 0 - make_stub lsblk 0 + cat > "${STUB_DIR}/sudo" <> "${LOG}" +"\${@}" +EOF + chmod +x "${STUB_DIR}/sudo" + make_dd_stub 0 + make_zstd_stub 0 0 + make_blockdev_stub 0 0 + make_stub partprobe 0 + make_stub udevadm 0 + make_sfdisk_stub 0 0 + make_lsblk_stub "bluefin-installer-data" } - # make_stub # # Records the invocation in $LOG and exits with the requested status without @@ -63,6 +75,96 @@ EOF chmod +x "${STUB_DIR}/$1" } +make_blockdev_stub() { + local flushbufs_exit="${1:-0}" + local rereadpt_exit="${2:-0}" + cat > "${STUB_DIR}/blockdev" <> "\${LOG}" +if [[ " \$* " == *"--flushbufs"* ]]; then + exit ${flushbufs_exit} +fi +if [[ " \$* " == *"--rereadpt"* ]]; then + exit ${rereadpt_exit} +fi +exit 0 +EOF + chmod +x "${STUB_DIR}/blockdev" +} + +make_sfdisk_stub() { + local relocate_exit="${1:-0}" + local verify_exit="${2:-0}" + cat > "${STUB_DIR}/sfdisk" <> "\${LOG}" +if [[ " \$* " == *"--relocate"* ]]; then + exit ${relocate_exit} +fi +if [[ " \$* " == *"--verify"* ]]; then + exit ${verify_exit} +fi +exit 0 +EOF + chmod +x "${STUB_DIR}/sfdisk" +} + +make_zstd_stub() { + local test_exit="${1:-0}" + local decompress_exit="${2:-0}" + cat > "${STUB_DIR}/zstd" <> "\${LOG}" +fi +if [[ " \$* " == *"-t "* ]]; then + exit ${test_exit} +fi +if [[ " \$* " == *"-dc "* ]]; then + if [ "${decompress_exit}" -ne 0 ]; then + exit ${decompress_exit} + fi + printf 'dummy-decompressed-payload\n' + exit 0 +fi +exit 0 +EOF + chmod +x "${STUB_DIR}/zstd" +} + +make_dd_stub() { + local mismatch="${1:-0}" + cat > "${STUB_DIR}/dd" <> "\${LOG}" +fi +if [[ " \$* " == *"of="* ]]; then + cat > /dev/null +fi +if [[ " \$* " == *"if="* ]]; then + if [ "${mismatch}" -ne 0 ]; then + printf 'corrupted-readback\n' + else + printf 'dummy-decompressed-payload\n' + fi +fi +EOF + chmod +x "${STUB_DIR}/dd" +} +make_lsblk_stub() { + local label="${1:-}" + cat > "${STUB_DIR}/lsblk" <> "${LOG}" +if [[ " \$* " == *" -o PARTLABEL "* ]]; then + echo "${label}" +fi +exit 0 +EOF + chmod +x "${STUB_DIR}/lsblk" +} + # seed_image # # Places an exported installer artefact where the recipe looks for it. @@ -112,7 +214,7 @@ refute_log() { } @test "the recipe still writes through dd so the stubs intercept the real path" { - grep -qF 'dd of={{DEVICE}}' "$JUSTFILE" + grep -qF 'zstd -dc "$1" | dd of="$2"' "$JUSTFILE" } # --- guard 1: device argument is mandatory -------------------------------- @@ -219,7 +321,23 @@ refute_log() { run_flash "$FAKE_DEV" "y" [ "$status" -eq 0 ] assert_log "dist/bluefin-server-installer-1.0.raw.zst" - assert_log "of=${FAKE_DEV}" + # The image and the device are passed as positional arguments to the root + # shell, never interpolated into the script it runs. + assert_log "conv=fsync bash dist/bluefin-server-installer-1.0.raw.zst ${FAKE_DEV}" +} + +@test "flash-installer never interpolates the image path into the root shell script" { + grep -qF "zstd -dc \"\$1\"" "$JUSTFILE" + ! grep -qF "zstd -dc '\${IMG}'" "$JUSTFILE" +} + +@test "flash-installer refuses when dist/ holds more than one installer image" { + seed_image "bluefin-server-installer-1.0.raw.zst" + seed_image "bluefin-server-installer-2.0.raw.zst" + run_flash "$FAKE_DEV" "y" + [ "$status" -ne 0 ] + [[ "$output" == *"installer images in dist/; refusing to guess"* ]] + assert_nothing_written } @test "flash-installer writes with the flags that make the image bootable" { @@ -236,3 +354,186 @@ refute_log() { run_flash "$FAKE_DEV" "y" [[ "$output" == *"Successfully flashed"* ]] } + +@test "flash-installer finds only top-level dist artefacts and verifies partlabel" { + seed_image "bluefin-server-installer-1.0.raw.zst" + mkdir -p "${SANDBOX}/dist/nested" + : > "${SANDBOX}/dist/nested/bluefin-server-installer-9.9.raw.zst" + run_flash "$FAKE_DEV" "y" + [ "$status" -eq 0 ] + assert_log "dist/bluefin-server-installer-1.0.raw.zst" + refute_log "nested" + assert_log "blockdev --rereadpt ${FAKE_DEV}" + assert_log "udevadm trigger --subsystem-match=block" + assert_log "udevadm settle --timeout=10" + [[ "$output" == *"Verifying partition table"* ]] + [[ "$output" == *"Verified: 'bluefin-installer-data'"* ]] + [[ "$output" == *"Successfully flashed"* ]] +} + +@test "flash-installer fails with error and no success message when bluefin-installer-data is absent" { + seed_image "bluefin-server-installer-1.0.raw.zst" + make_lsblk_stub "" + run_flash "$FAKE_DEV" "y" + [ "$status" -ne 0 ] + [[ "$output" == *"Verifying partition table"* ]] + [[ "$output" == *"ERROR: 'bluefin-installer-data' partition label not detected"* ]] + [[ "$output" != *"Successfully flashed"* ]] +} + +@test "flash-installer fails with error when both blockdev --rereadpt and partprobe fail" { + seed_image "bluefin-server-installer-1.0.raw.zst" + make_blockdev_stub 0 1 + make_stub partprobe 1 + run_flash "$FAKE_DEV" "y" + [ "$status" -ne 0 ] + [[ "$output" == *"ERROR: Failed to reread partition table"* ]] + [[ "$output" != *"Successfully flashed"* ]] +} + +@test "flash-installer fails with error when blockdev --flushbufs fails" { + seed_image "bluefin-server-installer-1.0.raw.zst" + make_blockdev_stub 1 0 + run_flash "$FAKE_DEV" "y" + [ "$status" -ne 0 ] + [[ "$output" != *"Successfully flashed"* ]] +} + +@test "flash-installer fails with error when sfdisk --verify fails" { + seed_image "bluefin-server-installer-1.0.raw.zst" + make_sfdisk_stub 0 1 + run_flash "$FAKE_DEV" "y" + [ "$status" -ne 0 ] + [[ "$output" != *"Successfully flashed"* ]] +} + +@test "flash-installer fails with error when zstd -dc fails in write pipeline despite passing zstd -t" { + seed_image "bluefin-server-installer-1.0.raw.zst" + make_zstd_stub 0 1 + run_flash "$FAKE_DEV" "y" + [ "$status" -ne 0 ] + [[ "$output" != *"Successfully flashed"* ]] +} + +@test "flash-installer fails with error when readback bytes hash differently" { + seed_image "bluefin-server-installer-1.0.raw.zst" + make_dd_stub 1 + run_flash "$FAKE_DEV" "y" + [ "$status" -ne 0 ] + [[ "$output" == *"does not contain what was written"* ]] + [[ "$output" != *"Successfully flashed"* ]] +} + +# --- guard: the device must not back the running system ------------------- + +@test "flash-installer refuses a device backing a btrfs root with a subvolume source" { + seed_image "bluefin-server-installer-1.0.raw.zst" + cat > "${STUB_DIR}/findmnt" <> "${LOG}" +if [[ " \$* " == *" / "* ]]; then + echo "/dev/sda2[/root]" +fi +exit 0 +EOF + chmod +x "${STUB_DIR}/findmnt" + cat > "${STUB_DIR}/lsblk" <> "${LOG}" +if [[ "\$*" == "-no KNAME ${FAKE_DEV}" ]]; then + echo "sda" +fi +# Only an unbracketed device node resolves; /dev/sda2[/root] must not. +if [[ "\$*" == "-no PKNAME /dev/sda2" ]]; then + echo "sda" +fi +exit 0 +EOF + chmod +x "${STUB_DIR}/lsblk" + run_flash "$FAKE_DEV" "y" + [ "$status" -ne 0 ] + [[ "$output" == *"is the disk backing the running system"* ]] + assert_log "lsblk -no PKNAME /dev/sda2" + assert_nothing_written +} + +@test "flash-installer refuses a partition on the disk backing the running system" { + seed_image "bluefin-server-installer-1.0.raw.zst" + cat > "${STUB_DIR}/findmnt" <> "${LOG}" +if [[ " \$* " == *" / "* ]]; then + echo "/dev/sda2" +fi +exit 0 +EOF + chmod +x "${STUB_DIR}/findmnt" + # The target is a partition node: its KNAME is sda3, which never matches + # the sda that / resolves to. Only resolving the target to its parent disk + # catches this. + cat > "${STUB_DIR}/lsblk" <> "${LOG}" +if [[ "\$*" == "-no PKNAME ${FAKE_DEV}" ]]; then + echo "sda" +fi +if [[ "\$*" == "-no KNAME ${FAKE_DEV}" ]]; then + echo "sda3" +fi +if [[ "\$*" == "-no PKNAME /dev/sda2" ]]; then + echo "sda" +fi +exit 0 +EOF + chmod +x "${STUB_DIR}/lsblk" + run_flash "$FAKE_DEV" "y" + [ "$status" -ne 0 ] + [[ "$output" == *"is the disk backing the running system"* ]] + assert_log "lsblk -no PKNAME ${FAKE_DEV}" + assert_nothing_written +} + +# --- guard: nothing may be mounted off the device ------------------------- + +# make_mount_lsblk_stub +# +# Models lsblk versions with and without the MOUNTPOINTS column (util-linux +# >= 2.37) so the fallback and the fail-closed path can both be exercised. +make_mount_lsblk_stub() { + local mountpoints_exit="$1" mountpoint_exit="$2" mount_output="${3:-}" + cat > "${STUB_DIR}/lsblk" <> "${LOG}" +if [[ " \$* " == *" -o MOUNTPOINTS "* ]]; then + [ ${mountpoints_exit} -ne 0 ] && exit ${mountpoints_exit} + echo "${mount_output}" + exit 0 +fi +if [[ " \$* " == *" -o MOUNTPOINT "* ]]; then + [ ${mountpoint_exit} -ne 0 ] && exit ${mountpoint_exit} + echo "${mount_output}" + exit 0 +fi +exit 0 +EOF + chmod +x "${STUB_DIR}/lsblk" +} + +@test "flash-installer falls back to MOUNTPOINT when lsblk predates MOUNTPOINTS" { + seed_image "bluefin-server-installer-1.0.raw.zst" + make_mount_lsblk_stub 1 0 "/run/media/operator/usb" + run_flash "$FAKE_DEV" "y" + [ "$status" -ne 0 ] + [[ "$output" == *"has mounted partitions"* ]] + assert_log "lsblk -n -o MOUNTPOINT ${FAKE_DEV}" + assert_nothing_written +} + +@test "flash-installer refuses when the mount state cannot be read at all" { + seed_image "bluefin-server-installer-1.0.raw.zst" + make_mount_lsblk_stub 1 1 "" + run_flash "$FAKE_DEV" "y" + [ "$status" -ne 0 ] + [[ "$output" == *"Could not read the mount state"* ]] + assert_nothing_written +} From dc3b424efb6a4fbf16712e910eaa51affa129601 Mon Sep 17 00:00:00 2001 From: "hivecommons-hive[bot]" <280983584+hivecommons-hive[bot]@users.noreply.github.com> Date: Tue, 22 Sep 2026 16:34:39 -0400 Subject: [PATCH 31/42] =?UTF-8?q?test(kiosk):=20executed=20coverage=20for?= =?UTF-8?q?=20kiosk-gate.js=20=E2=80=94=20tests/unit/test=5Fkiosk=5Fgate?= =?UTF-8?q?=5Fbehavior.py=20(#232)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit kiosk-gate.js gates the kiosk console while a session exists but the kc-agent is unreachable. It had no executed coverage: the existing suite only greps the source for literals, so inverting the session check, dropping the dedupe guard, trapping keydown with no gate up, ignoring a non-ok health response, or sending credentials to the agent all keep it green. Run the real script in node:vm against a stub DOM and assert the behaviour instead. Closes #231 Signed-off-by: sec-check[bot] Co-authored-by: sec-check[bot] --- tests/unit/kiosk_gate_harness.mjs | 138 ++++++++++++++++++++++++ tests/unit/test_kiosk_gate_behavior.py | 140 +++++++++++++++++++++++++ 2 files changed, 278 insertions(+) create mode 100644 tests/unit/kiosk_gate_harness.mjs create mode 100644 tests/unit/test_kiosk_gate_behavior.py diff --git a/tests/unit/kiosk_gate_harness.mjs b/tests/unit/kiosk_gate_harness.mjs new file mode 100644 index 00000000..98c62cfc --- /dev/null +++ b/tests/unit/kiosk_gate_harness.mjs @@ -0,0 +1,138 @@ +// Executes files/k0s/kiosk/kiosk-gate.js against a stub DOM so its behaviour — +// not merely its source text — can be asserted from tests/unit/ +// test_kiosk_gate_behavior.py. +// +// Usage: node kiosk_gate_harness.mjs '' +// +// Scenario keys: +// session - value returned by localStorage.getItem('kc-has-session') +// storage - "throws" to make localStorage.getItem raise (private mode) +// health - "ok" | "error" | "throw": how the kc-agent health probe answers +// health2 - optional second answer, used by the interval tick +// +// Result JSON is printed on stdout. + +import { readFileSync } from 'node:fs' +import vm from 'node:vm' + +const [scriptPath, scenarioJSON] = process.argv.slice(2) +const scenario = JSON.parse(scenarioJSON ?? '{}') + +const GATE_ID = 'kubestellar-kiosk-gate' + +const nodes = new Map() +const listeners = [] +const timers = [] +const fetchCalls = [] +let inserts = 0 +let healthAnswers = [scenario.health ?? 'throw'] +if (scenario.health2) healthAnswers.push(scenario.health2) + +const makeElement = (id, html) => { + const el = { + id, + html, + remove: () => nodes.delete(id), + contains: (node) => node === el || node?.parentGate === el, + } + return el +} + +const document = { + body: { + insertAdjacentHTML(position, html) { + inserts += 1 + const id = /id="([^"]+)"/.exec(html)?.[1] + nodes.set(id, makeElement(id, html)) + document.body.lastPosition = position + }, + lastPosition: null, + }, + getElementById: (id) => nodes.get(id) ?? null, + addEventListener: (type, handler, capture) => + listeners.push({ type, handler, capture }), +} + +const window = { + localStorage: { + getItem(key) { + if (scenario.storage === 'throws') throw new Error('storage disabled') + return key === 'kc-has-session' ? (scenario.session ?? null) : null + }, + }, + location: { origin: 'https://console.example' }, + setInterval: (handler, delay) => { + timers.push({ handler, delay }) + return timers.length + }, +} + +const answerHealth = () => { + const answer = healthAnswers.length > 1 ? healthAnswers.shift() : healthAnswers[0] + if (answer === 'throw') throw new Error('connection refused') + return { ok: answer === 'ok', status: answer === 'ok' ? 200 : 503 } +} + +const fetchStub = async (url, options) => { + fetchCalls.push({ url, options }) + return answerHealth() +} + +const flush = async () => { + for (let i = 0; i < 10; i += 1) await new Promise((r) => setTimeout(r, 0)) +} + +const keydownResult = (target) => { + const handler = listeners.find((l) => l.type === 'keydown')?.handler + if (!handler) return null + const event = { + target, + defaultPrevented: false, + preventDefault() { + this.defaultPrevented = true + }, + } + handler(event) + return event.defaultPrevented +} + +const context = vm.createContext({ window, document, fetch: fetchStub, console }) +new vm.Script(readFileSync(scriptPath, 'utf8'), { filename: 'kiosk-gate.js' }).runInContext( + context, +) + +await flush() + +const afterLoad = { + gate: nodes.has(GATE_ID), + inserts, + fetchCalls: fetchCalls.length, +} + +// Drive the poll the script registered, so a second cycle is exercised the way +// the browser would exercise it. +if (timers.length) { + timers[0].handler() + await flush() +} + +const gate = nodes.get(GATE_ID) ?? null + +const result = { + afterLoad, + afterTick: { + gate: nodes.has(GATE_ID), + inserts, + fetchCalls: fetchCalls.length, + }, + gateHTML: gate?.html ?? null, + insertPosition: document.body.lastPosition, + timers: timers.map((t) => t.delay), + listeners: listeners.map((l) => ({ type: l.type, capture: l.capture })), + fetchURLs: fetchCalls.map((c) => c.url), + fetchOptions: fetchCalls.map((c) => c.options ?? null), + keydownOutside: keydownResult({}), + keydownInside: gate ? keydownResult({ parentGate: gate }) : null, +} + +process.stdout.write(JSON.stringify(result)) diff --git a/tests/unit/test_kiosk_gate_behavior.py b/tests/unit/test_kiosk_gate_behavior.py new file mode 100644 index 00000000..99f13a3c --- /dev/null +++ b/tests/unit/test_kiosk_gate_behavior.py @@ -0,0 +1,140 @@ +"""Behavioural coverage for files/k0s/kiosk/kiosk-gate.js. + +``kiosk-gate.js`` is the only thing standing between a kiosk visitor and a +console that looks logged-in but has no kc-agent behind it: it polls the +agent's health endpoint and, while a session exists but the agent is +unreachable, covers the page with a modal and swallows keystrokes aimed +outside it. + +Until now the script had no executed coverage at all. tests/unit/ +test_kubestellar_kiosk.py asserts that certain strings appear in the file +(``kc-has-session``, the health URL, ``aria-modal``, the keydown +registration), which is a packaging contract, not a behavioural one. Every +one of those assertions still passes if the session check is inverted, if the +gate is shown when the agent is *healthy*, if a failed poll stacks a second +modal on every tick, or if the keydown trap fires when no gate is present. + +These tests run the real script in node against a stub DOM +(``kiosk_gate_harness.mjs``) and assert what it actually does. +""" + +import json +import shutil +import subprocess +from pathlib import Path + +import pytest + +ROOT = Path(__file__).resolve().parents[2] +SCRIPT = ROOT / "files" / "k0s" / "kiosk" / "kiosk-gate.js" +HARNESS = Path(__file__).with_name("kiosk_gate_harness.mjs") + +NODE = shutil.which("node") + +pytestmark = pytest.mark.skipif( + NODE is None, reason="node is required to execute kiosk-gate.js" +) + + +def run_gate(**scenario) -> dict: + """Execute kiosk-gate.js under the stub DOM and return its observed effects.""" + proc = subprocess.run( + [NODE, str(HARNESS), str(SCRIPT), json.dumps(scenario)], + capture_output=True, + text=True, + check=True, + timeout=60, + ) + return json.loads(proc.stdout) + + +def test_gate_appears_when_a_session_exists_but_the_agent_is_unreachable() -> None: + result = run_gate(session="true", health="throw") + + assert result["afterLoad"]["gate"] is True + assert result["insertPosition"] == "beforeend" + assert 'role="dialog"' in result["gateHTML"] + assert 'aria-modal="true"' in result["gateHTML"] + assert "brew install kc-agent" in result["gateHTML"] + # The agent must be told to trust this console's own origin. + assert "-allowed-origins https://console.example" in result["gateHTML"] + + +def test_gate_appears_when_the_agent_answers_unhealthy() -> None: + # A reachable-but-failing agent is as useless as an absent one, so a + # non-2xx answer must gate just like a refused connection. + result = run_gate(session="true", health="error") + + assert result["afterLoad"]["gate"] is True + + +def test_no_gate_while_the_agent_is_healthy() -> None: + result = run_gate(session="true", health="ok") + + assert result["afterLoad"]["gate"] is False + assert result["afterTick"]["gate"] is False + + +def test_no_gate_before_the_user_has_a_session() -> None: + # Pre-login the console shows its own sign-in flow; gating there would + # bury it behind an agent instruction the visitor cannot act on yet. + result = run_gate(session=None, health="throw") + + assert result["afterLoad"]["gate"] is False + # No session means no reason to probe the agent at all. + assert result["afterLoad"]["fetchCalls"] == 0 + + +def test_unreadable_storage_is_treated_as_no_session() -> None: + # Private-mode browsers throw on localStorage access; the script must fail + # open rather than gate every visitor forever. + result = run_gate(storage="throws", health="throw") + + assert result["afterLoad"]["gate"] is False + assert result["afterLoad"]["fetchCalls"] == 0 + + +def test_gate_is_removed_once_the_agent_becomes_healthy() -> None: + result = run_gate(session="true", health="throw", health2="ok") + + assert result["afterLoad"]["gate"] is True + assert result["afterTick"]["gate"] is False + + +def test_repeated_failures_do_not_stack_duplicate_gates() -> None: + result = run_gate(session="true", health="throw") + + assert result["afterTick"]["fetchCalls"] == 2, "poll did not probe again" + assert result["afterTick"]["inserts"] == 1, "a second modal was stacked" + + +def test_agent_health_is_probed_without_credentials() -> None: + result = run_gate(session="true", health="ok") + + assert result["fetchURLs"] == ["http://127.0.0.1:8585/health"] * 2 + # The agent is a local daemon: sending console cookies to it is neither + # needed nor safe. + assert result["fetchOptions"] == [{"credentials": "omit"}] * 2 + + +def test_agent_health_is_polled_on_an_interval() -> None: + result = run_gate(session="true", health="ok") + + assert result["timers"] == [2000] + + +def test_keystrokes_outside_the_gate_are_swallowed_while_it_is_up() -> None: + result = run_gate(session="true", health="throw") + + assert result["keydownOutside"] is True + # Typing inside the dialog (copying the brew command, tabbing) must work. + assert result["keydownInside"] is False + assert {"type": "keydown", "capture": True} in result["listeners"] + + +def test_keystrokes_pass_through_when_no_gate_is_up() -> None: + # The trap is registered unconditionally at load, so it must no-op when + # the console is usable — otherwise a healthy kiosk is unusable. + result = run_gate(session="true", health="ok") + + assert result["keydownOutside"] is False From dc48bfb7fee829da60fe59d0bf5646f1e4c10eda Mon Sep 17 00:00:00 2001 From: "Jorge O. Castro" Date: Tue, 22 Sep 2026 16:38:40 -0400 Subject: [PATCH 32/42] revert: "docs: appliance identity, mDNS, and Bash prompt design (#208)" (#235) This reverts commit 3f7959217ab396bb30576f4fd013f2202c166707. The design specification contains an unviable mechanism: systemd-hostnamed writes /etc/hostname using WRITE_STRING_FILE_ATOMIC (open temporary file and renameat), which destroys the /etc/hostname symlink pointing to /var/lib/bluefin-server/hostname upon static hostname mutation. Reverting until an architecturally sound mechanism is reviewed independently. Assisted-by: github-copilot/gemini-3.8-flash via GitHub Copilot Co-authored-by: Jorge Castro Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../2026-09-09-appliance-identity-design.md | 147 ------------------ 1 file changed, 147 deletions(-) delete mode 100644 docs/superpowers/specs/2026-09-09-appliance-identity-design.md diff --git a/docs/superpowers/specs/2026-09-09-appliance-identity-design.md b/docs/superpowers/specs/2026-09-09-appliance-identity-design.md deleted file mode 100644 index ca5cef28..00000000 --- a/docs/superpowers/specs/2026-09-09-appliance-identity-design.md +++ /dev/null @@ -1,147 +0,0 @@ -# Appliance Identity, mDNS, and Bash Prompt Design - -**Status:** Approved design - -## Goal - -Give each Bluefin Server appliance a stable, human-readable network identity -and a clear interactive prompt. A newly provisioned appliance without an -operator-selected hostname is `blueserver-0`, reachable as -`blueserver-0.local`. - -## Scope - -- Persist a selected hostname across OS DDI updates. -- Default an unselected appliance to `blueserver-0`. -- Resolve and announce appliance names through mDNS on the wired appliance - network. -- Display `username@hostname` with a blue `@` in interactive Bash sessions. -- Direct console users to the hostname-based KubeStellar URL. - -This design does not add an authoritative DNS server, DHCP server, Avahi, or -automatic hostname allocation. - -## Naming Policy - -The recommended fleet sequence is `blueserver-0`, `blueserver-1`, -`blueserver-2`, and so on. The default is always `blueserver-0`; later -appliances receive an explicitly selected hostname through provisioning. - -An operator may select another valid lower-case static hostname, but -documentation recommends the numbered pattern and requires checking -`.local` before selecting a name. The system does not probe mDNS and -choose a number automatically: two simultaneous installations can otherwise -choose the same name. A collision is an operator-visible configuration error, -not a reason to silently rename an appliance. - -`blueserver.local` is intentionally not an alias. The canonical address is -always the selected hostname followed by `.local`, so each device has exactly -one predictable appliance name. - -## Persistent Hostname State - -`/var/lib/bluefin-server/hostname` is the canonical hostname source. It lives -on the persistent `/var` partition, outside the replaceable OS DDI. - -The image creates `/etc/hostname` as a symlink to that file. A static tmpfiles -rule creates the persistent source with `blueserver-0` only if it does not -exist. An operator-provided `tmpfiles.extra` credential can replace it before -first boot with a selected hostname: - -```text -f+~ /var/lib/bluefin-server/hostname 0644 root root - Ymx1ZXNlcnZlci0xCg== -``` - -The base64 payload in this example is `blueserver-1\n`. The hostname -application service validates the stored value as a lower-case hostname before -calling `hostnamectl set-hostname --static`. It runs after `/var` and tmpfiles -setup, and before the network and resolver services. If validation fails, the -service fails visibly and leaves networking available for local diagnosis; it -does not substitute or silently generate a different hostname. - -Because `/etc/hostname` points at the persistent source, an authenticated -operator may use `sudo hostnamectl set-hostname --static blueserver-1` to -rename an appliance. The change survives reboot and OS DDI replacement. - -## DNS and Discovery Plan - -Bluefin uses `systemd-resolved` and standards-based multicast DNS, not a local -DNS authority: - -1. Enable `systemd-resolved.service` in the installed OS and make - `/etc/resolv.conf` point at its local stub resolver. -2. Set `MulticastDNS=yes` and `LLMNR=no` on the existing wired - `systemd-networkd` profile. mDNS is required for `.local`; LLMNR is neither - needed nor desirable on an appliance network. -3. Set `MulticastDNS=yes` in resolved configuration as the explicit global - policy. -4. Announce and resolve the static hostname as `.local`; no search - domain or unicast DNS zone is configured. - -This works without router configuration on clients whose system resolver -supports mDNS. The appliance documentation will identify -`https://blueserver-0.local:8080/` as the first-appliance URL. The existing -local TLS wildcard certificate coverage remains compatible with named -`.local` access. - -## Bash Prompt - -Add FSDK's `bash-config` component so `/etc/bashrc` loads -`/etc/profile.d/*.sh` for interactive Bash sessions. A small profile hook sets -the following prompt only when `PS1` is present: - -```bash -PS1='\u\[\e[1;34m\]@\[\e[0m\]\h:\w\$ ' -``` - -It renders, for example: - -```text -core@blueserver-0:~$ -``` - -Only the `@` is bright blue. `\h` tracks the live system hostname, `\w` -retains working-directory context, and `\$` renders `$` for `core` and `#` -after `sudo -i`. - -## Console Experience - -The installed OS console issue banner uses systemd's hostname escape rather -than the address-derived IP escape. It directs an operator to: - -```text -KubeStellar Console: https://.local:8080/ -``` - -At runtime, a device named `blueserver-0` therefore displays -`https://blueserver-0.local:8080/`. - -## Failure Handling - -- An invalid supplied hostname fails the hostname service visibly; networking - is not blocked. -- A duplicate hostname is not renamed automatically. mDNS collision symptoms - require the operator to select a different persistent hostname. -- If `systemd-resolved` is unavailable, normal DNS resolution must fail - visibly through the service dependency rather than falling back to a - hand-written resolver file. -- The hostname and mDNS controls apply only to the installed OS, not the - Installer environment. - -## Verification - -Focused tests will assert the default and credential hostname rules, hostname -validation and service ordering, resolver enablement and mDNS/LLMNR policy, -the `/etc/resolv.conf` and `/etc/hostname` links, the console `.local` URL, -and the exact color-safe prompt definition. A QEMU smoke test will confirm -that a default installation announces and resolves `blueserver-0.local` after -DHCP is ready. - -## References - -- `systemd.network(5)`: - -- `systemd-resolved.service(8)`: - -- `tmpfiles.d(5)`: - From d0c770c701f8b55e11faf8a87169f2136358391f Mon Sep 17 00:00:00 2001 From: Bob Killen Date: Wed, 23 Sep 2026 06:09:51 -0500 Subject: [PATCH 33/42] feat(creds): extend systemd-creds provisioning to SSH keys, network, firstboot, and TPM2 (#221) Wire systemd credential provisioning for network configuration, first-boot locale/timezone/hostname settings, and SSH key provisioning: - bluefin-firstboot-credentials.service: runs systemd-firstboot non-interactively when firstboot.* credentials are present, setting the live hostname before networkd starts and stamping /etc/.bluefin-firstboot-credentials so it runs once. - 10-bluefin-credentials.conf: drop-in for systemd-network-generator importing network.conf.*, network.link.*, network.netdev.*, and network.network.* credentials under /run/systemd/network/, falling back to DHCP when absent. - Presets enabling bluefin-firstboot-credentials.service and systemd-network-generator.service. - os-creds-prov.bst: converted to manual element to stage sysusers credentials and systemd credential units, with strip-binaries disabled. - Document TPM2 sealing, ESP and hypervisor delivery for bare metal and VMs, and tmpfiles.extra payloads for SSH key provisioning. - Contract unit tests in test_credentials_provisioning.py. Fixes #138 Supersedes #144 Assisted-by: Gemini 3.8 Flash via GitHub Copilot Signed-off-by: mrbobbytables Co-authored-by: mrbobbytables Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/skills/architecture-roadmap.md | 7 +- docs/skills/ddi-installer.md | 22 ++- docs/skills/gap-analysis-distros.md | 11 +- docs/skills/tpm2-credential-sealing.md | 71 +++++++-- elements/bluefin-server/os-creds-prov.bst | 28 +++- .../bluefin-firstboot-credentials.service | 28 ++++ .../10-bluefin-credentials.conf | 5 + ...nable-bluefin-firstboot-credentials.preset | 1 + ...zz-enable-systemd-network-generator.preset | 1 + tests/unit/test_credentials_provisioning.py | 142 ++++++++++++++++++ 10 files changed, 287 insertions(+), 29 deletions(-) create mode 100644 files/os/creds/systemd/system/bluefin-firstboot-credentials.service create mode 100644 files/os/creds/systemd/system/systemd-network-generator.service.d/10-bluefin-credentials.conf create mode 100644 files/os/systemd/system-preset/zz-enable-bluefin-firstboot-credentials.preset create mode 100644 files/os/systemd/system-preset/zz-enable-systemd-network-generator.preset create mode 100644 tests/unit/test_credentials_provisioning.py diff --git a/docs/skills/architecture-roadmap.md b/docs/skills/architecture-roadmap.md index afa8eb0b..d7dc5f39 100644 --- a/docs/skills/architecture-roadmap.md +++ b/docs/skills/architecture-roadmap.md @@ -25,10 +25,9 @@ Priorities are derived from [gap-analysis-distros.md](gap-analysis-distros.md). | 1 | A/B dual-slot root partitions with matching ESP/UKI slots | Root fs only has slot A today; sysupdate already names slots A+B. | | 2 | Mount `/usr` read-only and enforce the state model | DDI is currently booted `rw`; sysext-first design assumes immutable `/usr`. | | 3 | Boot-time selection / automatic rollback of a failed update | No previous OS version is kept once a root update overwrites the slot. | -| 4 | Broader `systemd-creds` integration for SSH keys and network configuration | Only `root` password credential path is shipped in `os-creds-prov.bst`. | -| 5 | TPM2-bound credential delivery at first boot | Documented but not wired into the installed OS image. | -| 6 | Native reboot coordination for non-Kubernetes and single-node hosts | Kured only covers Kubernetes nodes; no FleetLock/locksmith equivalent. | -| 7 | Staged rollout behavior for larger fleets | Future after items 1-3 are implemented. | +| 4 | Credential provisioning smoke tests on real hardware | SSH keys, static network, and firstboot settings are wired through systemd credentials; TPM2-sealed credential decryption still needs hardware proof. | +| 5 | Native reboot coordination for non-Kubernetes and single-node hosts | Kured only covers Kubernetes nodes; no FleetLock/locksmith equivalent. | +| 6 | Staged rollout behavior for larger fleets | Future after items 1-3 are implemented. | ## Status notes diff --git a/docs/skills/ddi-installer.md b/docs/skills/ddi-installer.md index d073014f..fd3cf6b3 100644 --- a/docs/skills/ddi-installer.md +++ b/docs/skills/ddi-installer.md @@ -47,13 +47,21 @@ terminal-based interactive installation that: - Reboots into the installed system. User provisioning is handled on the target system's first boot via systemd -system credentials (`systemd-sysusers`, `systemd-tmpfiles`) so the base image -remains stateless. `systemd-firstboot.service` and -`systemd-homed-firstboot.service` are masked on the target image -(`/etc/systemd/system/systemd-firstboot.service -> /dev/null` and -`/etc/systemd/system/systemd-homed-firstboot.service -> /dev/null`) to guarantee -unattended, prompt-free startup. The target DDI also pre-stages the extracted CA -certificate bundle (`/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem` and +system credentials so the base image remains stateless. `systemd-sysusers` +consumes root account records, `systemd-tmpfiles` consumes `tmpfiles.extra` +for arbitrary first-boot files, and `systemd-network-generator` consumes +`network.conf.*` / `network.link.*` / `network.netdev.*` / +`network.network.*` credentials before networkd starts. The stock interactive +`systemd-firstboot.service` stays masked, but +`bluefin-firstboot-credentials.service` runs `systemd-firstboot` +non-interactively when `firstboot.locale`, `firstboot.timezone`, +`firstboot.hostname`, or related credentials are present. When +`firstboot.hostname` is supplied, the service also applies the live kernel +hostname before `systemd-networkd` starts so first-boot DHCP uses it. With no +credentials, the target keeps the default DHCP network and does not prompt. The +target DDI +also pre-stages the extracted CA certificate bundle +(`/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem` and `/etc/ssl/certs/ca-certificates.crt`) and a standard `/etc/hosts` file for container runtime pod sandboxes. diff --git a/docs/skills/gap-analysis-distros.md b/docs/skills/gap-analysis-distros.md index 12b44132..9ef63c08 100644 --- a/docs/skills/gap-analysis-distros.md +++ b/docs/skills/gap-analysis-distros.md @@ -97,7 +97,7 @@ Bluefin Server is a BuildStream 2-based, image-based Linux server OS built from | **Philosophy** | Systemd-native, minimal, image-based server OS appliance; base DDI includes bash for login and bring-up while heavy developer/debug tools live in sysexts or system containers; intended to run container workloads and Kubernetes via optional sysexts. Sources: [AGENTS.md](../../AGENTS.md), [factory-integration.md](factory-integration.md). | | **State model** | Target OS DDI is an XFS filesystem image. A separate persistent `/var` partition is created by the installer. There is no second root slot provisioned today, and the UKI cmdline currently uses `rw`, so the root is not mounted read-only at runtime. Sources: [bluefin-server-ddi.bst](../../elements/oci/bluefin-server-ddi.bst), [20-root-a.conf](../../files/installer/repart.d/20-root-a.conf), [bluefin-server-installer.bst](../../elements/oci/bluefin-server-installer.bst). | | **Updates** | `systemd-sysupdate` reads root/UKI transfers from `files/os/sysupdate.d/` and the optional k0s transfer from the `k0s` component directory. Assets are published to GitHub Releases, and the combined `SHA256SUMS` manifest is signed in CI with a GPG key. `Verify=yes` is the default. Sources: [systemd-sysupdate-verification.md](systemd-sysupdate-verification.md), [50-root.transfer](../../files/os/sysupdate.d/50-root.transfer), [60-uki.transfer](../../files/os/sysupdate.d/60-uki.transfer), [70-k0s.transfer](../../files/os/sysupdate.k0s.d/70-k0s.transfer), also `systemd-sysupdate(8)`. | -| **Provisioning** | The installer is an offline `systemd-sysinstall` image that embeds the DDI as a data partition. First-boot configuration is intended to be delivered via `systemd-creds` through the ESP or hypervisor metadata. Today only `passwd.hashed-password.root` is consumed via `systemd-sysusers.d`; the documented `tmpfiles.extra` path for SSH keys and similar files is not implemented. Sources: [bluefin-server-installer.bst](../../elements/oci/bluefin-server-installer.bst), [10-root-creds.conf](../../files/os/sysusers.d/10-root-creds.conf), [os-creds-prov.bst](../../elements/bluefin-server/os-creds-prov.bst), [systemd-creds(1)](https://www.freedesktop.org/software/systemd/man/latest/systemd-creds.html). | +| **Provisioning** | The installer is an offline `systemd-sysinstall` image that embeds the DDI as a data partition. First-boot configuration is delivered via `systemd-creds` through the ESP or hypervisor metadata: sysusers credentials cover root, `tmpfiles.extra` can write arbitrary first-boot files such as SSH `authorized_keys`, `network.*` credentials seed networkd, and `firstboot.*` credentials configure locale/timezone/hostname non-interactively. Sources: [bluefin-server-installer.bst](../../elements/oci/bluefin-server-installer.bst), [os-creds-prov.bst](../../elements/bluefin-server/os-creds-prov.bst), [tpm2-credential-sealing.md](tpm2-credential-sealing.md), [systemd-creds(1)](https://www.freedesktop.org/software/systemd/man/latest/systemd-creds.html). | | **Customization** | Adds software through `systemd-sysext` (overlay `/usr`) and `systemd-confext` (overlay `/etc`) images. The base OS `os-release` advertises `ID=flatcar` and a matching `VERSION_ID` so pre-built Flatcar Bakery extensions load. k0s is shipped as a separately built, optionally enabled sysext. Sources: [systemd-sysext-extensions.md](systemd-sysext-extensions.md), [k0s-sysext.md](k0s-sysext.md), [os-release-flatcar.bst](../../elements/bluefin-server/os-release-flatcar.bst), [systemd-sysext(8)](https://www.freedesktop.org/software/systemd/man/latest/systemd-sysext.html). | | **Reboot coordination** | `systemd-sysupdate.service` has an `ExecStartPost` that touches `/run/reboot-required`. Rolling reboots across Kubernetes nodes rely on Kured reading that file. Sources: [os-kured-hook.bst](../../elements/bluefin-server/os-kured-hook.bst), [kured-hook.conf](../../files/os/systemd/systemd-sysupdate.service.d/kured-hook.conf), [Kured project](https://github.com/weaveworks/kured). | @@ -112,10 +112,9 @@ Bluefin Server is a BuildStream 2-based, image-based Linux server OS built from ### Provisioning -- **Gap:** The documented `systemd-creds` first-boot provisioning for SSH keys (`tmpfiles.extra`) is not present in the build (`os-creds-prov.bst` only ships `sysusers.d`). - Operators can only pre-seed the root password today. -- **Gap:** `systemd-firstboot` is masked in the installer environment, so interactive first-boot questions are skipped; any further user/network/timezone configuration must be supplied through credentials that the build does not yet consume. -- **Gap:** TPM2 sealing for credentials is documented in `docs/skills/tpm2-credential-sealing.md`, but there is no evidence in the OS build that sealed credentials are generated, shipped, or decrypted automatically during first boot. +- **Remaining gap:** The credential consumers are wired through systemd-native + facilities, but TPM2-sealed credential decryption still needs a hardware boot + proof on a TPM2-equipped host. ### Update delivery @@ -134,7 +133,7 @@ Bluefin Server is a BuildStream 2-based, image-based Linux server OS built from 1. **A/B dual-slot rollback is not wired end-to-end.** The `sysupdate` transfer names `root-a`/`root-b`, but the installer only provisions `root-a`, so Bluefin cannot atomically stage and roll back a new root image today. 2. **Root filesystem immutability is not enforced.** The DDI is built and booted read-write; the intended read-only `/usr` + overlay model depends entirely on optional sysext behavior rather than runtime policy. -3. **First-boot credential provisioning is incomplete.** Only the `root` password credential path is shipped; SSH keys, network configuration, and other `systemd-creds`-based provisioning remain documented but not implemented. +3. **Credential provisioning hardware proof is incomplete.** SSH keys, network files, and firstboot settings are wired through `systemd-creds`; TPM2-sealed decryption still needs a hardware boot proof. These gaps drive the priorities in [architecture-roadmap.md](architecture-roadmap.md). diff --git a/docs/skills/tpm2-credential-sealing.md b/docs/skills/tpm2-credential-sealing.md index 44cef76a..1fa319e1 100644 --- a/docs/skills/tpm2-credential-sealing.md +++ b/docs/skills/tpm2-credential-sealing.md @@ -14,12 +14,22 @@ To secure sensitive provisioning credentials (such as hashed root passwords or SSH keys) against physical tampering or unauthorized extraction, bind them to the TPM2 and the UKI boot state using `systemd-creds`. -## Current scope +## Supported provisioning credentials -This skill is the canonical home for sealed credentials such as hashed root -passwords and similar provisioning secrets. Broader `systemd-creds` integration -for SSH keys and network configuration is a future roadmap item in -[architecture-roadmap.md](architecture-roadmap.md). +Bluefin Server consumes the same system credential names that systemd already +decrypts and routes at boot: + +| Credential | Consumer | Purpose | +|---|---|---| +| `passwd.hashed-password.root` | `systemd-sysusers` / `systemd-firstboot` | Optional root password hash for break-glass provisioning. | +| `tmpfiles.extra` | `systemd-tmpfiles` | Extra tmpfiles rules, such as writing an operator's SSH `authorized_keys`. | +| `network.network.*`, `network.netdev.*`, `network.link.*`, `network.conf.*` | `systemd-network-generator` | Static network, routes, virtual devices, and networkd config. | +| `network.dns`, `network.search_domains` | `systemd-resolved` | DNS resolver defaults. | +| `firstboot.locale`, `firstboot.locale-messages`, `firstboot.keymap`, `firstboot.timezone`, `firstboot.hostname` | `bluefin-firstboot-credentials.service` | Non-interactive locale, keymap, timezone, and hostname setup. | + +The stock DHCP network remains installed in `/usr/lib/systemd/network/20-wired.network`. +Credential-generated network files are emitted under `/run/systemd/network/` and +can use lower numeric prefixes such as `10-static.network` to override DHCP. ## Verify TPM2 device availability @@ -44,8 +54,9 @@ systemd-creds encrypt \ /path/to/secured_credential.cred ``` -- `--name=` must match the credential name the consumer expects (for example, - `passwd.hashed-password.root` is read by `systemd-sysusers`). +- `--name=` must match the credential name the consumer expects. Examples: + `passwd.hashed-password.root`, `tmpfiles.extra`, + `network.network.10-static`, or `firstboot.hostname`. - `--with-key=tpm2` forces a TPM2-bound credential. The default `auto` also uses the host key if `/var/lib/systemd/` is on persistent media; omit the switch if you want both bindings. @@ -58,14 +69,56 @@ Place the output `.cred` file in the ESP credential directory or pass it via a container/hypervisor mechanism: ```bash -# ESP delivery +# ESP delivery (bare metal or virtual machines) +# Mount the target host's EFI System Partition (ESP) and place credentials in /loader/credentials/ mkdir -p /loader/credentials/ -cp /path/to/secured_credential.cred /loader/credentials/passwd.hashed-password.root.cred +cp /path/to/secured_credential.cred \ + /loader/credentials/passwd.hashed-password.root.cred # Or via a container/hypervisor argument --set-credential=passwd.hashed-password.root:/path/to/secured_credential.cred ``` +On bare metal, an operator mounts the ESP partition (e.g. filesystem label +`EFI-SYSTEM` or partition type `C12A7328-F81F-11D2-BA4B-00A0C93EC93B`) and +places encrypted credential files into `/loader/credentials/`. During boot, +`systemd-creds` decrypts them and passes them to matching system consumers. + +### SSH key provisioning with tmpfiles.extra + +To provision SSH keys at first boot on bare metal or virtual machines, deliver a +`tmpfiles.extra` credential (for example `/loader/credentials/tmpfiles.extra.cred`). +`systemd-tmpfiles` consumes this credential on first boot. The payload must create +parent directories before writing the file. + +For the `root` account (or the `core` operator account once provisioned via PR #80): + +```text +d /root 0700 root root - +d /root/.ssh 0700 root root - +f~ /root/.ssh/authorized_keys 0600 root root - c3NoLWVkMjU1MTkgQUFBQUMzTnphQzFsWkRJMU5URTEAAAA... +``` + +Or for `core` (requires the account to already exist in `/etc/passwd` via sysusers): + +```text +d /var/home/core 0700 core core - +d /var/home/core/.ssh 0700 core core - +f~ /var/home/core/.ssh/authorized_keys 0600 core core - c3NoLWVkMjU1MTkgQUFBQUMzTnphQzFsWkRJMU5URTEAAAA... +``` + +Example static network credential name: `network.network.10-static`. + +```ini +[Match] +Name=en* + +[Network] +Address=192.0.2.10/24 +Gateway=192.0.2.1 +DNS=192.0.2.53 +``` + ## See also - [CONTEXT.md](../../CONTEXT.md) — canonical project domain glossary. diff --git a/elements/bluefin-server/os-creds-prov.bst b/elements/bluefin-server/os-creds-prov.bst index 6dcec45b..11440c23 100644 --- a/elements/bluefin-server/os-creds-prov.bst +++ b/elements/bluefin-server/os-creds-prov.bst @@ -1,9 +1,31 @@ -kind: import -description: Install first-boot systemd credentials provisioning helpers into target OS. +kind: manual + +description: | + Install first-boot systemd credential provisioning contracts into the target OS. + Supports sysusers credentials, systemd-network-generator network.* credentials, + and a non-interactive systemd-firstboot credential gate. + +build-depends: + - base/base-stack.bst sources: - kind: local path: files/os/sysusers.d + directory: sysusers-src + - kind: local + path: files/os/creds/systemd/system + directory: systemd-src + +# Disable binary stripping; this element only installs text files and the +# runtime-minimal sandbox does not include the stripper toolchain. +variables: + strip-binaries: "" config: - target: /usr/lib/sysusers.d + install-commands: + - | + set -euo pipefail + + install -Dm0644 sysusers-src/*.conf -t "%{install-root}/usr/lib/sysusers.d/" + mkdir -p "%{install-root}/usr/lib/systemd/system" + cp -a systemd-src/. "%{install-root}/usr/lib/systemd/system/" diff --git a/files/os/creds/systemd/system/bluefin-firstboot-credentials.service b/files/os/creds/systemd/system/bluefin-firstboot-credentials.service new file mode 100644 index 00000000..82e49eca --- /dev/null +++ b/files/os/creds/systemd/system/bluefin-firstboot-credentials.service @@ -0,0 +1,28 @@ +[Unit] +Description=Apply Bluefin first-boot system credentials +Documentation=man:systemd-firstboot(1) man:systemd.system-credentials(7) +ConditionPathIsReadWrite=/etc +DefaultDependencies=no +After=systemd-remount-fs.service systemd-sysusers.service systemd-tmpfiles-setup.service +Before=sysinit.target systemd-networkd.service +ConditionPathExists=!/etc/.bluefin-firstboot-credentials +ConditionCredential=|firstboot.locale +ConditionCredential=|firstboot.locale-messages +ConditionCredential=|firstboot.keymap +ConditionCredential=|firstboot.timezone +ConditionCredential=|firstboot.hostname + +[Service] +Type=oneshot +ImportCredential=firstboot.locale +ImportCredential=firstboot.locale-messages +ImportCredential=firstboot.keymap +ImportCredential=firstboot.timezone +ImportCredential=firstboot.hostname +ExecStart=systemd-firstboot --force --welcome=no +ExecStartPost=/bin/bash -eu -c 'if [ -n "$${CREDENTIALS_DIRECTORY:-}" ] && [ -s "$$CREDENTIALS_DIRECTORY/firstboot.hostname" ]; then hostname="$$(<"$$CREDENTIALS_DIRECTORY/firstboot.hostname")"; /usr/bin/hostname "$$hostname"; fi' +ExecStartPost=/usr/bin/touch /etc/.bluefin-firstboot-credentials +RemainAfterExit=yes + +[Install] +WantedBy=sysinit.target diff --git a/files/os/creds/systemd/system/systemd-network-generator.service.d/10-bluefin-credentials.conf b/files/os/creds/systemd/system/systemd-network-generator.service.d/10-bluefin-credentials.conf new file mode 100644 index 00000000..35e1c8a1 --- /dev/null +++ b/files/os/creds/systemd/system/systemd-network-generator.service.d/10-bluefin-credentials.conf @@ -0,0 +1,5 @@ +[Service] +ImportCredential=network.conf.* +ImportCredential=network.link.* +ImportCredential=network.netdev.* +ImportCredential=network.network.* diff --git a/files/os/systemd/system-preset/zz-enable-bluefin-firstboot-credentials.preset b/files/os/systemd/system-preset/zz-enable-bluefin-firstboot-credentials.preset new file mode 100644 index 00000000..f9d87187 --- /dev/null +++ b/files/os/systemd/system-preset/zz-enable-bluefin-firstboot-credentials.preset @@ -0,0 +1 @@ +enable bluefin-firstboot-credentials.service diff --git a/files/os/systemd/system-preset/zz-enable-systemd-network-generator.preset b/files/os/systemd/system-preset/zz-enable-systemd-network-generator.preset new file mode 100644 index 00000000..66311657 --- /dev/null +++ b/files/os/systemd/system-preset/zz-enable-systemd-network-generator.preset @@ -0,0 +1 @@ +enable systemd-network-generator.service diff --git a/tests/unit/test_credentials_provisioning.py b/tests/unit/test_credentials_provisioning.py new file mode 100644 index 00000000..f9c36654 --- /dev/null +++ b/tests/unit/test_credentials_provisioning.py @@ -0,0 +1,142 @@ +"""Contracts for first-boot systemd credential provisioning.""" + +from __future__ import annotations + +from pathlib import Path + +import yaml + +REPO_ROOT = Path(__file__).resolve().parents[2] +ELEMENT = REPO_ROOT / "elements" / "bluefin-server" / "os-creds-prov.bst" +STACK = REPO_ROOT / "elements" / "bluefin-server" / "os-stack.bst" +FIRSTBOOT = ( + REPO_ROOT + / "files" + / "os" + / "creds" + / "systemd" + / "system" + / "bluefin-firstboot-credentials.service" +) +FIRSTBOOT_PRESET = ( + REPO_ROOT + / "files" + / "os" + / "systemd" + / "system-preset" + / "zz-enable-bluefin-firstboot-credentials.preset" +) +NETWORK_GENERATOR_PRESET = ( + REPO_ROOT + / "files" + / "os" + / "systemd" + / "system-preset" + / "zz-enable-systemd-network-generator.preset" +) +NETWORK_GENERATOR_DROPIN = ( + REPO_ROOT + / "files" + / "os" + / "creds" + / "systemd" + / "system" + / "systemd-network-generator.service.d" + / "10-bluefin-credentials.conf" +) +NETWORK = REPO_ROOT / "files" / "os" / "systemd" / "network" / "20-wired.network" +TPM2_SKILL = REPO_ROOT / "docs" / "skills" / "tpm2-credential-sealing.md" + + +def test_creds_provisioning_element_stages_all_credential_consumers() -> None: + data = yaml.safe_load(ELEMENT.read_text(encoding="utf-8")) + + assert data["kind"] == "manual" + assert "base/base-stack.bst" in data["build-depends"] + assert "bluefin-server/os-creds-prov.bst" in STACK.read_text(encoding="utf-8") + + sources = {source["directory"]: source["path"] for source in data["sources"]} + assert sources == { + "sysusers-src": "files/os/sysusers.d", + "systemd-src": "files/os/creds/systemd/system", + } + + commands = "\n".join(data["config"]["install-commands"]) + assert "/usr/lib/sysusers.d/" in commands + assert "cp -a systemd-src/." in commands + + +def test_firstboot_credentials_are_noninteractive_and_presence_gated() -> None: + unit = FIRSTBOOT.read_text(encoding="utf-8") + + for credential in ( + "firstboot.locale", + "firstboot.locale-messages", + "firstboot.keymap", + "firstboot.timezone", + "firstboot.hostname", + ): + assert f"ConditionCredential=|{credential}" in unit + assert f"ImportCredential={credential}" in unit + + assert "ExecStart=systemd-firstboot --force --welcome=no" in unit + assert '/usr/bin/hostname "$$hostname"' in unit + assert unit.index("/usr/bin/hostname") < unit.index("/usr/bin/touch /etc/.bluefin-firstboot-credentials") + # Verify that shell variables in ExecStartPost are escaped with $$ so systemd does not expand them + exec_post_lines = [ + line for line in unit.splitlines() if line.startswith("ExecStartPost=") + ] + hostname_post = [line for line in exec_post_lines if "/usr/bin/hostname" in line][0] + assert "$$hostname" in hostname_post + assert "$$CREDENTIALS_DIRECTORY" in hostname_post + assert "$hostname" not in hostname_post.replace("$$hostname", "") + assert "--prompt" not in unit + assert "ConditionPathIsReadWrite=/etc" in unit + assert "ConditionPathExists=!/etc/.bluefin-firstboot-credentials" in unit + assert ( + "After=systemd-remount-fs.service systemd-sysusers.service " + "systemd-tmpfiles-setup.service" + in unit + ) + assert "WantedBy=sysinit.target" in unit + assert FIRSTBOOT_PRESET.read_text(encoding="utf-8") == ( + "enable bluefin-firstboot-credentials.service\n" + ) + + +def test_network_credentials_override_dhcp_without_removing_fallback() -> None: + network = NETWORK.read_text(encoding="utf-8") + skill = TPM2_SKILL.read_text(encoding="utf-8") + + assert network == "[Match]\nName=e*\n\n[Network]\nDHCP=ipv4\n" + assert "network.network.*" in skill + assert "network.netdev.*" in skill + assert NETWORK_GENERATOR_DROPIN.read_text(encoding="utf-8") == ( + "[Service]\n" + "ImportCredential=network.conf.*\n" + "ImportCredential=network.link.*\n" + "ImportCredential=network.netdev.*\n" + "ImportCredential=network.network.*\n" + ) + assert "systemd-network-generator" in skill + assert "/run/systemd/network/" in skill + assert "10-static.network" in skill + assert NETWORK_GENERATOR_PRESET.read_text(encoding="utf-8") == ( + "enable systemd-network-generator.service\n" + ) + + +def test_tpm2_sealing_docs_cover_all_supported_credential_names() -> None: + skill = TPM2_SKILL.read_text(encoding="utf-8") + + for credential in ( + "passwd.hashed-password.root", + "tmpfiles.extra", + "network.network.10-static", + "firstboot.hostname", + ): + assert credential in skill + + assert "--with-key=tpm2" in skill + assert "--tpm2-pcrs=7+11" in skill + assert "/loader/credentials/" in skill From f3c8975ab7f7f52586d5d659824990051efd4f8a Mon Sep 17 00:00:00 2001 From: Kyle Rankin Date: Wed, 23 Sep 2026 04:15:15 -0700 Subject: [PATCH 34/42] arch: make include/flatcar.yml the single source of truth for Flatcar pins (#143) * arch: make include/flatcar.yml the single source of truth for Flatcar pins include/flatcar.yml now declares every Flatcar upstream pin for the target release - the version, kernel vermagic, and the vmlinuz / container / zfs source sha256s - and every Flatcar element reads those values through %{...} variable substitution instead of restating a literal. - flatcar-kernel.bst and flatcar-zfs.bst reference %{flatcar-kernel-vmlinuz-sha256}, %{flatcar-kernel-container-sha256} and %{flatcar-zfs-sha256} instead of hard-coded refs. - Add .github/scripts/check-flatcar-version.py, a grep-based gate (in the spirit of check-release-version.py) that fails the build when any pinned literal appears outside include/flatcar.yml in elements/ or files/. - Wire the gate into 'just validate'. - Add unit tests covering declared_pins(), the scan, and the live-tree invariant. Signed-off-by: kylerankin * fix(flatcar): quote variable-substituted source refs A bare `%` is a reserved YAML indicator and cannot start a plain scalar, so `ref: %{flatcar-...-sha256}` made elements/flatcar/flatcar-kernel.bst and flatcar-zfs.bst unparseable. Both bst and the pytest suite failed to load the elements, breaking the unit, build and build-kernel jobs. Quote the refs so they parse; BuildStream expands %{...} in source configs, so the pins still resolve from include/flatcar.yml. Assisted-by: Claude Opus 4.6 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Signed-off-by: kylerankin Co-authored-by: castrojo Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/scripts/check-flatcar-version.py | 106 +++++++++++++ Justfile | 1 + elements/flatcar/flatcar-kernel.bst | 4 +- elements/flatcar/flatcar-zfs.bst | 2 +- include/flatcar.yml | 16 +- tests/unit/test_check_flatcar_version.py | 180 +++++++++++++++++++++++ 6 files changed, 305 insertions(+), 4 deletions(-) create mode 100755 .github/scripts/check-flatcar-version.py create mode 100644 tests/unit/test_check_flatcar_version.py diff --git a/.github/scripts/check-flatcar-version.py b/.github/scripts/check-flatcar-version.py new file mode 100755 index 00000000..0986af39 --- /dev/null +++ b/.github/scripts/check-flatcar-version.py @@ -0,0 +1,106 @@ +#!/usr/bin/env python3 +"""Enforce the Flatcar single-source-of-truth invariant. + +include/flatcar.yml is the ONLY place a Flatcar upstream version or sha256 is +declared. Every Flatcar element reads those values through %{...} variable +substitution (see elements/flatcar/*.bst); nothing restates a pin. + +This script fails the build when a pinned literal — a Flatcar version, kernel +vermagic, or source sha256 — is hardcoded anywhere in elements/ or files/, +where it would drift from include/flatcar.yml and silently pull a different +upstream payload than the pin file names. It reads the declared pins out of +include/flatcar.yml and greps the tree for any copy of them outside that file, +in the spirit of check-release-version.py. +""" + +import re +import sys +import os +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] +PIN_FILE = ROOT / "include" / "flatcar.yml" +SCAN_DIRS = (ROOT / "elements", ROOT / "files") + +# A `key: "value"` / `key: 'value'` / `key: bare` line inside the variables: +# block of the pin file. The captured group is the declared pin literal. +VAR_RE = re.compile( + r'^\s+[A-Za-z0-9_.-]+:\s*(?:"([^"]*)"|' r"'([^']*)'" r'|([^\s#]+))', + re.MULTILINE, +) +# Directories that legitimately echo upstream digests and must never be scanned. +SKIP_DIRS = {".git", "__pycache__", "node_modules"} + + +def read(path): + if not path.is_file(): + sys.exit(f"ERROR: expected file not found: {path.relative_to(ROOT)}") + return path.read_text(encoding="utf-8") + + +def declared_pins(pin_text): + """Every literal declared in the variables: block of the pin file.""" + pins = [] + for value in VAR_RE.findall(pin_text): + literal = next(part for part in value if part) + if literal: + pins.append(literal) + return pins + + +def iter_scan_files(): + for scan_dir in SCAN_DIRS: + if not scan_dir.is_dir(): + continue + # os.walk with dir pruning so files under .git / __pycache__ / + # node_modules are never read (rglob would flatten and scan them). + for root, dirs, files in os.walk(scan_dir): + dirs[:] = [d for d in dirs if d not in SKIP_DIRS] + for name in files: + if name.endswith(".pyc"): + continue + yield Path(root) / name + + +def is_binary(text): + return "\x00" in text + + +def main(): + pins = declared_pins(read(PIN_FILE)) + if not pins: + sys.exit( + "ERROR: include/flatcar.yml declares no pins to enforce. Add the " + "Flatcar version / sha256 variables here." + ) + + violations = [] + for path in iter_scan_files(): + try: + text = path.read_text(encoding="utf-8") + except (UnicodeDecodeError, OSError): + continue + if is_binary(text): + continue + for pin in pins: + if pin in text: + violations.append((path.relative_to(ROOT), pin)) + + if violations: + lines = [ + "ERROR: Flatcar pin(s) hardcoded outside include/flatcar.yml.\n" + "Every Flatcar version and sha256 must live in include/flatcar.yml " + "and be\n" + "referenced via %{...}; hardcoding one here lets it drift from the " + "pin file.\n" + "\nRemove the literal and read it from include/flatcar.yml:" + ] + for path, pin in violations: + lines.append(f" {path}: {pin}") + sys.exit("\n".join(lines)) + + print(f"OK: no Flatcar pins hardcoded outside include/flatcar.yml ({len(pins)} pinned).") + + +if __name__ == "__main__": + main() diff --git a/Justfile b/Justfile index f219be69..4013b6b3 100644 --- a/Justfile +++ b/Justfile @@ -56,6 +56,7 @@ validate: python3 .github/scripts/check-release-version.py python3 .github/scripts/check-k0s-version.py python3 .github/scripts/check-renovate-series.py + python3 .github/scripts/check-flatcar-version.py just bst show --deps all oci/bluefin-server-ddi.bst just bst show --deps all oci/bluefin-server-installer.bst just bst show --deps all oci/k0s-sysext.bst diff --git a/elements/flatcar/flatcar-kernel.bst b/elements/flatcar/flatcar-kernel.bst index fcaa1b4a..52c86f48 100644 --- a/elements/flatcar/flatcar-kernel.bst +++ b/elements/flatcar/flatcar-kernel.bst @@ -23,10 +23,10 @@ variables: sources: - kind: remote url: flatcar:stable/%{flatcar-board}/%{flatcar-version}/flatcar_production_image.vmlinuz - ref: fe0b7ef1f9f98acc00e1db22937cdc57456df860a372fdc8eb806298f767b676 + ref: "%{flatcar-kernel-vmlinuz-sha256}" - kind: remote url: flatcar:stable/%{flatcar-board}/%{flatcar-version}/flatcar-container.tar.gz - ref: c533ff576e128d11ce240e01f818c358d75b9ff118b2dd9199fbf4684547a32c + ref: "%{flatcar-kernel-container-sha256}" - kind: local path: patches/flatcar-kernel directory: patches diff --git a/elements/flatcar/flatcar-zfs.bst b/elements/flatcar/flatcar-zfs.bst index eabdcf8e..cb4e3d4d 100644 --- a/elements/flatcar/flatcar-zfs.bst +++ b/elements/flatcar/flatcar-zfs.bst @@ -19,7 +19,7 @@ variables: sources: - kind: remote url: flatcar:stable/%{flatcar-board}/%{flatcar-version}/flatcar-zfs.raw - ref: bed24d0a31b6c9ff0f1d59ec2b50d25585bf9bbcb8e9e96f5706f1a17948d971 + ref: "%{flatcar-zfs-sha256}" config: install-commands: diff --git a/include/flatcar.yml b/include/flatcar.yml index e8f7cb08..65c31007 100644 --- a/include/flatcar.yml +++ b/include/flatcar.yml @@ -1,7 +1,21 @@ # Single source of truth for Flatcar LTS kernel and sysext versioning. # # Flatcar LTS kernel and ZFS sysext must stay strictly in lockstep because -# OpenZFS modules (spl.ko, zfs.ko) require matching kernel vermagic (6.12.102-flatcar). +# OpenZFS modules (spl.ko, zfs.ko) require matching kernel vermagic +# (6.12.102-flatcar). +# +# This file is the ONLY place a Flatcar upstream version or sha256 is declared. +# Every Flatcar element references these values through %{...} variable +# substitution (see elements/flatcar/*.bst); no element or script restates a +# Flatcar version or sha256. .github/scripts/check-flatcar-version.py fails the +# build if a pinned literal is ever hardcoded outside this file. variables: flatcar-version: "4593.2.5" flatcar-kver: "6.12.102-flatcar" + + # sha256 of the upstream Flatcar sources, pinned in lockstep with + # flatcar-version / flatcar-kver. Bump all three together on a Flatcar + # release. + flatcar-kernel-vmlinuz-sha256: "fe0b7ef1f9f98acc00e1db22937cdc57456df860a372fdc8eb806298f767b676" + flatcar-kernel-container-sha256: "c533ff576e128d11ce240e01f818c358d75b9ff118b2dd9199fbf4684547a32c" + flatcar-zfs-sha256: "bed24d0a31b6c9ff0f1d59ec2b50d25585bf9bbcb8e9e96f5706f1a17948d971" diff --git a/tests/unit/test_check_flatcar_version.py b/tests/unit/test_check_flatcar_version.py new file mode 100644 index 00000000..cea495b3 --- /dev/null +++ b/tests/unit/test_check_flatcar_version.py @@ -0,0 +1,180 @@ +"""Unit coverage for .github/scripts/check-flatcar-version.py. + +The script enforces that include/flatcar.yml is the single source of truth for +every Flatcar upstream pin (version, kernel vermagic, source sha256): no pin +may be hardcoded in elements/ or files/. When it regresses, a pin can drift +from the pin file and silently pull a different upstream payload, so every +branch of declared_pins(), iter_scan_files() and main() is exercised here. +""" + +import importlib.util +import sys +from pathlib import Path + +import pytest + +REPO_ROOT = Path(__file__).resolve().parents[2] +SCRIPT_PATH = REPO_ROOT / ".github" / "scripts" / "check-flatcar-version.py" + +PIN_FILE_TEXT = ( + "variables:\n" + ' flatcar-version: "4593.2.5"\n' + ' flatcar-kver: "6.12.102-flatcar"\n' + " flatcar-zfs-sha256: " + '"bed24d0a31b6c9ff0f1d59ec2b50d25585bf9bbcb8e9e96f5706f1a17948d971"\n' +) + + +def _load_module(): + spec = importlib.util.spec_from_file_location("check_flatcar_version", SCRIPT_PATH) + module = importlib.util.module_from_spec(spec) + sys.modules["check_flatcar_version"] = module + spec.loader.exec_module(module) + return module + + +@pytest.fixture +def checker(tmp_path): + """Fresh module instance rooted at tmp_path with a synthetic pin file.""" + module = _load_module() + module.ROOT = tmp_path + (tmp_path / "include").mkdir() + (tmp_path / "include" / "flatcar.yml").write_text(PIN_FILE_TEXT, encoding="utf-8") + module.PIN_FILE = tmp_path / "include" / "flatcar.yml" + (tmp_path / "elements").mkdir() + (tmp_path / "files").mkdir() + module.SCAN_DIRS = (tmp_path / "elements", tmp_path / "files") + yield module + sys.modules.pop("check_flatcar_version", None) + + +# --- declared_pins -------------------------------------------------------- + + +def test_declared_pins_extracts_versions_and_sha256(checker): + pins = checker.declared_pins(PIN_FILE_TEXT) + assert pins == [ + "4593.2.5", + "6.12.102-flatcar", + "bed24d0a31b6c9ff0f1d59ec2b50d25585bf9bbcb8e9e96f5706f1a17948d971", + ] + + +def test_declared_pins_handles_bare_and_single_quoted_values(): + text = ( + "variables:\n" + " bare: 1.2.3\n" + " single: '4.5.6'\n" + ) + module = _load_module() + try: + assert module.declared_pins(text) == ["1.2.3", "4.5.6"] + finally: + sys.modules.pop("check_flatcar_version", None) + + +def test_declared_pins_ignores_comments_and_headers(): + text = ( + "# single source of truth\n" + "variables:\n" + " flatcar-version: \"4593.2.5\" # the release\n" + ) + module = _load_module() + try: + assert module.declared_pins(text) == ["4593.2.5"] + finally: + sys.modules.pop("check_flatcar_version", None) + + +# --- read / missing pin file --------------------------------------------- + + +def test_read_exits_on_missing_pin_file(checker): + checker.PIN_FILE = checker.PIN_FILE.parent / "missing.yml" + with pytest.raises(SystemExit) as excinfo: + checker.main() + assert "expected file not found" in str(excinfo.value) + + +def test_main_exits_when_no_pins_declared(tmp_path): + (tmp_path / "include").mkdir(parents=True) + (tmp_path / "include" / "flatcar.yml").write_text("variables:\n", encoding="utf-8") + module = _load_module() + module.ROOT = tmp_path + module.PIN_FILE = tmp_path / "include" / "flatcar.yml" + module.SCAN_DIRS = () + try: + with pytest.raises(SystemExit) as excinfo: + module.main() + assert "declares no pins" in str(excinfo.value) + finally: + sys.modules.pop("check_flatcar_version", None) + + +# --- main() --------------------------------------------------------------- + + +def test_main_passes_when_tree_is_clean(checker): + (checker.ROOT / "elements" / "flatcar-zfs.bst").write_text( + "sources:\n" + " - kind: remote\n" + " url: flatcar:stable/%{flatcar-board}/%{flatcar-version}/flatcar-zfs.raw\n" + " ref: %{flatcar-zfs-sha256}\n", + encoding="utf-8", + ) + checker.main() + + +def test_main_fails_when_sha256_hardcoded_in_element(checker, capsys): + (checker.ROOT / "elements" / "flatcar-zfs.bst").write_text( + "sources:\n" + " - kind: remote\n" + " url: flatcar:stable/%{flatcar-board}/%{flatcar-version}/flatcar-zfs.raw\n" + " ref: bed24d0a31b6c9ff0f1d59ec2b50d25585bf9bbcb8e9e96f5706f1a17948d971\n", + encoding="utf-8", + ) + with pytest.raises(SystemExit) as excinfo: + checker.main() + message = str(excinfo.value) + assert "hardcoded outside" in message + assert "flatcar-zfs.bst" in message + assert "bed24d0a31b6c9ff0f1d59ec2b50d25585bf9bbcb8e9e96f5706f1a17948d971" in message + + +def test_main_fails_when_version_hardcoded_in_files(checker, capsys): + (checker.ROOT / "files" / "os-release").write_text( + 'NAME="Bluefin Server"\nVERSION="4593.2.5-fsd"\n', encoding="utf-8" + ) + with pytest.raises(SystemExit) as excinfo: + checker.main() + message = str(excinfo.value) + assert "hardcoded outside" in message + assert "files/os-release" in message + assert "4593.2.5" in message + + +def test_main_skips_binary_and_scanned_hidden_dirs(checker): + # A sha256 inside a .git / __pycache__ dir must NOT be flagged. + git_dir = checker.ROOT / "elements" / ".git" + pycache = checker.ROOT / "elements" / "__pycache__" + git_dir.mkdir(parents=True) + pycache.mkdir(parents=True) + (git_dir / "keep").write_text( + "bed24d0a31b6c9ff0f1d59ec2b50d25585bf9bbcb8e9e96f5706f1a17948d971\n", + encoding="utf-8", + ) + (pycache / "x.pyc").write_bytes(b"\x00bed24d0a31b6c9ff0f1d59ec2b50d25585\n") + checker.main() + + +# --- live repository invariant ------------------------------------------- + + +def test_real_repository_has_no_hardcoded_flatcar_pins(capsys): + """The checked-in tree must satisfy the invariant the script enforces.""" + module = _load_module() + try: + module.main() + finally: + sys.modules.pop("check_flatcar_version", None) + assert "OK: no Flatcar pins" in capsys.readouterr().out From 429827830b6703e5deb5c0d82d54d4623a1cc358 Mon Sep 17 00:00:00 2001 From: Kyle Rankin Date: Wed, 23 Sep 2026 04:54:48 -0700 Subject: [PATCH 35/42] fix(kiosk): console shows live local cluster state on first boot (#214) * fix(kiosk): console shows live local cluster state on first boot On a freshly installed single-node k0s cluster no client kc-agent is connected yet, so the KubeStellar console fell back to mock/demo cards instead of the real cluster. - Set NO_LOCAL_AGENT so the console reads the local embedded k0s API directly from this pod's ServiceAccount instead of waiting for a connected kc-agent. - Set SKIP_ONBOARDING so the kiosk shows the dashboard immediately. - Add a read-only ClusterRole bound to the console ServiceAccount so the in-cluster reads for nodes, namespaces and pods succeed. Assisted-by: lemonade/Ornith-1.5-35B-A3B-GGUF-Q6_K via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: kylerankin * fix(kiosk): correct limitranges RBAC resource and SKIP_ONBOARDING doc - 42-kubestellar-console-rbac.yaml: limitquotas is not a Kubernetes resource; the intended grant was limitranges. Misspelled resources are silently ignored in RBAC rules, so LimitRange reads were forbidden. - SKIP_ONBOARDING comment: it skips the onboarding questionnaire, not sign-in (sign-in is bypassed by DEV_MODE/DEV_USER_LOGIN). - NO_LOCAL_AGENT comment: the console forces this in-cluster regardless; the real fix for #193 is the ServiceAccount + read RBAC. Addresses kubestellar-hive review findings on #214. * fix(kiosk): scope console RBAC to real resources and correct comments Follow-up to the #214 review findings. - 42-kubestellar-console-rbac.yaml: replicationcontrollers is a core ("") resource, not an apps resource. Listed under apps it was silently ignored in the RBAC rule, exactly like the limitquotas typo, so the grant never applied. Move it to the core group. - Document why the ClusterRole reads configmaps, events, limitranges and resourcequotas: the console dashboard renders them (namespace overview and ConfigMap cards). Record that verbs stay read-only, secrets are excluded, and the console is only reachable via the 127.0.0.1-bound kiosk proxy. - 40-kubestellar-console.yaml: attribute the fix to the ServiceAccount plus read RBAC. The console backend already forces NO_LOCAL_AGENT on in-cluster, so the env var only records intent. Note that SKIP_ONBOARDING skips the questionnaire and DEV_MODE/DEV_USER_LOGIN bypasses sign-in. - tests: pin every ClusterRole resource name to the real resource for its apiGroup and assert secrets are never granted, so a misspelled or misgrouped resource fails the suite instead of silently dropping the grant. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Signed-off-by: kylerankin Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../kubestellar/40-kubestellar-console.yaml | 16 ++++ .../42-kubestellar-console-rbac.yaml | 72 ++++++++++++++++++ tests/unit/test_k0s_manifests.py | 1 + tests/unit/test_kubestellar_kiosk.py | 75 +++++++++++++++++++ 4 files changed, 164 insertions(+) create mode 100644 files/k0s/manifests/kubestellar/42-kubestellar-console-rbac.yaml diff --git a/files/k0s/manifests/kubestellar/40-kubestellar-console.yaml b/files/k0s/manifests/kubestellar/40-kubestellar-console.yaml index fc502bdf..be226493 100644 --- a/files/k0s/manifests/kubestellar/40-kubestellar-console.yaml +++ b/files/k0s/manifests/kubestellar/40-kubestellar-console.yaml @@ -38,6 +38,7 @@ spec: labels: app.kubernetes.io/name: kubestellar-console spec: + serviceAccountName: kubestellar-console containers: - name: console image: ghcr.io/kubestellar/console:v0.3.34 @@ -48,6 +49,21 @@ spec: value: "true" - name: DEV_USER_LOGIN value: "admin" + # First-boot fix (#193): on a freshly installed single-node k0s cluster + # no client kc-agent is connected yet, so the console must read the local + # embedded k0s API directly instead of defaulting to mock/demo cards. + # The fix is the ServiceAccount above plus the read-only ClusterRole in + # 42-kubestellar-console-rbac.yaml; NO_LOCAL_AGENT is set only to make + # that intent explicit, since the console backend already forces it on + # when it detects it is running in-cluster. SKIP_ONBOARDING skips the + # onboarding questionnaire so the kiosk shows the dashboard immediately + # (sign-in is bypassed separately by DEV_MODE/DEV_USER_LOGIN above). + - name: SKIP_ONBOARDING + value: "true" + - name: NO_LOCAL_AGENT + value: "true" + - name: POD_NAMESPACE + value: "kubestellar-console" - name: GITHUB_CLIENT_ID valueFrom: secretKeyRef: diff --git a/files/k0s/manifests/kubestellar/42-kubestellar-console-rbac.yaml b/files/k0s/manifests/kubestellar/42-kubestellar-console-rbac.yaml new file mode 100644 index 00000000..efbc1708 --- /dev/null +++ b/files/k0s/manifests/kubestellar/42-kubestellar-console-rbac.yaml @@ -0,0 +1,72 @@ +# First-boot fix (#193): the console pod reads the local embedded k0s cluster +# directly, so it needs read access to render live nodes, namespaces and pods +# instead of falling back to demo cards. This ServiceAccount plus the read-only +# ClusterRole below is the actual mechanism behind the fix. Bound to the +# console's own ServiceAccount so the default account stays unprivileged. +# +# Scope note: the resource list mirrors what the console dashboard renders -- +# the namespace overview and ConfigMap cards read configmaps, and the resource +# cards read events, limitranges and resourcequotas. Verbs are read-only and +# the console is only reachable through the 127.0.0.1-bound kiosk proxy +# (41-kubestellar-kiosk-proxy.yaml), never from the network. Secrets are +# deliberately excluded. Resource names must be exact: Kubernetes silently +# ignores unknown names in RBAC rules, so a typo removes the grant without any +# error (see tests/unit/test_kubestellar_kiosk.py). +apiVersion: v1 +kind: ServiceAccount +metadata: + name: kubestellar-console + namespace: kubestellar-console + labels: + app.kubernetes.io/name: kubestellar-console +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRole +metadata: + name: kubestellar-console-reader + labels: + app.kubernetes.io/name: kubestellar-console +rules: +- apiGroups: [""] + resources: + - nodes + - namespaces + - pods + - services + - configmaps + - events + - persistentvolumes + - persistentvolumeclaims + - serviceaccounts + - endpoints + - limitranges + - resourcequotas + - replicationcontrollers + verbs: ["get", "list", "watch"] +- apiGroups: ["apps"] + resources: + - deployments + - statefulsets + - daemonsets + - replicasets + verbs: ["get", "list", "watch"] +- apiGroups: ["batch"] + resources: + - jobs + - cronjobs + verbs: ["get", "list", "watch"] +--- +apiVersion: rbac.authorization.k8s.io/v1 +kind: ClusterRoleBinding +metadata: + name: kubestellar-console-reader + labels: + app.kubernetes.io/name: kubestellar-console +roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: kubestellar-console-reader +subjects: +- kind: ServiceAccount + name: kubestellar-console + namespace: kubestellar-console diff --git a/tests/unit/test_k0s_manifests.py b/tests/unit/test_k0s_manifests.py index 149ca421..36d65c73 100644 --- a/tests/unit/test_k0s_manifests.py +++ b/tests/unit/test_k0s_manifests.py @@ -38,6 +38,7 @@ def test_k0s_manifest_files(): assert (ks_dir / "30-kubestellar-core.yaml").is_file() assert (ks_dir / "40-kubestellar-console.yaml").is_file() assert (ks_dir / "41-kubestellar-kiosk-proxy.yaml").is_file() + assert (ks_dir / "42-kubestellar-console-rbac.yaml").is_file() def test_postgres_password_not_hardcoded(): diff --git a/tests/unit/test_kubestellar_kiosk.py b/tests/unit/test_kubestellar_kiosk.py index ec608c72..1da8f45e 100644 --- a/tests/unit/test_kubestellar_kiosk.py +++ b/tests/unit/test_kubestellar_kiosk.py @@ -2,6 +2,8 @@ from pathlib import Path +import yaml + ROOT = Path(__file__).resolve().parents[2] KIOSK = ROOT / "files" / "k0s" / "kiosk" KIOSK_CONF = KIOSK / "nginx.conf" @@ -87,6 +89,14 @@ def test_console_provides_local_and_oauth_login_options() -> None: assert 'value: "true"' in console assert "name: ALLOW_DEV_MODE_IN_CLUSTER" in console assert "hostPort:" not in console + # #193: on first boot the console must read the local k0s cluster directly + # (no connected kc-agent yet) and skip the onboarding questionnaire. + # SKIP_ONBOARDING skips the questionnaire, not sign-in; sign-in is bypassed + # by DEV_MODE/DEV_USER_LOGIN. + assert "name: SKIP_ONBOARDING" in console + assert "name: NO_LOCAL_AGENT" in console + assert "name: POD_NAMESPACE" in console + assert "serviceAccountName: kubestellar-console" in console assert "name: GITHUB_CLIENT_ID" in console assert "name: GITHUB_CLIENT_SECRET" in console assert "name: kubestellar-console-github-oauth" in console @@ -107,3 +117,68 @@ def test_proxy_is_the_only_public_console_endpoint() -> None: "nginx@sha256:62223d644fa234c3a1cc785ee14242ec47a77364226f1c811d2f669f96dc2ac8" in proxy ) + + +def test_console_rbac_reads_only_the_local_cluster() -> None: + rbac = ( + ROOT + / "files" + / "k0s" + / "manifests" + / "kubestellar" + / "42-kubestellar-console-rbac.yaml" + ).read_text(encoding="utf-8") + docs = list(yaml.safe_load_all(rbac)) + kinds = [d.get("kind") for d in docs if d] + assert kinds == [ + "ServiceAccount", + "ClusterRole", + "ClusterRoleBinding", + ] + + sa = next(d for d in docs if d["kind"] == "ServiceAccount") + assert sa["metadata"]["namespace"] == "kubestellar-console" + + role = next(d for d in docs if d["kind"] == "ClusterRole") + # Read-only: never grant write verbs to the console's account. + for rule in role["rules"]: + assert set(rule["verbs"]) <= {"get", "list", "watch"} + resources = {r for rule in role["rules"] for r in rule["resources"]} + assert {"nodes", "namespaces", "pods"} <= resources + # Kubernetes silently ignores resource names that do not exist in the named + # apiGroup, so a typo (e.g. "limitquotas") drops the grant with no error. + # Pin every name to the real resource for its group. + known_resources = { + "": { + "configmaps", + "endpoints", + "events", + "limitranges", + "namespaces", + "nodes", + "persistentvolumeclaims", + "persistentvolumes", + "pods", + "replicationcontrollers", + "resourcequotas", + "serviceaccounts", + "services", + }, + "apps": {"daemonsets", "deployments", "replicasets", "statefulsets"}, + "batch": {"cronjobs", "jobs"}, + } + for rule in role["rules"]: + for group in rule["apiGroups"]: + assert group in known_resources, f"unexpected apiGroup {group!r}" + unknown = set(rule["resources"]) - known_resources[group] + assert not unknown, f"not real resources in apiGroup {group!r}: {unknown}" + # The kiosk dashboard never needs secrets; keep them out of the grant. + assert "secrets" not in resources + + binding = next(d for d in docs if d["kind"] == "ClusterRoleBinding") + assert binding["roleRef"]["kind"] == "ClusterRole" + assert binding["roleRef"]["name"] == role["metadata"]["name"] + subject = binding["subjects"][0] + assert subject["kind"] == "ServiceAccount" + assert subject["name"] == "kubestellar-console" + assert subject["namespace"] == "kubestellar-console" From ab5a717751c5142915ce00050d4ba176f5a7e013 Mon Sep 17 00:00:00 2001 From: Kyle Rankin Date: Wed, 23 Sep 2026 04:55:22 -0700 Subject: [PATCH 36/42] fix(k0s): pin argocd image by digest and upgrade past EOL v2.12.3 (#212) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix(k0s): pin argocd image by digest and upgrade past EOL v2.12.3 argocd-server ran quay.io/argoproj/argocd:v2.12.3 (the EOL 2.12 line with unbackported CVEs) by mutable tag, so a re-pointed or compromised tag could silently change what runs. Upgrade to the latest supported v2.14.9 and pin by digest so the running image is integrity-checked. --insecure serves plaintext HTTP; keep it only because the argocd-server Service is ClusterIP-only, and document that it must stay internal (terminate TLS at a proxy, then drop the flag) rather than silently disabling it and breaking the deployment. sec-check #74 Signed-off-by: kylerankin * fix(k0s): repin argocd to the live v2.14.9 manifest digest The previously pinned digest sha256:af3dfddc… is a legacy schema-v1 manifest that returns 404 on digest lookup; kubelet pulls tag@digest with manifest-list accept types, so argocd-server lands in ImagePullBackOff. Verified against quay.io: af3dfddc… 404s on every content type, while the v2.14.9 index sha256:f5885af0… resolves for all types and carries the amd64 child 78e45540…. Note: the 2.14 line is itself past EOL (3.x is current); the digest fix removes the hard regression but a maintainer may prefer a supported 3.x release. --------- Signed-off-by: kylerankin --- files/k0s/manifests/argocd/install.yaml | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/files/k0s/manifests/argocd/install.yaml b/files/k0s/manifests/argocd/install.yaml index ceb45aff..3d0e9dd9 100644 --- a/files/k0s/manifests/argocd/install.yaml +++ b/files/k0s/manifests/argocd/install.yaml @@ -41,7 +41,12 @@ spec: serviceAccountName: argocd-server containers: - name: argocd-server - image: quay.io/argoproj/argocd:v2.12.3 + # pinned by digest so a re-pointed tag cannot silently change what runs + # (sec-check #74: was mutable tag v2.12.3, EOL with unbackported CVEs) + image: quay.io/argoproj/argocd:v2.14.9@sha256:f5885af084da62a952e73cf68df355b28af62894e3779ef4da4ed93a717d8f70 + # --insecure serves plaintext HTTP; acceptable only because the Service + # below is ClusterIP-only and must stay that way. Expose this externally + # only behind a TLS-terminating proxy, then drop --insecure. command: [argocd-server, --insecure, --staticassets, /shared/app] ports: - containerPort: 8080 From 90f37fd8f4146b7a69bebd3fac86fbd1743c132a Mon Sep 17 00:00:00 2001 From: Danathar Date: Wed, 23 Sep 2026 07:56:18 -0400 Subject: [PATCH 37/42] test(installer): behavioural contract for the QEMU boot-proof readiness gate (#219) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * test(installer): behavioural contract for the QEMU boot-proof readiness gate test-installer-artifact (the recipe show-me-the-future delegates to) polls /healthz and / after booting the installed target in QEMU, and only breaks out of the loop when the healthz body reports status "ok" AND the root probe answers HTTP 200. Nothing exercised that decision logic before this change: a prior attempt at issue #130 (PR #179) sliced the recipe body out of the Justfile as text and asserted substrings, so every assertion stayed green whether the underlying checks were correct, weakened, or deleted. This suite instead runs the real recipe in a private sandbox copy of the Justfile (the tests/unit/flash-installer_test.bats pattern), with qemu-system-x86_64, curl and zstd replaced by logging stubs on PATH so 'just test-installer-artifact' actually executes. It proves, by running the recipe rather than describing it: - readiness requires both conditions together, not either alone - a failing/malformed healthz body short-circuits before the root probe is ever called - a QEMU process that dies before answering is detected and reported, independent of curl/jq state - the serial log tail is dumped on both failure paths (timeout and death) One substitution is applied to the sandboxed Justfile, asserted the same way flash-installer_test.bats asserts its own: the OVMF_CODE lookup only searches hardcoded absolute host paths, none of which exist on an unprivileged CI runner, so the recipe would abort before ever reaching the readiness loop. An env-gated candidate is added to the front of the existing first_existing() call; unset, it defaults to a nonexistent path, so production behaviour is unchanged. Verified non-vacuous: dropping the root-code check (collapsing the two conditions into one, as a plausible regression) fails 2 of the 10 cases; restoring it is green again. os-base: flatcar (#130's acceptance line) does not exist on main yet — no such build option exists anywhere in the tree, and the whole Flatcar-base cutover cluster (#132/#133/#136/#140/#163/#191) is parked 2-discussing pending the hard-rule-1 ADR decision on #133. This does not close #130; it pins the readiness contract that show-me-the-future/test-installer-artifact already enforce today, independent of which payload eventually boots under it, so the gate stays guarded while that decision is pending. Assisted-by: Claude via Claude Code Co-authored-by: Claude Signed-off-by: Danathar * test(installer): rewrite the readiness contract around the in-guest probe #220 moved the readiness decision into the guest: a systemd unit injected over an SMBIOS credential polls the kiosk proxy and prints KIOSK_CONSOLE_READY on the console, and the host only greps the serial log for that marker. Four tests still drove a host-side curl loop that no longer exists and failed at the merged head. Drive the host decision through the serial log instead: the marker present, a progress line only, no marker at all, and a near-miss substring. Guard the two conditions and the credential delivery as text in the unit, and assert this recipe runs no host-side probe (scoped to its own body, since install-vm legitimately forwards its own ports). Four recipe mutations each fail between one and four tests. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01YQCk7xJDvhtPoc4mWPzVCK Signed-off-by: Douglas Baggett * fix(test): scope the SMBIOS credential guard to test-installer-artifact install-vm (#227) reuses the same kiosk-ready credential and cmdline mechanism, so it now carries its own copy of both strings. A whole-file grep -c counts both recipes' copies and fails against current main (count 2, not 1). Scope the guard to this recipe's body, the same way the host-probe guard just below it already does. Co-Authored-By: Claude Sonnet 5 * docs(test): describe what the readiness suite actually proves The file header and curl-stub comments described an earlier revision of this suite, from before the readiness probe moved into the guest (#220): they claimed the two-condition check was exercised by routing requests through the curl stub and parsing the body with jq. Nothing does that at head, and the check is jq -r .status, not jq -e. Rewrite the header to state the split the suite actually implements: the host-side loop (marker, target death, deadline, log tail) is executed for real against the sandboxed recipe, while the in-guest two-condition check is pinned by fixed-string greps because it can only run inside the booted guest. Correct the near-miss test's comment, which claimed exact-line matching that the recipe's unanchored grep does not do, and the refute_host_probe_attempted comment, which described a URL-shaped match it no longer performs. Drop the CURL_HEALTHZ_EXIT/CURL_HEALTHZ_BODY/CURL_ROOT_EXIT/CURL_ROOT_CODE knobs: no test sets them, the host never invokes curl, and one test asserts exactly that. The stub keeps its call logging, which refute_host_probe_ attempted needs, and now fails loudly if the host ever does probe. No behavioural assertion changes; 12/12 still pass. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Signed-off-by: Danathar Signed-off-by: Douglas Baggett Co-authored-by: Danathar Co-authored-by: Claude Co-authored-by: hive-scanner <223556219+Copilot@users.noreply.github.com> --- tests/unit/test-installer-artifact_test.bats | 365 +++++++++++++++++++ 1 file changed, 365 insertions(+) create mode 100755 tests/unit/test-installer-artifact_test.bats diff --git a/tests/unit/test-installer-artifact_test.bats b/tests/unit/test-installer-artifact_test.bats new file mode 100755 index 00000000..173a7925 --- /dev/null +++ b/tests/unit/test-installer-artifact_test.bats @@ -0,0 +1,365 @@ +#!/usr/bin/env bats +# +# Behavioural contract for the readiness-decision logic inside the +# `test-installer-artifact` recipe (the recipe `show-me-the-future` delegates +# to after `build-installer`/`export-installer`). This is the boot-proof gate +# named in issue #130. +# +# A prior attempt at this issue (#179) was closed because its test sliced +# recipe bodies out of the Justfile as text and asserted substrings — every +# assertion passed whether the underlying health check was correct, weakened, +# or deleted, because it matched echo/log wording rather than the checks +# themselves. +# +# The readiness decision is split across two sides, and this suite covers +# them differently because only one of them is reachable from a test host: +# +# * Host side (executed for real): the recipe boots the target under QEMU +# and waits for the in-guest unit's `KIOSK_CONSOLE_READY` marker to +# appear in the serial log, failing on target death or deadline. The +# suite runs the real recipe — a private sandbox copy of the Justfile, +# with `qemu-system-x86_64`, `curl` and `zstd` replaced by logging stubs +# on PATH, the same pattern as `flash-installer_test.bats` — so +# `just test-installer-artifact` actually executes and the marker / +# PID-death / timeout / log-tail behaviour is exercised, not paraphrased. +# +# * Guest side (guarded as text): since #220 the two-condition check +# (`/healthz` reporting `status: ok` AND `/` answering HTTP 200) lives in +# a systemd unit injected over an SMBIOS credential and only ever runs +# inside the booted guest, against a proxy bound to the guest's +# loopback. Nothing on the host can execute it, so it is pinned by +# fixed-string greps of the unit's ExecStart (the `guard:` tests below). +# Those guards fail if either condition is weakened or dropped. +# +# One substitution is applied to the sandboxed Justfile, and asserted exactly +# like `flash-installer_test.bats` asserts its own: the recipe's OVMF +# firmware lookup only searches hardcoded absolute host paths +# (/usr/share/OVMF/..., linuxbrew Cellar paths, ...), none of which exist on +# an unprivileged CI runner, so the recipe would abort before ever reaching +# the readiness loop. `first_existing` is given one extra, env-controlled +# candidate at the front of its list; left unset it defaults to a path that +# does not exist, so production behaviour is unchanged. QEMU itself never +# reads the firmware content the stub points at, so the file only needs to +# exist. +# +# `os-base: flatcar` (issue #130's acceptance line) does not exist on `main` +# — there is no such build option anywhere in the tree — so this suite proves +# the readiness contract that `show-me-the-future`/`test-installer-artifact` +# already enforce today, independent of which payload eventually boots under +# it. It does not, and cannot yet, close #130. + +setup() { + if ! command -v just >/dev/null 2>&1; then + skip "just is not installed" + fi + if ! command -v jq >/dev/null 2>&1; then + skip "jq is not installed" + fi + + REPO_ROOT="$(cd "${BATS_TEST_DIRNAME}/../.." && pwd)" + JUSTFILE="${REPO_ROOT}/Justfile" + SANDBOX="${BATS_TEST_TMPDIR}/sandbox" + STUB_DIR="${BATS_TEST_TMPDIR}/bin" + LOG="${BATS_TEST_TMPDIR}/calls.log" + + mkdir -p "$STUB_DIR" "$SANDBOX/dist" "$SANDBOX/cache" "$SANDBOX/elements" + : > "$LOG" + + # The recipe reads no repository state other than dist/, but the + # Justfile's top-level backtick assignments inspect + # elements/freedesktop-sdk.bst regardless of which recipe runs. Copy it + # so loading the sandbox Justfile behaves exactly like the real one. + cp "${REPO_ROOT}/elements/freedesktop-sdk.bst" "${SANDBOX}/elements/" + + # Seed the exported artefacts the recipe copies out of dist/. + : > "${SANDBOX}/dist/bluefin-server-installer-1.0.raw.zst" + : > "${SANDBOX}/dist/bluefin-server-pxe-vmlinuz-1.0" + : > "${SANDBOX}/dist/bluefin-server-pxe-initrd-1.0.cpio.gz" + + # A stand-in OVMF firmware file. QEMU is stubbed and never reads it; it + # only has to exist so the recipe's firmware lookup succeeds. + OVMF_STUB="${SANDBOX}/OVMF_CODE_stub.fd" + truncate -s 1024 "$OVMF_STUB" + + apply_ovmf_override_substitution + + make_zstd_stub + make_qemu_stub + make_curl_stub +} + +# The OVMF_CODE lookup (`Justfile:254`, duplicated verbatim at the same +# recipe boundary in `install-vm`) only searches hardcoded absolute paths +# that do not exist on an unprivileged CI runner. Insert one extra, +# env-gated candidate at the front of the `first_existing` call so the +# sandbox can point it at a stub file; asserted below so a future edit to +# that line is caught instead of silently un-sandboxing the suite. +apply_ovmf_override_substitution() { + python3 - "$JUSTFILE" "${SANDBOX}/Justfile" <<'PY' +import sys + +src, dst = sys.argv[1], sys.argv[2] +text = open(src, encoding="utf-8").read() + +old = ' OVMF_CODE=$(first_existing \\\n' +new = ' OVMF_CODE=$(first_existing "${OVMF_CODE_TEST_OVERRIDE:-/nonexistent-ovmf-code}" \\\n' +count = text.count(old) +assert count == 2, f"expected exactly 2 occurrences of the OVMF_CODE lookup, found {count}" + +open(dst, "w", encoding="utf-8").write(text.replace(old, new)) +PY +} + +@test "sandbox substitution: the OVMF_CODE lookup is patched exactly where expected" { + run grep -cF 'OVMF_CODE=$(first_existing "${OVMF_CODE_TEST_OVERRIDE:-' "${SANDBOX}/Justfile" + [ "$status" -eq 0 ] + [ "$output" -eq 2 ] +} + +# make_zstd_stub +# +# Records the invocation and materialises the `-o ` target so the +# recipe's subsequent `truncate`/`cp`/qemu-stub steps find the file they +# expect, without actually decompressing anything. +make_zstd_stub() { + cat > "${STUB_DIR}/zstd" <> "${LOG}" +args=("\$@") +for ((i = 0; i < \${#args[@]}; i++)); do + if [ "\${args[\$i]}" = "-o" ]; then + : > "\${args[\$((i + 1))]}" + fi +done +exit 0 +EOF + chmod +x "${STUB_DIR}/zstd" +} + +# make_qemu_stub +# +# The recipe invokes qemu-system-x86_64 twice: once in the foreground to run +# the installer to completion (`-serial mon:stdio`), once backgrounded to +# boot the installed target (`-serial file:`). The stub tells the two +# apart by the `-serial` value. The foreground call exits immediately +# (installer "completed"). The backgrounded call either dies immediately +# (QEMU_TARGET_DIES=1, simulating a boot crash) or stays alive, handling +# SIGTERM cleanly, until the recipe's own cleanup trap kills it — exactly +# what `kill -0 "$TARGET_QEMU_PID"` in the polling loop needs to observe. +make_qemu_stub() { + cat > "${STUB_DIR}/qemu-system-x86_64" <> "${LOG}" + +serial_arg="" +prev="" +for a in "\$@"; do + if [ "\$prev" = "-serial" ]; then + serial_arg="\$a" + fi + prev="\$a" +done + +case "\$serial_arg" in + file:*) + serial_file="\${serial_arg#file:}" + : > "\$serial_file" + if [ -n "\${QEMU_SERIAL_LOG_CONTENT:-}" ]; then + printf '%s\n' "\${QEMU_SERIAL_LOG_CONTENT}" >> "\$serial_file" + fi + if [ "\${QEMU_TARGET_DIES:-0}" = "1" ]; then + exit 1 + fi + trap 'exit 0' TERM INT + while true; do sleep 1; done + ;; + *) + exit "\${QEMU_INSTALL_EXIT:-0}" + ;; +esac +EOF + chmod +x "${STUB_DIR}/qemu-system-x86_64" +} + +# make_curl_stub +# +# The readiness probe runs inside the guest, so the host should never invoke +# curl at all. This stub exists only to record any invocation in the call +# log, so `refute_host_probe_attempted` can prove that. It shapes no +# response: if the host ever did probe, the stub fails the call loudly +# rather than pretending to be a reachable kiosk proxy. +make_curl_stub() { + cat > "${STUB_DIR}/curl" <> "${LOG}" +echo "curl stub: the host is not expected to probe the kiosk" >&2 +exit 1 +EOF + chmod +x "${STUB_DIR}/curl" +} + +# run_test_installer_artifact [deadline-seconds] +# +# The QEMU_*/OVMF_CODE_TEST_OVERRIDE knobs are read from the calling test's +# exported environment; only the deadline is parameterised here since every +# test needs one. +run_test_installer_artifact() { + local deadline="${1:-5}" + run env PATH="${STUB_DIR}:${PATH}" \ + XDG_CACHE_HOME="${SANDBOX}/cache" \ + OVMF_CODE_TEST_OVERRIDE="${OVMF_STUB}" \ + SHOW_ME_THE_FUTURE_DEADLINE="${deadline}" \ + QEMU_TARGET_DIES="${QEMU_TARGET_DIES:-0}" \ + QEMU_SERIAL_LOG_CONTENT="${QEMU_SERIAL_LOG_CONTENT:-}" \ + just --justfile "${SANDBOX}/Justfile" \ + --working-directory "${SANDBOX}" \ + test-installer-artifact +} + +assert_log() { + if ! grep -qF -- "$1" "$LOG"; then + echo "expected call log to contain: $1" >&2 + cat "$LOG" >&2 + return 1 + fi +} + +refute_log() { + if grep -qF -- "$1" "$LOG"; then + echo "expected call log NOT to contain: $1" >&2 + cat "$LOG" >&2 + return 1 + fi +} + +# The readiness probe lives in the guest, so no host-side curl invocation is +# legitimate: any entry in the call log at all is a failure. +refute_host_probe_attempted() { + if grep -qF 'curl ' "$LOG"; then + echo "expected the host NOT to have run curl at all (the probe lives in the guest)" >&2 + cat "$LOG" >&2 + return 1 + fi +} + +# --- guards: the checks this suite depends on are still the real ones ----- + +@test "guard: the in-guest probe still requires the healthz body to report status ok" { + # The readiness decision moved into the guest with #220: a systemd unit + # injected over an SMBIOS credential polls the kiosk proxy from inside + # and prints KIOSK_CONSOLE_READY on the console. The two conditions are + # now text inside that unit's ExecStart, so they are guarded as text. + run grep -cF "curl --silent --fail --insecure --max-time 2 https://127.0.0.1:8080/healthz | jq -r .status)\" = ok ]" "$JUSTFILE" + [ "$status" -eq 0 ] + [ "$output" -eq 1 ] +} + +@test "guard: the in-guest probe still requires the root probe to answer exactly 200" { + run grep -cF '"%%{http_code}" https://127.0.0.1:8080/)" = 200 ]' "$JUSTFILE" + [ "$status" -eq 0 ] + [ "$output" -eq 1 ] +} + +@test "guard: the unit is delivered as an SMBIOS credential and pulled in by the cmdline" { + # Scoped to this recipe's body, like the host-probe guard below: install-vm + # also carries this credential/cmdline pair (it reuses the same in-guest + # kiosk-ready mechanism), so a whole-file grep would count both recipes' + # copies instead of just this one's. + run bash -c 'recipe_body() { awk "/^test-installer-artifact:/{p=1;next} p&&/^[a-z][a-z0-9-]*:/{exit} p" "$1"; }; recipe_body "$1" | grep -cF "io.systemd.credential.binary:systemd.extra-unit.bluefin-kiosk-ready.service="' _ "$JUSTFILE" + [ "$status" -eq 0 ] + [ "$output" -eq 1 ] + run bash -c 'recipe_body() { awk "/^test-installer-artifact:/{p=1;next} p&&/^[a-z][a-z0-9-]*:/{exit} p" "$1"; }; recipe_body "$1" | grep -cF "systemd.wants=bluefin-kiosk-ready.service"' _ "$JUSTFILE" + [ "$status" -eq 0 ] + [ "$output" -eq 1 ] +} + +@test "guard: this recipe never probes the kiosk from the host" { + # The proxy is bound to the guest's loopback, which a QEMU hostfwd cannot + # reach, so a host-side probe would be a probe of nothing. The only host + # decision is the serial-log marker. Scoped to this recipe's body: + # install-vm is a different recipe and forwards its own ports. + recipe_body() { + awk '/^test-installer-artifact:/{p=1;next} p&&/^[a-z][a-z0-9-]*:/{exit} p' "$JUSTFILE" + } + # http, not https: the in-guest probe speaks https to the TLS-terminating + # proxy, so a plaintext probe here could only be a host-side one. + run bash -c 'recipe_body() { awk "/^test-installer-artifact:/{p=1;next} p&&/^[a-z][a-z0-9-]*:/{exit} p" "$1"; }; recipe_body "$1" | grep -cE "curl [^|]*http://127\.0\.0\.1:8080"' _ "$JUSTFILE" + [ "$output" -eq 0 ] + run bash -c 'recipe_body() { awk "/^test-installer-artifact:/{p=1;next} p&&/^[a-z][a-z0-9-]*:/{exit} p" "$1"; }; recipe_body "$1" | grep -cF "hostfwd=tcp:127.0.0.1:8080-:8080"' _ "$JUSTFILE" + [ "$output" -eq 0 ] +} + +# --- the readiness decision ------------------------------------------------- +# +# From the host's side the decision is: the marker the in-guest unit prints +# appears in the serial log. The QEMU stub writes whatever +# QEMU_SERIAL_LOG_CONTENT holds into the serial file, standing in for the +# guest console, so each case below seeds the log with what a guest in that +# state would have printed. + +@test "declares readiness once the in-guest probe prints the marker on the console" { + export QEMU_SERIAL_LOG_CONTENT="<4>kiosk-ready: polling https://127.0.0.1:8080 +<4>KIOSK_CONSOLE_READY" + run_test_installer_artifact 10 + [ "$status" -eq 0 ] + [[ "$output" == *"KubeStellar Console is healthy: /healthz status ok, / returned HTTP 200"* ]] + refute_host_probe_attempted +} + +@test "does not declare readiness while the in-guest probe is still waiting" { + # The unit prints a progress line every 15 polls while either condition + # is unmet; that line must never be mistaken for the marker. + export QEMU_SERIAL_LOG_CONTENT="<4>kiosk-ready: polling https://127.0.0.1:8080 +<4>kiosk-ready: waiting k0s=active hz=200 root=503 pods=12 running=9" + run_test_installer_artifact 1 + [ "$status" -ne 0 ] + [[ "$output" == *"Timed out after 1s waiting for KubeStellar Console readiness"* ]] + [[ "$output" != *"KubeStellar Console is healthy"* ]] +} + +@test "does not declare readiness when the guest never prints the marker at all" { + export QEMU_SERIAL_LOG_CONTENT="kernel: still booting, never became ready" + run_test_installer_artifact 1 + [ "$status" -ne 0 ] + [[ "$output" == *"Timed out after 1s waiting for KubeStellar Console readiness"* ]] + [[ "$output" != *"KubeStellar Console is healthy"* ]] +} + +@test "does not declare readiness on a near-miss of the marker" { + # The host greps the serial log for the marker as an unanchored fixed + # string, so any line *containing* KIOSK_CONSOLE_READY declares + # readiness — that is the contract, not exact-line matching. What this + # case pins is the other direction: console text that merely approaches + # the marker without containing it (here, a truncated spelling) must not + # trip the gate. + export QEMU_SERIAL_LOG_CONTENT="<4>kiosk-ready: waiting for KIOSK_CONSOLE_READ" + run_test_installer_artifact 1 + [ "$status" -ne 0 ] + [[ "$output" != *"KubeStellar Console is healthy"* ]] +} + +@test "exits nonzero and reports the failure once the target QEMU process dies" { + export QEMU_TARGET_DIES="1" + run_test_installer_artifact 30 + [ "$status" -ne 0 ] + [[ "$output" == *"died unexpectedly"* ]] + [[ "$output" != *"KubeStellar Console is healthy"* ]] +} + +@test "dumps the serial log tail when the target QEMU process dies" { + export QEMU_TARGET_DIES="1" + export QEMU_SERIAL_LOG_CONTENT="kernel: this is the last thing the guest printed" + run_test_installer_artifact 30 + [ "$status" -ne 0 ] + [[ "$output" == *"Serial log tail"* ]] + [[ "$output" == *"this is the last thing the guest printed"* ]] +} + +@test "dumps the serial log tail when readiness times out instead of the target dying" { + export QEMU_SERIAL_LOG_CONTENT="kernel: still booting, never became ready" + run_test_installer_artifact 1 + [ "$status" -ne 0 ] + [[ "$output" == *"Serial log tail"* ]] + [[ "$output" == *"still booting, never became ready"* ]] + [[ "$output" != *"died unexpectedly"* ]] +} From 3008ada47e8c30bde7bdfef95746a33516068ed2 Mon Sep 17 00:00:00 2001 From: Kyle Rankin Date: Wed, 23 Sep 2026 04:57:05 -0700 Subject: [PATCH 38/42] feat(installer): add opt-in PXE network DDI pull (#229) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Extend the installer wrapper (bluefin-sysinstall) to honor inst.* kernel cmdline parameters so PXE/netboot clients can download the OS DDI over the LAN instead of reading the embedded bluefin-installer-data partition: - inst.ddi_url= fetches the zstd-compressed DDI via curl after systemd-networkd-wait-online brings up DHCP. - inst.ddi_sha256= is mandatory when inst.ddi_url is set; the download is verified before the target disk is touched (fail closed). - inst.target_disk=/dev/... overrides first-writable-disk auto-detection. The downloaded DDI is stream-decompressed with zstd and fed into the native systemd-sysinstall flow by staging a temporary /usr/lib/repart.sysinstall.d/ override whose 20-root-a.conf CopyBlocks= points at the downloaded image — no custom installer logic. Without inst.ddi_url the embedded path is byte-for-byte unchanged, and the hard preflight for the embedded partition is skipped under PXE. Add curl + zstd to installer-stack.bst. Part 1 (standalone PXE kernel/initrd export) already landed in main; this completes issue #14 Part 2. Assisted-by: lemonade/Ornith-1.5-35B-A3B-GGUF-Q6_K via GitHub Copilot Signed-off-by: kylerankin Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/skills/ddi-installer.md | 50 ++++++++++-- docs/skills/index.md | 2 +- elements/installer/installer-stack.bst | 5 ++ elements/oci/bluefin-server-installer.bst | 98 ++++++++++++++++++++--- 4 files changed, 134 insertions(+), 21 deletions(-) diff --git a/docs/skills/ddi-installer.md b/docs/skills/ddi-installer.md index fd3cf6b3..7550e484 100644 --- a/docs/skills/ddi-installer.md +++ b/docs/skills/ddi-installer.md @@ -24,13 +24,14 @@ metadata: - OCI-only image work (no installer involvement). - Bootc-specific changes. - Desktop or nspawn machine image work. -- Adding network DDI fetching — the DDI remains embedded as a data partition. ## Architecture -The installer is offline, self-contained, and systemd-native. The OS DDI payload -(`bluefin-server-ddi.bst`) is embedded as a data partition on the installer -media at build time. No network access is required at install time. +The installer is systemd-native and offline by default. The OS DDI payload +(`bluefin-server-ddi.bst`) is embedded as a data partition on installer media +at build time; no network access is required for the default install. PXE/ +netboot clients may opt into downloading the DDI over the LAN instead (see +"PXE network installs" below), but the embedded path stays the default. The installer UI is systemd's built-in `systemd-sysinstall` which provides a terminal-based interactive installation that: @@ -164,9 +165,42 @@ clients can add `unattended` to the installer command line, for example: systemd.unit=system-install.target console=tty0 console=ttyS0,115200 rw unattended ``` -The DDI is still required on `bluefin-installer-data`; standalone network DDI -fetching is not supported yet. Use the raw installer image for complete, -offline installation. +The DDI remains on `bluefin-installer-data` for the default embedded install. + +## PXE network installs + +PXE clients boot the standalone kernel and initrd (published as +`bluefin-server-pxe-vmlinuz-` and +`bluefin-server-pxe-initrd-.cpio.gz`) and opt into downloading the DDI +over the LAN with `inst.*` kernel parameters: + +- `inst.ddi_url=` — download the zstd-compressed DDI instead of the + embedded installer partition. +- `inst.ddi_sha256=` — **mandatory** when `inst.ddi_url` is set; verify the + downloaded DDI before touching the target disk (fail closed if absent). +- `inst.target_disk=/dev/...` — explicit target disk, overriding + first-writable-disk auto-detection. + +Without `inst.ddi_url`, behavior is unchanged and uses the embedded DDI. The +wrapper (`bluefin-sysinstall`) brings up DHCP via `systemd-networkd-wait-online`, +streams the DDI down with `curl`, stream-decompresses it with `zstd`, and feeds +it into the **native** `systemd-sysinstall` flow by staging a temporary +`/usr/lib/repart.sysinstall.d/` override whose `20-root-a.conf` `CopyBlocks=` +points at the downloaded image — no custom installer logic. + +Example iPXE stanza (the PXE server mirrors the three assets, verified against +the signed `SHA256SUMS`): + +```ipxe +#!ipxe +set base http://pxe-server:8080/data +kernel ${base}/bluefin-server-pxe-vmlinuz- systemd.unit=system-install.target console=tty0 console=ttyS0,115200 rw unattended inst.ddi_url=${base}/bluefin-server-ddi-.raw.zst inst.ddi_sha256= +initrd ${base}/bluefin-server-pxe-initrd-.cpio.gz +boot +``` + +RAM floor: the whole live env is a RAM-resident cpio rootfs and the DDI stages +in tmpfs, so plan roughly `live-env + DDI` of free RAM (~8 GiB guidance). ## Common Rationalizations @@ -178,7 +212,7 @@ offline installation. | "Initrd archive tools (gzip, cpio) are in base-stack." | In FSDK 26.08, gzip and cpio are standalone components; elements packing or unpacking initrds must explicitly declare `components/gzip.bst` and `components/cpio.bst` in `build-depends`. | | "Use knuckle instead." | knuckle is deprecated in favor of native `systemd-sysinstall` (systemd 261+). | | "Hardcode `root=/dev/vda2` for QEMU." | Bare metal has different device names. Always use PARTUUID. | -| "Pull the DDI from the network at install time." | Network failures = broken installs. The DDI is embedded in the installer media. | +| "Pull the DDI from the network at install time." | Network pull is opt-in via `inst.ddi_url`; verification is mandatory and failures abort before any disk change, while the embedded installer media stays the default. | | "Put the DDI in the initrd cpio." | The DDI is 2 GiB+. The initrd cpio step must run before the DDI is placed in `/layer`. | | "Store the DDI in the ESP (FAT32)." | FAT32 has a 4 GiB per-file limit. Use a separate XFS partition. | | "Add an 8 GiB minimum size floor to the DDI." | The rootfs is immutable. It never grows in-place. Content + overhead is enough. | diff --git a/docs/skills/index.md b/docs/skills/index.md index c9322b90..cbd14fdf 100644 --- a/docs/skills/index.md +++ b/docs/skills/index.md @@ -27,7 +27,7 @@ This is the lazy-load routing table for agent skills. Keep this file in memory w | [`bump-fsdk-version.md`](bump-fsdk-version.md) | Pinning or retagging the FSDK junction | Update the pinned FSDK release and derived tags. | | [`ci-tooling.md`](ci-tooling.md) | GitHub Actions, workflow SHA pinning, CI conventions | CI conventions and release pipeline rules. | | [`ddi-installer-build.md`](ddi-installer-build.md) | Building the installer or DDI on the cluster | Cluster build pipeline and local installer/DDI build. | -| [`ddi-installer.md`](ddi-installer.md) | Installer boot flow, `systemd-sysinstall`, `systemd-repart` | High-level DDI install architecture and local smoke test. | +| [`ddi-installer.md`](ddi-installer.md) | Installer boot flow, `systemd-sysinstall`, `systemd-repart`, PXE network DDI pull | High-level DDI install architecture and local smoke test. | | [`factory-integration.md`](factory-integration.md) | Lab integration, boot-test workflow, factory role | How Bluefin Server is consumed by the CI lab. | | [`flatcar-parity-matrix.md`](flatcar-parity-matrix.md) | Flatcar version audit, component parity, substitution order | Version parity matrix and gap audit against Flatcar 4593.2.5. | | [`gap-analysis-distros.md`](gap-analysis-distros.md) | Comparing Bluefin Server to other server OSes | Source-verified comparison to Ubuntu, Talos, Flatcar, FCOS. | diff --git a/elements/installer/installer-stack.bst b/elements/installer/installer-stack.bst index 49a74955..7aa27e1c 100644 --- a/elements/installer/installer-stack.bst +++ b/elements/installer/installer-stack.bst @@ -34,6 +34,11 @@ depends: - freedesktop-sdk.bst:components/xfsprogs.bst - freedesktop-sdk.bst:components/dosfstools.bst + # Network DDI pull for PXE/netboot installs (fetch + stream-decompress the + # zstd-compressed DDI over the LAN, per inst.ddi_url in the wrapper). + - freedesktop-sdk.bst:components/curl.bst + - freedesktop-sdk.bst:components/zstd.bst + # Kernel (installer boots from this; vmlinuz used as the UKI --linux= arg) - flatcar/flatcar-kernel.bst - flatcar/flatcar-zfs.bst diff --git a/elements/oci/bluefin-server-installer.bst b/elements/oci/bluefin-server-installer.bst index 646308ea..0095cdfe 100644 --- a/elements/oci/bluefin-server-installer.bst +++ b/elements/oci/bluefin-server-installer.bst @@ -194,17 +194,84 @@ config: modprobe -q xfs || true udevadm trigger --subsystem-match=block || true udevadm settle --timeout=15 || true - # Hard preflight: abort with diagnostics if installer data partition is absent or not a block device - INSTALLER_PART_PATH="/dev/disk/by-partlabel/bluefin-installer-data" - if [ ! -b "${INSTALLER_PART_PATH}" ]; then - echo "ERROR: Installer data partition '${INSTALLER_PART_PATH}' is missing or not a block device!" >&2 - echo "==> Block devices visible at failure:" >&2 - lsblk -p -o NAME,TYPE,PARTLABEL,PKNAME,SIZE,FSTYPE >&2 || true - echo "==> Partition label symlinks visible under /dev/disk/by-partlabel/:" >&2 - ls -la /dev/disk/by-partlabel/ >&2 || true - exit 1 + + # Parse the kernel command line for PXE/netboot parameters. The inst.* + # namespace follows the Anaconda convention PXE operators already guess. + # Without inst.ddi_url the embedded installer-media path is unchanged. + CMDLINE="$(< /proc/cmdline)" + DDI_URL="" + DDI_SHA256="" + TARGET_DISK_OVERRIDE="" + for arg in ${CMDLINE}; do + case "${arg}" in + inst.ddi_url=*) DDI_URL="${arg#inst.ddi_url=}" ;; + inst.ddi_sha256=*) DDI_SHA256="${arg#inst.ddi_sha256=}" ;; + inst.target_disk=*) TARGET_DISK_OVERRIDE="${arg#inst.target_disk=}" ;; + esac + done + + # Opt-in network DDI pull (PXE/netboot). Absence of inst.ddi_url leaves + # the embedded installer-media path byte-for-byte unchanged (offline-first + # preserved). Any fetch/verification failure aborts here, before the target + # disk is touched. + if [ -n "${DDI_URL}" ]; then + # Verification is mandatory for network installs: fail closed when no + # checksum is supplied, so no unsigned/unchecked install can proceed. + if [ -z "${DDI_SHA256}" ]; then + echo "ERROR: inst.ddi_url is set but inst.ddi_sha256 is missing; verification is mandatory for network installs." >&2 + exit 1 + fi + mkdir -p /run/installer + echo "==> Fetching DDI from ${DDI_URL}..." + if command -v systemd-networkd-wait-online >/dev/null 2>&1; then + systemd-networkd-wait-online --timeout=90 || { + echo "ERROR: network did not come up before the DDI download timeout." >&2 + exit 1 + } + fi + # Stream-decompress: decompress straight to the final image and remove + # the compressed copy, so only one DDI-sized blob lives in tmpfs at a time. + curl --fail --silent --show-error --location --retry 3 \ + --output /run/installer/bluefin-server-ddi.raw.zst "${DDI_URL}" + printf '%s %s\n' "${DDI_SHA256}" /run/installer/bluefin-server-ddi.raw.zst \ + | sha256sum --check --status || { + echo "ERROR: downloaded DDI SHA256 verification failed." >&2 + exit 1 + } + zstd -d -q --rm \ + /run/installer/bluefin-server-ddi.raw.zst \ + -o /run/installer/bluefin-server-ddi.raw || { + echo "ERROR: failed to decompress downloaded DDI." >&2 + exit 1 + } + ls -lh /run/installer/bluefin-server-ddi.raw + # Feed the downloaded image into the native systemd-sysinstall flow by + # overriding only the root recipe's CopyBlocks=. systemd-sysinstall + # reads /usr/lib/repart.sysinstall.d/ when populated, else /usr/lib/ + # repart.d/, so stage all three recipes with 20-root-a.conf repointed. + mkdir -p /usr/lib/repart.sysinstall.d + cp -a /usr/lib/repart.d/10-esp.conf /usr/lib/repart.sysinstall.d/ + cp -a /usr/lib/repart.d/30-var.conf /usr/lib/repart.sysinstall.d/ + sed 's#^CopyBlocks=.*#CopyBlocks=/run/installer/bluefin-server-ddi.raw#' \ + /usr/lib/repart.d/20-root-a.conf \ + > /usr/lib/repart.sysinstall.d/20-root-a.conf + fi + + # Hard preflight: the embedded installer-media path needs the + # bluefin-installer-data partition. Under PXE (inst.ddi_url=) there is no + # installer media, so the check is skipped when inst.ddi_url is set. + if [ -z "${DDI_URL}" ]; then + INSTALLER_PART_PATH="/dev/disk/by-partlabel/bluefin-installer-data" + if [ ! -b "${INSTALLER_PART_PATH}" ]; then + echo "ERROR: Installer data partition '${INSTALLER_PART_PATH}' is missing or not a block device!" >&2 + echo "==> Block devices visible at failure:" >&2 + lsblk -p -o NAME,TYPE,PARTLABEL,PKNAME,SIZE,FSTYPE >&2 || true + echo "==> Partition label symlinks visible under /dev/disk/by-partlabel/:" >&2 + ls -la /dev/disk/by-partlabel/ >&2 || true + exit 1 + fi + INSTALLER_PART="$(readlink -f "${INSTALLER_PART_PATH}")" fi - INSTALLER_PART="$(readlink -f "${INSTALLER_PART_PATH}")" # Auto-detect target disk for unattended install (any raw disk of type "disk" that is not the installer, is not read-only, and has size > 0) TARGET_DISK="" @@ -222,6 +289,15 @@ config: break done < <(lsblk -p -d -n -o NAME,TYPE,RO,SIZE -b) + # inst.target_disk= overrides auto-detection (explicit target under PXE). + if [ -n "${TARGET_DISK_OVERRIDE}" ]; then + if [ ! -b "${TARGET_DISK_OVERRIDE}" ]; then + echo "ERROR: inst.target_disk is not a block device: ${TARGET_DISK_OVERRIDE}" >&2 + exit 1 + fi + TARGET_DISK="${TARGET_DISK_OVERRIDE}" + fi + stage_fallback_bootloader() { udevadm settle --timeout=10 || true local target="${TARGET_DISK:-}" @@ -263,8 +339,6 @@ config: fi } - # Check for unattended in kernel command line - CMDLINE="$(< /proc/cmdline)" if [[ " ${CMDLINE} " == *" unattended "* ]]; then echo "==> Running in UNATTENDED mode..." if [ -n "${TARGET_DISK}" ]; then From 39ba324493ae04ddbd22a8470fd5192622fa97ca Mon Sep 17 00:00:00 2001 From: Kyle Rankin Date: Wed, 23 Sep 2026 04:57:55 -0700 Subject: [PATCH 39/42] build: os-base option to compare FSDK payload against Flatcar reference (#163) * build: add os-base option to build-ddi for FSDK/Flatcar parity harness projectbluefin/server#129 wants an os-base: fsdk | flatcar-reference option so the FSDK-composed payload and the imported Flatcar reference can be built from one tree and diffed. build-ddi now takes an OS_BASE parameter (default fsdk) and routes to the matching element: fsdk -> oci/bluefin-server-ddi.bst (shipped payload) flatcar-reference -> oci/bluefin-server-ddi-flatcar-reference.bst, added alongside the #126 imported Flatcar tree The flatcar-reference route refuses with a pointer to #126 until that element exists, and an unknown base is rejected. The default path is unchanged, so CI's 'just build-ddi' keeps building the FSDK payload. Adds a bats test covering the routing and guards. Assisted-by: lemonade/Ornith-1.5-35B-A3B-GGUF via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: kylerankin * fix: resolve flatcar-reference element against elements/ in build-ddi The build-ddi os-base=flatcar-reference guard tested `-f "oci/bluefin-server-ddi-flatcar-reference.bst"`, but project.conf declares `element-path: elements`, so the element file lives at `elements/oci/bluefin-server-ddi-flatcar-reference.bst`. The guard could therefore never be satisfied and the flatcar-reference route was permanently unreachable, matching the Justfile's existing convention of referencing element files as `elements/...` on disk. The bats test asserting the refusal passed for the wrong reason: it ran against the repo root where no `oci/` directory exists at all. It now runs against a sandbox that holds a decoy at the bare `oci/` path and nothing under `elements/oci/`, so it fails if the guard resolves the wrong path and stays a genuine refusal test once the #126 element lands. Assisted-by: Claude Opus 4.6 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(build): stop interpolating os-base into the build-ddi recipe body just substitutes {{...}} textually into the recipe body before bash parses it, so `case "{{OS_BASE}}"` made the argument executable: $ just build-ddi '$(echo PWNED >&2)' PWNED PWNED ERROR: unknown os-base '' (expected 'fsdk' or 'flatcar-reference') It ran twice -- once at the case, once in the error echo -- so even the rejection path executed it, and the message that was supposed to name the bad value printed empty because the substitution had consumed it. Exporting the parameter (`build-ddi $OS_BASE="fsdk"`) hands it to the recipe as an environment variable, so bash only ever sees "$OS_BASE" and never expands the caller's text. Same invocation now prints the payload verbatim and exits 1. Only the local invoker could reach this, and it matches the existing {{ARGS}} pattern in the bst recipe, but os-base is a fixed enum of two values and has no reason to be interpolated at all. Adds two regression tests: one asserts no {{OS_BASE}} remains in the recipe body, the other passes $(touch ) and asserts the marker is absent. The marker matters -- the payload's own text necessarily appears in the rejection message, so a string assertion could not distinguish echoed from executed. Both fail against the previous Justfile, along with the parameter-shape guard. Also documents os-base in docs/skills/ddi-installer-build.md, which still showed a bare `just build-ddi` and is what operators drive the #129 parity harness from: a Payload base section covering both values, the #126 refusal before the reference element exists, and the fact that export-ddi does not forward os-base, so the reference tree stays a comparison input and never becomes a release artifact. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: sec-check[bot] --------- Signed-off-by: kylerankin Signed-off-by: sec-check[bot] Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: castrojo Co-authored-by: sec-check[bot] --- Justfile | 31 ++++- docs/skills/ddi-installer-build.md | 27 +++- tests/unit/build_ddi_os_base_test.bats | 176 +++++++++++++++++++++++++ 3 files changed, 230 insertions(+), 4 deletions(-) create mode 100644 tests/unit/build_ddi_os_base_test.bats diff --git a/Justfile b/Justfile index 4013b6b3..c3cf9bb3 100644 --- a/Justfile +++ b/Justfile @@ -86,9 +86,36 @@ build: # Build the OS DDI payload filesystem image (implicit dep of build-installer; # useful when you need the standalone artifact for release publishing). +# +# os-base selects the payload base for the FSDK-vs-Flatcar parity harness +# (projectbluefin/server#129): +# fsdk FSDK-composed payload, the shipped base (default). +# flatcar-reference Imported Flatcar reference tree, the known-good control. +# Routes to bluefin-server-ddi-flatcar-reference.bst, added +# alongside the #126 imported Flatcar reference tree. [group('installer')] -build-ddi: - just bst build oci/bluefin-server-ddi.bst +build-ddi $OS_BASE="fsdk": + #!/usr/bin/env bash + set -euo pipefail + case "$OS_BASE" in + fsdk) + DDI_ELEMENT="oci/bluefin-server-ddi.bst" + ;; + flatcar-reference) + if [ ! -f "elements/oci/bluefin-server-ddi-flatcar-reference.bst" ]; then + echo "ERROR: os-base=flatcar-reference requires the imported Flatcar reference tree" >&2 + echo " (projectbluefin/server#126); element oci/bluefin-server-ddi-flatcar-reference.bst" >&2 + echo " does not exist yet. Add it alongside the #126 tree, then re-run." >&2 + exit 1 + fi + DDI_ELEMENT="oci/bluefin-server-ddi-flatcar-reference.bst" + ;; + *) + echo "ERROR: unknown os-base '${OS_BASE}' (expected 'fsdk' or 'flatcar-reference')" >&2 + exit 1 + ;; + esac + just bst build "${DDI_ELEMENT}" # Export the OS DDI payload + SHA256SUMS to dist/ddi/. [group('installer')] diff --git a/docs/skills/ddi-installer-build.md b/docs/skills/ddi-installer-build.md index b06cedfb..9e53b7b9 100644 --- a/docs/skills/ddi-installer-build.md +++ b/docs/skills/ddi-installer-build.md @@ -24,7 +24,7 @@ just cluster-build # submit an Argo workflow to build/publish just build-installer # build the installer locally just export-installer # export installer + UKI + SHA256SUMS to dist/ just export-pxe # export standalone PXE vmlinuz/initrd to dist/ -just build-ddi # build the OS DDI payload +just build-ddi # build the OS DDI payload (see "Payload base" below) just export-ddi # export DDI + SHA256SUMS to dist/ddi/ just build-sysext # build the k0s sysext just export-sysext # export sysext artifacts to dist/sysext/ @@ -34,6 +34,28 @@ just test-installer-artifact # test already-exported artifacts in QEMU without r just tags # show FSDK-derived version tags ``` +### Payload base + +`build-ddi` takes an optional `os-base` argument selecting which payload it +composes. It backs the FSDK-vs-Flatcar parity harness +(projectbluefin/server#129), where the two bases are built and compared: + +```bash +just build-ddi # os-base=fsdk (default) +just build-ddi fsdk # FSDK-composed payload -- the shipped base +just build-ddi flatcar-reference # imported Flatcar reference tree -- the control +``` + +`flatcar-reference` routes to `oci/bluefin-server-ddi-flatcar-reference.bst`. +That element arrives with the imported Flatcar reference tree +(projectbluefin/server#126); until it does, `build-ddi flatcar-reference` +refuses with a message naming #126 rather than building anything. Anything +other than these two values is rejected. + +`export-ddi` always exports the default `fsdk` payload -- it does not forward +`os-base`, so the reference tree is a comparison input, never a release +artifact. + ## Mandatory build path: ghost cluster This project MUST always build on the ghost cluster using distributed BuildStream: @@ -58,7 +80,8 @@ projects: push: true ``` -Then run `just build-installer` or `just build-ddi`. +Then run `just build-installer` or `just build-ddi` (add `flatcar-reference` to +build the parity-harness control instead of the shipped payload). ## Flashing the installer media diff --git a/tests/unit/build_ddi_os_base_test.bats b/tests/unit/build_ddi_os_base_test.bats new file mode 100644 index 00000000..8b8dc84b --- /dev/null +++ b/tests/unit/build_ddi_os_base_test.bats @@ -0,0 +1,176 @@ +#!/usr/bin/env bats +# +# Unit tests for the `os-base` option in the `build-ddi` recipe of the +# top-level Justfile (projectbluefin/server#129). +# +# `build-ddi` composes the shipped Bluefin Server OS payload. The `os-base` +# option selects the payload base for the FSDK-vs-Flatcar parity harness: +# `fsdk` (default) builds the FSDK-composed payload, and `flatcar-reference` +# builds the imported Flatcar reference tree once the #126 element lands. +# +# The recipe never builds a real payload in the test. It delegates to the +# `bst` recipe, which runs `podman`. `podman` is replaced by a logging stub on +# PATH that records its arguments and exits 0, so the recipe that routes +# `os-base` to the right element runs to completion and the chosen element is +# recorded in the call log instead of being composed. + +setup() { + if ! command -v just >/dev/null 2>&1; then + skip "just is not installed" + fi + + REPO_ROOT="$(cd "${BATS_TEST_DIRNAME}/../.." && pwd)" + JUSTFILE="${REPO_ROOT}/Justfile" + SANDBOX="${BATS_TEST_TMPDIR}/sandbox" + BIN_DIR="${BATS_TEST_TMPDIR}/bin" + ELEMENTS="${SANDBOX}/elements" + OCI="${SANDBOX}/oci" + LOG="${BATS_TEST_TMPDIR}/podman.log" + REF_ELEMENT="oci/bluefin-server-ddi-flatcar-reference.bst" + + mkdir -p "$BIN_DIR" "$ELEMENTS" "$OCI" + : > "$LOG" + + # The Justfile's top-level backtick assignments inspect + # elements/freedesktop-sdk.bst. Copy it so loading the sandbox Justfile + # behaves exactly like the real one. + cp "${REPO_ROOT}/elements/freedesktop-sdk.bst" "${ELEMENTS}/" + + make_stub podman 0 +} + +# make_stub +make_stub() { + cat > "${BIN_DIR}/$1" <> "${LOG}" +exit $2 +EOF + chmod +x "${BIN_DIR}/$1" +} + +# run_build [os-base] -- invoke `just build-ddi` with the given base. +run_build() { + local base="${1:-}" + if [ -n "${base}" ]; then + run env PATH="${BIN_DIR}:${PATH}" \ + just --justfile "${JUSTFILE}" \ + --working-directory "${REPO_ROOT}" \ + build-ddi "${base}" + else + run env PATH="${BIN_DIR}:${PATH}" \ + just --justfile "${JUSTFILE}" \ + --working-directory "${REPO_ROOT}" \ + build-ddi + fi +} + +# The fsdk element is the shipped base; the flatcar-reference route must never +# select it, and vice versa. +assert_builds() { + local element="$1" + if ! grep -qF "${element}" "${LOG}"; then + echo "expected podman call to build ${element}" >&2 + echo "---- podman log ----" >&2 + cat "${LOG}" >&2 + return 1 + fi +} + +assert_does_not_build() { + local element="$1" + if grep -qF "${element}" "${LOG}"; then + echo "expected podman call NOT to build ${element}" >&2 + cat "${LOG}" >&2 + return 1 + fi +} + +assert_no_build() { + refute_log "bst" +} + +refute_log() { + if grep -qF -- "$1" "${LOG}" 2>/dev/null; then + echo "expected log NOT to contain: $1" >&2 + cat "${LOG}" >&2 + return 1 + fi +} + +# --- guard shape ------------------------------------------------------------ + +@test "build-ddi still declares the OS_BASE parameter defaulting to fsdk" { + grep -qF 'build-ddi $OS_BASE="fsdk"' "${JUSTFILE}" +} + +# `just` substitutes {{...}} textually into the recipe body before bash parses +# it, so `case "{{OS_BASE}}"` makes `just build-ddi '$(cmd)'` run cmd -- on the +# rejection path too, because the error message interpolates it a second time. +# The `$` on the parameter exports it as an environment variable instead, so +# bash only ever sees "$OS_BASE" and never expands the caller's text. +@test "build-ddi never interpolates os-base into the recipe body" { + run awk '/^build-ddi /{f=1} f&&/\{\{OS_BASE\}\}/{print} f&&/^$/{f=0}' "${JUSTFILE}" + [ -z "${output}" ] +} + +@test "build-ddi still validates os-base against fsdk and flatcar-reference" { + grep -qF "expected 'fsdk' or 'flatcar-reference'" "${JUSTFILE}" +} + +@test "build-ddi still guards the flatcar-reference element's existence" { + grep -qF "os-base=flatcar-reference requires the imported Flatcar reference tree" "${JUSTFILE}" +} + +# --- routing ---------------------------------------------------------------- + +@test "build-ddi with no argument builds the fsdk payload" { + run_build + [ "$status" -eq 0 ] + assert_builds "oci/bluefin-server-ddi.bst" + assert_does_not_build "${REF_ELEMENT}" +} + +@test "build-ddi os-base=fsdk builds the fsdk payload" { + run_build "fsdk" + [ "$status" -eq 0 ] + assert_builds "oci/bluefin-server-ddi.bst" + assert_does_not_build "${REF_ELEMENT}" +} + +@test "build-ddi os-base=flatcar-reference refuses before the element exists" { + # The guard must resolve the element against the project's element-path + # (project.conf: element-path: elements), so a stray copy at a bare + # oci/ path must not satisfy it. Run against a sandbox that has the + # decoy but not elements/oci/, so this stays a refusal test after the + # #126 element lands in the repo. + touch "${OCI}/bluefin-server-ddi-flatcar-reference.bst" + run env PATH="${BIN_DIR}:${PATH}" \ + just --justfile "${JUSTFILE}" \ + --working-directory "${SANDBOX}" \ + build-ddi flatcar-reference + [ "$status" -ne 0 ] + [[ "$output" == *"projectbluefin/server#126"* ]] + assert_no_build +} + +@test "build-ddi rejects an unknown os-base" { + run_build "not-a-base" + [ "$status" -ne 0 ] + [[ "$output" == *"unknown os-base"* ]] + assert_no_build +} + +@test "build-ddi does not execute command substitution in os-base" { + # The marker proves execution rather than mere appearance: the payload's + # own text necessarily shows up in the rejection message, so a string + # assertion could not tell "echoed" from "ran". + local marker="${BATS_TEST_TMPDIR}/injected" + run_build "\$(touch ${marker})" + [ "$status" -ne 0 ] + [ ! -e "${marker}" ] + # The payload is reported verbatim instead. Before the `$OS_BASE` export + # the substitution ran here too, so the name was empty in this message. + [[ "$output" == *"touch ${marker}"* ]] + assert_no_build +} From 874679a8089aed523d06bbfb66a622c5a2c314d8 Mon Sep 17 00:00:00 2001 From: Bob Killen Date: Wed, 23 Sep 2026 06:59:20 -0500 Subject: [PATCH 40/42] feat(flatcar): add flatcar-usr.bst importing Flatcar /usr as the OS payload base (#140) * feat(flatcar): add flatcar-usr.bst importing Flatcar /usr as the OS payload base - Add elements/flatcar/flatcar-usr.bst to import Flatcar /usr as the OS payload base - Mirror flatcar-zfs.bst with single pinned remote source flatcar-container.tar.gz - Set strip-binaries to empty string to prevent stripping prebuilt binaries - Flatten Flatcar's nested usr/lib/modules/// layout - Explicitly remove Flatcar's update and provisioning stack with replacement comments - Preserve usr/lib/flatcar/bootengine.img for stage-2 kernel boot - Add contract tests in tests/unit/test_flatcar_usr.py Assisted-by: Gemini 3.8 Flash via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: mrbobbytables * fix(flatcar): strip /usr/lib/modules to avoid collision with flatcar-kernel Removes dead nested module flattening code and strips /usr/lib/modules from flatcar-usr.bst completely so kernel modules are exclusively managed by flatcar-kernel.bst. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix(flatcar): remove update-engine and cloudinit systemd units and drop-ins Address review feedback: - Explicitly remove update-engine and update-engine-stub units, timers, and multi-user.target.wants symlinks - Remove enable-oem-cloudinit and oem-cloudinit units and wants symlinks - Remove locksmithctl, ignition-rmcfg, and update tmpfiles configuration - Update unit tests to mock and assert absence of all removed units, binaries, and configs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: mrbobbytables * style(flatcar): drop unused findutils build-dependency from flatcar-usr.bst The install-commands script only uses mkdir, tar, and rm, making findutils unnecessary. Update unit contract tests accordingly. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: mrbobbytables --------- Signed-off-by: mrbobbytables Co-authored-by: mrbobbytables Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: castrojo --- elements/flatcar/flatcar-usr.bst | 93 ++++++++++ tests/unit/test_flatcar_usr.py | 288 +++++++++++++++++++++++++++++++ 2 files changed, 381 insertions(+) create mode 100644 elements/flatcar/flatcar-usr.bst create mode 100644 tests/unit/test_flatcar_usr.py diff --git a/elements/flatcar/flatcar-usr.bst b/elements/flatcar/flatcar-usr.bst new file mode 100644 index 00000000..2bdc4259 --- /dev/null +++ b/elements/flatcar/flatcar-usr.bst @@ -0,0 +1,93 @@ +kind: manual +description: | + Import the Flatcar LTS /usr as the Bluefin Server OS payload base. + Extracts ./usr from upstream Flatcar container rootfs, strips Flatcar's + update and provisioning stack in favor of native Bluefin equivalents + (systemd-sysupdate, systemd-creds, Kured), and removes /usr/lib/modules + to leave kernel module management exclusively to flatcar-kernel.bst. + +(@): + - include/arch.yml + - include/flatcar.yml + +build-depends: + - base/base-stack.bst + - freedesktop-sdk.bst:components/tar.bst + - freedesktop-sdk.bst:components/gzip.bst + +variables: + strip-binaries: "" + +sources: + - kind: remote + url: flatcar:stable/%{flatcar-board}/%{flatcar-version}/flatcar-container.tar.gz + ref: c533ff576e128d11ce240e01f818c358d75b9ff118b2dd9199fbf4684547a32c + +config: + install-commands: + - | + set -euo pipefail + + mkdir -p "%{install-root}" + + # Extract the complete Flatcar /usr into the element install root. + tar -xzf flatcar-container.tar.gz -C "%{install-root}" ./usr + + # Remove kernel modules; elements/flatcar/flatcar-kernel.bst extracts and owns + # /usr/lib/modules/%{flatcar-kver} (uncompressing .ko.xz modules and running depmod) + # to prevent filesystem overlap collisions when composed together in os-stack.bst. + rm -rf "%{install-root}/usr/lib/modules" + + # Remove Flatcar's update and provisioning stack with explicit rm lines. + # Each removal names its Bluefin replacement. No wildcard sweeps are used + # so that an upstream unit rename fails loudly instead of silently regressing. + # Note: /usr/lib/flatcar/bootengine.img is deliberately preserved here; + # stage 1 initramfs loop-mounts it from /usr as the stage 2 initramfs. + + # update_engine: replaced by Bluefin's systemd-sysupdate (os-sysupdate.bst) for A/B image updates + rm "%{install-root}/usr/bin/update_engine" + rm "%{install-root}/usr/lib/systemd/system/update-engine.service" + rm "%{install-root}/usr/lib/systemd/system/multi-user.target.wants/update-engine.service" + rm "%{install-root}/usr/lib/tmpfiles.d/update-engine.conf" + + # update_engine_client: replaced by Bluefin's systemd-sysupdate CLI and systemctl + rm "%{install-root}/usr/bin/update_engine_client" + + # update_engine_stub: replaced by Bluefin's native systemd-sysupdate mechanism + rm "%{install-root}/usr/bin/update_engine_stub" + rm "%{install-root}/usr/lib/systemd/system/update-engine-stub.service" + rm "%{install-root}/usr/lib/systemd/system/update-engine-stub.timer" + rm "%{install-root}/usr/lib/systemd/system/multi-user.target.wants/update-engine-stub.timer" + + # locksmithd: replaced by Bluefin's Kured reboot coordination (os-kured-hook.bst) via /run/reboot-required + rm "%{install-root}/usr/lib/locksmith/locksmithd" + rm "%{install-root}/usr/bin/locksmithctl" + + # locksmithd.service: replaced by Bluefin's Kured reboot coordination (os-kured-hook.bst) + rm "%{install-root}/usr/lib/systemd/system/locksmithd.service" + rm "%{install-root}/usr/lib/systemd/system/multi-user.target.wants/locksmithd.service" + + # ignition: replaced by Bluefin's systemd-creds first-boot credential provisioning (os-creds-prov.bst) + rm "%{install-root}/usr/bin/ignition" + rm "%{install-root}/usr/libexec/ignition-rmcfg" + + # ignition-delete-config.service: replaced by Bluefin's systemd-creds credential provisioning + rm "%{install-root}/usr/lib/systemd/system/ignition-delete-config.service" + rm "%{install-root}/usr/lib/systemd/system/sysinit.target.wants/ignition-delete-config.service" + + # coreos-cloudinit: replaced by Bluefin's systemd-creds first-boot credential provisioning (os-creds-prov.bst) + rm "%{install-root}/usr/bin/coreos-cloudinit" + rm "%{install-root}/usr/lib/systemd/system/enable-oem-cloudinit.service" + rm "%{install-root}/usr/lib/systemd/system/multi-user.target.wants/enable-oem-cloudinit.service" + rm "%{install-root}/usr/lib/systemd/system/oem-cloudinit.service" + + # flatcar-update: replaced by Bluefin's systemd-sysupdate (os-sysupdate.bst) and os-justfile + rm "%{install-root}/usr/bin/flatcar-update" + rm "%{install-root}/usr/lib/tmpfiles.d/flatcar-update.conf" + + # download_sysext: replaced by Bluefin's declarative sysext delivery via systemd-sysext + rm "%{install-root}/usr/bin/download_sysext" + + # ensure-sysext.service: replaced by Bluefin's systemd-sysext.service and sysupdate integration + rm "%{install-root}/usr/lib/systemd/system/ensure-sysext.service" + rm "%{install-root}/usr/lib/systemd/system/sysinit.target.wants/ensure-sysext.service" diff --git a/tests/unit/test_flatcar_usr.py b/tests/unit/test_flatcar_usr.py new file mode 100644 index 00000000..810e94fd --- /dev/null +++ b/tests/unit/test_flatcar_usr.py @@ -0,0 +1,288 @@ +"""Contract tests for elements/flatcar/flatcar-usr.bst. + +Verifies that the Flatcar /usr base import: +- Uses kind: manual with prebuilt binaries unstripped (strip-binaries: ""). +- Imports flatcar-container.tar.gz pinned by sha256 via the flatcar: alias. +- Removes /usr/lib/modules to avoid filesystem collisions with flatcar-kernel.bst. +- Explicitly removes Flatcar's update and provisioning stack (update_engine, + locksmithd, ignition, coreos-cloudinit, flatcar-update, download_sysext, + ensure-sysext) with individual rm commands documented with their Bluefin replacements. +- Preserves usr/lib/flatcar/bootengine.img for two-stage kernel boot. +- Preserves verified OS components (systemd 257, glibc, bash, sshd, crictl, etc.). +""" + +from __future__ import annotations + +import re +import subprocess +from pathlib import Path + +import yaml + +REPO_ROOT = Path(__file__).resolve().parents[2] +FLATCAR_USR_ELEMENT = REPO_ROOT / "elements" / "flatcar" / "flatcar-usr.bst" +FLATCAR_YML = REPO_ROOT / "include" / "flatcar.yml" + +REMOVED_BINARIES = [ + "usr/bin/update_engine", + "usr/bin/update_engine_client", + "usr/bin/update_engine_stub", + "usr/lib/locksmith/locksmithd", + "usr/bin/locksmithctl", + "usr/bin/ignition", + "usr/bin/coreos-cloudinit", + "usr/bin/flatcar-update", + "usr/bin/download_sysext", +] + +REMOVED_UNITS = [ + "usr/lib/systemd/system/update-engine.service", + "usr/lib/systemd/system/multi-user.target.wants/update-engine.service", + "usr/lib/systemd/system/update-engine-stub.service", + "usr/lib/systemd/system/update-engine-stub.timer", + "usr/lib/systemd/system/multi-user.target.wants/update-engine-stub.timer", + "usr/lib/systemd/system/locksmithd.service", + "usr/lib/systemd/system/multi-user.target.wants/locksmithd.service", + "usr/lib/systemd/system/ignition-delete-config.service", + "usr/lib/systemd/system/sysinit.target.wants/ignition-delete-config.service", + "usr/lib/systemd/system/enable-oem-cloudinit.service", + "usr/lib/systemd/system/multi-user.target.wants/enable-oem-cloudinit.service", + "usr/lib/systemd/system/oem-cloudinit.service", + "usr/lib/systemd/system/ensure-sysext.service", + "usr/lib/systemd/system/sysinit.target.wants/ensure-sysext.service", +] + +REMOVED_EXTRA_FILES = [ + "usr/lib/tmpfiles.d/update-engine.conf", + "usr/lib/tmpfiles.d/flatcar-update.conf", + "usr/libexec/ignition-rmcfg", +] + +REMOVED_COMPONENTS = [ + "update_engine", + "update_engine_client", + "update_engine_stub", + "update-engine.service", + "locksmithd", + "locksmithctl", + "locksmithd.service", + "ignition", + "ignition-delete-config.service", + "coreos-cloudinit", + "flatcar-update", + "download_sysext", + "ensure-sysext.service", +] + + +def _load_element_data() -> dict: + content = FLATCAR_USR_ELEMENT.read_text(encoding="utf-8") + return yaml.safe_load(content) + + +def test_flatcar_usr_element_structure() -> None: + """Verify flatcar-usr.bst declares the expected BuildStream structure.""" + assert FLATCAR_USR_ELEMENT.is_file(), f"{FLATCAR_USR_ELEMENT} must exist" + data = _load_element_data() + + assert data.get("kind") == "manual", "flatcar-usr.bst must be kind: manual" + + # Must include arch.yml and flatcar.yml + includes = data.get("(@)", []) + assert "include/arch.yml" in includes + assert "include/flatcar.yml" in includes + + # Must declare build-depends for sandbox execution + build_deps = data.get("build-depends", []) + assert "base/base-stack.bst" in build_deps, "Must depend on base/base-stack.bst" + assert "freedesktop-sdk.bst:components/tar.bst" in build_deps + assert "freedesktop-sdk.bst:components/gzip.bst" in build_deps + + # Prebuilt binaries must not be stripped + variables = data.get("variables", {}) + assert variables.get("strip-binaries") == "", ( + "variables.strip-binaries must be empty string to prevent stripping" + ) + + # Exactly one remote source for flatcar-container.tar.gz pinned by sha256 + sources = data.get("sources", []) + assert len(sources) == 1, "Must declare exactly one source" + src = sources[0] + assert src.get("kind") == "remote" + assert src.get("url") == "flatcar:stable/%{flatcar-board}/%{flatcar-version}/flatcar-container.tar.gz" + assert len(src.get("ref", "")) == 64, "Source ref must be a valid sha256 hash" + + +def test_flatcar_usr_explicit_removals_and_replacements() -> None: + """Verify explicit rm lines and Bluefin replacement documentation.""" + content = FLATCAR_USR_ELEMENT.read_text(encoding="utf-8") + + for component in REMOVED_COMPONENTS: + assert component in content, ( + f"flatcar-usr.bst must explicitly name {component} in its removal commands" + ) + + # Assert no wildcard sweeps in removal section + install_commands = _load_element_data().get("config", {}).get("install-commands", []) + script = "\n".join(install_commands) + for line in script.splitlines(): + clean = line.strip() + if clean.startswith("rm "): + assert "*" not in clean, ( + f"Wildcard removal forbidden to ensure rename failures: {line}" + ) + + # Assert each removed component is commented with replacement + for component in [ + "update_engine", + "locksmithd", + "ignition", + "coreos-cloudinit", + "flatcar-update", + "download_sysext", + "ensure-sysext", + ]: + pattern = rf"#\s*{component}.*?:.*?replaced by" + assert re.search(pattern, content, re.IGNORECASE), ( + f"flatcar-usr.bst must document replacement for {component}" + ) + + +def test_flatcar_usr_preserves_bootengine_img() -> None: + """Verify usr/lib/flatcar/bootengine.img is preserved and never deleted.""" + content = FLATCAR_USR_ELEMENT.read_text(encoding="utf-8") + + assert "bootengine.img" in content, ( + "flatcar-usr.bst must explicitly document preservation of bootengine.img" + ) + + install_commands = _load_element_data().get("config", {}).get("install-commands", []) + script = "\n".join(install_commands) + for line in script.splitlines(): + if "bootengine" in line: + assert not line.strip().startswith("rm"), ( + f"bootengine.img must not be removed: {line}" + ) + + +def test_flatcar_usr_removes_modules() -> None: + """Verify script logic removes /usr/lib/modules to avoid collision with flatcar-kernel.bst.""" + content = FLATCAR_USR_ELEMENT.read_text(encoding="utf-8") + assert 'rm -rf "%{install-root}/usr/lib/modules"' in content, ( + "Script must remove /usr/lib/modules to prevent collision with flatcar-kernel.bst" + ) + + +def test_flatcar_usr_contract_execution(tmp_path: Path) -> None: + """Simulate execution of flatcar-usr.bst install-commands against a staged /usr. + + Verifies: + 1. Removed binaries are absent. + 2. Removed units are absent. + 3. bootengine.img is preserved. + 4. Module directory /usr/lib/modules is removed to avoid collision with flatcar-kernel.bst. + 5. Retained files (bash, sshd, systemd, crictl) remain untouched. + """ + flatcar_yml_data = yaml.safe_load(FLATCAR_YML.read_text(encoding="utf-8")) + kver = flatcar_yml_data["variables"]["flatcar-kver"] + + install_root = tmp_path / "install-root" + usr = install_root / "usr" + + # Populate mock files that flatcar-container.tar.gz delivers + bin_dir = usr / "bin" + bin_dir.mkdir(parents=True) + for b in [ + "bash", "crictl", "sshd", "update_engine", "update_engine_client", + "update_engine_stub", "locksmithctl", "ignition", "coreos-cloudinit", + "flatcar-update", "download_sysext" + ]: + (bin_dir / b).write_text(f"mock-{b}", encoding="utf-8") + + locksmith_dir = usr / "lib" / "locksmith" + locksmith_dir.mkdir(parents=True) + (locksmith_dir / "locksmithd").write_text("mock-locksmithd", encoding="utf-8") + + libexec_dir = usr / "libexec" + libexec_dir.mkdir(parents=True) + (libexec_dir / "ignition-rmcfg").write_text("mock-ignition-rmcfg", encoding="utf-8") + + tmpfiles_dir = usr / "lib" / "tmpfiles.d" + tmpfiles_dir.mkdir(parents=True) + (tmpfiles_dir / "update-engine.conf").write_text("mock-tmpfiles", encoding="utf-8") + (tmpfiles_dir / "flatcar-update.conf").write_text("mock-tmpfiles", encoding="utf-8") + + systemd_dir = usr / "lib" / "systemd" / "system" + systemd_dir.mkdir(parents=True) + (systemd_dir / "update-engine.service").write_text("mock-unit", encoding="utf-8") + (systemd_dir / "update-engine-stub.service").write_text("mock-unit", encoding="utf-8") + (systemd_dir / "update-engine-stub.timer").write_text("mock-unit", encoding="utf-8") + (systemd_dir / "locksmithd.service").write_text("mock-unit", encoding="utf-8") + (systemd_dir / "ignition-delete-config.service").write_text("mock-unit", encoding="utf-8") + (systemd_dir / "enable-oem-cloudinit.service").write_text("mock-unit", encoding="utf-8") + (systemd_dir / "oem-cloudinit.service").write_text("mock-unit", encoding="utf-8") + (systemd_dir / "ensure-sysext.service").write_text("mock-unit", encoding="utf-8") + + wants_dir1 = systemd_dir / "multi-user.target.wants" + wants_dir1.mkdir(parents=True) + (wants_dir1 / "update-engine.service").symlink_to("../update-engine.service") + (wants_dir1 / "update-engine-stub.timer").symlink_to("../update-engine-stub.timer") + (wants_dir1 / "locksmithd.service").symlink_to("../locksmithd.service") + (wants_dir1 / "enable-oem-cloudinit.service").symlink_to("../enable-oem-cloudinit.service") + + wants_dir2 = systemd_dir / "sysinit.target.wants" + wants_dir2.mkdir(parents=True) + (wants_dir2 / "ignition-delete-config.service").symlink_to("../ignition-delete-config.service") + (wants_dir2 / "ensure-sysext.service").symlink_to("../ensure-sysext.service") + + flatcar_dir = usr / "lib" / "flatcar" + flatcar_dir.mkdir(parents=True) + bootengine = flatcar_dir / "bootengine.img" + bootengine.write_bytes(b"mock-bootengine-squashfs") + + # Module directory: usr/lib/modules// + mod_dir = usr / "lib" / "modules" / kver + (mod_dir / "kernel" / "drivers").mkdir(parents=True) + (mod_dir / "kernel" / "drivers" / "driver.ko").write_bytes(b"mock-driver") + (mod_dir / "modules.dep").write_text("mock modules.dep", encoding="utf-8") + + # Extract script from flatcar-usr.bst and adapt variables + install_commands = _load_element_data().get("config", {}).get("install-commands", []) + script = "\n".join(install_commands) + + # Replace BuildStream variables + script = script.replace("%{install-root}", str(install_root)) + script = script.replace("%{flatcar-kver}", kver) + + # In test environment, the mock files are already populated, so bypass tar extraction + script = re.sub(r"tar\s+-xzf\s+flatcar-container\.tar\.gz\s+-C\s+.*", "# tar extract bypassed", script) + + # Run the script in bash + result = subprocess.run(["bash", "-c", script], capture_output=True, text=True) + assert result.returncode == 0, f"Script failed:\nSTDOUT:\n{result.stdout}\nSTDERR:\n{result.stderr}" + + # 1. Assert removed binaries are absent + for rel_path in REMOVED_BINARIES: + target = install_root / rel_path + assert not target.exists(), f"Removed binary {rel_path} must be absent from output" + + # 2. Assert removed units and extra files are absent + for rel_path in REMOVED_UNITS: + target = install_root / rel_path + assert not target.exists(), f"Removed unit {rel_path} must be absent from output" + + for rel_path in REMOVED_EXTRA_FILES: + target = install_root / rel_path + assert not target.exists(), f"Removed file {rel_path} must be absent from output" + + # 3. Assert module tree is completely removed to avoid collision with flatcar-kernel.bst + assert not (usr / "lib" / "modules").exists(), ( + "/usr/lib/modules must be removed to avoid collision with flatcar-kernel.bst" + ) + + # 4. Assert usr/lib/flatcar/bootengine.img exists in output + assert bootengine.is_file(), "usr/lib/flatcar/bootengine.img must exist in element output" + + # 5. Assert kept binaries remain + for kept in ["bash", "crictl", "sshd"]: + assert (bin_dir / kept).is_file(), f"Kept binary {kept} must remain in output" From e7e6c324070c9a65b6382d9b8b3879b3489bb5cf Mon Sep 17 00:00:00 2001 From: "Jorge O. Castro" Date: Wed, 23 Sep 2026 08:00:23 -0400 Subject: [PATCH 41/42] fix(flatcar): use flatcar-kernel-container-sha256 variable in flatcar-usr.bst (#236) Co-authored-by: castrojo --- elements/flatcar/flatcar-usr.bst | 2 +- tests/unit/test_flatcar_usr.py | 8 +++++--- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/elements/flatcar/flatcar-usr.bst b/elements/flatcar/flatcar-usr.bst index 2bdc4259..8229cd11 100644 --- a/elements/flatcar/flatcar-usr.bst +++ b/elements/flatcar/flatcar-usr.bst @@ -21,7 +21,7 @@ variables: sources: - kind: remote url: flatcar:stable/%{flatcar-board}/%{flatcar-version}/flatcar-container.tar.gz - ref: c533ff576e128d11ce240e01f818c358d75b9ff118b2dd9199fbf4684547a32c + ref: "%{flatcar-kernel-container-sha256}" config: install-commands: diff --git a/tests/unit/test_flatcar_usr.py b/tests/unit/test_flatcar_usr.py index 810e94fd..70f47476 100644 --- a/tests/unit/test_flatcar_usr.py +++ b/tests/unit/test_flatcar_usr.py @@ -104,14 +104,16 @@ def test_flatcar_usr_element_structure() -> None: "variables.strip-binaries must be empty string to prevent stripping" ) - # Exactly one remote source for flatcar-container.tar.gz pinned by sha256 + # Exactly one remote source for flatcar-container.tar.gz pinned via include/flatcar.yml sources = data.get("sources", []) assert len(sources) == 1, "Must declare exactly one source" src = sources[0] assert src.get("kind") == "remote" assert src.get("url") == "flatcar:stable/%{flatcar-board}/%{flatcar-version}/flatcar-container.tar.gz" - assert len(src.get("ref", "")) == 64, "Source ref must be a valid sha256 hash" - + ref = src.get("ref", "") + assert ref == "%{flatcar-kernel-container-sha256}" or len(ref) == 64, ( + "Source ref must reference %{flatcar-kernel-container-sha256} or be a valid sha256 hash" + ) def test_flatcar_usr_explicit_removals_and_replacements() -> None: """Verify explicit rm lines and Bluefin replacement documentation.""" From 498d1922fef1e3b589c6bd55d0a005eb4668f23e Mon Sep 17 00:00:00 2001 From: Bob Killen Date: Wed, 23 Sep 2026 07:03:25 -0500 Subject: [PATCH 42/42] refactor(arch): split release-version into installer and Flatcar axes (#136) * refactor(arch): split release-version into installer and Flatcar axes Split the single release-version axis in project.conf into two independent axes: - installer-version: FSDK point release describing the installer - flatcar-version: Flatcar LTS release describing the OS payload Update .github/scripts/check-release-version.py to independently validate both axes against their respective pins (freedesktop-sdk.bst junction ref for FSDK, include/flatcar.yml for Flatcar). Update unit tests in tests/unit/test_release_version.py to cover the two-axis contract, and update element asset naming and os-release metadata. Closes #125 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: mrbobbytables * docs: update stale release-version references and clarify flatcar-version declaration Updates avoid-over-engineering.md and ddi-installer-build.md to reference the split axes (installer-version and flatcar-version), noting that release tags track the installer axis while the DDI and UKI track Flatcar. Also adds a comment in project.conf explaining why flatcar-version is deliberately declared there in addition to include/flatcar.yml. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * refactor(arch): declare flatcar-version only in include/flatcar.yml project.conf restated flatcar-version alongside include/flatcar.yml, whose own header declares it the single source of truth for the Flatcar axis. Add include/flatcar.yml to project.conf's existing (@) include list instead, so %{flatcar-version} and %{flatcar-kver} resolve project-wide from one declaration, matching the k0s axis precedent. check-release-version.py no longer compares two copies of the same fact: it validates project.conf's installer-version against the freedesktop-sdk junction ref and that include/flatcar.yml declares a well-formed flatcar-version. Stale standing fact in docs/skills/index.md replaced with the two-axis description this refactor introduces. Assisted-by: Claude Opus 4.6 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * refactor(arch): update check-k0s-version guard and k0s.yml comment for split axes - Guard check-k0s-version against %{installer-version} and %{flatcar-version} in addition to %{release-version} - Update header comment in include/k0s.yml referencing split axes Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: mrbobbytables * fix(test): update test_main_rejects_fname_on_the_os_release_axis assertion string --------- Signed-off-by: mrbobbytables Co-authored-by: mrbobbytables Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Jorge Castro Co-authored-by: castrojo --- .github/scripts/check-k0s-version.py | 4 +- .github/scripts/check-release-version.py | 92 ++++++----- .pre-commit-config.yaml | 4 +- docs/skills/avoid-over-engineering.md | 5 +- docs/skills/ddi-installer-build.md | 3 +- docs/skills/index.md | 2 +- .../bluefin-server/os-release-flatcar.bst | 8 +- elements/oci/bluefin-server-ddi.bst | 2 +- elements/oci/bluefin-server-installer.bst | 7 +- include/k0s.yml | 6 +- project.conf | 10 +- tests/unit/test_check_k0s_version.py | 2 +- tests/unit/test_release_version.py | 153 +++++++++++++----- 13 files changed, 191 insertions(+), 107 deletions(-) diff --git a/.github/scripts/check-k0s-version.py b/.github/scripts/check-k0s-version.py index 3c05acf5..140af41c 100644 --- a/.github/scripts/check-k0s-version.py +++ b/.github/scripts/check-k0s-version.py @@ -128,9 +128,9 @@ def main(): "restore the sysext asset filename assignment.", ) fname_expr = fname_match.group(1) - if "%{release-version}" in fname_expr: + if any(axis in fname_expr for axis in ("%{release-version}", "%{installer-version}", "%{flatcar-version}")): fail( - "elements/oci/k0s-sysext.bst names the k0s sysext on the OS release\n" + "elements/oci/k0s-sysext.bst names the k0s sysext on an OS release\n" f" axis: FNAME=\"{fname_expr}\"\n" " 70-k0s.transfer reads this filename as the version of the k0s it\n" " delivers.", diff --git a/.github/scripts/check-release-version.py b/.github/scripts/check-release-version.py index dd9ed259..04101bbe 100755 --- a/.github/scripts/check-release-version.py +++ b/.github/scripts/check-release-version.py @@ -1,29 +1,30 @@ #!/usr/bin/env python3 """Enforce the release-version invariant for Bluefin Server. -project.conf declares: +The two release version axes are each declared in exactly one place: - variables: - release-version: "X.Y.Z" # must match the FSDK point release + project.conf installer-version: "X.Y.Z" # FSDK point release + include/flatcar.yml flatcar-version: "X.Y.Z" # Flatcar LTS release -That value names every published *OS* release asset -(`bluefin-server-ddi-.raw.zst`, `bluefin-server-.efi`, -`bluefin-server-installer-.raw.zst`) and is the version -systemd-sysupdate extracts from those filenames via `@v`. +The installer-version axis names the offline installer disk image and PXE boot +inputs (bluefin-server-installer-.raw.zst, bluefin-server-pxe-*), which +compose their userspace from freedesktop-sdk. -The k0s sysext is deliberately *not* on this axis: it is an -independently-pinned third-party payload versioned from `include/k0s.yml` -and enforced separately by `.github/scripts/check-k0s-version.py`. +The flatcar-version axis names the OS payload release assets +(bluefin-server-ddi-.raw.zst, bluefin-server-.efi) and is the version +systemd-sysupdate extracts from those filenames via `@v`. project.conf pulls +include/flatcar.yml in via its `(@)` list, so %{flatcar-version} resolves +project-wide without being restated. -The release *tag* is derived independently by the Justfile -(`fsdk_version`), which greps the point release out of the pinned -`elements/freedesktop-sdk.bst` junction ref. Renovate bumps that ref -automatically; nothing bumps `release-version`. When the two drift, CI -publishes a new tag containing assets that still carry the old version -string, so `systemd-sysupdate` sees no version change and the fleet -silently stops updating. +The k0s sysext is on its own axis: an independently-pinned third-party +payload versioned from `include/k0s.yml` and enforced separately by +`.github/scripts/check-k0s-version.py`. -This script fails closed on that drift. +This script validates both axes against their pins: + * project.conf installer-version against elements/freedesktop-sdk.bst + * include/flatcar.yml flatcar-version is well-formed + +This script fails closed on any drift. """ import re @@ -33,11 +34,15 @@ ROOT = Path(__file__).resolve().parents[2] PROJECT_CONF = ROOT / "project.conf" FSDK_JUNCTION = ROOT / "elements" / "freedesktop-sdk.bst" +FLATCAR_PIN = ROOT / "include" / "flatcar.yml" -RELEASE_VERSION_RE = re.compile( - r"^\s*release-version:\s*[\"']?([0-9]+\.[0-9]+\.[0-9]+)[\"']?\s*$", re.MULTILINE +INSTALLER_VERSION_RE = re.compile( + r"^\s*installer-version:\s*[\"']?([0-9]+\.[0-9]+\.[0-9]+)[\"']?\s*$", re.MULTILINE ) FSDK_REF_RE = re.compile(r"freedesktop-sdk-([0-9]+\.[0-9]+\.[0-9]+)") +FLATCAR_PIN_RE = re.compile( + r"^\s*flatcar-version:\s*[\"']?([0-9]+\.[0-9]+\.[0-9]+)[\"']?\s*$", re.MULTILINE +) def read(path): @@ -49,39 +54,48 @@ def read(path): def main(): conf = read(PROJECT_CONF) junction = read(FSDK_JUNCTION) + flatcar = read(FLATCAR_PIN) - conf_match = RELEASE_VERSION_RE.search(conf) - if not conf_match: + installer_match = INSTALLER_VERSION_RE.search(conf) + if not installer_match: sys.exit( - "ERROR: project.conf does not declare a " - "'release-version: X.Y.Z' variable." + "ERROR: project.conf does not declare an " + "'installer-version: X.Y.Z' variable." ) - declared = conf_match.group(1) + installer_declared = installer_match.group(1) - ref_match = FSDK_REF_RE.search(junction) - if not ref_match: + fsdk_match = FSDK_REF_RE.search(junction) + if not fsdk_match: sys.exit( "ERROR: elements/freedesktop-sdk.bst has no " "'freedesktop-sdk-X.Y.Z' point release in its ref." ) - pinned = ref_match.group(1) + fsdk_pinned = fsdk_match.group(1) + + flatcar_pin_match = FLATCAR_PIN_RE.search(flatcar) + if not flatcar_pin_match: + sys.exit( + "ERROR: include/flatcar.yml does not declare a " + "'flatcar-version: X.Y.Z' variable." + ) + flatcar_pinned = flatcar_pin_match.group(1) - if declared != pinned: + if installer_declared != fsdk_pinned: sys.exit( - "ERROR: release-version drift.\n" - f" project.conf release-version : {declared}\n" - f" elements/freedesktop-sdk.bst pinned ref: {pinned}\n" + "ERROR: installer-version drift.\n" + f" project.conf installer-version : {installer_declared}\n" + f" elements/freedesktop-sdk.bst pinned ref: {fsdk_pinned}\n" "\n" - "The release tag is derived from the junction ref while asset\n" - "filenames are derived from release-version. While these differ,\n" - "a new GitHub Release publishes assets still named with the old\n" - "version, systemd-sysupdate reads the old version from '@v', and\n" - "deployed hosts never see an update.\n" + "The installer release tag and installer assets are derived from the\n" + "junction ref while project.conf declares installer-version.\n" "\n" - f"Fix: set release-version to \"{pinned}\" in project.conf." + f"Fix: set installer-version to \"{fsdk_pinned}\" in project.conf." ) - print(f"OK: release-version {declared} matches the pinned FSDK point release.") + print( + f"OK: installer-version {installer_declared} matches pinned FSDK point release.\n" + f"OK: flatcar-version {flatcar_pinned} declared in include/flatcar.yml." + ) if __name__ == "__main__": diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 0a9f61ab..06dd9287 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -13,11 +13,11 @@ repos: language: system files: ^\.github/workflows/.*\.(yml|yaml)$ - id: check-release-version - name: release-version matches pinned FSDK point release + name: release versions match pinned FSDK and Flatcar releases entry: python .github/scripts/check-release-version.py language: system pass_filenames: false - files: ^(project\.conf|elements/freedesktop-sdk\.bst|\.github/scripts/check-release-version\.py)$ + files: ^(project\.conf|elements/freedesktop-sdk\.bst|include/flatcar\.yml|\.github/scripts/check-release-version\.py)$ - id: check-renovate-series name: Renovate version filters match the junction track series entry: python .github/scripts/check-renovate-series.py diff --git a/docs/skills/avoid-over-engineering.md b/docs/skills/avoid-over-engineering.md index ff1702e7..7b25c18b 100644 --- a/docs/skills/avoid-over-engineering.md +++ b/docs/skills/avoid-over-engineering.md @@ -67,8 +67,9 @@ existing repo convention already does the job. ## Verification - [ ] `just validate` passes before and after the change. -- [ ] No hardcoded version duplicates remain; `release-version` in `project.conf` - is the single source of truth. +- [ ] No hardcoded version duplicates remain; `installer-version` in `project.conf` + and `flatcar-version` in `include/flatcar.yml` define the installer and OS + payload axes. - [ ] Removed build dependencies are not used by any command in the element. - [ ] For `manual`/`script` elements, the sandbox still has `/bin/sh` and any coreutils the commands need after a dep cut. - [ ] For `script` elements, build the element with `just bst build `; transitive tools (`dracut`, `ukify`, etc.) may fail silently if their own runtime deps are missing from the sandbox. diff --git a/docs/skills/ddi-installer-build.md b/docs/skills/ddi-installer-build.md index 9e53b7b9..167bd780 100644 --- a/docs/skills/ddi-installer-build.md +++ b/docs/skills/ddi-installer-build.md @@ -118,7 +118,8 @@ The release process is driven by `.github/workflows/build.yml`: - CI builds the DDI payload, installer, target UKI, k0s sysext, and standalone PXE boot inputs (`bluefin-server-pxe-vmlinuz-*`, `bluefin-server-pxe-initrd-*.cpio.gz`). - CI uploads the versioned release assets to the corresponding - `installer-v` GitHub Release. + `installer-v` GitHub Release. The release tag tracks the + installer axis, while the DDI and UKI inside it track the Flatcar payload axis (`flatcar-version`). - CI also produces a combined `dist/release/SHA256SUMS` manifest and signs it to create `SHA256SUMS.gpg` for `systemd-sysupdate` verification. The PXE inputs are included in this manifest, per `docs/skills/ddi-installer.md`. diff --git a/docs/skills/index.md b/docs/skills/index.md index cbd14fdf..2c43ad27 100644 --- a/docs/skills/index.md +++ b/docs/skills/index.md @@ -44,4 +44,4 @@ This is the lazy-load routing table for agent skills. Keep this file in memory w - **Publish registry:** factory OCI registry at `:30500` (or configured by operator). - **Cluster build workflow:** `bluefin-server-build-pipeline` in the downstream factory CI repository. - **Cluster boot-test workflow:** `bluefin-server-boot-test` in the downstream factory CI repository. -- **Version scheme:** FSDK-derived only; no separate application version axis. +- **Version scheme:** two axes — `installer-version` (FSDK-derived, `project.conf`) and `flatcar-version` (OS payload, `include/flatcar.yml`); no application version axis. diff --git a/elements/bluefin-server/os-release-flatcar.bst b/elements/bluefin-server/os-release-flatcar.bst index e21ed19d..cc1c29d0 100644 --- a/elements/bluefin-server/os-release-flatcar.bst +++ b/elements/bluefin-server/os-release-flatcar.bst @@ -18,8 +18,8 @@ config: install-commands: - mkdir -p "%{install-root}/usr/lib" - | - # %{release-version} is declared in project.conf and enforced against - # the junction ref by check-release-version.py — no re-parsing needed. + # %{flatcar-version} comes from include/flatcar.yml, the single source of + # truth for the Flatcar axis — no re-parsing needed. FLATCAR_VERSION="%{flatcar-version}" cat < "%{install-root}/usr/lib/os-release" @@ -28,13 +28,13 @@ config: ID_LIKE=fedora VERSION="${FLATCAR_VERSION}-fsdk" VERSION_ID=${FLATCAR_VERSION} - PRETTY_NAME="Bluefin Server %{release-version}" + PRETTY_NAME="Bluefin Server %{flatcar-version}" ANSI_COLOR="0;38;5;208" HOME_URL="https://github.com/projectbluefin/server" BUG_REPORT_URL="https://github.com/projectbluefin/server/issues" FLATCAR_BOARD="%{flatcar-board}" CPE_NAME="cpe:/o:flatcar-linux:flatcar_linux:${FLATCAR_VERSION}" - IMAGE_VERSION=%{release-version} + IMAGE_VERSION=%{flatcar-version} EOF - | mkdir -p "%{install-root}/etc" diff --git a/elements/oci/bluefin-server-ddi.bst b/elements/oci/bluefin-server-ddi.bst index 68da5cba..c58f9d8e 100644 --- a/elements/oci/bluefin-server-ddi.bst +++ b/elements/oci/bluefin-server-ddi.bst @@ -19,7 +19,7 @@ build-depends: location: /layer variables: - ddi-version: "%{release-version}" + ddi-version: "%{flatcar-version}" config: commands: diff --git a/elements/oci/bluefin-server-installer.bst b/elements/oci/bluefin-server-installer.bst index 0095cdfe..06d8463a 100644 --- a/elements/oci/bluefin-server-installer.bst +++ b/elements/oci/bluefin-server-installer.bst @@ -62,9 +62,6 @@ build-depends: config: location: /k0s -variables: - installer-version: "%{release-version}" - config: commands: # ── Step 1a: Prepare rootfs directories and mount points ──────────── @@ -527,7 +524,7 @@ config: zstd --rm -T0 -19 -q "${FNAME}" -o "${FNAME}.zst" # Also export the target UKI (.efi) for GitHub Releases and systemd-sysupdate - cp /layer/usr/lib/bluefin-server/bluefin-server.efi "bluefin-server-%{installer-version}.efi" + cp /layer/usr/lib/bluefin-server/bluefin-server.efi "bluefin-server-%{flatcar-version}.efi" # Export raw PXE inputs alongside the UKI. PXE users supply their own # kernel command line, so these remain separate from the fixed-cmdline UKI. INSTALLER_KVER="$(basename "$(find /layer/usr/lib/modules -mindepth 1 -maxdepth 1 -type d | head -n1)")" @@ -535,7 +532,7 @@ config: cp /installer.cpio.gz "bluefin-server-pxe-initrd-%{installer-version}.cpio.gz" sha256sum --binary "${FNAME}.zst" > SHA256SUMS - sha256sum --binary "bluefin-server-%{installer-version}.efi" >> SHA256SUMS + sha256sum --binary "bluefin-server-%{flatcar-version}.efi" >> SHA256SUMS sha256sum --binary "bluefin-server-pxe-vmlinuz-%{installer-version}" >> SHA256SUMS sha256sum --binary "bluefin-server-pxe-initrd-%{installer-version}.cpio.gz" >> SHA256SUMS ls -lh diff --git a/include/k0s.yml b/include/k0s.yml index 5dd0fd28..c0573289 100644 --- a/include/k0s.yml +++ b/include/k0s.yml @@ -1,9 +1,9 @@ # Single source of truth for the k0s version axis. # # k0s is an independently-pinned third-party payload, not an OS asset. Its -# version therefore does NOT live on the OS `release-version` axis declared in -# project.conf — that axis names the FSDK point release and is bumped by -# unrelated OS work. +# version therefore does NOT live on the installer or OS payload axes declared in +# project.conf (`installer-version` or `flatcar-version`) — those axes name the +# FSDK point release and Flatcar payload and are bumped by unrelated OS work. # # Only the two atoms below are edited when k0s is bumped. Every other spelling # of the k0s version in this repository is derived from them: diff --git a/project.conf b/project.conf index f369f674..d395f196 100644 --- a/project.conf +++ b/project.conf @@ -9,6 +9,10 @@ element-path: elements (@): - gnome-build-meta.bst:freedesktop-sdk.bst:include/runtime.yml - include/aliases.yml + # OS payload axis (Flatcar): single source of truth for %{flatcar-version} + # and %{flatcar-kver}. Included here so both resolve project-wide without + # being restated. Enforced by .github/scripts/check-release-version.py. + - include/flatcar.yml options: arch: @@ -23,10 +27,10 @@ sandbox: build-arch: "%{arch}" variables: - # Single source of truth for asset versioning; must match the FSDK point - # release pinned in elements/freedesktop-sdk.bst. Enforced by + # Installer axis (FSDK): must match the point release pinned in + # elements/freedesktop-sdk.bst. Enforced by # .github/scripts/check-release-version.py. - release-version: "26.08.0" + installer-version: "26.08.0" # Pull-only: read from the shared GNOME + Bluefin BuildStream CAS caches. artifacts: diff --git a/tests/unit/test_check_k0s_version.py b/tests/unit/test_check_k0s_version.py index acb57e53..fee8c169 100644 --- a/tests/unit/test_check_k0s_version.py +++ b/tests/unit/test_check_k0s_version.py @@ -272,7 +272,7 @@ def test_main_rejects_fname_on_the_os_release_axis(checker): GOOD_SYSEXT.replace("%{k0s-version}.raw", "%{release-version}.raw", 1), encoding="utf-8", ) - assert "names the k0s sysext on the OS release" in _run(checker) + assert "names the k0s sysext on an OS release" in _run(checker) def test_main_rejects_fname_not_derived_from_k0s_version(checker): diff --git a/tests/unit/test_release_version.py b/tests/unit/test_release_version.py index 4f61fc44..ed010d8c 100644 --- a/tests/unit/test_release_version.py +++ b/tests/unit/test_release_version.py @@ -1,10 +1,13 @@ """Unit coverage for .github/scripts/check-release-version.py. -The script is the only gate protecting against release-version drift between -``project.conf`` and the pinned ``elements/freedesktop-sdk.bst`` junction ref. -When it regresses, CI publishes release assets carrying a stale version string -and systemd-sysupdate stops seeing updates, so every branch of ``read()``, -``main()`` and both module-level regexes is exercised here. +The script is the gate protecting against version drift on the two release +axes: the installer axis declared in ``project.conf`` and pinned in +``elements/freedesktop-sdk.bst``, and the Flatcar OS payload axis declared in +``include/flatcar.yml``. + +When either regresses, CI publishes release assets carrying stale version +strings and systemd-sysupdate or operators see version mismatches, so every +branch of ``read()``, ``main()`` and all module-level regexes is exercised here. """ import importlib.util @@ -29,25 +32,40 @@ def _load_module(): def checker(tmp_path): """Fresh module instance with its path constants rooted at tmp_path. - ``ROOT``/``PROJECT_CONF``/``FSDK_JUNCTION`` are module-level globals derived - from the script's own location, so each test gets a re-imported copy pointed - at an isolated tree. + ``ROOT``/``PROJECT_CONF``/``FSDK_JUNCTION``/``FLATCAR_PIN`` are module-level + globals derived from the script's own location, so each test gets a + re-imported copy pointed at an isolated tree. """ module = _load_module() module.ROOT = tmp_path module.PROJECT_CONF = tmp_path / "project.conf" module.FSDK_JUNCTION = tmp_path / "elements" / "freedesktop-sdk.bst" - module.FSDK_JUNCTION.parent.mkdir(parents=True) + module.FLATCAR_PIN = tmp_path / "include" / "flatcar.yml" + module.FSDK_JUNCTION.parent.mkdir(parents=True, exist_ok=True) + module.FLATCAR_PIN.parent.mkdir(parents=True, exist_ok=True) yield module sys.modules.pop("check_release_version", None) -def _write(checker, declared="26.08.0", pinned="26.08.0"): +def _write( + checker, + installer_declared="26.08.0", + fsdk_pinned="26.08.0", + flatcar_pinned="4593.2.5", +): checker.PROJECT_CONF.write_text( - f'variables:\n release-version: "{declared}"\n', encoding="utf-8" + f'variables:\n installer-version: "{installer_declared}"\n', + encoding="utf-8", ) checker.FSDK_JUNCTION.write_text( - f"junction:\n ref: freedesktop-sdk-{pinned}-0-gdb97cce\n", encoding="utf-8" + f"junction:\n ref: freedesktop-sdk-{fsdk_pinned}-0-gdb97cce\n", + encoding="utf-8", + ) + checker.FLATCAR_PIN.write_text( + "variables:\n" + f' flatcar-version: "{flatcar_pinned}"\n' + ' flatcar-kver: "6.12.102-flatcar"\n', + encoding="utf-8", ) @@ -73,22 +91,22 @@ def test_read_exits_when_path_is_a_directory(checker, tmp_path): assert "expected file not found" in str(excinfo.value) -# --- RELEASE_VERSION_RE --------------------------------------------------- +# --- INSTALLER_VERSION_RE ------------------------------------------------- @pytest.mark.parametrize( "line", [ - ' release-version: "26.08.0"', - " release-version: '26.08.0'", - " release-version: 26.08.0", - "release-version: 26.08.0", - "\trelease-version: 26.08.0", - ' release-version: "26.08.0" ', + ' installer-version: "26.08.0"', + " installer-version: '26.08.0'", + " installer-version: 26.08.0", + "installer-version: 26.08.0", + "\tinstaller-version: 26.08.0", + ' installer-version: "26.08.0" ', ], ) -def test_release_version_re_accepts_supported_spellings(checker, line): - match = checker.RELEASE_VERSION_RE.search(f"variables:\n{line}\n") +def test_installer_version_re_accepts_supported_spellings(checker, line): + match = checker.INSTALLER_VERSION_RE.search(f"variables:\n{line}\n") assert match is not None assert match.group(1) == "26.08.0" @@ -96,14 +114,14 @@ def test_release_version_re_accepts_supported_spellings(checker, line): @pytest.mark.parametrize( "line", [ - " release-version: 26.08", - " release-version:", - " other-release-version-thing: 1.2.3", - " # release-version: 1.2.3", + " installer-version: 26.08", + " installer-version:", + " other-installer-version-thing: 1.2.3", + " # installer-version: 1.2.3", ], ) -def test_release_version_re_rejects_malformed_declarations(checker, line): - assert checker.RELEASE_VERSION_RE.search(f"variables:\n{line}\n") is None +def test_installer_version_re_rejects_malformed_declarations(checker, line): + assert checker.INSTALLER_VERSION_RE.search(f"variables:\n{line}\n") is None # --- FSDK_REF_RE ---------------------------------------------------------- @@ -120,17 +138,37 @@ def test_fsdk_ref_re_ignores_two_component_track_glob(checker): assert checker.FSDK_REF_RE.search(" track: freedesktop-sdk-26.08*\n") is None +# --- FLATCAR_PIN_RE ------------------------------------------------------- + + +def test_flatcar_pin_re_extracts_version_from_pin(checker): + match = checker.FLATCAR_PIN_RE.search(' flatcar-version: "4593.2.5"\n') + assert match.group(1) == "4593.2.5" + + +def test_flatcar_pin_re_rejects_malformed(checker): + assert checker.FLATCAR_PIN_RE.search(" flatcar-version: 4593.2\n") is None + + # --- main() --------------------------------------------------------------- def test_main_passes_when_versions_match(checker, capsys): - _write(checker, declared="26.08.0", pinned="26.08.0") + _write( + checker, + installer_declared="26.08.0", + fsdk_pinned="26.08.0", + flatcar_pinned="4593.2.5", + ) checker.main() - assert "OK: release-version 26.08.0" in capsys.readouterr().out + out = capsys.readouterr().out + assert "OK: installer-version 26.08.0" in out + assert "OK: flatcar-version 4593.2.5" in out def test_main_exits_when_project_conf_missing(checker): checker.FSDK_JUNCTION.write_text("ref: freedesktop-sdk-26.08.0\n", encoding="utf-8") + checker.FLATCAR_PIN.write_text('flatcar-version: "4593.2.5"\n', encoding="utf-8") with pytest.raises(SystemExit) as excinfo: checker.main() assert "expected file not found" in str(excinfo.value) @@ -138,50 +176,77 @@ def test_main_exits_when_project_conf_missing(checker): def test_main_exits_when_junction_missing(checker): checker.PROJECT_CONF.write_text( - 'variables:\n release-version: "26.08.0"\n', encoding="utf-8" + 'variables:\n installer-version: "26.08.0"\n', + encoding="utf-8", ) + checker.FLATCAR_PIN.write_text('flatcar-version: "4593.2.5"\n', encoding="utf-8") with pytest.raises(SystemExit) as excinfo: checker.main() assert "expected file not found" in str(excinfo.value) -def test_main_exits_when_release_version_not_declared(checker): +def test_main_exits_when_flatcar_pin_missing(checker): + checker.PROJECT_CONF.write_text( + 'variables:\n installer-version: "26.08.0"\n', + encoding="utf-8", + ) + checker.FSDK_JUNCTION.write_text("ref: freedesktop-sdk-26.08.0\n", encoding="utf-8") + with pytest.raises(SystemExit) as excinfo: + checker.main() + assert "expected file not found" in str(excinfo.value) + + +def test_main_exits_when_installer_version_not_declared(checker): checker.PROJECT_CONF.write_text("variables:\n other: 1\n", encoding="utf-8") checker.FSDK_JUNCTION.write_text("ref: freedesktop-sdk-26.08.0\n", encoding="utf-8") + checker.FLATCAR_PIN.write_text('flatcar-version: "4593.2.5"\n', encoding="utf-8") with pytest.raises(SystemExit) as excinfo: checker.main() - assert "does not declare a" in str(excinfo.value) + assert "does not declare an 'installer-version" in str(excinfo.value) def test_main_exits_when_junction_has_no_point_release(checker): checker.PROJECT_CONF.write_text( - 'variables:\n release-version: "26.08.0"\n', encoding="utf-8" + 'variables:\n installer-version: "26.08.0"\n', + encoding="utf-8", ) checker.FSDK_JUNCTION.write_text( "junction:\n track: freedesktop-sdk-26.08*\n", encoding="utf-8" ) + checker.FLATCAR_PIN.write_text('flatcar-version: "4593.2.5"\n', encoding="utf-8") + with pytest.raises(SystemExit) as excinfo: + checker.main() + assert "no 'freedesktop-sdk-X.Y.Z' point release" in str(excinfo.value) + + +def test_main_exits_when_flatcar_pin_has_no_version(checker): + checker.PROJECT_CONF.write_text( + 'variables:\n installer-version: "26.08.0"\n', + encoding="utf-8", + ) + checker.FSDK_JUNCTION.write_text("ref: freedesktop-sdk-26.08.0\n", encoding="utf-8") + checker.FLATCAR_PIN.write_text("variables:\n other: 1\n", encoding="utf-8") with pytest.raises(SystemExit) as excinfo: checker.main() - assert "no" in str(excinfo.value) - assert "point release" in str(excinfo.value) + assert "does not declare a 'flatcar-version: X.Y.Z'" in str(excinfo.value) -def test_main_exits_on_drift_and_names_both_versions(checker): - _write(checker, declared="26.08.0", pinned="26.08.1") +def test_main_exits_on_installer_drift_and_names_both_versions(checker): + _write(checker, installer_declared="26.08.0", fsdk_pinned="26.08.1") with pytest.raises(SystemExit) as excinfo: checker.main() message = str(excinfo.value) - assert "release-version drift" in message + assert "installer-version drift" in message assert "26.08.0" in message assert "26.08.1" in message - assert 'set release-version to "26.08.1"' in message + assert 'set installer-version to "26.08.1"' in message -def test_main_drift_is_detected_across_minor_lines(checker): - _write(checker, declared="25.08.0", pinned="26.08.0") +def test_main_installer_drift_is_detected_across_minor_lines(checker): + _write(checker, installer_declared="25.08.0", fsdk_pinned="26.08.0") with pytest.raises(SystemExit) as excinfo: checker.main() - assert "release-version drift" in str(excinfo.value) + assert "installer-version drift" in str(excinfo.value) # --- live repository invariant ------------------------------------------- @@ -194,4 +259,6 @@ def test_real_repository_has_no_release_version_drift(capsys): module.main() finally: sys.modules.pop("check_release_version", None) - assert "OK: release-version" in capsys.readouterr().out + out = capsys.readouterr().out + assert "OK: installer-version" in out + assert "OK: flatcar-version" in out