Charts get the attention, but releases are what you actually operate.

Most introductions to Helm spend their time on charts, the packages that describe an application. That is natural, because charts are what people write and share. But once an application is running in a cluster, the chart is no longer the thing you work with every day. What you work with is the release: the specific, named installation of that chart, with its own settings, its own history, and its own current state.

Almost every practical question about Helm is really a question about a release. Which version of the application is running in production right now? What values were used the last time we upgraded? Why is the upgrade stuck? How do I go back to yesterday’s version? Can two teams install the same chart without disturbing each other? Every one of these questions is answered by understanding how releases are named, recorded, and changed.

What goes wrong when releases are misunderstood

Teams that do not understand releases often lose track of what is deployed, overwrite each other’s installations by accident, fail to recover from interrupted upgrades, or rely on rollback to protect things it cannot protect. These problems are avoidable. Once the release model is clear, Helm becomes predictable and much less stressful to use.

A named, tracked installation of a chart in one namespace of a cluster.

A Helm release is one instance of a chart that has been installed into a Kubernetes cluster. It is made of three things that always go together: the chart that was installed, the values that were used to customise it, and the set of Kubernetes resources that were created from the result. Helm gives the release a name and keeps a record of it, so it can recognise the installation later and change it in a controlled way.

The same chart can be installed many times. Each installation is a separate release with its own name, its own values, and its own life. Installing a database chart three times, for three different teams, creates three independent releases. They share the same blueprint, but they do not share state or settings. This is what makes charts reusable and releases safe to run side by side.

flowchart TD
    C[One chart
the blueprint] --> R1[Release: shop-db
values for the shop team]
    C --> R2[Release: blog-db
values for the blog team]
    C --> R3[Release: test-db
values for testing]
    R1 --> K1[Resources in the shop namespace]
    R2 --> K2[Resources in the blog namespace]
    R3 --> K3[Resources in the test namespace]
        

Every revision stores enough information to describe and repeat what happened.

Each time Helm installs, upgrades, or rolls back a release, it writes a record describing the result. This record is the release’s memory. Everything Helm can tell you about a release, and everything it needs to roll one back, comes from these stored records. Knowing what is inside them explains a lot of Helm’s behaviour and also shows why they deserve protection.

Why a copy of the chart is stored

Helm stores the chart itself inside each revision record. This is what makes rollback independent of where the chart came from. Even if the chart repository disappears or the chart is removed from your computer, Helm can still restore an earlier revision, because everything it needs is stored with that revision.

A release is identified by its name together with its namespace.

Every release has a name, chosen by the person who installs it, and it lives in one namespace. The pair of name and namespace identifies the release. Two releases with the same name can exist as long as they live in different namespaces, but within a single namespace each name must be unique. This scoping is a big improvement of the current major version over the first one, where names were global across the whole cluster.

Why names shape your resources

Most charts build the names of their resources from the release name, so that two releases of the same chart never clash. A release called shop-db might create a workload called shop-db and a service called shop-db. Choosing clear release names therefore also makes every resource in the cluster easier to recognise and search.

Every change adds a numbered entry, and nothing is silently overwritten.

A revision is a numbered version of a release. The first install creates revision one. Every upgrade creates the next number, and so does every rollback. The list of all revisions is the release history, and it is what lets you see exactly what changed and when. Because each revision stores its own chart, values, and manifests, any of them can be inspected or restored.

sequenceDiagram
    participant U as User
    participant H as Helm
    participant S as Release records
    U->>H: Install
    H->>S: Store revision 1
    U->>H: Upgrade with new image
    H->>S: Store revision 2
    U->>H: Upgrade with new setting
    H->>S: Store revision 3
    U->>H: Roll back to revision 2
    H->>S: Store revision 4 with the content of revision 2
        

Rollback moves forward in history

A common surprise is that rolling back to revision two does not make the release go back to being revision two. Instead, Helm creates a new revision, number four in the example above, whose content is a copy of revision two. The history therefore stays complete and honest: it shows the release was upgraded twice and then rolled back, rather than pretending the later revisions never happened.

A release always has a status, and each status tells you what to do next.

