diff --git a/.github/scripts/check-flatcar-version.py b/.github/scripts/check-flatcar-version.py new file mode 100755 index 00000000..0986af39 --- /dev/null +++ b/.github/scripts/check-flatcar-version.py @@ -0,0 +1,106 @@ +#!/usr/bin/env python3 +"""Enforce the Flatcar single-source-of-truth invariant. + +include/flatcar.yml is the ONLY place a Flatcar upstream version or sha256 is +declared. Every Flatcar element reads those values through %{...} variable +substitution (see elements/flatcar/*.bst); nothing restates a pin. + +This script fails the build when a pinned literal — a Flatcar version, kernel +vermagic, or source sha256 — is hardcoded anywhere in elements/ or files/, +where it would drift from include/flatcar.yml and silently pull a different +upstream payload than the pin file names. It reads the declared pins out of +include/flatcar.yml and greps the tree for any copy of them outside that file, +in the spirit of check-release-version.py. +""" + +import re +import sys +import os +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] +PIN_FILE = ROOT / "include" / "flatcar.yml" +SCAN_DIRS = (ROOT / "elements", ROOT / "files") + +# A `key: "value"` / `key: 'value'` / `key: bare` line inside the variables: +# block of the pin file. The captured group is the declared pin literal. +VAR_RE = re.compile( + r'^\s+[A-Za-z0-9_.-]+:\s*(?:"([^"]*)"|' r"'([^']*)'" r'|([^\s#]+))', + re.MULTILINE, +) +# Directories that legitimately echo upstream digests and must never be scanned. +SKIP_DIRS = {".git", "__pycache__", "node_modules"} + + +def read(path): + if not path.is_file(): + sys.exit(f"ERROR: expected file not found: {path.relative_to(ROOT)}") + return path.read_text(encoding="utf-8") + + +def declared_pins(pin_text): + """Every literal declared in the variables: block of the pin file.""" + pins = [] + for value in VAR_RE.findall(pin_text): + literal = next(part for part in value if part) + if literal: + pins.append(literal) + return pins + + +def iter_scan_files(): + for scan_dir in SCAN_DIRS: + if not scan_dir.is_dir(): + continue + # os.walk with dir pruning so files under .git / __pycache__ / + # node_modules are never read (rglob would flatten and scan them). + for root, dirs, files in os.walk(scan_dir): + dirs[:] = [d for d in dirs if d not in SKIP_DIRS] + for name in files: + if name.endswith(".pyc"): + continue + yield Path(root) / name + + +def is_binary(text): + return "\x00" in text + + +def main(): + pins = declared_pins(read(PIN_FILE)) + if not pins: + sys.exit( + "ERROR: include/flatcar.yml declares no pins to enforce. Add the " + "Flatcar version / sha256 variables here." + ) + + violations = [] + for path in iter_scan_files(): + try: + text = path.read_text(encoding="utf-8") + except (UnicodeDecodeError, OSError): + continue + if is_binary(text): + continue + for pin in pins: + if pin in text: + violations.append((path.relative_to(ROOT), pin)) + + if violations: + lines = [ + "ERROR: Flatcar pin(s) hardcoded outside include/flatcar.yml.\n" + "Every Flatcar version and sha256 must live in include/flatcar.yml " + "and be\n" + "referenced via %{...}; hardcoding one here lets it drift from the " + "pin file.\n" + "\nRemove the literal and read it from include/flatcar.yml:" + ] + for path, pin in violations: + lines.append(f" {path}: {pin}") + sys.exit("\n".join(lines)) + + print(f"OK: no Flatcar pins hardcoded outside include/flatcar.yml ({len(pins)} pinned).") + + +if __name__ == "__main__": + main() diff --git a/Justfile b/Justfile index f219be69..4013b6b3 100644 --- a/Justfile +++ b/Justfile @@ -56,6 +56,7 @@ validate: python3 .github/scripts/check-release-version.py python3 .github/scripts/check-k0s-version.py python3 .github/scripts/check-renovate-series.py + python3 .github/scripts/check-flatcar-version.py just bst show --deps all oci/bluefin-server-ddi.bst just bst show --deps all oci/bluefin-server-installer.bst just bst show --deps all oci/k0s-sysext.bst diff --git a/elements/flatcar/flatcar-kernel.bst b/elements/flatcar/flatcar-kernel.bst index fcaa1b4a..52c86f48 100644 --- a/elements/flatcar/flatcar-kernel.bst +++ b/elements/flatcar/flatcar-kernel.bst @@ -23,10 +23,10 @@ variables: sources: - kind: remote url: flatcar:stable/%{flatcar-board}/%{flatcar-version}/flatcar_production_image.vmlinuz - ref: fe0b7ef1f9f98acc00e1db22937cdc57456df860a372fdc8eb806298f767b676 + ref: "%{flatcar-kernel-vmlinuz-sha256}" - kind: remote url: flatcar:stable/%{flatcar-board}/%{flatcar-version}/flatcar-container.tar.gz - ref: c533ff576e128d11ce240e01f818c358d75b9ff118b2dd9199fbf4684547a32c + ref: "%{flatcar-kernel-container-sha256}" - kind: local path: patches/flatcar-kernel directory: patches diff --git a/elements/flatcar/flatcar-zfs.bst b/elements/flatcar/flatcar-zfs.bst index eabdcf8e..cb4e3d4d 100644 --- a/elements/flatcar/flatcar-zfs.bst +++ b/elements/flatcar/flatcar-zfs.bst @@ -19,7 +19,7 @@ variables: sources: - kind: remote url: flatcar:stable/%{flatcar-board}/%{flatcar-version}/flatcar-zfs.raw - ref: bed24d0a31b6c9ff0f1d59ec2b50d25585bf9bbcb8e9e96f5706f1a17948d971 + ref: "%{flatcar-zfs-sha256}" config: install-commands: diff --git a/include/flatcar.yml b/include/flatcar.yml index e8f7cb08..65c31007 100644 --- a/include/flatcar.yml +++ b/include/flatcar.yml @@ -1,7 +1,21 @@ # Single source of truth for Flatcar LTS kernel and sysext versioning. # # Flatcar LTS kernel and ZFS sysext must stay strictly in lockstep because -# OpenZFS modules (spl.ko, zfs.ko) require matching kernel vermagic (6.12.102-flatcar). +# OpenZFS modules (spl.ko, zfs.ko) require matching kernel vermagic +# (6.12.102-flatcar). +# +# This file is the ONLY place a Flatcar upstream version or sha256 is declared. +# Every Flatcar element references these values through %{...} variable +# substitution (see elements/flatcar/*.bst); no element or script restates a +# Flatcar version or sha256. .github/scripts/check-flatcar-version.py fails the +# build if a pinned literal is ever hardcoded outside this file. variables: flatcar-version: "4593.2.5" flatcar-kver: "6.12.102-flatcar" + + # sha256 of the upstream Flatcar sources, pinned in lockstep with + # flatcar-version / flatcar-kver. Bump all three together on a Flatcar + # release. + flatcar-kernel-vmlinuz-sha256: "fe0b7ef1f9f98acc00e1db22937cdc57456df860a372fdc8eb806298f767b676" + flatcar-kernel-container-sha256: "c533ff576e128d11ce240e01f818c358d75b9ff118b2dd9199fbf4684547a32c" + flatcar-zfs-sha256: "bed24d0a31b6c9ff0f1d59ec2b50d25585bf9bbcb8e9e96f5706f1a17948d971" diff --git a/tests/unit/test_check_flatcar_version.py b/tests/unit/test_check_flatcar_version.py new file mode 100644 index 00000000..cea495b3 --- /dev/null +++ b/tests/unit/test_check_flatcar_version.py @@ -0,0 +1,180 @@ +"""Unit coverage for .github/scripts/check-flatcar-version.py. + +The script enforces that include/flatcar.yml is the single source of truth for +every Flatcar upstream pin (version, kernel vermagic, source sha256): no pin +may be hardcoded in elements/ or files/. When it regresses, a pin can drift +from the pin file and silently pull a different upstream payload, so every +branch of declared_pins(), iter_scan_files() and main() is exercised here. +""" + +import importlib.util +import sys +from pathlib import Path + +import pytest + +REPO_ROOT = Path(__file__).resolve().parents[2] +SCRIPT_PATH = REPO_ROOT / ".github" / "scripts" / "check-flatcar-version.py" + +PIN_FILE_TEXT = ( + "variables:\n" + ' flatcar-version: "4593.2.5"\n' + ' flatcar-kver: "6.12.102-flatcar"\n' + " flatcar-zfs-sha256: " + '"bed24d0a31b6c9ff0f1d59ec2b50d25585bf9bbcb8e9e96f5706f1a17948d971"\n' +) + + +def _load_module(): + spec = importlib.util.spec_from_file_location("check_flatcar_version", SCRIPT_PATH) + module = importlib.util.module_from_spec(spec) + sys.modules["check_flatcar_version"] = module + spec.loader.exec_module(module) + return module + + +@pytest.fixture +def checker(tmp_path): + """Fresh module instance rooted at tmp_path with a synthetic pin file.""" + module = _load_module() + module.ROOT = tmp_path + (tmp_path / "include").mkdir() + (tmp_path / "include" / "flatcar.yml").write_text(PIN_FILE_TEXT, encoding="utf-8") + module.PIN_FILE = tmp_path / "include" / "flatcar.yml" + (tmp_path / "elements").mkdir() + (tmp_path / "files").mkdir() + module.SCAN_DIRS = (tmp_path / "elements", tmp_path / "files") + yield module + sys.modules.pop("check_flatcar_version", None) + + +# --- declared_pins -------------------------------------------------------- + + +def test_declared_pins_extracts_versions_and_sha256(checker): + pins = checker.declared_pins(PIN_FILE_TEXT) + assert pins == [ + "4593.2.5", + "6.12.102-flatcar", + "bed24d0a31b6c9ff0f1d59ec2b50d25585bf9bbcb8e9e96f5706f1a17948d971", + ] + + +def test_declared_pins_handles_bare_and_single_quoted_values(): + text = ( + "variables:\n" + " bare: 1.2.3\n" + " single: '4.5.6'\n" + ) + module = _load_module() + try: + assert module.declared_pins(text) == ["1.2.3", "4.5.6"] + finally: + sys.modules.pop("check_flatcar_version", None) + + +def test_declared_pins_ignores_comments_and_headers(): + text = ( + "# single source of truth\n" + "variables:\n" + " flatcar-version: \"4593.2.5\" # the release\n" + ) + module = _load_module() + try: + assert module.declared_pins(text) == ["4593.2.5"] + finally: + sys.modules.pop("check_flatcar_version", None) + + +# --- read / missing pin file --------------------------------------------- + + +def test_read_exits_on_missing_pin_file(checker): + checker.PIN_FILE = checker.PIN_FILE.parent / "missing.yml" + with pytest.raises(SystemExit) as excinfo: + checker.main() + assert "expected file not found" in str(excinfo.value) + + +def test_main_exits_when_no_pins_declared(tmp_path): + (tmp_path / "include").mkdir(parents=True) + (tmp_path / "include" / "flatcar.yml").write_text("variables:\n", encoding="utf-8") + module = _load_module() + module.ROOT = tmp_path + module.PIN_FILE = tmp_path / "include" / "flatcar.yml" + module.SCAN_DIRS = () + try: + with pytest.raises(SystemExit) as excinfo: + module.main() + assert "declares no pins" in str(excinfo.value) + finally: + sys.modules.pop("check_flatcar_version", None) + + +# --- main() --------------------------------------------------------------- + + +def test_main_passes_when_tree_is_clean(checker): + (checker.ROOT / "elements" / "flatcar-zfs.bst").write_text( + "sources:\n" + " - kind: remote\n" + " url: flatcar:stable/%{flatcar-board}/%{flatcar-version}/flatcar-zfs.raw\n" + " ref: %{flatcar-zfs-sha256}\n", + encoding="utf-8", + ) + checker.main() + + +def test_main_fails_when_sha256_hardcoded_in_element(checker, capsys): + (checker.ROOT / "elements" / "flatcar-zfs.bst").write_text( + "sources:\n" + " - kind: remote\n" + " url: flatcar:stable/%{flatcar-board}/%{flatcar-version}/flatcar-zfs.raw\n" + " ref: bed24d0a31b6c9ff0f1d59ec2b50d25585bf9bbcb8e9e96f5706f1a17948d971\n", + encoding="utf-8", + ) + with pytest.raises(SystemExit) as excinfo: + checker.main() + message = str(excinfo.value) + assert "hardcoded outside" in message + assert "flatcar-zfs.bst" in message + assert "bed24d0a31b6c9ff0f1d59ec2b50d25585bf9bbcb8e9e96f5706f1a17948d971" in message + + +def test_main_fails_when_version_hardcoded_in_files(checker, capsys): + (checker.ROOT / "files" / "os-release").write_text( + 'NAME="Bluefin Server"\nVERSION="4593.2.5-fsd"\n', encoding="utf-8" + ) + with pytest.raises(SystemExit) as excinfo: + checker.main() + message = str(excinfo.value) + assert "hardcoded outside" in message + assert "files/os-release" in message + assert "4593.2.5" in message + + +def test_main_skips_binary_and_scanned_hidden_dirs(checker): + # A sha256 inside a .git / __pycache__ dir must NOT be flagged. + git_dir = checker.ROOT / "elements" / ".git" + pycache = checker.ROOT / "elements" / "__pycache__" + git_dir.mkdir(parents=True) + pycache.mkdir(parents=True) + (git_dir / "keep").write_text( + "bed24d0a31b6c9ff0f1d59ec2b50d25585bf9bbcb8e9e96f5706f1a17948d971\n", + encoding="utf-8", + ) + (pycache / "x.pyc").write_bytes(b"\x00bed24d0a31b6c9ff0f1d59ec2b50d25585\n") + checker.main() + + +# --- live repository invariant ------------------------------------------- + + +def test_real_repository_has_no_hardcoded_flatcar_pins(capsys): + """The checked-in tree must satisfy the invariant the script enforces.""" + module = _load_module() + try: + module.main() + finally: + sys.modules.pop("check_flatcar_version", None) + assert "OK: no Flatcar pins" in capsys.readouterr().out