docs: explain when to pin the coreos-stable kernel (#569)

ZFS failing on a too-new CoreOS stable kernel turns the whole
coreos-stable check red and blocks nvidia and CVE updates. The
Justfile pin exists for that hold, but it was only a comment, so
the 7.1 incident went to local ZFS backports instead.

Document the pin policy in the README and point the ZFS configure
failure path at it when the kernel looks newer than OpenZFS
declares supported.

Justfile

@@ -36,10 +36,10 @@ zfs_configure_args := env(
     if zfs_linux_experimental == 'true' { '--enable-linux-experimental' } else { '' }
 )
 
-# Kernel Pin for coreos-stable (Maximum Version Cap)
-# Set to a specific kernel version (e.g., '6.17.12') to cap coreos-stable builds
-# Set to empty string '' for no pin (use latest kernel from upstream fedora-coreos:stable)
-# This gives maintainers a clear, version-controlled view of the current pin state
+# Kernel pin for coreos-stable (maximum version cap)
+# Empty '' follows upstream fedora-coreos:stable.
+# Set to major.minor.patch (e.g. '6.17.12') to hold all coreos-stable targets.
+# When to use this: README.md#pinning-the-coreos-stable-kernel
 coreos_stable_kernel_pin := ''
 
 # Check if valid

README.md

@@ -89,6 +89,30 @@ We build both the open and closed drivers from NVIDIA. The open driver is the on
 - NVIDIA Pascal: Quadro: P2000, P4000, P5000, P6000, GP100; Tesla: P100, P40, P4
 - NVIDIA Maxwell: Quadro: K2200, M2000, M4000, M5000, M6000, M6000 24GB; - - Tesla: M60, M40, M6, M4
 
+### Pinning the coreos-stable kernel
+
+`coreos_stable_kernel_pin` in the `Justfile` is a temporary ceiling on the kernel used for **every** `coreos-stable` target (`common`, `nvidia-lts`, `nvidia-open`, `zfs`). It exists so publication can continue when Fedora CoreOS stable ships a kernel that OpenZFS cannot yet build.
+
+Empty `''` means follow upstream `fedora-coreos:stable`. A value like `'6.17.12'` is a `major.minor.patch` cap applied in `get-kernel-version` for `coreos-stable` only. Newer detected kernels are rewritten to that pin plus the detected release suffix, then verified in Koji. Kernels at or below the pin pass through.
+
+Use the pin when **all** of these are true:
+
+1. `coreos-stable` ZFS builds are **reliably** failing, not flaking.
+2. The failure is kernel-version incompatibility: OpenZFS `META` `Linux-Maximum` is below the current CoreOS stable kernel, or `configure` rejects the kernel as unsupported.
+3. Waiting for an OpenZFS release would keep the entire `coreos-stable` check job red, blocking publication of the other targets (and kernel CVE / nvidia updates) to downstream stable images such as `ucore:stable`.
+
+Do **not** use the pin for transient CI or network flakes, failures that are not “kernel newer than OpenZFS supports,” `coreos-testing` (set `zfs.linux_experimental` in `images.yaml` if you intentionally want to track newer kernels), or as a long-term fork of the CoreOS stable kernel. Prefer the pin over inventing local OpenZFS kernel-compat backports when the only goal is to restore publication. Carry an already-upstreamed ZFS fix only when the team has explicitly decided to do that.
+
+To apply the pin:
+
+1. Read the last successful `major.minor.patch` from a published image (`ostree.linux` on `ghcr.io/ublue-os/akmods-zfs:coreos-stable-<ver>`) or from a prior `build/*/KCWD/rpms/cache.json`.
+2. Set `coreos_stable_kernel_pin := 'X.Y.Z'` in the `Justfile`, then commit and merge.
+3. Clear it back to `''` as soon as ZFS builds on the current CoreOS stable kernel.
+
+Downstream stable images keep the older kernel until the pin is cleared. That is intentional: operations continue, but new kernel CVEs in the unpinned CoreOS kernel wait.
+
+A `coreos-stable` ZFS job that fails for this unsupported-kernel reason prints a pointer to this section.
+
 ## Usage
 
 To install one of these kmods, you'll need to install any of their specific dependencies (checkout the `build-prep.sh` and the specific `build-FOO.sh` script for details), and ensure you are on a compatible kernel.

build_files/zfs/build-kmod-zfs.sh

@@ -106,12 +106,65 @@ if [ "$(uname -m)" = "aarch64" ]; then
         echo "SKIP patch to raidz aarch64 neon, already applied upstream"
     fi
 fi
+# Hint at the coreos-stable kernel pin when OpenZFS rejects this kernel.
+# See README.md#pinning-the-coreos-stable-kernel
+suggest_coreos_stable_kernel_pin() {
+    local flavor="${KERNEL_FLAVOR:-}"
+    if [[ ! "${flavor}" =~ coreos-stable ]]; then
+        return 0
+    fi
+
+    local looks_unsupported=false
+    local linux_max=""
+    local kernel_mm=""
+
+    if [[ -f META ]]; then
+        linux_max="$(awk -F: '/^Linux-Maximum:/ { gsub(/[[:space:]]/, "", $2); print $2 }' META)"
+    fi
+    kernel_mm="$(echo "${KERNEL}" | grep -oE '^[0-9]+\.[0-9]+')"
+
+    # Linux-Maximum is major.minor; 7.1.4 does not exceed a declared 7.1.
+    if [[ -n "${linux_max}" && -n "${kernel_mm}" ]]; then
+        if [[ "$(printf '%s\n' "${linux_max}" "${kernel_mm}" | sort -V | tail -n1)" == "${kernel_mm}" && \
+              "${kernel_mm}" != "${linux_max}" ]]; then
+            looks_unsupported=true
+        fi
+    fi
+
+    if [[ -f config.log ]] && grep -Eiq \
+        'not a supported kernel|maximum supported kernel|unsupported Linux kernel|Cannot enable unsupported' \
+        config.log; then
+        looks_unsupported=true
+    fi
+
+    if [[ "${looks_unsupported}" != true ]]; then
+        return 0
+    fi
+
+    cat >&2 <<'EOF'
+
+========================================================================
+This coreos-stable ZFS build failed because the kernel looks newer than
+OpenZFS currently declares supported.
+
+Pinning the last successful coreos-stable kernel unblocks the rest of
+the coreos-stable publication pipeline (common, nvidia, and downstream
+stable images) until an OpenZFS release supports this kernel.
+
+Read this before carrying local ZFS kernel-compat backports:
+https://github.com/ublue-os/akmods/blob/main/README.md#pinning-the-coreos-stable-kernel
+========================================================================
+EOF
+}
+
 if ! ./configure \
         -with-linux="/usr/src/kernels/${KERNEL}/" \
         -with-linux-obj="/usr/src/kernels/${KERNEL}/" \
         "${ZFS_CONFIGURE_ARGS_ARRAY[@]}" \
     || ! make -j "$(nproc)" rpm-utils rpm-kmod; then
-    cat config.log && exit 1
+    cat config.log || true
+    suggest_coreos_stable_kernel_pin
+    exit 1
 fi
 
 # validate RAIDZ math implementations when we've locally patched on aarch64