Each revision of a release carries a status that describes its condition. Reading the status is the fastest way to know whether a release is healthy, still being worked on, or in need of repair. There are a small number of statuses, and learning them removes most of the mystery from Helm’s output.

stateDiagram-v2
    [*] --> pending_install
    pending_install --> deployed: success
    pending_install --> failed: error
    deployed --> pending_upgrade: upgrade starts
    pending_upgrade --> deployed: success
    pending_upgrade --> failed: error
    deployed --> pending_rollback: rollback starts
    pending_rollback --> deployed: success
    deployed --> uninstalling: uninstall starts
    uninstalling --> uninstalled: history kept
    uninstalling --> [*]: history removed
        

From a chart and some values to a recorded, running release.

Installing a release turns a chart and a set of values into resources in a cluster and a first revision in history. Helm does this in a fixed sequence, and knowing the sequence helps you understand where failures can occur and what state a failed install leaves behind.

flowchart TD
    A[Install requested] --> B{Name free and values valid?}
    B -->|No| X[Stop, nothing created]
    B -->|Yes| C[Render templates]
    C --> D{Render succeeded?}
    D -->|No| X
    D -->|Yes| E[Record pending revision]
    E --> F[Create resources]
    F --> G{Resources accepted and ready?}
    G -->|Yes| H[Status: deployed]
    G -->|No| I[Status: failed]
        

An upgrade applies a new chart version or new values and records a new revision.

An upgrade changes an existing release. You may give it a newer version of the chart, different values, or both. Helm renders the new manifests, compares them with what is currently deployed, updates only what changed, and records the result as the next revision. The previous revision becomes superseded but remains in history.

The three-way comparison

To decide what to change, Helm compares three sources of information: the manifests from the last deployed revision, the live state of the resources in the cluster, and the newly rendered manifests. This is called a three-way merge. It lets Helm apply the differences between the old and the new chart while also noticing resources that were changed directly in the cluster, producing a more sensible outcome than simply overwriting everything.

flowchart LR
    OLD[Last deployed manifests] --> M[Three-way merge]
    LIVE[Live state in the cluster] --> M
    NEW[Newly rendered manifests] --> M
    M --> P[Patch sent to the cluster]
    P --> REV[New revision recorded]
        

Return to an earlier revision quickly, as long as you understand its limits.

When an upgrade goes badly, rollback lets you return the release to an earlier revision. You name the revision you want, or leave it out to return to the one before the current one. Helm takes the stored manifests of that revision, reapplies them to the cluster, and records the result as a new revision. Because the chart is stored inside each revision, rollback works even if the original chart is no longer available.

sequenceDiagram
    participant U as User
    participant H as Helm
    participant S as Release records
    participant K as Cluster
    U->>H: Roll back to revision 2
    H->>S: Read manifests of revision 2
    H->>S: Store new revision 4 as pending-rollback
    H->>K: Apply the older manifests
    K-->>H: Resources updated
    H->>S: Mark revision 4 deployed
        

Removal deletes the resources, and you decide whether the memory of them stays.

Uninstalling a release removes the resources that the release created. By default, Helm also removes the release’s history, so the name becomes free again. If you ask Helm to keep the history, the resources are still removed, but the records remain with an uninstalled status. You can then still see what was installed, and in some cases roll back to bring the release back to life.

Resources that should survive uninstall

Some resources are too valuable to remove automatically, such as storage that holds data. A resource can carry an annotation that tells Helm to keep it when the release is removed. Helm then leaves the resource in place and stops tracking it. This protects data, but the resource becomes an orphan that someone must eventually clean up.

flowchart TD
    U[Uninstall requested] --> H1[Run pre-delete hooks]
    H1 --> D[Delete tracked resources]
    D --> K{Any resource marked to keep?}
    K -->|Yes| KEEP[Leave it in the cluster, untracked]
    K -->|No| C[Continue]
    KEEP --> C
    C --> H2[Run post-delete hooks]
    H2 --> Q{Keep history?}
    Q -->|Yes| S[Status uninstalled, records kept]
    Q -->|No| G[Records removed, name free]
        

Helm can tell you almost everything about a release without touching it.

