Releases & Upgrades

helm upgrade --install upgrades a release when one with that name already exists in the namespace and installs it when none does. Pipelines use it because the same command works on the first deploy and every deploy after it.

Helm sorts every rendered manifest by Kubernetes kind using a fixed, hard-coded list: Namespace first, then config and RBAC, then Service, then workloads, then Ingress. File names under templates/ do not decide the order.

An object of that kind and name is already in the cluster and does not carry this release's Helm ownership metadata. Helm refuses to overwrite anything it cannot prove belongs to the release being applied.

Helm writes one Secret per release revision into the release's own namespace, named sh.helm.release.v1.<name>.v<rev> with type helm.sh/release.v1. It carries the chart, the values supplied, the rendered manifest and the status, as JSON that is gzipped and base64-encoded.

helm history <release> prints one row per stored revision: the revision number, when it was written, its status (deployed, superseded, failed or a pending state), the chart name with its chart version, the app version, and a description.

--rollback-on-failure makes helm upgrade restore the previous release revision automatically when the upgrade fails, so no half-applied change is left running. In Helm 4 --atomic is a deprecated alias of that same flag.

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.

It stops Helm patching the existing object and has it removed and created again from the rendered manifest, which is how a change to a write-once field such as a selector lands. Everything the object manages is torn down and rebuilt, so it means an outage.

Revision 6. helm rollback never rewinds the counter: it appends a new revision holding revision 3's content, marks revision 5 superseded, and leaves 3, 4 and 5 in history with their original numbers.

Helm can only roll back failures it has observed. Setting --rollback-on-failure therefore defaults the wait strategy to watcher, so Helm stays until the release is ready; without waiting it would exit successfully before crash-looping pods ever appeared.

Helm 4 installs with server-side apply: on helm install --server-side is a boolean defaulting to true. On helm upgrade and helm rollback it is a string defaulting to auto, which reuses whatever apply method the previous revision used.

It means the release's newest stored revision still has a pending status, so Helm refuses to start a second write. Usually nothing is running: an earlier helm process was killed before it could record a terminal status.

In Helm 4 --wait names a strategy, not a boolean: watcher (event-driven, kstatus-based), legacy (Helm 3's polling waiter), or hookOnly. Bare --wait means watcher; omitting it leaves hookOnly, so Helm does not wait for workloads.

Helm only deletes objects listed in the release's stored manifest. Claims created by the StatefulSet controller were never rendered, so Helm has no record of them, and CRDs installed from a chart's crds/ directory are deleted by Helm never, by design.

They are the in-flight statuses Helm writes on a revision before it touches the cluster, one per operation: a first install, an upgrade, a rollback. Seeing one after the operation ended means the revision was never finished.

--timeout is the budget for the waiting Helm does during a release: hook execution and, when a wait strategy is on, readiness. It takes a Go duration string such as 9m30s and defaults to 5m0s.

--force-replace abandons updating an object and recreates it, which is how a change to a write-once field lands. --force-conflicts keeps the normal apply but overrides another field manager's ownership. Only the first clears an immutable-field failure.

A Helm release name must be unique within its namespace, not across the cluster. The same name in two namespaces is two independent releases, and one chart can be installed twice in one namespace under two different names.

No. Helm renders the parent and every subchart into one flat set of manifests and applies the fixed kind sort across all of them together, so a subchart's Service goes before the parent's Deployment. Charts are not sequenced.

Either put Helm's ownership metadata on the live object by hand — the managed-by label and the two meta.helm.sh annotations — then upgrade; or pass --take-ownership (Helm 3.17), which claims the object and writes that metadata for you.

It caps how many revision records Helm keeps for one release, defaulting to 10. When an upgrade exceeds the cap, Helm deletes the oldest records, so those revisions leave helm history and can no longer be rolled back to.

No re-render. Each revision record carries the chart, the supplied values and the fully rendered manifest, and helm rollback re-applies that stored manifest. Nothing is fetched, so a deleted chart version or an unreachable repository does not block a rollback.

Helm 3 built the patch itself from three inputs: the manifest stored with the previous revision, the newly rendered manifest, and the live object. Helm 4 sends the whole rendered object and the API server merges it, tracking which manager owns each field.

helm.sh/resource-policy: keep tells Helm to skip deleting that object when an operation would otherwise remove it — uninstall, or an upgrade that drops it from the chart. The object survives as an orphan Helm no longer manages.

The StatefulSet object has to be recreated, so the decision is how. --force-replace takes every pod down at once; removing the object out-of-band while leaving its pods running lets the next upgrade recreate it with no gap; renaming it makes a fresh object and needs a data migration.

Release names are unique per namespace, but ClusterRoles, CustomResourceDefinitions and webhook configurations have one cluster-wide name. A second release of a chart that renders them collides on objects the first release already owns, whatever namespaces the two live in.

Job sits near the end of Helm's hard-coded install-order table, behind Deployment and StatefulSet, and nothing in a chart can move it. Even if it sorted first, Helm submits manifests without waiting, so the Job would still not be finished.

It turns off Helm's ownership check for the whole run, so the release claims every object it collides with — including ones another release owns — and each claimed object is then deleted by a later uninstall. Stamp the specific objects instead.

The record embeds the whole chart plus supplied values and rendered manifest, gzipped into one Secret the API server rejects past roughly 1 MiB. Shrink what the chart carries, split the release, or change backend; trimming history will not help.