What does Helm's --history-max control, and what does exceeding it remove?

### What the limit does Each revision of a release is a separate record object, and each record embeds a full copy of the chart, the supplied values and the rendered manifest. Left unbounded, a release that is upgraded on every merge accumulates one such record per deploy forever. `--history-max` is the bound: after a new revision is written, Helm deletes the oldest records for that release until at most that many remain. The default is 10, and `0` disables trimming entirely. Two details matter for reading `helm history` correctly. First, revision numbers are monotonic — trimming does not renumber anything, so history's lowest revision simply climbs over time. A telemetry ingest gateway deployed 214 times under the default shows revisions 205 to 214, not 1 to 10. Second, trimming touches only Helm's records. No Deployment is deleted, no rollout is triggered, nothing about the running system notices. ### What you actually lose The stored record is the entire basis for rolling back: `helm rollback N` reads revision N's record and re-applies the chart, values and manifest it holds. Delete the record and there is nothing to roll back to. So the retention number is not a housekeeping preference — it is literally how far back you can go. A cap of 3 on a service that deploys ten times a day means your rollback horizon is about twenty minutes of deploy activity, and a bad change discovered the next morning has no stored good revision to return to. That is the tension the question is really about. Small numbers keep the cluster's datastore healthy but shorten the safety net; large numbers preserve the safety net and multiply the storage each release consumes, since every retained revision carries its own chart copy. The reasonable posture is to size retention against how quickly you would realistically detect a bad deploy, and to notice that the answer differs between a batch job upgraded twice a year and a gateway upgraded hourly. ### It is a flag, not a setting `--history-max` is passed per invocation. It is not recorded on the release, and there is nothing in the release that remembers what the last caller asked for. The practical failure this produces: a CI pipeline standardises on `--history-max 30`, an engineer runs a manual `helm upgrade` during an incident without it, and that one command trims the release back to the default of 10 — quietly deleting twenty revisions of rollback history at the exact moment history is most valuable. If you care about the number, it goes in the wrapper script or the deploy template that every path uses, including the break-glass one. The same invocation-scoped nature means changing your mind is cheap in one direction and not the other: raising the cap only takes effect for revisions that still exist, because the ones already trimmed are gone for good. ### Why the numbers add up faster than expected Because the record embeds the chart, the size of one revision is driven by what the chart carries, not by what changed. Upgrading with a single value flipped — say raising a hook timeout to 96 seconds — writes a record just as large as the initial install, since the chart and rendered manifest are stored again in full. A large umbrella chart with subcharts can produce records of several hundred kilobytes each, and ten of those, times a few hundred releases, is a real number in the cluster's datastore. Compression helps enormously and is already applied, but it does not change the shape: cost is roughly (record size) × (retention) × (releases). That gives you two independent levers, and it is worth being clear that they solve different problems. Retention controls the *number* of records, and is the right lever for datastore pressure across an estate. It does nothing whatever for a *single* record that is too large to be written at all — that ceiling is per object, and trimming history to three will not make revision 8 fit. ### Operationally Set retention deliberately, once, in the path everyone deploys through. Pick it from your detection window rather than from a round number. Expect `helm history` to show a sliding window rather than the beginning of time, and do not treat that window as an audit trail — it is a rollback buffer that will be trimmed by the next few deploys. If you need the record of what was deployed and when to survive longer than that, it belongs somewhere outside the release store.