Capabilities & Lookup

Helm renders charts with Go templates plus a large function library, and almost every one of those functions is pure: it transforms values that are already in front of it. `lookup` is the exception. It asks a live Kubernetes API server for an object while the template executes, which makes the rendered output depend on something outside the chart and its values. ### Signature and return shape `lookup apiVersion kind namespace name` returns a dict. With all four arguments filled in, that dict is the object itself, so `$found.metadata.labels` or `$found.data` behave as you would expect. With an empty name, the dict carries an `items` key holding the list of matching objects. With an empty namespace, the query is cluster-scoped, which is the right form for kinds that have no namespace. The call is synchronous: it happens at the moment the action is evaluated, once per render. ### What happens with no cluster `helm template` is a local command. It renders and prints, it opens no connection, and it does not need a working kubeconfig — that is precisely why pipelines like it. A client-side dry run behaves the same way for this purpose. In that mode Helm hands `lookup` an empty map. It does not raise an error, there is no error value to catch, and nothing in the output says a query was skipped. Every conditional written around the result therefore takes its false branch, and every field access on the result yields nothing. ### The ambiguity that bites The empty result is also exactly what you get when the render *does* reach a cluster and the object genuinely is not there. A template cannot distinguish the two, because both are an empty map. That is why `lookup` must never be the guard on a decision that destroys something: "if I cannot see it, it does not exist" is a false statement in exactly the situation where it matters most. ### The pattern that keeps breaking The most common use is generating a credential only when none is already present: ```yaml {{- $found := lookup "v1" "Secret" .Release.Namespace "gateway-credentials" }} data: {{- if $found }} password: {{ index $found.data "password" }} {{- else }} password: {{ randAlphaNum 24 | b64enc }} {{- end }} ``` Run by an engineer whose kubeconfig points at the cluster, this preserves the existing password. Run by a CI job that renders offline, it mints a new one on every render — harmless as noise in a diff, and destructive the moment such a render is actually applied, because the live Secret is rewritten while running pods still hold the old value. Worse, the behaviour depends on *who ran it*, which is the hardest class of bug to reproduce. ### Where `lookup` really does resolve Any operation that talks to the cluster: `helm install`, `helm upgrade`, `helm rollback`, and a server-side dry run, where the render is pushed through the API server rather than staying local. A server-side dry run is therefore the honest way to preview a chart whose output depends on cluster state — at the cost of needing cluster access, which a plain offline render does not. ### Consequences for pipelines Because `lookup` is re-evaluated on every install and upgrade, the rendered manifest is not a pure function of chart plus values. Two consequences follow. First, an offline render in CI is no longer proof of what will be applied, so review artefacts built that way can be quietly wrong. Second, any system that renders the chart itself — a GitOps controller such as Argo CD or Flux, for example — produces its own answer to the same `lookup`, which may differ from yours. ### What to do instead Make the value explicit. Let the caller pass an existing-secret name through values, or let an external secret operator own the credential and have the chart reference it. Keep `lookup` for genuinely optional adaptations where an empty answer is a safe answer — adding a label if some other object happens to exist, for instance — and write the template so that the empty case is the conservative one.