versions

package
v0.2.0-beta.23 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 30, 2026 License: Apache-2.0 Imports: 0 Imported by: 0

README

Versions - Supported-Version Metadata

Go Reference

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 range also does not say that every kind kure emits applies at its lower bound. Some kinds are emitted at an API version the dependency first served later in the range, so their floor is higher. For example, the fluxcd range starts at 2.4, but OCIRepository v1 needs 2.6 and Provider/Alert v1 need 2.10. SupportedRange/Min/Max carry the range only. The per-kind floors are in the notes, which this API does not export.

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.

A widening can also come with a replace. The release kure widens to may require a transitive module at a version that does not build with kure's other pins, and kure then holds that module back with a replace in its go.mod. Go applies replace directives only in the main module, so a module that requires kure and resolves the same versions needs the same line in its own go.mod (external-secrets v2.14.0 and k8s.io/kube-openapi; see docs/dependency-updates.md). The widening's note in docs/compatibility.md records such a requirement.

A widening can also change the Go types a caller writes to. kure's builders hand back upstream structs, and a module that requires kure builds against at least the dependency version kure pins, so a release that removes or retypes a field breaks a caller's assignment to it even when kure's own code uses none of them (gateway-api v1.7.0 reshapes the experimental-channel SessionPersistence and retypes ForwardBodyConfig.MaxSize). The widening's note in docs/compatibility.md names such fields.

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).

The kustomize entry is not a deployed tool's range either. Kustomize runs inside kustomize-controller, so its SupportedRange names the kustomize library line kure builds and tests the Kustomizations it writes with, in the sigs.k8s.io/kustomize/api module's own terms (0.21 is kustomize v5.8). It holds only the line kustomize-controller pins, and moves only when that pin moves. kure reaches that version through replace directives in its go.mod, which apply to kure alone: a module that requires kure resolves the version minimum-version selection picks unless it carries the same directives (docs/dependency-updates.md, "Kustomize").

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.

Documentation

Overview

Package versions exposes kure's supported-version metadata as a stable Go API, so consumers do not have to parse versions.yaml key paths by hand.

The data in versions_gen.go is generated from versions.yaml by scripts/sync-versions.sh; `./scripts/sync-versions.sh check` (run in CI) fails if the generated file has drifted from versions.yaml.

Only machine-readable fields are exported. Reviewer prose (notes, related_packages), the release-pinning fields, and the go.mod build version are omitted: the build version moves on every dependency bump, and the others can change too (prose edits, a release-pinned dependency being re-pinned) even though not every routine bump touches them. Excluding all of them keeps this API's content stable rather than tied to prose or pin churn.

Index

Examples

Constants

View Source
const GoVersion string = "1.27.3" // doc-gate:trivial

GoVersion is the go.current field of versions.yaml.

Variables

This section is empty.

Functions

This section is empty.

Types

type Dependency

type Dependency struct {
	// Name is the versions.yaml key, e.g. "kubernetes".
	Name string
	// GoModule is the Go module path kure imports for this dependency.
	GoModule string
	// SupportedRange is the raw supported_range, e.g. "1.33 - 1.36" -- the
	// range of deployed tool versions kure targets, not the build version.
	SupportedRange string
	// Min is the low bound of SupportedRange, major.minor.
	Min string
	// Max is the high bound of SupportedRange; equals Min for a
	// single-value range such as "0.5".
	Max string
	// VersionBasis is "semver" (default) or "kubernetes" -- the latter for a
	// module versioned v0.N.x whose range is expressed in cluster terms (1.N).
	VersionBasis string
	// FloorModule 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. When non-empty,
	// SupportedRange, Min and Max are empty -- there is no hand-maintained
	// range to report, since kure never chose this version. Empty for every
	// other entry.
	FloorModule string
}

Dependency is one infrastructure entry's machine-readable metadata.

func All

func All() []Dependency

All returns every infrastructure dependency, in versions.yaml document order. The returned slice is a copy; callers may modify it freely.

func Get

func Get(name string) (Dependency, bool)

Get returns the dependency stored under the given versions.yaml key. ok is false when no such entry exists.

Example
package main

import (
	"fmt"

	"github.com/go-kure/kure/pkg/versions"
)

func main() {
	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
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL