Helm Capabilities & kubeVersion Gating Prompt
Make a chart render correct apiVersions across clusters using .Capabilities checks and Chart.yaml kubeVersion constraints, instead of shipping manifests that fail on older or newer clusters.
- Target user
- Chart authors supporting multiple cluster versions
- Difficulty
- Intermediate
- Tools
- Claude, ChatGPT, Cursor
The prompt
You are a senior chart author maintaining one chart that installs onto clusters ranging several minor versions apart. I want the chart to render the right APIs everywhere and fail loudly when it genuinely can't.
I will provide:
- The chart templates (or the resources it ships: HPA, Ingress, PDB, CronJob, etc.)
- The range of Kubernetes versions the chart must support
- Any version-specific behavior (a field that moved GA, an API that was removed)
Your job:
1. **Inventory version-sensitive resources**: any object whose apiVersion or fields changed across the supported range — autoscaling/v2 HPA, networking.k8s.io/v1 Ingress, policy/v1 PDB, batch/v1 CronJob, etc.
2. **Choose the right gate per resource**:
- `.Capabilities.APIVersions.Has "group/version/Kind"` — render based on what the target cluster actually serves (best for picking apiVersion)
- `.Capabilities.KubeVersion` semver comparisons — gate on cluster version when a field, not a whole API, changed
- `Chart.yaml` `kubeVersion:` constraint — hard floor/ceiling that makes `helm install` refuse an unsupported cluster up front
3. **Write the conditional template** that emits the correct apiVersion per cluster, with a clear `{{- fail ... }}` when no supported version is available so a user gets a real error, not a server-side rejection.
4. **Warn about the `helm template` gap**: `--dry-run`/`template` use built-in capability defaults unless you pass `--kube-version` / `--api-versions`, so CI rendering can mask a problem that only appears on the real cluster — show the flags to make CI render each supported version.
5. **Set the `kubeVersion` constraint** in Chart.yaml and explain how it interacts with the per-resource gates.
6. **Mark anything** that could silently drop a resource (a gate that evaluates false and emits nothing) as a correctness risk to test.
Output format: the version-sensitivity table, the conditional templates, the Chart.yaml constraint, and the CI render matrix commands. Render-and-review only; do not install.
---
Chart resources: [PASTE or DESCRIBE]
Supported K8s range: [e.g. 1.27–1.31]
Version-specific behavior: [DESCRIBE]
Why this prompt works
A chart that ships to a fleet of clusters spanning several Kubernetes minors is a compatibility minefield: an apiVersion that was autoscaling/v2beta2 on an old cluster and autoscaling/v2 on a new one, an Ingress field that moved, a PDB that changed groups. Ship one fixed apiVersion and the chart fails on half your clusters; guess wrong and the failure is a confusing server-side rejection at install time. Helm gives you .Capabilities and kubeVersion to handle this properly, but they interact in ways that bite people — especially the fact that helm template lies about capabilities unless you tell it the target version.
This prompt works because it inventories version-sensitive resources first and then picks the right gate for each: API-presence checks for choosing apiVersions, semver checks for field-level changes, and the Chart.yaml constraint as a hard floor. The standout is forcing the {{- fail }} branch and the CI render-matrix flags. A capability gate that quietly evaluates false and emits nothing is the worst outcome — a resource silently missing — and the only defense is rendering against each supported version and asserting the object exists. This prompt makes that explicit.
It keeps the workflow render-and-review: the assistant writes the conditionals and the matrix commands, and you confirm each cluster version produces the resources you expect before any install. For removed-API migrations on the cluster side, see the Kubernetes & Helm guides and the prompt library.
Related prompts
-
Helm Chart Major-Version Values Migration Prompt
Plan a breaking Helm chart major-version upgrade — diff the values schema, map renamed and removed keys, handle CRD upgrades, and stage the upgrade so the new template renders against your existing config safely.
-
Helm Template & Values Debug Prompt
Debug Helm template rendering — values precedence, scope (with/range), named templates, `helm template --debug`, partial templates, conditional logic.
-
Kubernetes Deprecated & Removed API Migration Prompt
Find and remediate deprecated/removed API usages (in live objects, Helm charts, and CI) before a version bump breaks them, using kubent, Pluto, and the API deprecation guide.