A large part of running releases well is knowing how to look at them. Helm provides read-only commands that show the list of releases, the status of one release, its history, the values it uses, the manifests it deployed, and the notes it produced. These commands are safe to run at any time and are the first tools to reach for when something looks wrong.

flowchart TD
    A[Something looks wrong] --> B[List releases
is the status deployed?]
    B --> C[Read history
what changed last?]
    C --> D[Read supplied values
are they what you expect?]
    D --> E[Read deployed manifest
is that what you intended?]
    E --> F[Inspect cluster resources
events and pod status]
        

What happens to your earlier choices when you upgrade is a frequent source of surprises.

When you upgrade a release, Helm needs to decide which values to use. By default, it does not carry over the values you supplied last time; it starts again from the chart’s defaults and applies whatever values you provide in this upgrade. This means that if you forget to pass your earlier customisations again, they silently disappear and the release changes back toward defaults.

The safest habit

The most reliable practice is to keep all your values in files under version control and pass the complete set on every upgrade. Then the release always reflects the files, no matter what was stored last time. This removes guesswork, makes upgrades repeatable, and makes it possible to rebuild a release from scratch in another cluster.

Helm marks what it creates, and refuses to take over what belongs to someone else.

Helm needs to know which resources belong to a release so it can update or remove them later. It does this by adding markers to every resource it creates: a label saying the resource is managed by Helm, and annotations recording the name and namespace of the release that owns it. When Helm later works on a release, it looks at these markers to be sure it only touches its own resources.

Conflicts and adoption

If a chart tries to create a resource that already exists and is not owned by that release, Helm stops with an error about the resource already existing. This protects you from two releases accidentally fighting over the same object. In some situations, though, you deliberately want a release to take over an existing resource, for example when moving hand-made resources under Helm’s management. This is done by adding the correct ownership markers to the existing resource, after which Helm adopts it.

flowchart TD
    A[Chart wants to create a resource] --> B{Resource already exists?}
    B -->|No| C[Create it and add ownership markers]
    B -->|Yes| D{Owned by this release?}
    D -->|Yes| E[Update it normally]
    D -->|No| F[Stop with an ownership error]
    F --> G[Remove it, rename it, or adopt it deliberately]
        

The power of separating the blueprint from its installations.

Because a release is an independent installation, you can create as many releases of the same chart as you need. This is the foundation of many practical setups: one release per environment, one per team, one per customer, or one per pull request. Each has its own values, its own history, and its own lifecycle, and changing one never affects the others.

flowchart LR
    CH[Chart version 2.0] --> D[dev release
values-dev]
    CH --> S[staging release
values-staging]
    CH --> P[production release
values-prod]
    D -->|promote after testing| S
    S -->|promote after approval| P
        

Records are ordinary cluster objects, with ordinary size limits.

By default, Helm stores each revision as a Secret in the release’s namespace, with a name that includes the release name and the revision number. The content is compressed and encoded to keep it small. Helm can be configured to use configuration maps instead, or a database, but secrets are the default and the most common choice.

The size limit

Kubernetes limits how large a single stored object can be, roughly one megabyte. A release record contains the entire chart, the values, and all the rendered manifests. For a very large chart, or one that embeds big files, the record can exceed the limit, and installs or upgrades fail with a size error. The remedies are to split the chart into smaller releases, remove large files from the chart, and avoid packing big data into values.

Hooks run at moments in a release’s life, but they are not fully part of it.

Hooks are special resources, typically short jobs, that Helm runs at defined moments of a release’s lifecycle: before or after install, upgrade, rollback, or deletion. They are recorded as part of the release, and Helm waits for them to complete before moving on. This makes them ideal for tasks such as database migrations before an upgrade, or cleanups after removal.

However, hooks differ from normal resources in one important way. Helm does not manage them as part of the release’s regular set of resources. When the release is upgraded or uninstalled, hook resources are not automatically updated or deleted unless a deletion policy says so. An unmanaged leftover job can block the next run of the same hook because of a name clash, or clutter the namespace.

sequenceDiagram
    participant H as Helm
    participant J as Pre-upgrade hook job
    participant K as Cluster
    H->>J: Start hook and wait
    J->>K: Run migration
    alt Job succeeds
        J-->>H: Completed
        H->>K: Apply upgrade
    else Job fails
        J-->>H: Failed
        H-->>H: Release revision marked failed
    end
        

