How do you decide how wide to make a shared Helm chart's values.yaml surface?

### Two ways to get this wrong A chart's values surface fails in opposite directions, and both are expensive. **Too narrow.** A team needs a toleration you did not anticipate. They cannot express it, so they copy the chart into their own repository and add three lines. Your next fix never reaches them. Multiply by a handful of teams and the platform chart is now five slowly diverging charts, and you find out at the worst possible moment - during an incident, when the fix you shipped turns out not to be running anywhere. **Too wide.** Every request became a key. The chart is now a YAML re-encoding of the pod spec with no opinion left in it: hundreds of keys, every install unique, no two consumers exercising the same render path, and no refactor possible because any template change might move a key someone depends on. The chart has stopped being a package and become a very slow templating library. The judgement is where to sit between them, and it is a judgement about *purpose*, not about taste. ### The rule: guarantee, variance, tail Sort every candidate setting into one of three buckets. **Guarantees** are the reason the chart exists. If the platform's job is that every workload runs unprivileged with a read-only root filesystem and carries the labels the fleet's tooling depends on, those are rendered from the template unconditionally. Crucially, a guarantee must not be shipped as a *default*, because a default with a values key behind it is exactly as strong as the weakest team's willingness to override it, and the override happens at 2 a.m. during an incident and is never reverted. If you cannot bring yourself to make it non-configurable, admit that it is not a guarantee. **Variance** is what legitimately differs per install and per environment: replica count, image reference, resource requests, scheduling constraints, ingress hostnames, the application's own configuration. This is the chart's real API, and it should be small, conventionally named, and documented. **The tail** is everything else - the one-off annotation, the sidecar's volume, the extra environment variable one team needs. Serve it with generic pass-through keys. The whole point is that the tail costs you nothing to support: you did not name it, you do not interpret it, and next quarter's request lands in a key that already exists. ### Evidence beats requests Deciding from a queue of feature requests biases the surface toward whoever asks loudest. Deciding from data does not. The values a caller supplied are stored with each release, so `helm get values` across every install of the chart - nine installs of a monitoring-stack chart across three clusters, say - tells you which keys are actually set, which are set to something other than the default, and which have never been touched by anyone. A key nobody has ever set is a maintenance liability with no benefit. A default that every single install overrides is not a default; it is a wrong guess that should be changed, or a required input that should be declared as one. ### The hatch versus the guarantee The uncomfortable corollary of shipping a generic hatch is that it can be used to defeat the very things the chart is meant to enforce - a pass-through block can add a container, a volume, an annotation that changes how the fleet treats the workload. Templates are a poor place to police this: you would be writing a policy engine in Go template, badly, and it only ever inspects what arrives through *your* chart. The right shape is layered: the chart makes the good path easy and the fleet's admission policy engine makes the bad path impossible, applied to everything on the cluster regardless of whether it came from your chart, a hand-applied manifest, or someone else's. Where a chart-owned entry must survive a user's map, merge the user's entries beneath yours rather than trusting them to leave yours alone. ### Keeping the surface honest over time New keys arrive one plausible request at a time, which is how a surface becomes unmaintainable without anyone deciding it should. A workable discipline: a new key needs a second asker or a guarantee behind it; anything satisfiable by an existing hatch goes to the hatch; and the whole surface is reviewed against the collected release values periodically rather than never. The candidate who can articulate this is describing the difference between a chart the platform team owns and a chart the platform team is owned by.