⚠️ Work in Progress
You are viewing development documentation built from the latest commit on main. APIs and features are subject to change.

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:

  1. Build Version (read from go.mod): The exact library version Kure imports and builds against
  2. Deployment Compatibility (supported_range in versions.yaml): The range of deployed tool versions that Kure can generate YAML for

Consumers that need the deployment-compatibility metadata (2) or the Go toolchain version programmatically should import github.com/go-kure/kure/pkg/versions rather than parsing versions.yaml. Per-dependency build versions (1) are not exported – they change on every routine bump, so keeping them out keeps this API’s content stable; read them from go.mod instead.

Go Version

Current: Go 1.26.8

Infrastructure Dependencies

ToolBuild VersionDeployment CompatibilityNotes
barman-cloud0.5.2-0.20260720143032-950b0f57e122derived from github.com/cloudnative-pg/plugin-barman-cloudBarman Cloud object-store API types (BarmanObjectStoreConfiguration, S3Credentials) — a separate module from both the CNPG operator and the barman-cloud plugin (cnpg-barman-cloud-plugin, below). Kure imports pkg/api directly. The pin is derived from floor_module’s own requirement, not chosen from barman-cloud’s tags — a hand-picked tag would be a downgrade Go’s minimum-version selection wouldn’t let the build use. renovate.json disables the standalone gomod bump for it (see the rule there). No supported_range is declared: the pin moves only when plugin-barman-cloud’s own go.mod requirement moves (validate_mvs_floors enforces that equality), so there is no independent range for kure to gate — a hand-maintained range here would only ever demand widening in lockstep with the plugin, never catch a choice kure actually made (go-kure/kure#703; validate_gomod skips the range check for any floor_module entry, see docs/dependency-updates.md).
cert-manager1.21.11.14 - 1.21Stable v1 APIs. v1.20 deprecated ObjectReference in favor of IssuerReference (type alias). v1.21 removed the deprecated ObjectReference type (#8625); kure already uses IssuerReference (plus LocalObjectReference/SecretKeySelector from meta/v1), so the imported certmanager/v1 + acme/v1 + meta/v1 surface is unaffected — build + tests pass.
cilium1.20.11.18 - 1.20Cilium CRDs. Every builder in pkg/kubernetes/cilium emits ciliumv2.SchemeGroupVersion — i.e. cilium.io/v2 — for all thirteen resources (CiliumNetworkPolicy, CiliumClusterwideNetworkPolicy, CiliumCIDRGroup, CiliumEgressGatewayPolicy, CiliumLocalRedirectPolicy, CiliumLoadBalancerIPPool, CiliumEnvoyConfig, CiliumClusterwideEnvoyConfig, and the five BGPv2 types). The floor is 1.18: BGPv2, CiliumCIDRGroup and CiliumLoadBalancerIPPool were served only as cilium.io/v2alpha1 up to and including 1.17 and were promoted to v2 in 1.18, so generated YAML does not apply to older clusters. v1.20 is a routine minor with no changes to the imported cilium.io/v2 spec types or to policy/api — build + tests pass unchanged.
fluxcd2.9.32.4 - 2.9v1beta2 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-operator0.53.00.23 - 0.53Upgraded 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-watcher2.2.22.0 - 2.2Optional FluxCD controller for source composition/decomposition. Manages ArtifactGenerator CRD (source.extensions.fluxcd.io/v1beta1). Not in default Flux installation; requires –components-extra=source-watcher.
metallb0.16.10.14 - 0.16v1beta1 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-operator0.93.10.75 - 0.93Prometheus 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.93 retyped the six scrape-limit fields on ServiceMonitorSpec/PodMonitorSpec (SampleLimit, TargetLimit, LabelLimit, LabelNameLengthLimit, LabelValueLengthLimit, KeepDroppedTargets) from *uint64 to *int64; kure imports only SampleLimit, so its public SampleLimit config field and SetServiceMonitorSampleLimit/SetPodMonitorSampleLimit signatures moved to int64 in lockstep. Wire format (monitoring.coreos.com/v1 JSON) is unchanged, so generated YAML still applies to clusters across this range.
external-secrets0.0.0-20260828112654-279f56c84d5d2.9 - 2.10Module path changed from root to /apis submodule in v1.0 (#5494). No semver tags for apis submodule — go.mod pins a pseudo-version, so upstream_release + upstream_release_commit above pin it to a named release instead of tracking main HEAD. sync-versions.sh substitutes upstream_release for the range check and asserts the pseudo-version’s embedded 12-char digest prefixes upstream_release_commit, so the pin can no longer drift off the declared release; it also best-effort verifies upstream_release_commit against upstream_repo@upstream_release live (network permitting) to catch a hand-edited upstream_release that skipped scripts/sync-eso-pin.sh. Re-pin with scripts/sync-eso-pin.sh. v2.9.0 changed SecretStoreSpec.RefreshInterval from int to *intstr.IntOrString — a breaking change for callers that assign a whole esv1.SecretStoreSpec to a SecretStore or ClusterSecretStore. Kure is pre-1.0 (v0.2.0-beta) and does not populate that field itself, so this repo’s own build is unaffected; external consumers constructing SecretStoreSpec{RefreshInterval: } will fail to compile against this bump. v2.10.0 adds providers/features only (no further apis type changes per the upstream changelog); build + tests pass unchanged.
cnpg1.30.01.24 - 1.30CloudNativePG 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, entry cnpg-barman-cloud-plugin below), which in turn requires its own separate barman-cloud module (entry barman-cloud above) for the underlying object-store API types — two distinct CNPG modules, not one. v1.30 is a routine minor with no changes to the imported postgresql.cnpg.io/v1 types (Cluster, Database, Pooler, ScheduledBackup) — build + tests pass unchanged.
cnpg-barman-cloud-plugin0.14.00.9 - 0.14Barman Cloud plugin for CNPG — provides ObjectStore CR (barmancloud.cnpg.io/v1). Versioned independently from the CNPG operator. Not to be confused with the barman-cloud entry above, a separate module this plugin itself depends on for object-store API types. v0.14 is a routine minor with no changes to the imported ObjectStore v1 type (build + tests pass unchanged).
controller-runtime0.24.10.22 - 0.24v0.24.1 fixes Apply typed error handling regression. Its own go.mod pins k8s.io/* v0.36.0 (Kubernetes 1.36) – the latest release as of the k8s v0.37.0 bump above; Go’s MVS resolves the shared k8s.io/* modules to v0.37.0 here since kure now requires that directly. controller-runtime’s client-go usage is compatible with the newer minor (build + tests pass unchanged); no v0.24.x+ release yet declares k8s.io/* v0.37.0 itself.
gateway-api1.6.11.0 - 1.6Gateway API v1 types (HTTPRoute). Used by pkg/kubernetes HTTPRoute builders. Kure generates gateway.networking.k8s.io/v1 resources (GA since v1.0). v1.6 is a routine minor with no changes to the imported gateway.networking.k8s.io/v1 HTTPRoute type — build + tests pass unchanged.
kubernetes0.37.01.33 - 1.37Go 1.26 baseline; generated YAML uses stable APIs compatible across this range. v1.37 added corev1.VolumeMount.BindMountOptions ([]string), making VolumeMount no longer comparable with ==/!=; kure’s own code never compares VolumeMount values (only pkg/kubernetes/container_test.go did, fixed to use reflect.DeepEqual). Build + tests otherwise pass unchanged. VolumeMount is also kure’s own public API (AddContainerVolumeMount takes one by value): external consumers that compare VolumeMount values or use them as map keys will fail to compile against this bump, the same class of break as external-secrets’ SecretStoreSpec.RefreshInterval above. Kure is pre-1.0 (v0.2.0-beta) and does not do either itself.

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 — except an entry whose Deployment Compatibility cell reads “derived from <module>” (an MVS-floor dependency): its pin is not chosen by Kure, so there is no independent range to assert, and CI instead only checks that the pin matches what <module>’s own go.mod requires. See docs/dependency-updates.md’s “MVS-floor dependencies” section.

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:

  1. Run go get <module>@<version> to update go.mod
  2. Update code for any API changes
  3. If the new version lands outside supported_range, widen the range and update notes in versions.yaml (only after confirming API compatibility). In-range patch bumps need no versions.yaml change.
  4. Run ./scripts/sync-versions.sh generate to update docs
  5. Run ./scripts/sync-versions.sh check to validate consistency
  • #133 - Go 1.25 upgrade tracking
  • #128 - FluxCD ecosystem upgrade (blocked by Go 1.25)