Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
106 changes: 106 additions & 0 deletions .github/scripts/check-flatcar-version.py
Original file line number Diff line number Diff line change
@@ -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()
1 change: 1 addition & 0 deletions Justfile
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions elements/flatcar/flatcar-kernel.bst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion elements/flatcar/flatcar-zfs.bst
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
16 changes: 15 additions & 1 deletion include/flatcar.yml
Original file line number Diff line number Diff line change
@@ -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"
180 changes: 180 additions & 0 deletions tests/unit/test_check_flatcar_version.py
Original file line number Diff line number Diff line change
@@ -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