Values API Design

### values.yaml is the chart's default configuration, not its documentation A Helm chart is a directory of templates plus `values.yaml`. When someone runs `helm install rr ./reranker` with no other input, Helm merges nothing on top: the templates render against exactly what `values.yaml` contains. That makes the file the chart's default configuration, and the unedited install the path most people take first - when they evaluate the chart, when they run it in a scratch namespace, and when CI renders it to check a change. If that path produces broken YAML, an image nobody outside your network can pull, or a workload that demands cluster-admin, the chart has failed before anyone has read a template. ### Rule one: every path a template reads must exist Helm renders with Go text/template, and the failure modes for missing keys are asymmetric. Reading a key that is absent from a map that *does* exist yields an empty value, which usually renders as a blank field. Reading through a map that is itself absent is fatal: if `values.yaml` has no `metrics` key at all, `{{ .Values.metrics.port }}` aborts with `nil pointer evaluating interface {}.port`. So the whole shape of the values tree should be written out, including the parts that are empty. A block like ```yaml podAnnotations: {} nodeSelector: {} tolerations: [] extraEnv: [] ``` costs four lines and removes an entire class of report. It also documents the type: `{}` tells a reader the key is a map and `[]` tells them it is a list, which matters because they will be pasting YAML into it. Writing `podAnnotations:` with nothing after it makes the value null, which is not the same as an empty map and behaves differently once a template tries to range over it. ### Rule two: defaults must be environment-neutral A default that only works inside your company is not a default. That means no internal registry mirror, no cluster-local DNS name for a database, no bucket name, and above all no credential. A values file travels with the chart into a public repository, into a packaged tarball, into every checkout of the repo that vendors it; treating it as a place to park a token is the single worst thing you can do to a chart. The neutral choices are a publicly pullable image reference, an in-chart Service name for anything the chart itself deploys, and an empty string for anything external. ### Rule three: no honest default means fail loudly, not plausibly Some inputs genuinely have no sensible default - the endpoint of a feature store, a licence key, the hostname an Ingress should answer on. The wrong fix is a plausible placeholder, because a placeholder installs successfully and then fails at runtime, in a pod log, at whatever hour someone notices. The right fix is a key present in `values.yaml` with an empty value and a comment, plus `{{ required "reranker.featureStoreUrl must be set" .Values.reranker.featureStoreUrl }}` in the template. `required` is one of the functions Helm adds on top of sprig; it aborts `helm install`, `helm upgrade` and `helm template` with your message and nothing is created. The candidate who knows this also knows the cost: `required` fires on every render, so it makes an unedited `helm template` fail, which is a deliberate trade - a chart that cannot render without an input is telling you so at the earliest possible moment. ### Rule four: the unedited install should be modest Defaults are also a security and capacity statement. One replica rather than nine, no `hostNetwork`, no privileged container, no cluster-scoped RBAC unless the chart's whole purpose is cluster-scoped, and a service type that does not silently provision a public load balancer and a bill. `helm create` models this: it ships `resources: {}` with commented suggestions rather than guessing numbers, precisely because the right requests depend on the cluster, and it leaves autoscaling disabled. Where you do pick a number, pick one that is obviously a starting point and say so in a comment next to it. ### How this is checked The cheap check is mechanical and belongs in CI: render the chart with no values at all and assert the output parses. Then render it again with each documented example values file. Most defaults defects - a missing intermediate map, a null where a list was meant, an indentation break from an empty block - surface in that first render, long before a cluster is involved.