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
593 changes: 593 additions & 0 deletions .github/scripts/track-binaries.py

Large diffs are not rendered by default.

145 changes: 145 additions & 0 deletions .github/workflows/track-binaries.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,145 @@
name: Track upstream binaries

# Proposes patch releases of the upstream binaries pinned by version and
# sha256 (the kubeadm sysext payload, k0s, ORAS): one pull request per
# component, on its own auto/track-binaries/<component> branch. What is
# tracked, how each sha256 is verified, and why this is not a Renovate rule:
# .github/scripts/track-binaries.py.
#
# Same shape as track-junctions.yml: schedule and manual dispatch only, never
# pull_request, and pull requests opened with the mergeraptor app token so
# that they get CI.
on:
schedule:
# After track-junctions (08:00 UTC).
- cron: '30 8 * * *'
workflow_dispatch:

permissions:
contents: read

concurrency:
group: track-binaries
cancel-in-progress: false

jobs:
check:
runs-on: ubuntu-26.04
timeout-minutes: 10
outputs:
updates: ${{ steps.check.outputs.updates }}
steps:
- name: Checkout repository
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: main
persist-credentials: false

- name: Find newer patch releases
id: check
env:
# Read-only; only raises the API rate limit for the release listings.
GITHUB_TOKEN: ${{ github.token }}
run: |
set -euo pipefail
# A component whose upstream cannot be read fails this job, but only
# after the other components' updates are recorded: one outage must
# neither pass as "nothing to track" nor hold back the rest.
status=0
python3 .github/scripts/track-binaries.py check --json > "$RUNNER_TEMP/updates.json" || status=$?
echo "updates=$(cat "$RUNNER_TEMP/updates.json")" >> "$GITHUB_OUTPUT"
exit "$status"

propose:
needs: check
if: ${{ !cancelled() && needs.check.outputs.updates != '' && needs.check.outputs.updates != '[]' }}
runs-on: ubuntu-26.04
timeout-minutes: 20
strategy:
fail-fast: false
matrix:
include: ${{ fromJSON(needs.check.outputs.updates) }}
steps:
# GITHUB_TOKEN stays read-only. The push and the pull request use the
# mergeraptor app token (pushes made with GITHUB_TOKEN never trigger CI),
# narrowed to what this job does.
- name: Get mergeraptor token
id: app-token
uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3
with:
app-id: ${{ secrets.MERGERAPTOR_APP_ID }}
private-key: ${{ secrets.MERGERAPTOR_PRIVATE_KEY }}
permission-contents: write
permission-pull-requests: write
# The ORAS pins live in .github/workflows/build.yml, and pushing a
# change to a workflow file needs the Workflows permission. An empty
# value requests nothing.
permission-workflows: ${{ matrix.component == 'oras' && 'write' || '' }}

- name: Checkout repository
uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: main
fetch-depth: 0
token: ${{ steps.app-token.outputs.token }}

- name: Apply the release and verify its checksums
env:
COMPONENT: ${{ matrix.component }}
VERSION: ${{ matrix.latest }}
run: |
set -euo pipefail
python3 .github/scripts/track-binaries.py apply "$COMPONENT" --version "$VERSION" \
--summary "$RUNNER_TEMP/pr-body.md" > "$RUNNER_TEMP/files.txt"

- name: Create or update the pull request
env:
GH_TOKEN: ${{ steps.app-token.outputs.token }}
COMPONENT: ${{ matrix.component }}
FROM: ${{ matrix.current }}
TO: ${{ matrix.latest }}
RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
run: |
set -euo pipefail
branch="auto/track-binaries/${COMPONENT}"
title="chore(deps): update ${COMPONENT} ${FROM} -> ${TO}"
if [ ! -s "$RUNNER_TEMP/files.txt" ]; then
echo "${COMPONENT} needs no change."
exit 0
fi

