From 3f91d3e02a31add143181a8a29115f703d1cee72 Mon Sep 17 00:00:00 2001 From: Jeffrey Sica Date: Tue, 29 Sep 2026 00:15:39 -0500 Subject: [PATCH 1/8] refactor(sysext): share one packing recipe across the sysext elements kubestellar, kubeadm and zfs each carried a copy of the same tail: stamp extension-release, mkfs.erofs, zstd, SHA256SUMS. include/sysext.yml now holds it as %{sysext-pack}; each element stages ./sysext, names itself with sysext-* variables and runs the recipe last. Outputs are unchanged: extracting the rebuilt images gives the same files, contents, modes, owners and mtimes as before. Only the erofs superblock UUID differs, which mkfs.erofs randomizes on every build. Assisted-by: Claude Opus 5.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- elements/oci/kubeadm-sysext.bst | 20 ++++++----------- elements/oci/kubestellar-sysext.bst | 20 ++++++++--------- elements/oci/zfs-sysext.bst | 25 ++++++--------------- include/sysext.yml | 35 +++++++++++++++++++++++++++++ tests/unit/test_kubeadm_sysext.py | 4 ++-- tests/unit/test_signed_lockstep.py | 4 ++-- 6 files changed, 63 insertions(+), 45 deletions(-) create mode 100644 include/sysext.yml diff --git a/elements/oci/kubeadm-sysext.bst b/elements/oci/kubeadm-sysext.bst index 02df2686..5e7400d7 100644 --- a/elements/oci/kubeadm-sysext.bst +++ b/elements/oci/kubeadm-sysext.bst @@ -17,6 +17,7 @@ description: | - include/arch.yml - include/image.yml - include/kubeadm.yml +- include/sysext.yml build-depends: - base/base-stack.bst @@ -33,6 +34,11 @@ sources: variables: strip-binaries: "" + sysext-name: "kubeadm" + sysext-image: "kubeadm_%{image-version}" + sysext-release: "kubeadm_%{image-version}" + sysext-version: "%{image-version}" + sysext-architecture: "%{systemd-arch}" config: install-commands: @@ -59,11 +65,6 @@ config: *) echo "ERROR: config.toml sandbox image is not %{pause-image} (include/kubeadm.yml)" >&2; exit 1 ;; esac - rel="${lib}/extension-release.d/extension-release.kubeadm_%{image-version}" - install -D -m 0644 "${src}/extension-release.kubeadm" "${rel}" - echo "VERSION_ID=%{image-version}" >> "${rel}" - echo "ARCHITECTURE=%{systemd-arch}" >> "${rel}" - # A sysext may only carry /usr (and /opt, which must stay a plain # writable host directory for /opt/cni/bin). for entry in sysext/* sysext/.[!.]*; do @@ -71,11 +72,4 @@ config: [ "${entry}" = "sysext%{prefix}" ] || { echo "ERROR: sysext ships ${entry#sysext}" >&2; exit 1; } done - - | - set -euo pipefail - OUT="%{install-root}" - FNAME="kubeadm_%{image-version}.raw" - mkdir -p "${OUT}" - mkfs.erofs -d0 "${OUT}/${FNAME}" sysext - zstd -T0 -19 -q "${OUT}/${FNAME}" -o "${OUT}/${FNAME}.zst" - (cd "${OUT}" && sha256sum --binary "${FNAME}.zst" > SHA256SUMS) + - "%{sysext-pack}" diff --git a/elements/oci/kubestellar-sysext.bst b/elements/oci/kubestellar-sysext.bst index 665ae867..05a7962e 100644 --- a/elements/oci/kubestellar-sysext.bst +++ b/elements/oci/kubestellar-sysext.bst @@ -11,6 +11,7 @@ description: | (@): - include/image.yml + - include/sysext.yml build-depends: - base/base-stack.bst @@ -33,23 +34,24 @@ sources: variables: strip-binaries: "" + sysext-name: "kubestellar" + sysext-image: "kubestellar_%{image-version}" + sysext-release: "kubestellar_%{image-version}" + sysext-version: "%{image-version}" + # Manifests, kiosk assets and shell scripts only. + sysext-architecture: "" config: install-commands: - | set -euo pipefail - OUT="%{install-root}" - FNAME="kubestellar_%{image-version}.raw" root=sysext/usr mkdir -p "${root}/lib/systemd/system/k0scontroller.service.wants" \ - "${root}/lib/extension-release.d" "${root}/lib/tmpfiles.d" "${root}/lib/issue.d" \ - "${root}/share/k0s/manifests" "${root}/share/k0s/kiosk" "${root}/share/k0s/kubeflex" "${OUT}" + "${root}/lib/tmpfiles.d" "${root}/lib/issue.d" \ + "${root}/share/k0s/manifests" "${root}/share/k0s/kiosk" "${root}/share/k0s/kubeflex" cp -a sysext-src/kubestellar-seed.service "${root}/lib/systemd/system/" ln -s ../kubestellar-seed.service "${root}/lib/systemd/system/k0scontroller.service.wants/kubestellar-seed.service" cp -a sysext-src/k0s-manifests.conf "${root}/lib/tmpfiles.d/" - rel="${root}/lib/extension-release.d/extension-release.kubestellar_%{image-version}" - cp -a sysext-src/extension-release.kubestellar "${rel}" - echo "VERSION_ID=%{image-version}" >> "${rel}" cp -a sysext-src/40-kubestellar.issue "${root}/lib/issue.d/" cp -a manifests-src/* "${root}/share/k0s/manifests/" cp -a kiosk-src/. "${root}/share/k0s/kiosk/" @@ -58,6 +60,4 @@ config: if find sysext -name '*.pem' | grep -q .; then echo "ERROR: key material in a public sysext" >&2; exit 1 fi - mkfs.erofs -d0 "${OUT}/${FNAME}" sysext - zstd -T0 -19 -q "${OUT}/${FNAME}" -o "${OUT}/${FNAME}.zst" - (cd "${OUT}" && sha256sum --binary "${FNAME}.zst" > SHA256SUMS) + - "%{sysext-pack}" diff --git a/elements/oci/zfs-sysext.bst b/elements/oci/zfs-sysext.bst index cef4d1b0..24f1a828 100644 --- a/elements/oci/zfs-sysext.bst +++ b/elements/oci/zfs-sysext.bst @@ -23,6 +23,7 @@ description: | - include/arch.yml - include/image.yml - include/zfs.yml +- include/sysext.yml build-depends: - base/base-stack.bst @@ -45,6 +46,11 @@ sources: variables: strip-binaries: "" + sysext-name: "zfs" + sysext-image: "zfs_%{image-version}" + sysext-release: "zfs_%{image-version}" + sysext-version: "%{image-version}" + sysext-architecture: "%{systemd-arch}" config: install-commands: @@ -120,21 +126,4 @@ config: ln -s "../${u}" "${unitdir}/zfs.target.wants/${u}" done - install -d "sysext%{indep-libdir}/extension-release.d" - rel="sysext%{indep-libdir}/extension-release.d/extension-release.zfs_%{image-version}" - cp sysext-src/extension-release.zfs "${rel}" - echo "VERSION_ID=%{image-version}" >> "${rel}" - echo "ARCHITECTURE=%{systemd-arch}" >> "${rel}" - - - | - set -euo pipefail - OUT="%{install-root}" - FNAME="zfs_%{image-version}.raw" - - mkdir -p "${OUT}" - mkfs.erofs -d0 "${OUT}/${FNAME}" sysext - zstd -T0 -19 -q "${OUT}/${FNAME}" -o "${OUT}/${FNAME}.zst" - ( - cd "${OUT}" - sha256sum --binary "${FNAME}.zst" > SHA256SUMS - ) + - "%{sysext-pack}" diff --git a/include/sysext.yml b/include/sysext.yml new file mode 100644 index 00000000..e8c0afff --- /dev/null +++ b/include/sysext.yml @@ -0,0 +1,35 @@ +# Shared packing recipe for the oci/*-sysext.bst elements. +# +# An element stages its payload as a /usr tree under ./sysext, stages its +# static extension identity as sysext-src/extension-release., +# sets the variables below, and runs "%{sysext-pack}" as its last install +# command. The recipe stamps the extension-release file, packs ./sysext into +# an EROFS image, compresses the release asset and checksums it: +# +# .raw uncompressed EROFS image +# .raw.zst release asset +# SHA256SUMS sha256 of the .raw.zst +# +# Variables each element sets: +# sysext-name stem of the static identity file in sysext-src/ +# sysext-image image file name without .raw +# sysext-release extension-release.d suffix: the name systemd-sysext +# merges the image under +# sysext-version VERSION_ID= +# sysext-architecture ARCHITECTURE= (%{systemd-arch}), or "" for a payload +# that runs on any architecture +variables: + sysext-pack: | + set -euo pipefail + rel="sysext%{indep-libdir}/extension-release.d/extension-release.%{sysext-release}" + install -D -m 0644 "sysext-src/extension-release.%{sysext-name}" "${rel}" + echo "VERSION_ID=%{sysext-version}" >> "${rel}" + if [ -n "%{sysext-architecture}" ]; then + echo "ARCHITECTURE=%{sysext-architecture}" >> "${rel}" + fi + + out="%{install-root}/%{sysext-image}.raw" + mkdir -p "%{install-root}" + mkfs.erofs -d0 "${out}" sysext + zstd -T0 -19 -q "${out}" -o "${out}.zst" + (cd "%{install-root}" && sha256sum --binary "%{sysext-image}.raw.zst" > SHA256SUMS) diff --git a/tests/unit/test_kubeadm_sysext.py b/tests/unit/test_kubeadm_sysext.py index 52effa27..c7a1b532 100644 --- a/tests/unit/test_kubeadm_sysext.py +++ b/tests/unit/test_kubeadm_sysext.py @@ -78,8 +78,8 @@ def test_sysext_ships_nothing_under_opt() -> None: def test_sysext_is_version_locked_and_in_the_signed_release_set() -> None: text = SYSEXT.read_text(encoding="utf-8") - assert "extension-release.kubeadm_%{image-version}" in text - assert 'FNAME="kubeadm_%{image-version}.raw"' in text + assert 'sysext-release: "kubeadm_%{image-version}"' in text + assert 'sysext-image: "kubeadm_%{image-version}"' in text release = dict( line.split("=", 1) for line in (SRC / "extension-release.kubeadm").read_text().splitlines() if "=" in line ) diff --git a/tests/unit/test_signed_lockstep.py b/tests/unit/test_signed_lockstep.py index 30eb515f..55ec18b9 100644 --- a/tests/unit/test_signed_lockstep.py +++ b/tests/unit/test_signed_lockstep.py @@ -51,8 +51,8 @@ def test_version_locked_sysexts_are_optional_features(name: str, transfer: str) @pytest.mark.parametrize("element,name", [("zfs-sysext.bst", "zfs"), ("kubestellar-sysext.bst", "kubestellar"), ("kubeadm-sysext.bst", "kubeadm")]) def test_extension_release_name_carries_the_image_version(element: str, name: str) -> None: text = (ROOT / "elements" / "oci" / element).read_text(encoding="utf-8") - assert f"extension-release.{name}_%{{image-version}}" in text - assert f'{name}_%{{image-version}}.raw' in text + assert f'sysext-release: "{name}_%{{image-version}}"' in text + assert f'sysext-image: "{name}_%{{image-version}}"' in text def test_sysext_units_are_started_after_a_boot_time_merge() -> None: From 77bff706d9b7adfa0e26ebccd70f75193666daea Mon Sep 17 00:00:00 2001 From: Jeffrey Sica Date: Tue, 29 Sep 2026 00:15:39 -0500 Subject: [PATCH 2/8] refactor(sysext): pack the k0s sysext with the shared recipe The asset name and VERSION_ID now live in sysext-image / sysext-version, so check-k0s-version.py reads those instead of FNAME= and the echoed VERSION_ID line, and the transfer test resolves sysext-image to the emitted .raw name. Drops the unused xz build dependency. Assisted-by: Claude Opus 5.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/scripts/check-k0s-version.py | 26 +++++++++--------- elements/oci/k0s-sysext.bst | 38 +++++++------------------- tests/unit/test_check_k0s_version.py | 24 ++++++++-------- tests/unit/test_sysupdate_transfers.py | 10 +++++-- 4 files changed, 42 insertions(+), 56 deletions(-) diff --git a/.github/scripts/check-k0s-version.py b/.github/scripts/check-k0s-version.py index 2d7b1a4b..d92553a7 100644 --- a/.github/scripts/check-k0s-version.py +++ b/.github/scripts/check-k0s-version.py @@ -14,7 +14,8 @@ three must move together or the sysext silently stops updating: * ``elements/k0s/k0s-bin.bst`` — the upstream download URL. - * ``elements/oci/k0s-sysext.bst`` — the release asset filename, which + * ``elements/oci/k0s-sysext.bst`` — the release asset name + (``sysext-image``, packed by include/sysext.yml), which ``files/os/sysupdate.d/70-k0s.transfer`` reads as the version oracle through its ``@v`` wildcard. * ``files/k0s/sysext/extension-release.k0s`` — the ``VERSION_ID=`` reported @@ -121,36 +122,35 @@ def main(): # The asset filename must be on the k0s axis, not the OS release axis. sysext_text = read(K0S_SYSEXT) - fname_match = re.search(r'^\s*FNAME="([^"]+)"\s*$', sysext_text, re.MULTILINE) + fname_match = re.search(r'^\s*sysext-image:\s*"([^"]+)"\s*$', sysext_text, re.MULTILINE) if not fname_match: fail( - 'elements/oci/k0s-sysext.bst declares no FNAME="..." asset name.', - "restore the sysext asset filename assignment.", + 'elements/oci/k0s-sysext.bst declares no sysext-image: "..." asset name.', + "restore the sysext-image variable.", ) fname_expr = fname_match.group(1) if any(axis in fname_expr for axis in ("%{release-version}", "%{installer-version}", "%{image-version}")): fail( "elements/oci/k0s-sysext.bst names the k0s sysext on an OS release\n" - f" axis: FNAME=\"{fname_expr}\"\n" + f" axis: sysext-image: \"{fname_expr}\"\n" " 70-k0s.transfer reads this filename as the version of the k0s it\n" " delivers.", - 'use FNAME="k0s-%{k0s-version}.raw".', + 'use sysext-image: "k0s-%{k0s-version}".', ) if "%{k0s-version}" not in fname_expr: fail( "elements/oci/k0s-sysext.bst does not derive the sysext asset name\n" - f" from the pinned k0s version: FNAME=\"{fname_expr}\"", - 'use FNAME="k0s-%{k0s-version}.raw".', + f" from the pinned k0s version: sysext-image: \"{fname_expr}\"", + 'use sysext-image: "k0s-%{k0s-version}".', ) # VERSION_ID must be generated, so sysext status matches the asset. - if 'echo "VERSION_ID=%{k0s-version}"' not in sysext_text: + if 'sysext-version: "%{k0s-version}"' not in sysext_text: fail( "elements/oci/k0s-sysext.bst does not generate VERSION_ID= from\n" " %{k0s-version}, so `systemd-sysext status` can disagree with the\n" " asset filename an operator sees on disk.", - 'append \'VERSION_ID=%{k0s-version}\' to the staged ' - "extension-release.k0s.", + 'set sysext-version: "%{k0s-version}" in elements/oci/k0s-sysext.bst.', ) ext_text = read(EXTENSION_RELEASE) @@ -184,7 +184,7 @@ def main(): ) # The produced asset name must satisfy the sysupdate transfer pattern. - asset = fname_expr.replace("%{k0s-version}", version) + ".zst" + asset = fname_expr.replace("%{k0s-version}", version) + ".raw.zst" transfer_text = read(TRANSFER) pattern_match = re.search( r"^\s*MatchPattern=(\S*@v\S*\.zst)\s*$", transfer_text, re.MULTILINE @@ -214,7 +214,7 @@ def main(): f" k0s-version : {version!r}\n" " Hosts compare the captured string against the version they have\n" " installed, so a mismatch means k0s updates silently stop.", - "align FNAME in elements/oci/k0s-sysext.bst with MatchPattern in " + "align sysext-image in elements/oci/k0s-sysext.bst with MatchPattern in " "files/os/sysupdate.d/70-k0s.transfer.", ) diff --git a/elements/oci/k0s-sysext.bst b/elements/oci/k0s-sysext.bst index ef837deb..a8a57b5f 100644 --- a/elements/oci/k0s-sysext.bst +++ b/elements/oci/k0s-sysext.bst @@ -11,11 +11,11 @@ description: | (@): - include/arch.yml - include/k0s.yml + - include/sysext.yml build-depends: - base/base-stack.bst - freedesktop-sdk.bst:components/erofs-utils.bst - - freedesktop-sdk.bst:components/xz.bst - freedesktop-sdk.bst:components/zstd.bst - filename: k0s/k0s-bin.bst config: @@ -28,43 +28,25 @@ sources: variables: strip-binaries: "" + sysext-name: "k0s" + sysext-image: "k0s-%{k0s-version}" + # Merged as /run/extensions/k0s.raw (k0s-first-boot.service), so the + # extension-release name carries no version. + sysext-release: "k0s" + sysext-version: "%{k0s-version}" + sysext-architecture: "%{systemd-arch}" config: install-commands: - | set -euo pipefail - OUT="%{install-root}" - FNAME="k0s-%{k0s-version}.raw" - if [ "%{arch}" != "x86_64" ]; then echo "ERROR: elements/oci/k0s-sysext.bst only supports x86_64 (got %{arch})" >&2 exit 1 fi - mkdir -p sysext/usr/bin - mkdir -p sysext/usr/lib/systemd/system - mkdir -p sysext/usr/lib/extension-release.d - mkdir -p "${OUT}" - - # Stage k0s binary + mkdir -p sysext/usr/bin sysext/usr/lib/systemd/system cp -a /usr/bin/k0s sysext/usr/bin/k0s chmod 0755 sysext/usr/bin/k0s - - # Stage systemd service cp -a sysext-src/k0scontroller.service sysext-src/k0sworker.service sysext/usr/lib/systemd/system/ - - # Stage extension release metadata - cp -a sysext-src/extension-release.k0s sysext/usr/lib/extension-release.d/ - echo "VERSION_ID=%{k0s-version}" >> sysext/usr/lib/extension-release.d/extension-release.k0s - echo "ARCHITECTURE=%{systemd-arch}" >> sysext/usr/lib/extension-release.d/extension-release.k0s - - # Build EROFS image - mkfs.erofs -d0 "${OUT}/${FNAME}" sysext - - # Compress release asset - zstd -T0 -19 -q "${OUT}/${FNAME}" -o "${OUT}/${FNAME}.zst" - - ( - cd "${OUT}" - sha256sum --binary "${FNAME}.zst" > SHA256SUMS - ) + - "%{sysext-pack}" diff --git a/tests/unit/test_check_k0s_version.py b/tests/unit/test_check_k0s_version.py index fee8c169..dc99d558 100644 --- a/tests/unit/test_check_k0s_version.py +++ b/tests/unit/test_check_k0s_version.py @@ -8,8 +8,8 @@ Covered here: ``read()``, ``scalar()``, ``expand()``, ``fail()`` and each rejection path of ``main()`` — non-filename-safe version, missing/hardcoded -upstream URL, missing/OS-axis/underived ``FNAME``, missing generated -``VERSION_ID``, a hardcoded ``VERSION_ID=`` in extension-release.k0s, literal +upstream URL, missing/OS-axis/underived ``sysext-image``, missing derived +``sysext-version``, a hardcoded ``VERSION_ID=`` in extension-release.k0s, literal k0s versions restated in any consumer, a missing sysupdate ``MatchPattern``, and an asset name whose ``@v`` capture disagrees with ``%{k0s-version}``. """ @@ -39,11 +39,9 @@ """ GOOD_SYSEXT = """kind: manual -config: - install-commands: - - | - FNAME="k0s-%{k0s-version}.raw" - echo "VERSION_ID=%{k0s-version}" >> extension-release.k0s +variables: + sysext-image: "k0s-%{k0s-version}" + sysext-version: "%{k0s-version}" """ GOOD_EXTENSION_RELEASE = "NAME=k0s\nID=_any\n" @@ -262,14 +260,14 @@ def test_main_rejects_hardcoded_upstream_tag_in_url(checker): def test_main_rejects_missing_fname(checker): checker.K0S_SYSEXT.write_text( - 'echo "VERSION_ID=%{k0s-version}"\n', encoding="utf-8" + 'sysext-version: "%{k0s-version}"\n', encoding="utf-8" ) - assert 'declares no FNAME="..." asset name' in _run(checker) + assert 'declares no sysext-image: "..." asset name' in _run(checker) def test_main_rejects_fname_on_the_os_release_axis(checker): checker.K0S_SYSEXT.write_text( - GOOD_SYSEXT.replace("%{k0s-version}.raw", "%{release-version}.raw", 1), + GOOD_SYSEXT.replace('"k0s-%{k0s-version}"', '"k0s-%{release-version}"'), encoding="utf-8", ) assert "names the k0s sysext on an OS release" in _run(checker) @@ -277,7 +275,7 @@ def test_main_rejects_fname_on_the_os_release_axis(checker): def test_main_rejects_fname_not_derived_from_k0s_version(checker): checker.K0S_SYSEXT.write_text( - GOOD_SYSEXT.replace('FNAME="k0s-%{k0s-version}.raw"', 'FNAME="k0s.raw"'), + GOOD_SYSEXT.replace('"k0s-%{k0s-version}"', '"k0s"'), encoding="utf-8", ) assert "does not derive the sysext asset name" in _run(checker) @@ -285,7 +283,7 @@ def test_main_rejects_fname_not_derived_from_k0s_version(checker): def test_main_rejects_missing_generated_version_id(checker): checker.K0S_SYSEXT.write_text( - 'FNAME="k0s-%{k0s-version}.raw"\n', encoding="utf-8" + 'sysext-image: "k0s-%{k0s-version}"\n', encoding="utf-8" ) assert "does not generate VERSION_ID= from" in _run(checker) @@ -354,7 +352,7 @@ def test_main_rejects_prefix_drift_between_fname_and_match_pattern(checker): def test_main_rejects_suffix_drift_between_fname_and_match_pattern(checker): checker.K0S_SYSEXT.write_text( GOOD_SYSEXT.replace( - 'FNAME="k0s-%{k0s-version}.raw"', 'FNAME="k0s-%{k0s-version}.erofs"' + '"k0s-%{k0s-version}"', '"k0s-%{k0s-version}-erofs"' ), encoding="utf-8", ) diff --git a/tests/unit/test_sysupdate_transfers.py b/tests/unit/test_sysupdate_transfers.py index 57fe9866..18fed61d 100644 --- a/tests/unit/test_sysupdate_transfers.py +++ b/tests/unit/test_sysupdate_transfers.py @@ -48,10 +48,16 @@ def load_transfer(path: Path) -> configparser.ConfigParser: def element_texts() -> str: - """Every element definition concatenated, for artifact-name lookups.""" - return "\n".join( + """Every element definition concatenated, for artifact-name lookups. + + Sysext elements name their image in ``sysext-image:`` and + ``include/sysext.yml`` writes ``%{sysext-image}.raw``; spell that out. + """ + text = "\n".join( p.read_text() for p in sorted(ELEMENTS_DIR.rglob("*.bst")) ) + images = re.findall(r'^\s*sysext-image:\s*"([^"]+)"', text, re.MULTILINE) + return "\n".join([text, *(f"{image}.raw" for image in images)]) def split_match_pattern(pattern: str) -> tuple[str, str]: From ded2c30bfb19c11fa081f7310ae869db135ed2cf Mon Sep 17 00:00:00 2001 From: Jeffrey Sica Date: Tue, 29 Sep 2026 00:16:18 -0500 Subject: [PATCH 3/8] docs(base): describe base-stack as the build sandbox it is The description pointed at elements/oci/base.bst, which does not exist, and described base-stack as a shipped distroless runtime. Every reference is a build-depends; the OS payload is bluefin-server/os-base.bst. Assisted-by: Claude Opus 5.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- elements/base/base-stack.bst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/elements/base/base-stack.bst b/elements/base/base-stack.bst index cbd90586..6164f66e 100644 --- a/elements/base/base-stack.bst +++ b/elements/base/base-stack.bst @@ -1,10 +1,10 @@ kind: stack description: | - Minimal distroless runtime: glibc + gcc-libs + base files, plus - CA certificates and timezone data. No package manager. In FSDK 26.08, - runtime-gnu provides /bin/sh for ldconfig and ca-certificates - integration scripts; bash is removed by an explicit rm -f step in - elements/oci/base.bst, not by a compose domain. + Build sandbox for this project's manual and script elements: glibc, + runtime-gnu (/bin/sh and coreutils, which the ldconfig and + ca-certificates integration commands also need in FSDK 26.08), CA + certificates and timezone data. Nothing ships it; the OS payload is + bluefin-server/os-base.bst. depends: - freedesktop-sdk.bst:public-stacks/runtime-gnu.bst From 4ad3d29d88abf8187c65a1de809d4d3a3215cacd Mon Sep 17 00:00:00 2001 From: Jeffrey Sica Date: Tue, 29 Sep 2026 00:16:18 -0500 Subject: [PATCH 4/8] docs(k0s): explain why k0s activation stays in the base image The KubeStellar banner already ships in oci/kubestellar-sysext.bst (/usr/lib/issue.d, which agetty reads when /etc/issue is absent); the base image's banner has no KubeStellar text, so fix the os-stack.bst comment that said otherwise. k0s-first-boot.service must stay in /usr: a sysext cannot merge itself, and the k0s image sits in /var/lib/k0s, outside the extension directories. Record that, and that 80-bluefin-opt-in.preset keeps both units off. Assisted-by: Claude Opus 5.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/skills/k0s-sysext.md | 10 ++++++++++ elements/bluefin-server/os-stack.bst | 2 +- 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/skills/k0s-sysext.md b/docs/skills/k0s-sysext.md index 60a15ea5..ffa9a105 100644 --- a/docs/skills/k0s-sysext.md +++ b/docs/skills/k0s-sysext.md @@ -63,6 +63,16 @@ Design choices: `systemctl enable --now k0s-first-boot.service`. The unit copies the image to `/run/extensions/k0s.raw`, runs `systemd-sysext refresh`, and enables the controller or worker. +- **Why the activation units stay in the base image.** A sysext cannot + activate itself: nothing in it runs until something merges it, and the k0s + image lives in `/var/lib/k0s`, outside the extension directories + `systemd-sysext` scans. `k0s-first-boot.service` (and its fetcher) is that + something, so it ships in `/usr` (`bluefin-server/os-k0s-first-boot.bst`). + A provisioner such as [Booty](https://github.com/jeefy/booty) or an + Ignition config writes `/var/lib/k0s/k0s.raw` and enables the unit. It is + inert otherwise: FSDK has no catch-all `disable *` preset, so + `80-bluefin-opt-in.preset` disables both units explicitly, and no preset in + the image or in any sysext enables them. - **OTA delivery.** A k0s component `systemd-sysupdate` transfer file (`70-k0s.transfer`) is installed in the base OS so hosts can pull new k0s sysext releases from GitHub Releases without updating the root or UKI. diff --git a/elements/bluefin-server/os-stack.bst b/elements/bluefin-server/os-stack.bst index e48b0b68..e12888ee 100644 --- a/elements/bluefin-server/os-stack.bst +++ b/elements/bluefin-server/os-stack.bst @@ -48,5 +48,5 @@ depends: # system-container helper (machinectl wrapper) - bluefin-server/os-system-container.bst - # Console issue banner with KubeStellar dashboard URL + # Console issue banner (the KubeStellar sysext adds its dashboard URL) - bluefin-server/os-issue.bst From c61873f2c1eb90c98a3c4e4ad20a2255f7df6406 Mon Sep 17 00:00:00 2001 From: Jeffrey Sica Date: Tue, 29 Sep 2026 00:26:03 -0500 Subject: [PATCH 5/8] build: drop unreachable ppc64le and riscv64 junction options options.arch in project.conf only allows aarch64 and x86_64, so the ppc64le and riscv64 bootstrap_build_arch branches could never be taken. Assisted-by: Claude Opus 5.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- elements/freedesktop-sdk.bst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/elements/freedesktop-sdk.bst b/elements/freedesktop-sdk.bst index a40589b5..73783a6d 100644 --- a/elements/freedesktop-sdk.bst +++ b/elements/freedesktop-sdk.bst @@ -17,10 +17,6 @@ config: bootstrap_build_arch: 'x86_64' - arch == 'aarch64': bootstrap_build_arch: 'aarch64' - - arch == "ppc64le": - bootstrap_build_arch: "ppc64le" - - arch == "riscv64": - bootstrap_build_arch: "x86_64" overrides: # Our public module signing certificate; FSDK's kernel trusts it and From 00b485c8a39239918d61d9bedbb21b71bef1fbd7 Mon Sep 17 00:00:00 2001 From: Jeffrey Sica Date: Tue, 29 Sep 2026 00:26:03 -0500 Subject: [PATCH 6/8] feat(k0s): pin the arm64 k0s binary for aarch64 builds k0s-bin.bst takes the arm64 asset under arch == aarch64 (sha256 from the release's sha256sums.txt) and installs the %{go-arch} file, a new amd64 / arm64 spelling in include/arch.yml. The x86_64-only guards in k0s-bin.bst and k0s-sysext.bst go; check-k0s-version.py now checks every source URL. The x86_64 k0s sysext is unchanged (same files, modes and mtimes); a -o arch aarch64 source fetch downloads and verifies only the arm64 asset. Assisted-by: Claude Opus 5.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/scripts/check-k0s-version.py | 11 ++++++----- elements/k0s/k0s-bin.bst | 28 +++++++++++++++------------- elements/oci/k0s-sysext.bst | 5 ----- include/arch.yml | 7 ++++++- tests/unit/test_check_k0s_version.py | 13 +++++++++++++ 5 files changed, 40 insertions(+), 24 deletions(-) diff --git a/.github/scripts/check-k0s-version.py b/.github/scripts/check-k0s-version.py index d92553a7..6be51ccd 100644 --- a/.github/scripts/check-k0s-version.py +++ b/.github/scripts/check-k0s-version.py @@ -101,16 +101,17 @@ def main(): "restrict k0s-version to [A-Za-z0-9._~^+-] in include/k0s.yml.", ) - # The upstream download URL must be derived, not restated. + # Every upstream download URL (one per architecture) must be derived. bin_text = read(K0S_BIN) - url_match = re.search(r"^\s*url:\s*(\S+)\s*$", bin_text, re.MULTILINE) - if not url_match: + urls = re.findall(r"^\s*url:\s*(\S+)\s*$", bin_text, re.MULTILINE) + if not urls: fail( "elements/k0s/k0s-bin.bst declares no source 'url:'.", "restore the pinned upstream k0s release URL.", ) - url = url_match.group(1) - if "%{k0s-upstream-tag}" not in url: + for url in urls: + if "%{k0s-upstream-tag}" in url: + continue fail( "elements/k0s/k0s-bin.bst hardcodes the upstream k0s release tag:\n" f" url: {url}\n" diff --git a/elements/k0s/k0s-bin.bst b/elements/k0s/k0s-bin.bst index 63997322..260b0182 100644 --- a/elements/k0s/k0s-bin.bst +++ b/elements/k0s/k0s-bin.bst @@ -1,14 +1,16 @@ kind: manual description: | - Import the upstream k0s release binary. + Import the upstream k0s release binary for the build architecture. - Pinned to the latest stable release for x86_64. The release tag comes from - include/k0s.yml (%{k0s-upstream-tag}); only the SHA256 below is restated - here, taken from that release's sha256sums.txt asset. + The release tag comes from include/k0s.yml (%{k0s-upstream-tag}); only the + SHA256 of each architecture's binary is restated here, taken from that + release's sha256sums.txt asset. # %{k0s-upstream-tag} — the upstream release tag, URL-escaped. Single source # of truth for the k0s version axis; see include/k0s.yml. -(@): include/k0s.yml +(@): + - include/arch.yml + - include/k0s.yml build-depends: # Base runtime providing /bin/sh and install in the sandbox. @@ -23,13 +25,13 @@ sources: url: github:k0sproject/k0s/releases/download/%{k0s-upstream-tag}/k0s-%{k0s-upstream-tag}-amd64 ref: ca1e9e68107335846e8296777fce2ccd654284e6265b4b5d32c34ead872af98f +(?): + - arch == "aarch64": + sources: + - kind: remote + url: github:k0sproject/k0s/releases/download/%{k0s-upstream-tag}/k0s-%{k0s-upstream-tag}-arm64 + ref: 6301f64d98f9e4f6fbc2892bc66d137bb4ad5840685300772d8391614d47b8aa + config: install-commands: - - | - if [ "%{arch}" != "x86_64" ]; then - echo "ERROR: elements/k0s/k0s-bin.bst pins the upstream k0s amd64 binary;" >&2 - echo " arch=%{arch} has no pinned source. Add an arch-conditional" >&2 - echo " source before building k0s for %{arch}." >&2 - exit 1 - fi - - install -D -m 0755 k0s-%{k0s-upstream-tag}-amd64 "%{install-root}/usr/bin/k0s" + - install -D -m 0755 k0s-%{k0s-upstream-tag}-%{go-arch} "%{install-root}/usr/bin/k0s" diff --git a/elements/oci/k0s-sysext.bst b/elements/oci/k0s-sysext.bst index a8a57b5f..d04de3fc 100644 --- a/elements/oci/k0s-sysext.bst +++ b/elements/oci/k0s-sysext.bst @@ -40,11 +40,6 @@ config: install-commands: - | set -euo pipefail - if [ "%{arch}" != "x86_64" ]; then - echo "ERROR: elements/oci/k0s-sysext.bst only supports x86_64 (got %{arch})" >&2 - exit 1 - fi - mkdir -p sysext/usr/bin sysext/usr/lib/systemd/system cp -a /usr/bin/k0s sysext/usr/bin/k0s chmod 0755 sysext/usr/bin/k0s diff --git a/include/arch.yml b/include/arch.yml index 2a391b4c..da93f8a1 100644 --- a/include/arch.yml +++ b/include/arch.yml @@ -7,16 +7,21 @@ # # %{arch} BuildStream / uname -m x86_64 aarch64 # %{systemd-arch} systemd `ARCHITECTURE=` x86-64 arm64 +# %{go-arch} Go / Kubernetes downloads amd64 arm64 # # `options.arch.values` in project.conf constrains the axis to the two # architectures mapped below, so an unmapped architecture cannot be selected. # # Included by: -# elements/oci/k0s-sysext.bst -> %{systemd-arch} +# elements/oci/*-sysext.bst -> %{systemd-arch} # elements/bluefin-server/os-release.bst -> %{systemd-arch} +# elements/k0s/k0s-bin.bst -> %{go-arch} +# elements/kubeadm/kubeadm-bin.bst -> %{go-arch} variables: (?): - arch == "x86_64": systemd-arch: "x86-64" + go-arch: "amd64" - arch == "aarch64": systemd-arch: "arm64" + go-arch: "arm64" diff --git a/tests/unit/test_check_k0s_version.py b/tests/unit/test_check_k0s_version.py index dc99d558..bc87ec8a 100644 --- a/tests/unit/test_check_k0s_version.py +++ b/tests/unit/test_check_k0s_version.py @@ -255,6 +255,19 @@ def test_main_rejects_hardcoded_upstream_tag_in_url(checker): assert "hardcodes the upstream k0s release tag" in _run(checker) +def test_main_rejects_hardcoded_tag_in_another_architectures_url(checker): + checker.K0S_BIN.write_text( + GOOD_BIN + + "(?):\n" + " - arch == \"aarch64\":\n" + " sources:\n" + " - kind: remote\n" + " url: github:k0sproject/k0s/releases/download/v1.36.4%2Bk0s.0/k0s-arm64\n", + encoding="utf-8", + ) + assert "k0s-arm64" in _run(checker) + + # --- main(): sysext asset filename --------------------------------------- From dbdf3b7ae1f1c5bacf461cec37c96add869a3bef Mon Sep 17 00:00:00 2001 From: Jeffrey Sica Date: Tue, 29 Sep 2026 00:26:03 -0500 Subject: [PATCH 7/8] feat(kubeadm): pin the arm64 kubeadm worker payload for aarch64 builds arm64 kubelet, kubeadm, kubectl, crictl, containerd static, runc and CNI plugins, each sha256 taken from the checksum its project publishes next to the asset (the amd64 pins match theirs too). The x86_64 kubeadm sysext is unchanged. architecture-roadmap.md lists what still blocks an aarch64 image: no aarch64 FSDK artifacts in any cache, no CI build, and x86-only dogfood scripts. Assisted-by: Claude Opus 5.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/skills/architecture-roadmap.md | 2 +- docs/skills/kubeadm-sysext.md | 3 +- elements/kubeadm/kubeadm-bin.bst | 45 +++++++++++++++++++++++++---- 3 files changed, 42 insertions(+), 8 deletions(-) diff --git a/docs/skills/architecture-roadmap.md b/docs/skills/architecture-roadmap.md index 66ac9124..843e27d0 100644 --- a/docs/skills/architecture-roadmap.md +++ b/docs/skills/architecture-roadmap.md @@ -38,7 +38,7 @@ Priorities are derived from [gap-analysis-distros.md](gap-analysis-distros.md). | # | Item | Rationale / source gap | |---|------|------------------------| | 1 | TPM2-sealed /var on installed nodes | Credential sealing exists (`tpm2-credential-sealing.md`); persistent state is not yet bound to the TPM. | -| 2 | aarch64 build axis | `project.conf` and `include/arch.yml` already model it; no CI coverage yet. | +| 2 | aarch64 build axis | `project.conf`, `include/arch.yml` and the k0s/kubeadm arm64 binary pins resolve `-o arch aarch64`. Missing: aarch64 FSDK artifacts in any cache (a full bootstrap build), an aarch64 CI build, and an aarch64 dogfood path (`scripts/dogfood-*.sh` run `qemu-system-x86_64` with x64 OVMF). | | 3 | Booty merge and its Secure Boot shim story | The Bluefin HTTP-boot support works from [Booty](https://github.com/jeefy/booty) `feat/bluefin-http-boot`; it still needs to merge, and enrollment-free first boots need a shim-signed path. | | 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. | diff --git a/docs/skills/kubeadm-sysext.md b/docs/skills/kubeadm-sysext.md index af9615f3..9cac9d6b 100644 --- a/docs/skills/kubeadm-sysext.md +++ b/docs/skills/kubeadm-sysext.md @@ -122,7 +122,8 @@ what democratic-csi's `chroot /host ... iscsiadm` node plugin needs. ## Known gaps -- x86_64 only (amd64 release binaries). +- aarch64: the arm64 release binaries are pinned, but no aarch64 image has + been built or booted. ## Verify diff --git a/elements/kubeadm/kubeadm-bin.bst b/elements/kubeadm/kubeadm-bin.bst index 72320336..4f67aeb9 100644 --- a/elements/kubeadm/kubeadm-bin.bst +++ b/elements/kubeadm/kubeadm-bin.bst @@ -4,7 +4,8 @@ description: | sha256 (published alongside the release asset): kubelet, kubeadm and kubectl from dl.k8s.io, crictl (cri-tools), the containerd static build (containerd, containerd-shim-runc-v2, ctr), the runc static build, and - the full CNI reference plugin set. Versions come from include/kubeadm.yml. + the full CNI reference plugin set. Versions come from include/kubeadm.yml; + the amd64 or arm64 asset is picked by the build architecture. Layout: binaries in /usr/bin, CNI plugins in /usr/libexec/cni. Nothing goes under /opt: /opt/cni/bin stays a writable host directory that the @@ -14,6 +15,7 @@ description: | private location and ships exactly these files. (@): +- include/arch.yml - include/kubeadm.yml build-depends: @@ -57,20 +59,51 @@ sources: base-dir: '' directory: cni +(?): +- arch == "aarch64": + sources: + - kind: remote + url: k8s_dl:release/v%{kubernetes-version}/bin/linux/arm64/kubelet + ref: 765b740e3ad9c590852652a2623424ec60e2dddce2c6280d7f042f56c8c98619 + directory: k8s + - kind: remote + url: k8s_dl:release/v%{kubernetes-version}/bin/linux/arm64/kubeadm + ref: 697cf3aa54f1a5740b883a3b18a5d051b4032fd68ba89af626781a43ec9bccc3 + directory: k8s + - kind: remote + url: k8s_dl:release/v%{kubernetes-version}/bin/linux/arm64/kubectl + ref: 46913a7aa0327f6cc2e1cc2775d53c4a2af5e52f7fd8dacbfbfd098e757f19e9 + directory: k8s + - kind: tar + url: github:kubernetes-sigs/cri-tools/releases/download/v%{crictl-version}/crictl-v%{crictl-version}-linux-arm64.tar.gz + ref: c31d252e203df5f4cf37f314bd3092eb79087e791631c1e607087c74b6d0423f + base-dir: '' + directory: crictl + - kind: tar + url: github:containerd/containerd/releases/download/v%{containerd-version}/containerd-static-%{containerd-version}-linux-arm64.tar.gz + ref: d1a1e64c4334e17d6f9f40093d5ff9f810b95ac34c7dcba55e7d2226d2a8ab79 + base-dir: bin + directory: containerd + - kind: remote + url: github:opencontainers/runc/releases/download/v%{runc-version}/runc.arm64 + ref: 3c9a8e9e6dafd00db61f4611692447ebab4a56388bae4f82192aed67b66df712 + directory: runc + - kind: tar + url: github:containernetworking/plugins/releases/download/v%{cni-plugins-version}/cni-plugins-linux-arm64-v%{cni-plugins-version}.tgz + ref: 16484966a46b4692028ba32d16afd994e079dc2cc63fbc2191d7bfaf5e11f3dd + base-dir: '' + directory: cni + config: install-commands: - | set -eu - if [ "%{arch}" != "x86_64" ]; then - echo "ERROR: elements/kubeadm/kubeadm-bin.bst pins amd64 release binaries only (arch=%{arch})" >&2 - exit 1 - fi bin="%{install-root}%{bindir}" install -d "${bin}" for b in kubelet kubeadm kubectl; do install -m 0755 "k8s/${b}" "${bin}/"; done install -m 0755 crictl/crictl "${bin}/" for b in containerd containerd-shim-runc-v2 ctr; do install -m 0755 "containerd/${b}" "${bin}/"; done - install -m 0755 runc/runc.amd64 "${bin}/runc" + install -m 0755 "runc/runc.%{go-arch}" "${bin}/runc" install -d "%{install-root}%{libexecdir}/cni" find cni -maxdepth 1 -type f -perm -u+x -exec install -m 0755 -t "%{install-root}%{libexecdir}/cni" {} + for p in loopback bridge host-local portmap; do From 927b90dabe8327beddafcb30b89f2e242626d378 Mon Sep 17 00:00:00 2001 From: Jeffrey Sica Date: Tue, 29 Sep 2026 00:46:19 -0500 Subject: [PATCH 8/8] fix(sysext): derive the erofs UUID from the image name mkfs.erofs gave every build a random filesystem UUID, the only difference between two builds of the same sysext: file contents, modes and mtimes already match because BuildStream exports SOURCE_DATE_EPOCH and mkfs.erofs clamps to it. With the UUID derived from sysext-image, two builds of each sysext with the artifacts deleted in between (and remote caches ignored) produce byte-identical .raw, .raw.zst and SHA256SUMS. Assisted-by: Claude Opus 5.5 via GitHub Copilot Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- include/sysext.yml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/include/sysext.yml b/include/sysext.yml index e8c0afff..2a98b35c 100644 --- a/include/sysext.yml +++ b/include/sysext.yml @@ -29,7 +29,10 @@ variables: fi out="%{install-root}/%{sysext-image}.raw" + # mkfs.erofs would pick a random filesystem UUID; derive it from the image + # name instead so a rebuild of the same image is byte-identical. + h="$(printf '%s' '%{sysext-image}' | sha256sum)" mkdir -p "%{install-root}" - mkfs.erofs -d0 "${out}" sysext + mkfs.erofs -d0 -U "${h:0:8}-${h:8:4}-${h:12:4}-${h:16:4}-${h:20:12}" "${out}" sysext zstd -T0 -19 -q "${out}" -o "${out}.zst" (cd "%{install-root}" && sha256sum --binary "%{sysext-image}.raw.zst" > SHA256SUMS)