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/.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/.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/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/.github/workflows/build.yml b/.github/workflows/build.yml index bf99f8ea..a00ed52b 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -12,57 +12,16 @@ 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: @@ -77,7 +36,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 @@ -182,7 +141,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/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/track-junctions.yml b/.github/workflows/track-junctions.yml new file mode 100644 index 00000000..3f438e00 --- /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@1.58.0 + + - 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/.github/workflows/unit-tests.yml b/.github/workflows/unit-tests.yml index fc4485d7..5a7569b3 100644 --- a/.github/workflows/unit-tests.yml +++ b/.github/workflows/unit-tests.yml @@ -4,18 +4,34 @@ on: pull_request: paths: - '.github/scripts/**' + - '.github/workflows/build.yml' - '.github/workflows/unit-tests.yml' + - '.pre-commit-config.yaml' + - 'elements/**' - 'files/**' + - 'include/**' + - 'project.conf' + - 'scripts/**' - 'tests/unit/**' - 'Justfile' + - 'renovate.json' + - 'elements/*.bst' push: branches: [main] paths: - '.github/scripts/**' + - '.github/workflows/build.yml' - '.github/workflows/unit-tests.yml' + - '.pre-commit-config.yaml' + - 'elements/**' - 'files/**' + - 'include/**' + - 'project.conf' + - 'scripts/**' - 'tests/unit/**' - 'Justfile' + - 'renovate.json' + - 'elements/*.bst' permissions: contents: read @@ -41,7 +57,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 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 95cf3104..06dd9287 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -13,11 +13,17 @@ 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 + 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/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/Justfile b/Justfile index f2dc1b23..c3cf9bb3 100644 --- a/Justfile +++ b/Justfile @@ -55,6 +55,8 @@ tags: 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 @@ -84,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')] @@ -195,12 +224,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}}" @@ -210,10 +294,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: @@ -317,6 +446,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 \ @@ -326,9 +479,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 & @@ -336,7 +490,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 @@ -348,13 +502,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) @@ -443,10 +593,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}" \ @@ -455,7 +661,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 @@ -465,19 +675,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/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/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/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/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..c4deaf91 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: @@ -59,13 +68,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 +98,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 +131,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. @@ -130,10 +151,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 +165,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 diff --git a/docs/skills/ddi-installer-build.md b/docs/skills/ddi-installer-build.md index 0916d10f..167bd780 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 @@ -71,8 +94,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 @@ -91,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/ddi-installer.md b/docs/skills/ddi-installer.md index f6fdfcf1..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: @@ -47,11 +48,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` is masked on the target image -(`/etc/systemd/system/systemd-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. @@ -94,7 +105,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 @@ -154,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 @@ -168,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/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/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/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/index.md b/docs/skills/index.md index 02c5b0a3..2c43ad27 100644 --- a/docs/skills/index.md +++ b/docs/skills/index.md @@ -27,8 +27,9 @@ 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. | | [`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. | @@ -43,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/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/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/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-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/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/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/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/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/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-usr.bst b/elements/flatcar/flatcar-usr.bst new file mode 100644 index 00000000..8229cd11 --- /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: "%{flatcar-kernel-container-sha256}" + +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/elements/flatcar/flatcar-zfs.bst b/elements/flatcar/flatcar-zfs.bst index 82832969..cb4e3d4d 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: @@ -18,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: @@ -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/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-ddi.bst b/elements/oci/bluefin-server-ddi.bst index 9f801570..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: @@ -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 @@ -78,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/elements/oci/bluefin-server-installer.bst b/elements/oci/bluefin-server-installer.bst index 44d9f300..5999abe2 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 ──────────── @@ -103,10 +100,13 @@ 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 + # 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 @@ -114,8 +114,12 @@ config: ldconfig # Build target-root linker cache and stage it at /etc/ld.so.cache for dracut + # 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 - 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 @@ -194,10 +198,87 @@ config: modprobe -q xfs || true udevadm trigger --subsystem-match=block || true udevadm settle --timeout=15 || true + + # 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 + # 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 @@ -212,6 +293,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:-}" @@ -253,8 +343,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 @@ -360,7 +448,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 \ @@ -443,7 +531,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)")" @@ -451,7 +539,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/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/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 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/41-kubestellar-kiosk-proxy.yaml b/files/k0s/manifests/kubestellar/41-kubestellar-kiosk-proxy.yaml index 80e38d5a..588288ae 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/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 name: http 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/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/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/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 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/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 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/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/renovate.json b/renovate.json index 45e9cdfe..1e1e09fd 100644 --- a/renovate.json +++ b/renovate.json @@ -14,11 +14,15 @@ ] } ], + "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"], "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/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/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!" 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" ]] } 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 +} 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 +} 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-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"* ]] +} diff --git a/tests/unit/test_build_depends.py b/tests/unit/test_build_depends.py index b2aa04ee..3110fac2 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,63 @@ 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)" + ) + + +def test_installer_linker_paths_split_host_and_target(): + """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") + + # 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)" + ) + # 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)" ) 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 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_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 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_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 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 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." + ) 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 diff --git a/tests/unit/test_flatcar_usr.py b/tests/unit/test_flatcar_usr.py new file mode 100644 index 00000000..70f47476 --- /dev/null +++ b/tests/unit/test_flatcar_usr.py @@ -0,0 +1,290 @@ +"""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 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" + 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.""" + 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" 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) 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 diff --git a/tests/unit/test_installer_contract.py b/tests/unit/test_installer_contract.py index d423c685..114df0b3 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 @@ -121,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") @@ -135,3 +145,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 + 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_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 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" 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 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(): 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