Automation manages releases best when the desired state lives in version control.

In automated delivery, a release is the unit that pipelines create and update. A pipeline typically builds an image, updates the values or chart version, and runs the install-or-upgrade action against the target namespace, then waits for readiness. The chart and the values files live in version control, so every revision of a release can be traced to a commit.

flowchart LR
    G[Git repository
chart reference and values] --> C[Controller or pipeline]
    C --> R[Release in the cluster]
    R --> S[Status and history]
    S -->|report back| C
    D[Manual change in the cluster] -.drift.-> R
    C -.corrects.-> R
        

Operations fail sometimes, and how you configure them decides what state you are left in.

By default, Helm reports success once the cluster has accepted the manifests. That says nothing about whether pods started or became healthy. Three options change this behaviour and make releases safer.

Recovering a stuck release

Helm itself is light, but the number and size of releases shape how it behaves.

Helm does little work of its own: it renders text, compares manifests, and talks to the API server. The costs that appear at scale come from the records and from the resources being managed. Every operation reads release records, so large records and long histories make commands slower. Releases with hundreds of resources take longer to apply and to wait for. Clusters with thousands of releases produce long lists that are slow to scan without filters.

Release records and release operations both deserve careful protection.

Because Helm works with the permissions of the person or pipeline that runs it, the security of a release depends on who is allowed to change it and who is allowed to read its records. A release can create powerful resources, and its records contain everything that was supplied to it, including any secrets passed through values.

Most release problems can be understood by reading records and cluster events in the right order.

Reliable habits that keep many releases understandable.

flowchart TD
    G[Values and chart version in Git] --> P[Pipeline]
    P --> L[Lint and dry-run render]
    L --> B[Backup if stateful]
    B --> U[Upgrade with wait and atomic]
    U --> V[Verify health]
    V -->|failure| R[Automatic rollback and alert]
    V -->|success| H[Record revision and notify]
        

Habits that make releases fragile and hard to recover.

A short checklist for running releases with confidence.

How teams handle releases in daily operations.

A release is one named installation of a chart in a namespace of a cluster, together with the values used, the resources created, and a numbered history of every change.

A chart is the reusable package. A release is one installed instance of it. One chart can produce many releases, each independent and with its own values and history.

Yes, if they are in different namespaces. Within one namespace, each release name must be unique.

By default as secrets in the release’s namespace, one per revision. Each contains the chart, values, manifests, and status, and can be configured to use other storage.

No. Rollback creates a new revision whose content copies the older one. The history keeps all entries, showing both the upgrades and the rollback.

By default, an upgrade starts from the chart’s defaults and applies only the values given now. Pass all your values every time, or use the reuse options carefully.

An operation is recorded as in progress. If it stays pending, the operation was probably interrupted. Confirm nothing is running, then roll back or repair before making further changes.

No. Install a new release with the desired name or namespace and remove the old one, taking care to preserve data.

Tracked resources are removed, which may include storage. Resources marked to be kept stay behind. Back up data before uninstalling anything that holds it.

An object with that name exists and is not owned by this release. Remove it, rename it, or adopt it by adding the correct ownership markers.

Upgrades keep ten past revisions by default and remove older ones. The limit can be changed, and long-term audit records should live in version control.

The controller. Manual changes with Helm would conflict with it, so make every change through the repository that the controller watches.

A Helm release is the living, named installation of a chart in a cluster, and it is the thing you actually operate. Each release is identified by its name and namespace, remembers everything about its past through numbered revisions, and carries a status that tells you whether it is healthy, changing, or in need of repair. Records of every revision, including the chart, values, and rendered manifests, are stored in the cluster and make upgrades, rollbacks, and inspection possible.

Working well with releases means being deliberate: keep values in version control and pass them completely, wait for readiness, plan for failures and stuck states, protect the records that contain your settings, and remember that rollback restores manifests but not data. Decide who owns each release, keep releases small and focused, and rehearse recovery before you need it. With those habits, releases become predictable, reviewable, and safe to change.