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
1 change: 1 addition & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,7 @@ All local `just` targets run BuildStream inside the FSDK `bst2` container via `j
| Work with `systemd-sysext` / `systemd-confext` | [`docs/skills/systemd-sysext-extensions.md`](docs/skills/systemd-sysext-extensions.md) |
| Build or ship the k0s sysext | [`docs/skills/k0s-sysext.md`](docs/skills/k0s-sysext.md), [`docs/skills/k0s-sysext-ops.md`](docs/skills/k0s-sysext-ops.md) |
| Update the FSDK pin / versioning | [`docs/skills/bump-fsdk-version.md`](docs/skills/bump-fsdk-version.md) |
| Flatcar version parity matrix / audit | [`docs/skills/flatcar-parity-matrix.md`](docs/skills/flatcar-parity-matrix.md) |
| CI workflows, action SHA pinning | [`docs/skills/ci-tooling.md`](docs/skills/ci-tooling.md) |
| Release signing / sysupdate trust | [`docs/skills/systemd-sysupdate-verification.md`](docs/skills/systemd-sysupdate-verification.md) |
| Credential sealing with TPM2 | [`docs/skills/tpm2-credential-sealing.md`](docs/skills/tpm2-credential-sealing.md) |
Expand Down
83 changes: 83 additions & 0 deletions docs/skills/flatcar-parity-matrix.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
---
name: flatcar-parity-matrix
description: |
Flatcar-to-FSDK version parity matrix for Bluefin Server (issue #142). Tracks component
versions, gaps, element paths, and substitution order against Flatcar 4593.2.5.
metadata:
type: reference
status: stable
last_updated: "2026-09-18"
---
# Flatcar-to-FSDK Parity Matrix

**Flatcar 4593.2.5 vs freedesktop-sdk 26.08 — version audit (design phase 2, issue #142).** Generated by `scripts/generate-parity-matrix.py` from pinned upstream release artifacts; do not edit by hand — re-run the generator.

| Component | Flatcar version | FSDK 26.08 version | Gap | Element path | Ordering |
|---|---|---|---|---|---|
| glibc | 2.41-r6 | 2.44-23 | fsdk-newer | `bootstrap/glibc.bst` | load-bearing |
| kernel | 4593.2.5 (6.12.102-flatcar) | n/a | n/a | `flatcar/flatcar-kernel.bst` | load-bearing |
| systemd | 257.9 | 261.2 | fsdk-newer | `components/systemd.bst` | load-bearing |
| bash | 5.3_p3-r3 | 5.3-16 | none | `bootstrap/bash.bst` | important |
| coreutils | 9.8-r1 | 9.11 | fsdk-newer | `bootstrap/coreutils.bst` | important |
| curl | 8.16.0-r1 | 8.21.0 | fsdk-newer | `components/curl.bst` | important |
| dbus | 1.16.2 | 1.16.2 | none | `components/dbus.bst` | important |
| glib | 2.84.4 | 2.88.3 | fsdk-newer | `components/glib.bst` | important |
| gnupg | 2.5.16 | 2.4.9 | flatcar-newer | `components/gnupg.bst` | important |
| kmod | 34.2 | 34.2 | none | `components/kmod.bst` | important |
| libcap | 2.76 | 2.78 | fsdk-newer | `components/libcap.bst` | important |
| libffi | 3.5.2 | 3.8.0 | fsdk-newer | `components/libffi.bst` | important |
| openssh | 10.4_p1-r1 | 10.5.P1 | fsdk-newer | `components/openssh.bst` | important |
| openssl | 3.5.5 | 3.5.8 | fsdk-newer | `components/openssl.bst` | important |
| shadow | 4.14.8-r1 | 4.20.2 | fsdk-newer | `components/shadow.bst` | important |
| util-linux | 2.41.2 | 2.42.2 | fsdk-newer | `components/util-linux.bst` | important |
| zstd | 1.5.7-r1 | 1.5.7 | none | `components/zstd.bst` | important |
| ca-certificates | 3.126 | 2010.63-3.fc14-175 | different-scheme | `components/ca-certificates.bst` | deferred |
| podman | 5.5.2 | 6.1.0 | fsdk-newer | `components/podman.bst` | deferred |
| xfsprogs | 6.16.0 | 7.1.1 | fsdk-newer | `components/xfsprogs.bst` | deferred |

## Gap Definitions

- `none` — FSDK already pins Flatcar's upstream version; no substitution required.
- `fsdk-newer` — FSDK pins a newer upstream release than Flatcar; substitute by pinning or backporting the Flatcar version in FSDK elements.
- `flatcar-newer` — Flatcar pins a newer upstream release than FSDK.
- `different-scheme` — Component version strings follow different packaging schemes and cannot be ordered numerically (e.g. Mozilla NSS certdata vs Fedora RPM).
- `n/a` — FSDK does not provide this component; imported whole as a reference.

## Ordering Guidance

- **load-bearing** — Boot-critical components (glibc, kernel, systemd). Must be substituted first because all subsequent layers depend on them.
- **important** — Base userspace runtime and installer dependencies (bash, coreutils, curl, dbus, glib, gnupg, kmod, libcap, libffi, openssh, openssl, shadow, util-linux, zstd).
- **deferred** — Optional payloads, sysext extensions, or filesystem utilities (ca-certificates, podman, xfsprogs).

## Source Citations

- Flatcar release 4593.2.5 artifacts fetched from `https://flatcar.cdn.cncf.io/stable/amd64-usr/4593.2.5/` with SHA256 checksums pinned in `scripts/generate-parity-matrix.py`:
- `version.txt` (`6e86c457...`): release identifier and build ID.
- `flatcar_production_image_packages.txt` (`58a43787...`): installed Portage atoms and versions.
- `flatcar-podman_packages.txt` (`befde0ac...`): container runtime sysext packages.
- FSDK 26.08 source elements: pinned junction ref `freedesktop-sdk-26.08.0` in `elements/freedesktop-sdk.bst`.