# One pull request per component. An open one with this exact title
# already proposes this release, so leave it and its CI run alone. A
# closed one with this title was turned down (or reverted); do not
# reopen it every day, the next release brings a new title. No
# pipes into grep and no `|| true`: a failed query must stop here,
# not pass for "no pull request".
open=$(gh pr list --head "$branch" --base main --state open --json number,title --jq '.[0] | select(.) | "\(.number)\t\(.title)"')
number="${open%%$'\t'*}"
if [ -n "$open" ] && [ "${open#*$'\t'}" = "$title" ]; then
echo "#${number} already proposes ${COMPONENT} ${TO}."
exit 0
fi
closed=$(gh pr list --head "$branch" --base main --state closed --json title --jq '.[].title')
if [ -z "$open" ] && grep -Fxq -- "$title" <<< "$closed"; then
echo "A closed pull request already proposed '${title}'; not reopening it."
exit 0
fi

# No attribution trailers, as in track-junctions.yml: this commit is
# the deterministic output of track-binaries.py.
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git checkout -B "$branch"
mapfile -t files < "$RUNNER_TEMP/files.txt"
git add -- "${files[@]}"
git commit -m "$title"
git push --force-with-lease origin "$branch"

printf '\n---\n*Generated by [Track upstream binaries](%s)*\n' "$RUN_URL" >> "$RUNNER_TEMP/pr-body.md"
if [ -n "$open" ]; then
gh pr edit "$number" --title "$title" --body-file "$RUNNER_TEMP/pr-body.md"
echo "Updated PR: $(gh pr view "$number" --json url --jq '.url')"
else
echo "Created PR: $(gh pr create --base main --head "$branch" --title "$title" --body-file "$RUNNER_TEMP/pr-body.md")"
fi
3 changes: 2 additions & 1 deletion docs/skills/ci-tooling.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ description: CI workflow conventions for Bluefin Server. Use when writing or edi
metadata:
type: reference
status: stable
last_updated: "2026-09-27"
last_updated: "2026-09-28"
context7-sources:
- /websites/github_en_actions
- /websites/cli_github_manual
Expand Down Expand Up @@ -121,6 +121,7 @@ sudo_cmd := if `podman info >/dev/null 2>&1 && echo 1 || echo 0` == "1" { "" } e
| `release` | `build.yml` | `push/main`, `workflow_dispatch` | Publishes `dist/diskless/` as-is: an immutable GitHub Release tagged `v<image-version>` plus an ORAS OCI artifact at `ghcr.io/<owner>/bluefin-server:<ver>,latest` (one layer per file, artifact type `application/vnd.projectbluefin.server.release.v1`) (`if: ${{ !failure() && !cancelled() && github.ref == 'refs/heads/main' }}`). `contents: write` + `packages: write`. |
| `docs` | `docs-checks.yml` | `pull_request`, `push/main` | Runs markdown and skill metadata checks via `docs-checks.py`. Read-only token. |
| `unit` | `unit-tests.yml` | `pull_request`, `push/main` | Runs pytest and BATS unit test suites. Read-only token. |
| `check`, `propose` | `track-binaries.yml` | `schedule` (08:30 UTC), `workflow_dispatch` | `check` finds the newest patch release in each pinned series of the upstream binaries pinned by version + sha256 (Kubernetes, cri-tools, containerd, runc, CNI plugins, k0s, ORAS) with `.github/scripts/track-binaries.py`; `propose` moves each version together with its sha256 pins, verified against upstream's checksum files and the downloaded assets, and opens or updates one PR per component on `auto/track-binaries/<component>`. Minor bumps stay manual (`kubeadm-sysext.md`, `k0s-sysext.md`). Read-only `GITHUB_TOKEN`; writes use the mergeraptor app token narrowed to `contents` + `pull-requests` (+ `workflows` for ORAS, pinned in `build.yml`). Never on `pull_request`. |

