Skip to content

docs: accuracy pass after the FSDK rebase - #276

Merged
castrojo merged 5 commits into
projectbluefin:mainfrom
jeefy:docs/accuracy-pass
Sep 29, 2026
Merged

castrojo merged 5 commits into
projectbluefin:mainfrom
jeefy:docs/accuracy-pass

Conversation

@jeefy

@jeefy jeefy commented Sep 29, 2026

Copy link
Copy Markdown
Collaborator

Summary

Docs accuracy pass after the FSDK rebase (#262). Fixes stale Flatcar narrative in shipped comments, corrects the FSDK patch count, removes an unused Justfile alias, adds two missing skills, and stages the system-container helper that was documented but never shipped.

Commits

Items done

  1. Stale Flatcar narrative — updated os-resolv-conf.bst, 20-bluefin-resolv.conf, bluefin-firstboot-credentials, and two test files to explain the FSDK 26.08 reality:

    • /etc/resolv.conf: FSDK ships no rule (upstream systemd leaves it to the distro), /etc is empty on boot, so the tmpfiles.d rule is still needed for kubelet.
    • bluefin-firstboot-credentials: the helper exists because Bluefin applies firstboot.hostname unconditionally and sets the live kernel hostname, not because systemd-firstboot is missing.
    • os-creds-prov.bst is owned by fix(security): ship root locked; provision access per node #275 and already fixed there; skipped.
  2. bump-fsdk-version.md patch count — corrected from "one patch remains" to six patches, with a warning that 0006 carries the Cilium/Kubernetes kernel options and must not be dropped.

  3. Justfile build alias — deleted. No doc, CI workflow, or script calls bare just build.

  4. New skills — created docs/skills/booty-integration.md and docs/skills/secure-boot-keys.md. Index rows deferred until feat(initrd): explain diskless boot failures and ignored Ignition kargs #273 merges (it owns docs/skills/index.md).

  5. Issue [architect] files/bin/system-container is unreachable payload: documented as /usr/bin/system-container but staged by no element #154 — staged files/bin/system-container in the base image via new os-system-container.bst. machinectl and systemd-nspawn ship in the base image via FSDK's systemd component, so dependencies are present. Removed the KNOWN_UNSTAGED waiver.

Items deferred (blocked by open PRs)

Item Blocking PR Intended edit
3. ci-tooling.md stale taiki-e SHA #269, #270, #272 Update the pinned SHA to match workflows (4cef1412...)
4. dangling signing-and-sbom ref #269 Already fixed in #269's diff; drop
5. tpm2 core user ref #275 Already fixed in #275's diff; drop
6. factory-integration podman sysext claim #275 Remove the claim that podman ships as an optional sysext; containerd ships only in the kubeadm sysext
8. Dedupe duplicated facts #269, #270, #271, #272, #273, #275 Canonicalize the sysupdate-signing/import-pubring key-pair description and the "release publishes dist/diskless as v + ORAS" fact to single sources
9. gap-analysis source list trim #271 Trim §6 source list to distro → docs-root links
10a. usb-installer skill #271, #273 Extract USB installer content from ddi-installer.md ~131-160 into docs/skills/usb-installer.md
12. README download section #269, #271 Add a short "Download a release" section before the build quick start

Follow-up after #273 merges

Add rows to docs/skills/index.md for:

  • booty-integration.md
  • secure-boot-keys.md
  • usb-installer.md (after extraction from ddi-installer.md)

Verification

  • python3 .github/scripts/docs-checks.py passes
  • pytest tests/unit/ passes (372 passed)
  • bats tests/unit/ passes
  • No internal-only hostnames or proprietary names added
  • No TODO/FIXME markers added

jeefy and others added 5 commits September 29, 2026 00:10
The OS payload is now pure FSDK 26.08 (systemd v261). Update comments in
shipped elements, scripts, and tests to remove Flatcar references and
explain why each workaround still exists:

- /etc/resolv.conf: FSDK ships no rule (upstream systemd leaves the
  symlink to the distro), and /etc is empty on every boot, so the
  tmpfiles.d rule is still required for kubelet pod sandboxes.
- firstboot credentials: the helper exists because Bluefin applies
  firstboot.hostname unconditionally and sets the live kernel hostname,
  which systemd-firstboot does not do; it is not because systemd-firstboot
  is missing from the image.

Assisted-by: Claude Opus 5.5 via GitHub Copilot
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
patches/freedesktop-sdk/ carries six patches (0001-0006), not one.
0006 adds the Cilium/Kubernetes kernel options (VXLAN, GENEVE, tc BPF,
conntrack/ss diagnostics); dropping it breaks the kubeadm and k0s
sysexts. Update the verification checklist and the notes so a bumper
does not drop it.

Assisted-by: Claude Opus 5.5 via GitHub Copilot
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The build recipe was a forwarding alias to export-image. No doc, CI
workflow, or script calls bare 'just build'. Remove it to match the
avoid-over-engineering skill's rule against forwarding aliases.

Assisted-by: Claude Opus 5.5 via GitHub Copilot
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
booty-integration.md: how Booty serves releases (HTTP Boot, iPXE
chainload, per-node bluefin-node.ign, doInstall, kubeadm workers).

secure-boot-keys.md: what each key signs (PK/KEK/DB, module cert,
sysupdate signing), where keys live, how CI gets them via
BOOT_KEYS_TARBALL and SYSUPDATE_SIGNING_KEY, and rotation mechanics.

Index rows are deferred until projectbluefin#273 merges (it owns docs/skills/index.md).

Assisted-by: Claude Opus 5.5 via GitHub Copilot
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
files/bin/system-container was documented as shipped at
/usr/bin/system-container but no element staged it. Add
os-system-container.bst to install it into /usr/bin and wire it into
os-stack.bst. Remove the KNOWN_UNSTAGED waiver.

machinectl and systemd-nspawn ship in the base image via FSDK's
systemd component, so the helper's dependencies are present.

Closes projectbluefin#154

Assisted-by: Claude Opus 5.5 via GitHub Copilot
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

@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.

Substantive review: verified accurate documentation updates reflecting FSDK 26.08 OS architecture, cleaned up obsolete Justfile aliases, added missing documentation skills (booty-integration, secure-boot-keys), and resolved issue #154 by properly staging the system-container helper in os-stack.bst. All docs checks and full unit test suite pass.

@castrojo
castrojo merged commit 32db0ec into projectbluefin:main Sep 29, 2026
5 checks passed
jeefy added a commit that referenced this pull request Sep 29, 2026
* docs(ci-tooling): stop pinning a literal install-action SHA in the examples

The documented taiki-e/install-action SHA went stale the next time the
workflows repinned. Show the pin format with a placeholder and point at
build.yml for the current value, which the prose already told readers to
check.

Deferred from #276.

Assisted-by: Claude Opus 5.5 via GitHub Copilot
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* docs(factory-integration): drop the podman-as-sysext claim

No podman sysext exists or is planned; the only container runtime we ship
is containerd, inside the opt-in kubeadm sysext. Say that instead of
implying podman (and other runtimes) ship as optional sysexts.

Deferred from #276.

Assisted-by: Claude Opus 5.5 via GitHub Copilot
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* docs: one canonical source for the signing keys and the release publish

Hard rule 6. The sysupdate-signing.asc / import-pubring.pgp pair, the
gen-dev-keys behaviour, and the CI secrets were restated in
ddi-installer-build.md, and the release-publishes-as-is fact was restated
in both build and architecture skills. Keep the key inventory and
gen-dev-keys in secure-boot-keys.md, the release-signing key in
systemd-sysupdate-verification.md, and the publish contract in the
ci-tooling.md release job; the build skill keeps only the
rotation-needs-a-new-image-version rationale and points at the rest.

Deferred from #276.

Assisted-by: Claude Opus 5.5 via GitHub Copilot
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* docs(gap-analysis-distros): trim the sources list to docs roots

Section 2 already links every specific claim inline; section 6 restated
the same URLs. Keep one link per distro documentation root.

Deferred from #276.

Assisted-by: Claude Opus 5.5 via GitHub Copilot
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* docs: extract the offline USB installer into its own skill

The installer section from #264/#268/#277 lived inside ddi-installer.md.
Move it to docs/skills/usb-installer.md covering the image layout and
boot flow, unattended installs through the
systemd.unit-dropin.systemd-sysinstall.service credential, the firstboot
root-password prompt drop-in, and provisioning the installed disk from
its ESP; ddi-installer.md keeps a one-line pointer and a short artifact
table row. ddi-installer.md's key and release paragraphs also collapse
to pointers (the dedupe from the previous commit).

Deferred from #276.

Assisted-by: Claude Opus 5.5 via GitHub Copilot
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* docs: route booty-integration, secure-boot-keys and usb-installer

All three skill files existed (or were just added) without a row in the
lazy-load routing table. List them in docs/skills/index.md and in the
AGENTS.md skill routing table.

Deferred from #276.

Assisted-by: Claude Opus 5.5 via GitHub Copilot
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* docs(readme): add a Download a release section

Point evaluators at the published artifacts before the build-oriented
quick start: the GitHub Release and OCI artifact, which file covers a
diskless USB boot versus an offline install versus Booty network boot,
and where the verification steps live.

Deferred from #276.

Assisted-by: Claude Opus 5.5 via GitHub Copilot
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[architect] files/bin/system-container is unreachable payload: documented as /usr/bin/system-container but staged by no element

2 participants