Skip to content

[architect] refactor: single source of truth for CPU-arch identity — new include/arch.yml, k3s-bin.bst, k3s-sysext.bst, os-release-flatcar.bst, extension-release.k3s - #40

Merged
castrojo merged 1 commit into
mainfrom
arch/refactor-arch-identity-single-source
Sep 5, 2026
Merged

castrojo merged 1 commit into
mainfrom
arch/refactor-arch-identity-single-source

Conversation

@hivecommons-hive

Copy link
Copy Markdown
Contributor

Claimed cluster

Exact ground this PR occupies, for the next occupied-ground comparison:

  • New file: include/arch.yml
  • elements/k3s/k3s-bin.bst — config.install-commands (adds a guard command; the existing install line is unchanged)
  • elements/oci/k3s-sysext.bst — the top-level (@) include and the extension-release.d staging lines inside install-commands
  • elements/bluefin-server/os-release-flatcar.bst — the top-level (@) include and the FLATCAR_BOARD= line
  • files/k3s/sysext/extension-release.k3s — removes the ARCHITECTURE= line

Does not touch project.conf, Justfile, .pre-commit-config.yaml, AGENTS.md, .github/, docs/, tests/, elements/installer/, elements/oci/bluefin-server-installer.bst, elements/oci/bluefin-server-ddi.bst, elements/bluefin-server/os-stack.bst, elements/bluefin-server/os-sshd-config.bst, files/os/, or files/k3s/sysext/{k3s.service,k3s-agent.service,50-bluefin-tuning.yaml,k3s-bluefin.conf}.

Disjoint from every open PR on this repo: #34 (project.conf release-version / Justfile validate / .pre-commit-config.yaml), #36 (os-stack.bst + sysupdate keyring + docs), #37 (files/os/justfile), #38 and #30 (tests/), #29 (sshd), #22/#25/#26/#27 (installer + PXE elements and docs), #18 and #21 (workflow/deps). No file in this PR appears in any of them.

