⚠️ 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.27.2

Infrastructure Dependencies

ToolBuild VersionDeployment CompatibilityNotes
barman-cloud0.6.0derived 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 directly — whether that requirement happens to land on a tag or a pseudo-version, a hand-picked tag could still 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.21.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.31.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.52.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.58.10.23 - 0.58Routine minors, assessed against the vendored CRDs rather than the Go types alone. Three of the four bundled CRDs (fluxinstances, fluxreports, resourcesets) are byte-identical between v0.53.0 and v0.58.1, including FluxInstance spec.distribution.version, so nothing the bootstrap generator emits is newly constrained. Only resourcesetinputproviders changes: a new ExternalArtifact type with its spec.selectors array, and four CEL rules replaced by widened forms that additionally permit it. The two real tightenings are a maximum of 10000 on spec.filter.limit and a new requirement that an OCI spec.url carry a repository path after the registry host. Kure has no setter for either field, but the builder contract lets callers assign them directly, so a caller-built ResourceSetInputProvider with a filter.limit above 10000 or an OCI url holding only a registry host, which the v0.53 CRD admitted, is rejected at apply time by the v0.58 CRD. That is an admission-breaking change for such callers, not unconditional compatibility. The Go api/v1 surface changes additively only, and fluxcd/pkg/apis acl 0.11.0, kustomize 1.21.0 and meta 1.32.0 carry no type changes at all. The vendored install bundle (pkg/stack/fluxcd/flux_operator_install.yaml) and FluxOperatorVersion constant are re-pinned to v0.58.1 in the same change and the install inventory is unchanged.
source-watcher2.2.42.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). BGPPeer is built at metallb.io/v1beta2, the stored version: the BGPPeer definition shipped at v0.14.0 already serves and stores v1beta2 beside the deprecated v1beta1, so that version is served across this range. A v1beta1 BGPPeer is still parsed.
prometheus-operator0.94.10.75 - 0.94Prometheus 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. v0.94 changes no API type kure imports. servicemonitor_types.go, podmonitor_types.go, probe_types.go and prometheusrule_types.go are unchanged from v0.93.1 — absent from the v0.93.1…v0.94.0 compare while present at both tags. Of the four changed v1 files, prometheus_types.go and alertmanager_types.go are purely additive (new optional retentionPercentage and clusterPeerName fields, no removals), thanos_types.go has no removed lines, and types.go removes only six malformed struct tags on TracingConfig, where omitempty sat outside the json tag string and is now inside it. kure does not reference TracingConfig. Nothing removed, nothing retyped.
external-secrets0.0.0-20261016092056-a82d14894fbc2.9 - 2.13Module 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. v2.11.0 adds the Barbican provider type and marks KeeperSecurityProvider.FolderID optional (Go type unchanged); no other apis type changes — build + tests pass unchanged. The field now carries omitempty, so a Keeper provider assigned to SecretStore.Spec.Provider with an empty FolderID serialises without folderID, which the v2.9 and v2.10 CRDs (folderID required) reject: set FolderID explicitly when targeting a cluster older than v2.11. Kure does not populate it itself. v2.12.0 adds three optional Conjur authenticators to ConjurAuth (IAM, Azure and GCP: new pointer fields and their types); nothing in externalsecrets/v1 is removed or retyped. The only other apis change is in generators/v1alpha1, which kure does not import. Build + tests pass unchanged. v2.13.0 changes nothing in externalsecrets/v1; the only apis type change is the v1beta1 ExternalSecret validator, which kure does not import. Its apis go.mod raises the go directive from 1.26.6 to 1.27.2, and kure’s go.mod inherits that floor, so building kure (and any module that requires it) now needs Go 1.27.2. Build + tests pass unchanged.
cnpg1.30.11.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.15.10.9 - 0.15Barman 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.15.0 adds a restore-hook sidecar and bumps Barman to 3.20.0, both internal/cnpgi-only. The imported barmancloud.cnpg.io/v1 ObjectStore type (api/v1) has zero file changes between v0.14.0 and v0.15.0 (verified against the upstream diff) — build and tests pass unchanged.
controller-runtime0.25.20.22 - 0.25v0.25.0’s breaking changes are the new EventRecorder interface and a bump to k8s.io/* v1.37, neither in kure’s surface: kure imports only pkg/client (verified — no other controller-runtime subpackage is imported anywhere), whose Client interface is unchanged; IndexerFunc/FieldIndexer became type aliases to a new cacheapi package but kure uses neither. kure already requires k8s.io/api v0.37.x directly, so the k8s.io/* bump is a no-op here. Build and tests pass unchanged.
gateway-api1.6.31.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.11.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)