How do you decide between Chart.yaml `kubeVersion` and `.Capabilities` branching for a chart installed across many cluster versions?

Both mechanisms answer "which Kubernetes versions does this chart work on?", but they answer it to different audiences and at different moments, and a published chart usually needs both. ### What each one actually does `kubeVersion` in `Chart.yaml` is a semver range evaluated before anything is applied. If the target cluster's reported version falls outside it, Helm refuses the operation and says the chart requires a version the cluster does not satisfy. It is a *declaration*: here is what we support, and we would rather stop than produce something untested. It is checked per operation, so an existing release is never retroactively broken by tightening it — the next upgrade simply stops. `.Capabilities` branching is evaluated during rendering and changes what the chart emits: a different apiVersion, an object included or omitted, a field set or left out. It is an *adaptation*: we support the whole span, and here is how we bend to fit each end of it. ### The costs, honestly A floor costs consumers: someone on an older cluster is simply blocked, and if the floor is aggressive they will fork the chart rather than upgrade a cluster on your schedule. It buys you a small, testable surface and an unambiguous error instead of a mysterious failure three steps later. Branching costs you. Each independent capability test doubles the render permutations that should be exercised, and in practice teams test the version they run and leave the other branch to rot. The failure mode is quiet: a branch that has been broken for a year is discovered by whichever consumer is unlucky enough to be on the old cluster. ### The bounds pitfall Write the range so real clusters match it: ```yaml apiVersion: v2 name: telemetry-gateway version: 4.2.0 appVersion: "2.11.3" kubeVersion: ">=1.29.0-0" ``` The `-0` matters. Clusters routinely report versions carrying a suffix after the patch number, and a semver constraint with no prerelease component excludes anything that has one. A bound of `>=1.29.0` can reject a cluster that is obviously newer than 1.29.0, and the reported error looks like a Helm bug to the person hitting it. Also decide deliberately whether to write an upper bound: it protects you from untested future versions and guarantees that every consumer is blocked the week their platform team upgrades. ### The third and fourth options Branching and gating are not the only choices. You can **cut a new chart major version**: raise the floor there, keep the old line available in the repository, and let consumers pin the `version` they can run. This is often the cleanest answer for a widely-consumed chart, because a consumer's upgrade of the chart and of their cluster become one decision they schedule themselves. You can also **push the decision to the values contract**: instead of detecting, require the consumer to declare what they want, which is honest when the difference is a policy choice rather than a hard capability. ### Making branches survive Whatever you keep, render it. A CI matrix that runs `helm template` once per supported version, with that version's API list, and compares against committed golden output turns a rotten branch into a diff: ```bash for kv in v1.29.11 v1.30.7 v1.31.4; do helm template gateway . --kube-version "$kv" \ --api-versions policy/v1 > "renders/$kv.yaml" done ``` The matrix also documents the support claim: the versions in that loop should be exactly the versions the floor admits. When you raise the floor, the same change should delete the branches below it — otherwise the chart accumulates code for clusters it now refuses to install on, which is the worst of both worlds. ### How I would land it Declare a floor that matches what you actually test, with a prerelease-tolerant bound and usually no upper bound. Branch sparingly, at the edges of the chart rather than in its core workload, and prefer the group/version/kind form of the capability test so the condition says exactly what it needs. Put every branch in the render matrix. Review the floor on a fixed cadence rather than when someone complains, and when raising it, ship it as a chart major with release notes rather than as a quiet metadata edit — the consumers pinning your chart are the ones who will feel it first.