skip to content

What does helm uninstall remove, and what does the --keep-history flag change?

level: juniorimportance: must knowfreq 74%

answer

  1. Uninstall works from a list, not a search
  2. Two halves: the objects, then the records
  3. One flag keeps only the second half
  4. An invisible release can still hold its name
  5. Helm 4 lists every status by default

basics

~10 s

helm uninstall deletes the Kubernetes objects recorded in the release's stored manifest, then deletes the release records, freeing the name. --keep-history keeps those records instead, so the release stays in history with status uninstalled.

solid answer

~40 s

`helm uninstall <name> -n <ns>` reads the release's stored manifest, deletes the objects listed in it, and then deletes the release records themselves, which frees the name for reuse in that namespace. It only ever touches what that manifest contains: objects annotated `helm.sh/resource-policy: keep`, CRDs installed from the chart's `crds/` directory, PersistentVolumeClaims a controller created rather than Helm, and the namespace itself all survive. `--keep-history` changes only the second half — the objects still go, but the release records stay with status `uninstalled`, so `helm history` still lists the revisions, the release can be rolled back to an earlier revision, and the name stays occupied until that stored record is removed. In Helm 4 `helm list` shows uninstalled releases by default; Helm 3 needed `-a`/`--all` or `--uninstalled`, and `-a` no longer exists.

code

bash · 8 lines
bash
# See exactly what uninstall will delete, before deleting it
helm get manifest re-ranker -n platform | grep -E '^kind:|^  name:'

# Delete the objects but keep the release record
helm uninstall re-ranker -n platform --keep-history

# The release is still there, with status uninstalled
helm history re-ranker -n platform

go deeper

for a junior

Be ready to say in one breath that uninstall deletes the release's objects and its history, and that --keep-history keeps the history. Know that you must pass -n for the right namespace or Helm will not find the release at all.

for a middle

Explain the mechanism: Helm deletes the objects listed in the stored manifest of the current revision, then removes the release records. Be able to name at least two things that survive because they were never in that manifest.

for a senior

An interviewer expects you to connect --keep-history to real incidents: a CI redeploy failing on an occupied name, and the false comfort of thinking a retained record protects data. Show how you check the delete set before running it.

for a principal

Own the policy question of whether uninstall is ever allowed to run unattended in production, and what evidence a teardown must leave behind. Retained history is an audit artefact with a cost — an occupied name and a stale record nobody prunes.

### What a release actually is A Helm release is two things at once: a set of live Kubernetes objects, and a stored record of the revisions that produced them. The record lives in the release namespace as a Secret per revision, named `sh.helm.release.v1.<name>.v<rev>`, and it contains — among other things — the rendered manifest of that revision. That stored manifest is the authoritative list of what Helm believes it owns. Every write-path operation, uninstall included, is driven from it. ### What uninstall does, step by step `helm uninstall <name>` is namespace-scoped, so `-n` (or `HELM_NAMESPACE`) has to point at the release's namespace or Helm will simply report that the release is not found. Given the release, Helm loads the current revision's stored manifest, decodes it into a list of objects, and deletes them. It then removes the release records, and the name becomes available again for a fresh `helm install`. The consequence worth internalising is that Helm's delete set is a list, not a query. Helm does not sweep the namespace, does not search by label, and does not ask the API server what belongs to the release. If an object is not in the stored manifest, uninstall will not consider it — which is why controller-created children such as StatefulSet PersistentVolumeClaims outlive the release. Two categories are additionally skipped even though Helm knows about them: objects carrying `helm.sh/resource-policy: keep`, and CRDs installed from the chart's `crds/` directory, which Helm never deletes on uninstall by design. The namespace is another survivor. Even a namespace Helm itself created at install time with `--create-namespace` is not removed by uninstall. ### What --keep-history changes `helm uninstall --keep-history <name>` still deletes the objects. What it preserves is the release record. The release remains in the store with status `uninstalled`, so: - `helm history <name>` still prints the revision table, with the last row showing the uninstalled status; - `helm rollback` can bring an earlier revision's objects back, because the manifest that describes them is still stored; - the release **name remains occupied** in that namespace, so a plain `helm install` under the same name is rejected. You get the name back by removing the retained record. That last point is the one that bites in practice. A team uninstalls with `--keep-history` for auditability, redeploys through CI a day later, and the pipeline fails on a name collision with a release nobody can see running anywhere. ### Finding uninstalled releases This is one of the few genuinely version-sensitive corners of the command. In Helm 3, `helm list` showed only deployed releases and you reached the uninstalled ones with `-a`/`--all` or the `--uninstalled` status filter. **Helm 4 removed `-a`/`--all`**: `helm list` returns every status by default, and the status flags now only narrow the result. `-A`/`--all-namespaces` is a different flag and is unaffected. Writing `helm list -a` into a Helm 4 script is a hard failure, not a no-op. ### Rollback is not undelete Rolling back an uninstalled release re-creates the objects the stored manifest describes. It does not restore state that lived inside them. A Deployment comes back identical; a database whose PersistentVolumeClaim was rendered by the chart and therefore deleted by uninstall comes back empty. Treat `--keep-history` as a way to keep the paperwork and the ability to re-materialise the shape of the release, not as a safety net for data. ### Reading the delete set before you run it Because the delete set is exactly the stored manifest, you can see it in advance: `helm get manifest <name> -n <ns>` prints the objects uninstall will attempt to delete. Anything in the namespace that is not in that output will still be there afterwards. Making that check a habit turns uninstall from an act of faith into a reviewable diff, and it is the fastest way to answer the follow-up question every interviewer asks next: what is left over?

  • Why does a release uninstalled with --keep-history block a fresh install under the same name?
    Release names are unique per namespace, and uniqueness is judged against the stored records, not against what is running. The retained record still claims the name even though every object it described is gone, so Helm rejects a new install under it. Removing the retained record is what frees the name.
  • Does helm uninstall delete the namespace it created with --create-namespace at install time?
    No. Helm creates the namespace as a convenience at install time but never records it as part of the release, so uninstall leaves it in place along with anything else in it that Helm did not render. Deleting the namespace is a separate, deliberate act.
  • If you roll back a release you uninstalled with --keep-history, do you get your data back?
    You get the objects back, not their contents. Rollback re-applies the stored manifest of the chosen revision, so Deployments, Services and ConfigMaps return as declared. Any state that lived in a claim the uninstall deleted is gone; rollback has nothing to restore it from.

Uninstall is a moving crew working from an inventory sheet, not from a walk-through of the flat. Anything the sheet never listed stays behind, and --keep-history means they file the sheet instead of shredding it.

saying these in an interview costs you the question

  • Claims uninstall wipes everything the chart ever touched
  • Thinks --keep-history keeps the running objects alive
  • Believes the release name is free after --keep-history
  • Says helm uninstall deletes the namespace too
  • Uses helm list -a on Helm 4 and expects it to work
  • Treats rollback of an uninstalled release as data recovery

context

resolving links…