circleci: run platformtests against well-defined ZFS releases (#921)

Before this PR we platformtests in CI only against the ZFS version that
shipped with the CircleCI machine image (ZFS 2.2).

Changes in this PR:
- add an `command` for building OpenZFS `.deb`'s from a Git checkout,
and for caching those `.deb`s in CircleCI
- use that command in the platform test build matrix. ZFS versions:
**2.2.9**, **2.3.5**, and **2.4.0**

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

.circleci/config.yml

@@ -51,6 +51,76 @@ commands:
           paths:
             - ~/.cache/uv
 
+  install-zfs-from-source:
+    parameters:
+      zfs_release:
+        type: string
+    steps:
+      - run:
+          name: Record kernel version for cache key
+          command: uname -r > /tmp/kernel-version
+      - restore_cache:
+          name: Restore ZFS native debs cache
+          keys:
+            - zfs-debs-v2-<<parameters.zfs_release>>-{{ checksum "/tmp/kernel-version" }}
+      - run:
+          # https://openzfs.github.io/openzfs-docs/Developer%20Resources/Building%20ZFS.html
+          name: Build ZFS <<parameters.zfs_release>> native debs (if not cached)
+          no_output_timeout: 20m
+          command: |
+            # CircleCI machine images have pyenv Python 3.13 shadowing the system
+            # Python 3.12. The apt python3-* packages (setuptools, cffi, etc.) only
+            # install for the system Python, and ZFS's dpkg-buildpackage needs them
+            # for --enable-pyzfs. Use the system Python so apt packages are visible.
+            export PYENV_VERSION=system
+            if [ -d /tmp/zfs-debs ]; then
+              echo "ZFS debs cache hit, skipping build"
+              exit 0
+            fi
+            sudo apt-get update
+            sudo apt-get install -y \
+              alien autoconf automake build-essential debhelper-compat dh-autoreconf \
+              dh-dkms dh-python dkms fakeroot gawk git libaio-dev libattr1-dev \
+              libblkid-dev libcurl4-openssl-dev libelf-dev libffi-dev libpam0g-dev \
+              libssl-dev libtirpc-dev libtool libudev-dev linux-headers-$(uname -r) lsb-release \
+              parallel po-debconf python3 python3-all-dev python3-cffi python3-dev \
+              python3-packaging python3-setuptools python3-sphinx uuid-dev zlib1g-dev
+            mkdir -p /tmp/zfs-build
+            cd /tmp/zfs-build
+            git clone --depth 1 --branch <<parameters.zfs_release>> https://github.com/openzfs/zfs.git zfs-src
+            cd zfs-src
+            sh autogen.sh
+            ./configure
+            make native-deb
+            mkdir -p /tmp/zfs-debs
+            find /tmp/zfs-build -name '*.deb' -exec mv -t /tmp/zfs-debs/ {} +
+      - save_cache:
+          name: Save ZFS native debs cache
+          key: zfs-debs-v2-<<parameters.zfs_release>>-{{ checksum "/tmp/kernel-version" }}
+          paths:
+            - /tmp/zfs-debs
+      - run:
+          name: Install ZFS <<parameters.zfs_release>>
+          command: |
+            ls /tmp/zfs-debs/
+            # Only install the debs we need. Exclude dracut (conflicts with
+            # initramfs-tools), dkms (we have prebuilt modules), and packages
+            # we don't need (pyzfs, test, doc).
+            sudo apt-get install -y $(find /tmp/zfs-debs -name '*.deb' \
+              ! -name '*dracut*' \
+              ! -name '*dkms*' \
+              ! -name '*initramfs*' \
+              ! -name '*pyzfs*' \
+              ! -name '*doc*' \
+              ! -name '*test*' \
+              -print)
+            sudo modprobe zfs
+      - run:
+          name: Verify ZFS version
+          command: |
+            sudo zfs version
+            sudo zpool version
+
   docs-publish-sh:
     parameters:
       push:
@@ -135,7 +205,7 @@ workflows:
               goversion: [*latest-go-release]
               goos: ["linux"]
               goarch: ["amd64"]
-              image: ["ubuntu-2204:current", "ubuntu-2404:current"]
+              zfs_release: ["zfs-2.2.9", "zfs-2.3.5", "zfs-2.4.0"]
           requires:
             - test-go
             - quickcheck-go-<< matrix.goarch >>-<< matrix.goos >>-<< matrix.goversion >>
@@ -239,10 +309,11 @@ jobs:
         type: string
       goarch:
         type: string
-      image:
+      zfs_release:
         type: string
     machine:
-      image: <<parameters.image>>
+      # pinned (not :current) to keep ZFS build cache valid across runs
+      image: ubuntu-2404:2025.09.1
     resource_class: medium
     environment:
       GOOS: <<parameters.goos>>
@@ -250,9 +321,8 @@ jobs:
     steps:
       - attach_workspace:
           at: .
-      - run: sudo apt-get update
+      - install-zfs-from-source:
-      - run: sudo apt-get install -y zfsutils-linux
+          zfs_release: <<parameters.zfs_release>>
-      - run: sudo zfs version
       - run: sudo make test-platform GOOS="$GOOS" GOARCH="$GOARCH"
 
   test-go:

README.md

@@ -171,6 +171,8 @@ Run `make lint` and `make vet`.
 Update the CI configuration `.circleci/config.yml`:
 - Update Go version references (we reference the minimum and max supported version)
 - Set `Makefile` `RELEASE_GOVERSION` to the new Go version
+- Update the pinned ZFS release tags in the `platformtest` matrix (`zfs_release` parameter) to the latest patch releases of each OpenZFS branch (currently 2.2, 2.3, 2.4)
+- Update the pinned Ubuntu machine image for `platformtest` (e.g. `ubuntu-2404:2025.09.1`) — this is pinned rather than `current` so the ZFS build cache stays valid across runs
 
 Update docs build tooling:
 - Update `uv` version in `.circleci/config.yml` (search for `astral.sh/uv/` and cache keys containing the version)