GitHub Actions runs the **complete BuildStream compilation pipeline** using `/mnt`
SSD storage on the runner for podman and BuildStream caches. Release assets are
Expand Down
3 changes: 2 additions & 1 deletion docs/skills/k0s-sysext.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ description: Build and ship the k0s systemd-sysext for Bluefin Server. KubeStell
metadata:
type: how-to
status: stable
last_updated: "2026-09-27"
last_updated: "2026-09-28"
context7-sources:
- /systemd/systemd
---
Expand Down Expand Up @@ -85,6 +85,7 @@ Design choices:
| `Justfile` | `build-sysext` / `export-sysext` targets. |
| `.github/workflows/build.yml` | Builds, signs, and publishes sysext assets. |
| `.github/scripts/check-k0s-version.py` | Fails closed if any consumer restates the k0s version instead of deriving it. |
| `.github/scripts/track-binaries.py` | Moves both atoms and the SHA256 together: `track-binaries.yml` proposes patch releases of the pinned minor, `apply k0s --version X.Y.Z+k0s.N` makes a minor bump by hand (then move the series in `tests/unit/test_k0s_version.py`). |

## Build Outputs

Expand Down
28 changes: 27 additions & 1 deletion docs/skills/kubeadm-sysext.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ description: Build, ship and operate the opt-in kubeadm worker systemd-sysext (k
metadata:
type: how-to
status: stable
last_updated: "2026-09-27"
last_updated: "2026-09-28"
---
# kubeadm worker sysext

Expand Down Expand Up @@ -43,6 +43,32 @@ Nothing ships under `/opt`: `/opt/cni/bin` stays a writable host directory for
the cluster CNI (Cilium's `cilium-cni`). containerd searches
`/opt/cni/bin` then `/usr/libexec/cni`.

## Versions

The sysext runs the Kubernetes minor of the cluster it joins: the series of
`kubernetes-version` in `include/kubeadm.yml`. It does not follow k0s, which
bundles its own Kubernetes for a separate cluster
([k0s-sysext.md](k0s-sysext.md)); the two minors move independently.
`kubeadm join` must use the minor that last ran `kubeadm init` or
`kubeadm upgrade` on that cluster, and kubelet may be older than the API server
but never newer. Patch releases change neither constraint.

- **Patches** are automatic. `.github/workflows/track-binaries.yml` opens one
pull request per component (Kubernetes, cri-tools, containerd, runc, CNI
plugins) when a newer patch of its pinned series is out, with the version
and its sha256 refs changed together and checked against the checksum files
upstream publishes.
- **Minors** are manual, once the cluster's control plane runs the new minor:
1. `python3 .github/scripts/track-binaries.py apply kubernetes --version X.Y.Z`,
and the same for `cri-tools` (its minor follows Kubernetes). `apply`
verifies the checksums exactly as the tracker does.
2. Set `pause-image` to the tag that
`kubeadm config images list --kubernetes-version vX.Y.Z` prints.
3. Check containerd's `RELEASES.md` support table for the new minor; move
`containerd` and `runc` with `apply` if it asks for newer ones.
4. Move the series in `tests/unit/test_kubeadm_sysext.py`, then boot-verify
as in [Verify](#verify).

## Runtime contract

- No preset enables anything; `80-kubeadm.preset` disables both units against
Expand Down
5 changes: 3 additions & 2 deletions include/k0s.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,9 @@
# project.conf (`installer-version`) or include/image.yml (`image-version`) — those
# axes name the FSDK point release and the OS build and change for unrelated reasons.
#
# Only the two atoms below are edited when k0s is bumped. Every other spelling
# of the k0s version in this repository is derived from them:
# Only the two atoms below are edited when k0s is bumped, by hand or by
# .github/workflows/track-binaries.yml. Every other spelling of the k0s version
# in this repository is derived from them; for release v1.36.4+k0s.0:
#
# %{k0s-k8s-version} upstream Kubernetes version 1.36.4
# %{k0s-patch} upstream k0s patch suffix number 0
Expand Down
22 changes: 13 additions & 9 deletions include/kubeadm.yml
Original file line number Diff line number Diff line change
@@ -1,21 +1,25 @@
# Single source of truth for the kubeadm sysext payload versions.
#
# Pinned to what the target kubeadm cluster's existing nodes run, so a
# Bluefin Server worker is indistinguishable from them at the CRI/kubelet
# level. The sha256 of every download sits next to its source in
# Each version stays on the release series the target kubeadm cluster's nodes
# run, so a Bluefin Server worker matches them at the CRI/kubelet level.
# .github/workflows/track-binaries.yml proposes patch releases inside those
# series; moving to another series is manual (docs/skills/kubeadm-sysext.md).
# The sha256 of every download sits next to its source in
# elements/kubeadm/kubeadm-bin.bst; the sysext itself is locked to the image
# version (kubeadm_<image-version>.raw.zst).
#
# %{kubernetes-version} kubelet, kubeadm, kubectl (dl.k8s.io)
# %{crictl-version} cri-tools
# %{containerd-version} containerd static build
# %{runc-version} runc static build
# %{cni-plugins-version} containernetworking/plugins
# %{pause-image} CRI sandbox image (matches kubeadm-flags.env)
# A comment line separates each version from the next, so the tracker's
# per-component pull requests never edit adjacent lines and merge in any order.
variables:
# kubelet, kubeadm, kubectl (dl.k8s.io)
kubernetes-version: "1.34.3"
# crictl (cri-tools)
crictl-version: "1.34.0"
# containerd static build
containerd-version: "2.1.5"
# runc static build
runc-version: "1.3.3"
# containernetworking/plugins
cni-plugins-version: "1.1.1"
# CRI sandbox image (matches kubeadm-flags.env)
pause-image: "registry.k8s.io/pause:3.10.1"
8 changes: 5 additions & 3 deletions tests/unit/test_k0s_version.py
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,10 @@ def test_k0s_version_ssot():
assert k0s_yml.is_file(), "include/k0s.yml missing"
data = yaml.safe_load(k0s_yml.read_text())
vars_ = data.get("variables", {})
assert vars_.get("k0s-k8s-version") == "1.36.4"
assert vars_.get("k0s-patch") == "0"
# Patch releases arrive through .github/workflows/track-binaries.yml; the
# 1.36 series only moves by hand.
assert re.fullmatch(r"1\.36\.\d+", vars_.get("k0s-k8s-version", ""))
assert re.fullmatch(r"\d+", vars_.get("k0s-patch", ""))
assert vars_.get("k0s-version") == "%{k0s-k8s-version}-k0s.%{k0s-patch}"


Expand All @@ -22,7 +24,7 @@ def test_k0s_bin_element():
content = bin_bst.read_text()
assert "base/base-stack.bst" in content
assert "github:k0sproject/k0s/releases/download/" in content
assert "ca1e9e68107335846e8296777fce2ccd654284e6265b4b5d32c34ead872af98f" in content
assert re.search(r"^\s+ref: [0-9a-f]{64}$", content, re.MULTILINE)


def test_k0s_version_checker_reads_the_component_transfer():
Expand Down
24 changes: 16 additions & 8 deletions tests/unit/test_kubeadm_sysext.py
Original file line number Diff line number Diff line change
Expand Up @@ -30,15 +30,23 @@ def versions() -> dict[str, str]:
return yaml.safe_load(VERSIONS.read_text(encoding="utf-8"))["variables"]


def test_versions_match_the_existing_cluster_nodes() -> None:
assert versions() == {
"kubernetes-version": "1.34.3",
"crictl-version": "1.34.0",
"containerd-version": "2.1.5",
"runc-version": "1.3.3",
"cni-plugins-version": "1.1.1",
"pause-image": "registry.k8s.io/pause:3.10.1",
def test_versions_stay_on_the_cluster_nodes_series() -> None:
# Patch releases arrive through .github/workflows/track-binaries.yml; a
# series change is a deliberate edit here (docs/skills/kubeadm-sysext.md).
pinned = versions()
series = {}
for name, version in pinned.items():
if name != "pause-image":
assert re.fullmatch(r"\d+\.\d+\.\d+", version), name
series[name] = version.rsplit(".", 1)[0]
assert series == {
"kubernetes-version": "1.34",
"crictl-version": "1.34",
"containerd-version": "2.1",
"runc-version": "1.3",
"cni-plugins-version": "1.1",
}
assert pinned["pause-image"] == "registry.k8s.io/pause:3.10.1"


def test_every_download_is_pinned_by_sha256() -> None:
Expand Down
Loading