Compatibility Matrix
Kure Compatibility Matrix
This document describes the versions of infrastructure tools that Kure supports.
It is generated from versions.yaml (deployment compatibility metadata) plus
go.mod (the build versions).
Version Philosophy
Kure maintains two version concepts for each dependency:
- Build Version (read from go.mod): The exact library version Kure imports and builds against
- Deployment Compatibility (
supported_rangein versions.yaml): The range of deployed tool versions that Kure can generate YAML for
Go Version
Current: Go 1.26.5
Infrastructure Dependencies
| Tool | Build Version | Deployment Compatibility | Notes |
|---|---|---|---|
| cert-manager | 1.20.2 | 1.14 - 1.20 | Stable v1 APIs. v1.20 deprecated ObjectReference in favor of IssuerReference (type alias). |
| fluxcd | 2.9.0 | 2.4 - 2.9 | v1beta2 APIs removed in 2.8, DependsOn uses DependencyReference. image-automation-controller promoted to v1. v2.9 (source-controller/api v1.9): OCIRepositoryVerification and HelmChartVerification split into distinct types (HelmChart.Spec.Verify is now HelmChartVerification); OCIRepositoryVerification gained TrustedRootSecretRef. notification-controller/api v1.9: Receiver.Spec.Resources is now []ReceiverResource (embeds CrossNamespaceObjectReference + CEL Filter) and Receiver.Spec.SecretRef is a pointer. Provider/Alert remain v1beta3 upstream (tracked by #250/#252). All github.com/fluxcd/ packages upgraded together. |
| flux-operator | 0.53.0 | 0.23 - 0.53 | Upgraded alongside the FluxCD 2.9 ecosystem. The vendored install bundle (pkg/stack/fluxcd/flux_operator_install.yaml) and FluxOperatorVersion constant are pinned in lockstep with this module version. |
| source-watcher | 2.2.1 | 2.0 - 2.2 | Optional FluxCD controller for source composition/decomposition. Manages ArtifactGenerator CRD (source.extensions.fluxcd.io/v1beta1). Not in default Flux installation; requires –components-extra=source-watcher. |
| metallb | 0.16.1 | 0.14 - 0.16 | v1beta1 APIs stable across this range. v0.16.0 is a minor release: BGP config-parsing refactor (selectedNodes/selectedPools rewrite), node-specific ConfigurationState validation, security fixes via govulncheck. No changes to the v1beta1 API types that kure imports (IPAddressPool, BGPPeer, BGPAdvertisement, L2Advertisement, BFDProfile). |
| prometheus-operator | 0.92.0 | 0.75 - 0.92 | Prometheus operator monitoring API types (ServiceMonitor, PodMonitor, PrometheusRule). Only the /pkg/apis/monitoring submodule is imported — not the full operator. Stable v1 APIs (monitoring.coreos.com/v1). v0.92 is a routine minor with no changes to the imported v1 types (build + tests pass unchanged). |
| external-secrets | 0.0.0-20260213133823-31b0c7c37342 | 1.3 | Module path changed from root to /apis submodule in v1.0 (#5494). No semver tags for apis submodule — go.mod pins a pseudo-version to a release commit, so the range guard skips it (pseudo-versions can’t map to semver). v1.3.2+ commit: 31b0c7c3734255a92dfe5cf9e1e204de127eb24c (includes controller-runtime v0.23.1 compat) |
| cnpg | 1.29.1 | 1.24 - 1.29 | CloudNativePG operator for PostgreSQL on Kubernetes. Cluster CR (with managed roles), Database CR (postgresql.cnpg.io/v1), ObjectStore CR (barmancloud.cnpg.io/v1), and ScheduledBackups. ObjectStore lives in a separate module (plugin-barman-cloud). |
| cnpg-barman-cloud | 0.13.0 | 0.9 - 0.13 | Barman Cloud plugin for CNPG — provides ObjectStore CR (barmancloud.cnpg.io/v1). Versioned independently from the CNPG operator. v0.13 is a routine minor with no changes to the imported ObjectStore v1 type (build + tests pass unchanged). |
| controller-runtime | 0.24.1 | 0.22 - 0.24 | v0.24.1 fixes Apply typed error handling regression; requires k8s.io/* v0.36.0 (Kubernetes 1.36) |
| gateway-api | 1.5.1 | 1.0 - 1.5 | Gateway API v1 types (HTTPRoute). Used by pkg/kubernetes HTTPRoute builders. Kure generates gateway.networking.k8s.io/v1 resources (GA since v1.0). |
| kubernetes | 0.36.0 | 1.33 - 1.36 | Go 1.26 baseline; generated YAML uses stable APIs compatible across this range |
Understanding the Matrix
Build Version (go.mod)
The version Kure imports and builds against — read directly from go.mod, the single
source of truth for the pin. CI (sync-versions.sh check) asserts it falls within the
declared supported_range.
Deployment Compatibility
The range of versions that Kure can generate valid YAML for. Kure may generate YAML compatible with older or newer versions than it builds against.
For example, Kure may build against a single cert-manager patch release while the generated YAML stays valid across several older and newer minor releases within its supported range.
Upgrading Dependencies
When upgrading a dependency:
- Run
go get <module>@<version>to update go.mod - Update code for any API changes
- If the new version lands outside
supported_range, widen the range and updatenotesinversions.yaml(only after confirming API compatibility). In-range patch bumps need noversions.yamlchange. - Run
./scripts/sync-versions.sh generateto update docs - Run
./scripts/sync-versions.sh checkto validate consistency