Fixes the arch-identity axis only. It deliberately does not touch the release-version axis (#31/#34) or the sysext-versioning question in #32.

Refactor

project.conf declares a real, selectable build axis and binds it to a variable:

options:
  arch:
    type: arch
    variable: arch
    values: [aarch64, x86_64]
sandbox:
  build-arch: "%{arch}"

elements/freedesktop-sdk.bst honours it with an explicit arch == 'aarch64' branch, so the axis is not vestigial. Three downstream sites then restated the architecture as an unguarded x86_64 literal in three different vendor spellings, with nothing comparing them to %{arch}:

Site Literal Consumer
elements/k3s/k3s-bin.bst sources[0].url the upstream amd64 k3s asset (SHA from sha256sum-amd64.txt, per the element's own docstring) installed unconditionally at /usr/bin/k3s
files/k3s/sysext/extension-release.k3s ARCHITECTURE=x86-64 copied byte-for-byte into /usr/lib/extension-release.d/
elements/bluefin-server/os-release-flatcar.bst FLATCAR_BOARD="amd64-usr" written into /usr/lib/os-release

Failure mode this closes

bst build -o arch aarch64 oci/k3s-sysext.bst succeeds today. There is no error surface on the arch axis anywhere in the graph: an x86-64 k3s ELF lands in an aarch64 rootfs, the sysext advertises ARCHITECTURE=x86-64 so systemd-sysext silently refuses to merge it (k3s never appears, on a green build), and /usr/lib/os-release advertises FLATCAR_BOARD=amd64-usr, which is the key third-party Flatcar extension matching uses. Quiet in exactly the way the release-version drift in #31 was quiet.

Changes

  1. include/arch.yml — the one place the vendor spellings of the arch axis are written: %{systemd-arch} (x86-64 / arm64) and %{flatcar-board} (amd64-usr / arm64-usr), selected with a (?) conditional on arch, using the same shape as the existing conditional in elements/freedesktop-sdk.bst. Because project.conf constrains options.arch.values to those two architectures, an unmapped architecture cannot be selected.
  2. elements/oci/k3s-sysext.bst includes it and appends ARCHITECTURE=%{systemd-arch} to the staged extension-release file.
  3. files/k3s/sysext/extension-release.k3s drops its ARCHITECTURE= line, so that field now has exactly one producer instead of two.
  4. elements/bluefin-server/os-release-flatcar.bst includes it and emits FLATCAR_BOARD="%{flatcar-board}".
  5. elements/k3s/k3s-bin.bst asserts %{arch} == x86_64 before installing, so the amd64-only pin is an explicit, loud constraint. Adding the k3s-arm64 source is a separate, deliberate change and is not made here — this PR does not enable aarch64, it stops aarch64 from silently mis-building.

This is the repo's own red flag from docs/skills/avoid-over-engineering.md — "The same value hardcoded in more than one file" — applied to the arch axis rather than the version axis.

No behavior change on the supported path

With arch == x86_64 the generated values are byte-identical to the literals they replace:

  • ARCHITECTURE=x86-64 — same line, same position (appended after VERSION_ID, which was already its position in the static file)
  • FLATCAR_BOARD="amd64-usr" — same line
  • install -D -m 0755 k3s ... — unchanged, now preceded by a guard that is a no-op on x86_64

Release asset names, the DDI/UKI/installer graph, and files/os/sysupdate.d/*.transfer are untouched.

Verification

All five files parse as YAML, and the (?) structure matches the shape BuildStream already consumes in elements/freedesktop-sdk.bst:

OK include/arch.yml
OK elements/oci/k3s-sysext.bst
OK elements/bluefin-server/os-release-flatcar.bst
OK elements/k3s/k3s-bin.bst
OK project.conf

{'variables': {'(?)': [{'arch == "x86_64"':  {'systemd-arch': 'x86-64', 'flatcar-board': 'amd64-usr'}},
                       {'arch == "aarch64"': {'systemd-arch': 'arm64',  'flatcar-board': 'arm64-usr'}}]}}

Reviewer note — just validate was not run. This session has no podman and no bst, so the bst show --deps all graph check could not be executed. A maintainer should run just validate before merging; the specific thing to confirm is that BuildStream composes the element-level (@): include/arch.yml fragment's variables block with each element's own variables block (strip-binaries: "" in both consumers) rather than replacing it.

Follow-up deliberately not bundled

The release assets (k3s-<ver>.raw.zst, the DDI, the UKI, the installer) carry no arch component in their filenames, and files/os/sysupdate.d/70-k3s.transfer fetches by that name from releases/latest/download/. Once a second architecture is actually built, two arch builds of the same release produce identically named assets and one would overwrite the other in the fleet's update path. Arch-qualifying the asset names is a release-contract change that also moves the MatchPatterns in files/os/sysupdate.d/, overlaps the ground of #34, and should be tracked on its own.

Refs #39


Filed by architect agent (ACMM L5 — hold-gated mode). Hold-gated: human review required. Structural only — no behavior change on the x86_64 path; do not merge without a maintainer just validate run.

— hive: agent=architect backend=copilot model=claude-opus-5

project.conf declares options.arch (aarch64, x86_64) and binds it to
%{arch}, and elements/freedesktop-sdk.bst resolves against it. Three
downstream sites then restated the architecture as an unguarded x86_64
literal in three different vendor spellings, with nothing comparing them
to %{arch}:

  - elements/k3s/k3s-bin.bst pinned the upstream amd64 k3s asset and
    installed it unconditionally.
  - files/k3s/sysext/extension-release.k3s hardcoded ARCHITECTURE=x86-64,
    copied verbatim by elements/oci/k3s-sysext.bst.
  - elements/bluefin-server/os-release-flatcar.bst hardcoded
    FLATCAR_BOARD=amd64-usr.

An aarch64 build therefore succeeded and produced an image carrying
x86_64 identity and an x86-64 k3s ELF, with no error surface anywhere.

Add include/arch.yml as the one place the vendor spellings are written
(%{systemd-arch}, %{flatcar-board}), keyed off the arch option; have the
two consuming elements include it and emit those variables instead of
literals; and make k3s-bin.bst assert its amd64-only pin explicitly so
the constraint is loud rather than silent.

No behavior change on the x86_64 path: the generated values are byte-
identical to the literals they replace.

Refs #39

Signed-off-by: architect <architect@users.noreply.github.com>
@hivecommons-hive hivecommons-hive Bot added the hold Indicates that a PR should not merge because someone has issued a /hold command. label Aug 29, 2026

@hanthor hanthor left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verified project.conf's options.arch and elements/freedesktop-sdk.bst's existing (?) conditional shape match the new include/arch.yml pattern; no behavior change on the x86_64 path confirmed line-by-line. CI green.


Generated by Claude Code

@castrojo castrojo left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved by @castrojo for Hive auto-merge on green CI.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

hold Indicates that a PR should not merge because someone has issued a /hold command.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants