fix: repair CNI matrix update from Dependabot #2145

.github/dependabot.yml

@@ -25,12 +25,7 @@ updates:
 
 # Kubernetes version matrix release pins
 - directories:
-    - "/images/capi/packer/config/kubernetes-version-dependencies/release-1-31"
-    - "/images/capi/packer/config/kubernetes-version-dependencies/release-1-32"
-    - "/images/capi/packer/config/kubernetes-version-dependencies/release-1-33"
-    - "/images/capi/packer/config/kubernetes-version-dependencies/release-1-34"
-    - "/images/capi/packer/config/kubernetes-version-dependencies/release-1-35"
-    - "/images/capi/packer/config/kubernetes-version-dependencies/release-1-36"
+    - "/images/capi/packer/config/kubernetes-version-dependencies/release-*/*"
   package-ecosystem: "gomod"
   open-pull-requests-limit: 5
   schedule:
@@ -41,6 +36,8 @@ updates:
   groups:
     kubernetes-version-matrix-release-pins:
       patterns: [ "*" ]
+  allow:
+    - dependency-type: "direct"
   ignore:
     - dependency-name: "github.com/containerd/containerd/v2"
       update-types:
@@ -72,7 +69,7 @@ updates:
 
 # Kubernetes version matrix rolling latest
 - directories:
-    - "/images/capi/packer/config/kubernetes-version-dependencies/latest"
+    - "/images/capi/packer/config/kubernetes-version-dependencies/latest/*"
   package-ecosystem: "gomod"
   open-pull-requests-limit: 3
   schedule:
@@ -83,6 +80,8 @@ updates:
   groups:
     kubernetes-version-matrix-latest:
       patterns: [ "*" ]
+  allow:
+    - dependency-type: "direct"
   ignore:
     - dependency-name: "github.com/containerd/containerd/v2"
       update-types:

.github/workflows/update-kubernetes-version-matrix.yaml

@@ -43,7 +43,7 @@ jobs:
             exit 1
           fi
 
-          tracking_pattern='^images/capi/packer/config/kubernetes-version-dependencies/(latest|release-[0-9]+-[0-9]+)/go\.(mod|sum)$'
+          tracking_pattern='^images/capi/packer/config/kubernetes-version-dependencies/(latest|release-[0-9]+-[0-9]+)/(containerd|cni-plugins|runc|kubernetes|cri-tools)/go\.(mod|sum)$'
           invalid_files="$(
             printf '%s\n' "${changed_files}" |
               grep -Ev "${tracking_pattern}" || true
@@ -78,7 +78,7 @@ jobs:
           fi
 
           generated_pattern='^images/capi/packer/config/kubernetes-version-(latest|matrix)\.yaml$'
-          tracking_pattern='^images/capi/packer/config/kubernetes-version-dependencies/(latest|release-[0-9]+-[0-9]+)/go\.(mod|sum)$'
+          tracking_pattern='^images/capi/packer/config/kubernetes-version-dependencies/(latest|release-[0-9]+-[0-9]+)/(containerd|cni-plugins|runc|kubernetes|cri-tools)/go\.(mod|sum)$'
           invalid_files="$(
             git diff --name-only |
               grep -Ev "(${generated_pattern})|(${tracking_pattern})" || true

docs/book/src/capi/kubernetes-version-matrix.md

