A CI job runs `helm template` and emits a different apiVersion than the cluster install does — why, and how do you fix the render?

This is the standard way an offline render lies to you, and it is worth walking through a concrete case. ### The incident shape A platform team installs a third-party ingress-controller chart from a public repository in front of a telemetry ingest gateway, driven by an 11-value override file per environment. CI renders the chart on every pull request and posts the diff for review. After a cluster upgrade the reviewed diff still shows the older beta apiVersion for one object, while the object that actually lands in the cluster carries the newer stable one. Nobody edited the chart; the two renders simply answered `.Capabilities` from different sources. ### Why the offline render differs `helm template` renders locally. It opens no connection to a cluster, which is the entire point: it works on a laptop with no kubeconfig and in a CI runner with no cluster credentials. But a chart branching on `.Capabilities` still has to be given answers, so Helm supplies a default capability set that is compiled into the binary. Its Kubernetes version tracks the client libraries that Helm build was compiled against — not your cluster — and its API list is a minimal set rather than the couple of hundred group/versions a real cluster advertises. The practical result: `Has` returns false for almost everything, and every version comparison is measured against a number nobody chose deliberately. ### Fixing the render Describe the target on the command line: ```bash helm template gateway ingress-controller/ingress-controller \ --values env/prod-gateway.yaml \ --kube-version v1.31.4 \ --api-versions policy/v1 \ --api-versions autoscaling/v2 ``` `--kube-version` sets what `.Capabilities.KubeVersion` reports. `--api-versions` adds entries that `.Capabilities.APIVersions.Has` will find, and it can be repeated. Note that neither flag implies the other: setting the version does not populate the API list, and listing APIs does not change the version. Charts that branch on both need both flags. Keep the pair beside the environment's values file, so the render is described in one reviewable place per environment rather than in ad-hoc pipeline arguments. ### Keeping the list honest A hand-written `--api-versions` list drifts the moment a cluster is upgraded or an operator is installed. Generate it instead: have a scheduled job read the served group/versions from each target cluster and commit the result next to that environment's values, so drift arrives as a reviewable diff rather than as a silently wrong render. Anything that must be exactly right at render time should not use the recorded list at all. ### When to stop rendering offline Two cases defeat the flags entirely. If the chart calls `lookup`, an offline render always sees an empty result, and no flag changes that. If the set of served APIs is large enough that maintaining a list is fiction, you are simulating a cluster badly. In both cases render through the API server instead: ```bash helm upgrade --install gateway ingress-controller/ingress-controller \ --namespace telemetry --values env/prod-gateway.yaml --dry-run=server ``` That needs cluster credentials in the pipeline, which is a real cost and a real decision — but it produces the manifest the cluster would actually get. ### Pin the renderer One more trap: the default capability set belongs to the binary. A CI image that silently picks up a newer Helm ships a newer default Kubernetes version, so a chart branching on `.Capabilities.KubeVersion` can render differently with no chart, values or flag change. Pin the Helm version in the image and treat upgrading it as a reviewed change, exactly as you would a dependency bump. If a render diff appears with no source change, check the renderer version before you check the chart. ### What the offline render is good for Even done well, an offline render is a review artefact, not a proof. It shows what the chart produces under stated assumptions. Say what those assumptions are — version, API list, Helm version — and reviewers can judge the diff; leave them implicit and everyone reads a manifest that no cluster will ever receive.