Versions

Versions - Supported-Version Metadata

Stable Go access to kure’s supported-version metadata.

versions.yaml at the repository root records, per infrastructure dependency, the range of deployed tool versions kure generates YAML for. This package exposes the machine-readable part of that file so consumers do not have to read it off disk and decode key paths by hand.

Usage

The block below is the body of an Example function in example_test.go, which imports this package as versions, and fmt. go test compiles it but does not run it: it has no expected output, for the reason the next paragraph gives.

k8s, ok := versions.Get("kubernetes")
if !ok {
    return // the key was renamed or removed
}
fmt.Println(k8s.SupportedRange, k8s.Min, k8s.Max)

for _, d := range versions.All() {
    fmt.Printf("%s: %s (%s)\n", d.Name, d.SupportedRange, d.GoModule)
}

fmt.Println(versions.GoVersion) // versions.yaml's go.current

None of these values are repeated here: SupportedRange, Min, Max and GoVersion all move on a routine dependency or toolchain bump, and a literal example printed in this file would go stale the next time one does. pkg/versions/versions_gen.go is the generated, authoritative record of whatever kure currently supports — read it directly, or call Get/All at runtime, rather than trusting a number written here.

What is exported, and what is not

Exported: Name, GoModule, SupportedRange, Min, Max, VersionBasis, FloorModule.

Not exported: notes, related_packages, upstream_repo, upstream_release, upstream_release_commit, the go.mod build version. The build version moves on every dependency bump; the others can change too (reviewer prose edits, a release-pinned dependency getting re-pinned) but not on every routine bump — an in-range patch bump needs no versions.yaml change at all. Excluding all of them either way keeps this API’s content stable rather than tied to prose or pin churn.

FloorModule is empty for almost every entry. It is set only for an MVS-floor dependency — one whose pin is not chosen directly but is the Go minimum-version-selection floor set by another module’s own go.mod requirement (versions.yaml’s floor_module key). For such an entry, SupportedRange/Min/Max are all empty: there is no hand-maintained range to report, since kure never chose that version, so SupportedRange == "" is ambiguous on its own — check FloorModule to tell “no range declared” from “range not applicable here.”

SupportedRange/Min/Max are a moving target, not a build-time constant

A dependency bump that lands outside its current supported_range fails CI until a human runs ./scripts/sync-versions.sh widen <dep> <new-upper-bound> --note "<assessment>" — the range only ever widens, and only after someone has actually confirmed the new version is compatible (go-kure/kure#593, go-kure/kure#765). That happens roughly as often as kure takes a dependency bump, not on a fixed schedule. A consumer that reads these fields once and caches the result — in a config file, a constant, a test fixture — will silently drift from what Get/All report on kure’s next release; call them at the point of use instead of hoisting the values out.

The assessment behind a widening is not reachable through this API. --note is appended to versions.yaml’s unexported notes key (--replace-notes overwrites it instead) and rendered into the Notes column of docs/compatibility.md, so that column accumulates the assessments of successive widenings; SupportedRange records only the conclusion. A consumer asking why a range covers a given version reads one of those two, not this package.

What a range does and does not promise: the assessment is made against the YAML kure generates and the deployed tool’s CRDs, so SupportedRange says that generated YAML applies across it. It does not say every object a caller builds by hand is admitted across it. A release inside the range can tighten CRD validation (a new maximum, a stricter URL rule), and kure’s builders let callers assign upstream fields directly, so an object the older release accepted can be rejected by the newer one. When that happens the widening’s note in docs/compatibility.md says so; check it before upgrading across a range boundary.

A widening can also move GoVersion. The release kure widens to may raise the go directive of the dependency’s own Go module, and kure’s go.mod must then declare at least that version, so the Go toolchain needed to build kure, and any module that requires it, rises with the range (external-secrets v2.13.0, go-kure/kure#1057). The widening’s note in docs/compatibility.md records such a raise.

An MVS-floor entry (FloorModule != "") moves on a different trigger: its pin tracks whichever version floor_module itself currently requires, tag or pseudo-version, whether or not that’s kure’s own dependency bump (see docs/dependency-updates.md’s “MVS-floor dependencies” section for why there is no independent range to gate there).

Regenerating

Never edit versions_gen.go by hand:

mise run versions:generate    # ./scripts/sync-versions.sh generate
mise run versions:check       # fails if the committed file has drifted (also run in CI)

Removing an infrastructure key an external consumer looks up is a breaking change for them even though no Go signature moved — see the organization API stability contract before doing it.