## Downstream Substitution Tickets

The following substitution tickets are derived directly from the matrix ordering:

1. **Load-bearing (phase 6a)**
- `subst(kernel)`: reference import `flatcar/flatcar-kernel.bst` (6.12.102-flatcar)
- `subst(glibc)`: pin glibc 2.41 in `bootstrap/glibc.bst`
- `subst(systemd)`: pin systemd 257 in `components/systemd.bst`
2. **Important base userspace (phase 6b)**
- `subst(coreutils)`: pin coreutils 9.8 in `bootstrap/coreutils.bst`
- `subst(curl)`: pin curl 8.16.0 in `components/curl.bst`
- `subst(glib)`: pin glib 2.84.4 in `components/glib.bst`
- `subst(gnupg)`: pin gnupg 2.5.16 in `components/gnupg.bst`
- `subst(libcap)`: pin libcap 2.76 in `components/libcap.bst`
- `subst(libffi)`: pin libffi 3.5.2 in `components/libffi.bst`
- `subst(openssh)`: pin openssh 10.4 in `components/openssh.bst`
- `subst(openssl)`: pin openssl 3.5.5 in `components/openssl.bst`
- `subst(shadow)`: pin shadow 4.14.8 in `components/shadow.bst`
- `subst(util-linux)`: pin util-linux 2.41.2 in `components/util-linux.bst`
- Version matches (verification only): `bash` (5.3), `dbus` (1.16.2), `kmod` (34.2), `zstd` (1.5.7)
3. **Deferred (phase 6c)**
- `subst(ca-certificates)`: evaluate NSS certdata 3.126 vs Fedora packaging
- `subst(podman)`: delivery via sysext matching Flatcar podman 5.5.2
- `subst(xfsprogs)`: pin xfsprogs 6.16.0 in `components/xfsprogs.bst`
1 change: 1 addition & 0 deletions docs/skills/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ This is the lazy-load routing table for agent skills. Keep this file in memory w
| [`ddi-installer-build.md`](ddi-installer-build.md) | Building the installer or DDI on the cluster | Cluster build pipeline and local installer/DDI build. |
| [`ddi-installer.md`](ddi-installer.md) | Installer boot flow, `systemd-sysinstall`, `systemd-repart` | High-level DDI install architecture and local smoke test. |
| [`factory-integration.md`](factory-integration.md) | Lab integration, boot-test workflow, factory role | How Bluefin Server is consumed by the CI lab. |
| [`flatcar-parity-matrix.md`](flatcar-parity-matrix.md) | Flatcar version audit, component parity, substitution order | Version parity matrix and gap audit against Flatcar 4593.2.5. |
| [`gap-analysis-distros.md`](gap-analysis-distros.md) | Comparing Bluefin Server to other server OSes | Source-verified comparison to Ubuntu, Talos, Flatcar, FCOS. |
| [`k0s-sysext-ops.md`](k0s-sysext-ops.md) | Operating k0s on Bluefin Server | Runtime operation and reboot coordination for k0s. |
| [`k0s-sysext.md`](k0s-sysext.md) | Building the k0s sysext | BuildStream element and publish steps for the k0s sysext. |
Expand Down
Loading
Loading