@@ -39,21 +39,79 @@ images/capi/hack/kubernetes-version-matrix.py update --write
 images/capi/hack/kubernetes-version-matrix.py verify
 ```
 
-Generated Go module manifests under
-`images/capi/packer/config/kubernetes-version-dependencies/` let Dependabot
-track the same versions as module dependencies. Release-pinned entries accept
-patch updates only. The rolling `latest` entry can move to newer minor versions.
-Kubernetes releases are tracked through `k8s.io/client-go` module tags and then
-mapped back to Kubernetes `v1.x.y` versions in the matrix.
+Dependabot tracks the same versions as Go module dependencies. Every tracked
+dependency gets its own synthetic module under
+`images/capi/packer/config/kubernetes-version-dependencies/`:
 
-When Dependabot updates those manifests, the
-`Update Kubernetes version matrix` workflow regenerates the YAML files with:
+```text
+kubernetes-version-dependencies/
+  latest/            # rolling entry
+    cni-plugins/     # github.com/containernetworking/plugins
+    containerd/      # github.com/containerd/containerd/v2
+    cri-tools/       # sigs.k8s.io/cri-tools
+    kubernetes/      # k8s.io/client-go
+    runc/            # github.com/opencontainers/runc
+  release-1-31/      # one directory per release pin, same five modules
+  ...
+```
+
+Each module requires exactly one dependency, so minimal version selection
+cannot let one tracked dependency raise the pin of another. Release-pinned
+entries accept patch updates only. The rolling `latest` entry can move to newer
+minor versions. Kubernetes releases are tracked through `k8s.io/client-go`
+module tags and then mapped back to Kubernetes `v1.x.y` versions in the matrix.
+
+Each module also has a `tools.go` file with a single blank import. Dependabot
+always runs `go mod tidy` after an update, and tidy drops requirements that no
+package imports, which would empty the manifest. The imported package is the
+lightest one in the tracked module so that tidy records no indirect
+requirements. Because tidy also rewrites the `go` directive and may add a
+`toolchain` line, `verify` checks the required module and version rather than
+comparing the whole file against a template. It also checks that go.sum carries
+both `h1:` checksums for the pinned version, so a go.mod left ahead of its
+go.sum fails instead of passing quietly.
+
+`kubernetes_cni_semver` pins the CNI plugins tarball and is tracked
+independently of `kubernetes_cni_deb_version` and
+`kubernetes_cni_rpm_version`, which pin the distro `kubernetes-cni` package.
+The two are versioned separately upstream, so `update --write` refreshes the
+package versions and carries the tarball version over unchanged. A CNI module
+update can therefore advance `kubernetes_cni_semver` before the matching
+`kubernetes-cni` package is published: URL-based targets then install the newer
+tarball while package-based targets keep the pinned package version.
+
+More generally, `update --write` only rewrites what it resolves from upstream
+release metadata: the Kubernetes version fields, the kubernetes-cni package
+versions and crictl. `containerd_version`, `runc_version` and
+`kubernetes_cni_semver` are carried over. This holds for the rolling `latest`
+entry too, which is refreshed from its own values rather than from the release
+pin for the same minor, so a version Dependabot moved ahead on `latest` is
+never rolled back by a refresh.
+
+When Dependabot updates the modules, the `Update Kubernetes version matrix`
+workflow regenerates the YAML files with:
 
 ```sh
 images/capi/hack/kubernetes-version-matrix.py sync-tracking --write
 images/capi/hack/kubernetes-version-matrix.py verify
 ```
 
 Run `update --write` when refreshing directly from upstream release and package
-metadata. It updates the YAML files and regenerates the Dependabot tracking
-manifests.
+metadata. It updates the YAML files and then rewrites and tidies any tracking
+module whose version changed.
+
+Bootstrap the tracking modules for a new release selector after adding its
+entry to the matrix with:
+
+```sh
+images/capi/hack/kubernetes-version-matrix.py render-tracking --write
+```
+
+`render-tracking --write` and `update --write` need the `go` command because
+they regenerate each changed module with `go mod tidy`. Both check for it up
+front and exit before touching a file, so a missing toolchain cannot leave a
+go.mod ahead of its go.sum. `verify` and `sync-tracking` do not need `go`.
+`verify` needs no network access beyond a `yq` binary, which `hack/ensure-yq.sh`
+downloads when one is not already installed. `sync-tracking` only reaches the
+network when the tracked Kubernetes version moved and the Debian package
+revision has to be resolved again.