Kubernetes is powerful, but describing a real application to it takes many files. To see why Helm exists, we first need to feel that pain.

Applications are described in many files

Kubernetes is a system that runs your programs, packaged as containers, across many computers. You tell Kubernetes what you want by writing manifests. A manifest is a text file, usually in a format called YAML, that describes one thing you want, such as a running program, a network address, or a piece of configuration.

A simple web application often needs many manifests. One describes the running program, called a Deployment. One gives it a stable network address, called a Service. One holds its settings, called a ConfigMap. One holds its passwords, called a Secret. One lets outside visitors reach it, called an Ingress. A real application can easily have ten to thirty such files.

The same application, many environments

Teams rarely run one copy of an application. There is a development copy, a testing copy, and a production copy, and each differs slightly. Production may run ten replicas, testing only one. Each environment has its own web address, its own database location, and its own memory limits. The bulk of the files are identical, but a handful of values change.

Without a tool, teams copy the whole folder of files for each environment and edit the differences by hand. Over time the copies drift apart. A fix made in one is forgotten in another. Nobody is sure which environment matches which version of the application.

The daily pains Helm was built to solve

Helm is the package manager for Kubernetes. It rests on three simple ideas: a chart, your values, and a release.

The idea in plain words

You may know a package manager from your phone or computer, such as an app store. You ask for an application by name, and the store downloads it, installs it, and can later update or remove it. Helm does the same job for applications running on Kubernetes. It is a program you run on your own computer, and it talks to your cluster on your behalf.

The package Helm installs is called a chart. A chart is a folder of files that contains templates, which are manifests with blanks in them, plus default values for those blanks. When you install a chart, you give Helm your own values to override the defaults. Helm fills in the blanks, produces ordinary manifests, and sends them to Kubernetes. Each installed copy of a chart is called a release, and Helm remembers every release so it can upgrade or remove it later.

The vocabulary you will use

Helm builds on top of ordinary Kubernetes objects. Knowing them makes charts easy to read.

Declarative: describe the goal, not the steps

Kubernetes works in a declarative way. You do not tell it “start three programs, then open this port”. You write down what the finished state should look like, and Kubernetes continually works to reach and keep that state. If a program crashes, Kubernetes starts a new one, because your manifest said three should exist.

This is the property Helm relies on. Helm does not invent a new way of running programs. It produces ordinary manifests, hands them to Kubernetes, and lets Kubernetes do the rest. Helm is a manager of manifests, not a replacement for anything Kubernetes already does.

A chart is just a folder with a known layout. Once you know the parts, any chart becomes easy to read.

flowchart TD
    CH["Chart folder"] --> Y["Chart.yaml: name, version, description"]
    CH --> VV["values.yaml: default settings"]
    CH --> T["templates folder: manifest templates"]
    CH --> D["charts folder: subcharts"]
    CH --> CR["crds folder: custom resource definitions"]
    T --> HL["helpers file: reusable named templates"]
    T --> NT["NOTES file: message shown after install"]
        

Read the figure from the top. The chart folder holds a description file, a file of default settings, and a templates folder that contains the real substance. It may also contain a folder of subcharts, which are dependencies, and a folder of custom resource definitions. Inside the templates folder, there are usually one file per Kubernetes object, plus a helpers file and a notes file.

Two version numbers, two meanings

A chart carries two separate version numbers, and confusing them is a very common mistake. The chart version describes the chart itself: its templates, its defaults, its structure. The application version describes the software inside, for example the version of the web server or database that the chart deploys. They change independently.

Templates and values are the heart of Helm. Together they turn one chart into many different, ready-to-use sets of manifests.

What a template is

A template is a manifest with blanks. In place of a fixed number of replicas, a template contains a marker that means “put the replica value here”. The markers are written between double curly braces. Helm reads the template, finds each marker, looks up the matching value, and writes the finished text.

Helm uses a text templating language that is common in the Go programming world, together with a library of extra helper functions. You do not need to be a programmer to read most templates. They are mostly ordinary manifests with a few markers scattered through them.

What templates can do

How values are layered

Values come from several places, and later sources override earlier ones. The chart’s own defaults come first. Then any values files you pass in are applied, in order. Finally, settings you give directly on the command line have the last word. This layering lets you keep one shared file of common settings and one small file for each environment.

Catching mistakes early with a schema

A chart can ship a schema file that describes which values are allowed, what type each must be, and which are required. When someone provides a value that does not fit, Helm stops before installing anything and says what is wrong. This turns silent misconfiguration into a clear, early error.

Helm has a small and clean architecture. Understanding where each piece lives explains how it behaves.

Helm today is a client-only tool. You run it on a computer, and it reads your cluster connection file, renders charts locally, and talks directly to the cluster’s API server. There is no Helm program running permanently inside the cluster. Older versions of Helm used a server component called Tiller, which sat in the cluster with wide permissions. It was removed in the third major version, mainly for security reasons, and the record of each release is now stored in the cluster as ordinary objects.

flowchart LR
    C["Chart: templates and default values"] --> H["Helm client renders the templates"]
    V["Your values"] --> H
    H -->|"plain Kubernetes manifests"| A["Kubernetes API server"]
    A --> R["Running resources"]
    H -->|"release record"| S["Secret stored in the cluster"]
        

Read the figure from the left. A chart and your values come together inside the Helm client, which renders them into plain manifests. Those manifests go to the API server, which creates the running resources. Helm also saves a release record in the cluster, so it can later find out what it installed. The client is the only active part, and it disappears when it finishes.

Where charts are stored

Charts can be shared through two kinds of homes. The older kind is a chart repository, which is a plain web server holding chart archives and an index file. The newer and increasingly popular kind is an OCI registry, the same type of storage that holds container images. Storing charts in a registry means teams can reuse their existing image storage, access controls, and signing tools.

An install looks like one command, but Helm performs a careful sequence of steps. Following them explains most of the messages you will ever see.

sequenceDiagram
    participant U as User
    participant H as Helm Client
    participant R as Chart Source
    participant A as API Server
    U->>H: Install a chart with a release name and values
    H->>R: Fetch the chart and its dependencies
    H->>H: Merge values and render the templates
    H->>A: Send hooks first, then the manifests
    A-->>H: Resources accepted
    H->>A: Save the release record as a Secret
    H-->>U: Report the status and the notes
        

Look before you leap

Helm offers two safe ways to look at what will happen. A rendering-only mode produces the final manifests on your screen, without contacting the cluster, so you can read exactly what would be sent. A dry-run mode goes a step further and asks the cluster to check the manifests without creating anything. Both catch typing errors, missing values, and mismatched settings before they cause harm.

Upgrading is where Helm earns its keep. It compares three pictures of your application and sends only the difference.

How an upgrade decides what to change

When you upgrade a release, Helm renders the new manifests from the new chart and values. It then compares three things: the manifests from the previous revision, the newly rendered manifests, and the live state of the objects in the cluster. This is called a three-way merge. It lets Helm work out which fields the chart wants to change, and it takes account of what is actually running.

flowchart TD
    O["Previous release manifest"] --> M["Three-way comparison"]
    N["New rendered manifest"] --> M
    L["Live state in the cluster"] --> M
    M --> P["Patch sent to the API server"]
    P --> Q{"Upgrade succeeded?"}
    Q -->|"Yes"| S["New revision recorded as deployed"]
    Q -->|"No"| F["Release marked failed, roll back to an earlier revision"]
        

The figure shows three inputs feeding one comparison. The result is a patch, which is a small set of changes, sent to the API server. If the changes are accepted and the application becomes healthy, a new revision is recorded. If not, the release is marked as failed, and you can return to an earlier revision.

Rollback: going back to a good revision

Every install and upgrade produces a numbered revision, and Helm keeps a limited history of them. A rollback takes the manifests from an earlier revision and applies them again. Importantly, the rollback itself becomes a new revision at the end of the history, so the history is never rewritten, only extended. You can always see what was done and in which order.

Two options make upgrades much safer. A wait option makes Helm hold until the programs are ready, so a broken upgrade is reported as a failure. An atomic option goes further, and automatically rolls back if the upgrade fails. Together they turn a risky change into one that undoes itself.

What a rollback cannot undo

A rollback only restores the Kubernetes objects. It cannot undo changes to data. If an upgrade ran a database migration, rolling back the application does not reverse the migration, and the old version may not understand the new data. Hooks are also not reversed, and custom resource definitions are not removed by a rollback. Plan for these limits before relying on rollback as a safety net.

Configuration changes that do not restart anything

A classic surprise is that changing a settings object does not restart the programs that read it. The deployment itself has not changed, so Kubernetes sees no reason to replace the pods. A well-known remedy is to put a fingerprint of the settings, called a checksum, into a label on the pod template. When the settings change, the fingerprint changes, the pod template changes, and Kubernetes rolls the pods automatically.

Real applications are rarely alone. Helm has built-in ways to bundle other charts, to run special jobs at key moments, and to test a release after it is installed.

Dependencies and subcharts

A chart can list other charts it depends on, such as a database or a cache. Helm downloads them into the charts folder, and installs them together with the parent as one release. The parent chart can switch a dependency on or off with a setting, and can pass values down to it using the dependency’s name as a section in its own values.

A lock file records the exact versions that were downloaded, so that everyone who builds the chart gets the same result. There is also a shared area of values, called global values, that every subchart can read. It is useful for settings such as a common domain name.

Hooks: special moments in a release

A hook is a resource that Helm runs at a chosen moment in the life of a release, instead of installing it as a normal part of the application. Hooks are marked with an annotation naming the moment. They are most often jobs, such as one that prepares a database before the new version starts.

Hooks run in an order controlled by a weight number, and a delete policy decides when finished hook objects are cleaned up. A hook that fails also fails the release step it belongs to, which is useful for stopping a bad upgrade early, but can also block a release if the hook is not written carefully.

Tests: proving a release works

A chart can include test resources, usually small pods that run a check and exit with success or failure. A user can ask Helm to run them after installing, and the result shows whether the application answers, connects to its database, or passes whatever check the chart’s author wrote. This gives every chart a simple, repeatable way to confirm it is healthy.

In most teams, nobody installs charts by hand in production. Helm sits inside automated pipelines that build, check, and deliver every change.

A typical delivery pipeline

A pipeline takes a chart from a developer’s change to a running release, with checks at each step. A well-built one catches nearly every mistake before it reaches a live cluster.

GitOps: the desired state lives in Git

In a GitOps approach, the desired state of the cluster is kept in a Git repository, and a tool inside the cluster continuously makes reality match it. Two popular tools handle Helm charts in different ways. Argo CD renders charts itself and applies the plain result, so it does not use Helm’s own release records. Flux uses a resource that describes a Helm release, and runs Helm operations inside the cluster on your behalf, so ordinary Helm records exist.

A release has a life of its own: it is born, changes, sometimes fails, and eventually is removed. Knowing its states helps you read the signs.

flowchart LR
    A["pending-install"] --> B["deployed"]
    B --> C["pending-upgrade"]
    C --> D["deployed as a new revision"]
    C --> E["failed"]
    D --> F["older revision becomes superseded"]
    E --> G["rollback creates a new revision"]
    B --> H["uninstalled"]
        

What stays behind after removal

Uninstalling a release removes the objects it created, but not everything. Storage volumes created by stateful programs are deliberately kept, so data is not lost by accident. Custom resource definitions placed in the special folder are also left in place, because removing them would delete every object of that kind across the cluster. Both are safe defaults, but they mean a full clean-up sometimes needs extra manual steps.

A chart is a program that creates other programs. Installing one from a stranger is a serious act of trust, and that deserves care.

A chart can create almost anything in your cluster, including powerful permissions, programs that run with high privileges, and jobs that execute at install time. Most charts are perfectly benign, but you cannot know that without looking. Treat charts the way you treat any software you download and run.

Why removing Tiller mattered

In the older design, a server component with very broad rights sat inside the cluster, and anyone who could reach it could do almost anything. Helm now performs actions with the caller’s own permissions, so a person or pipeline can only do what their credentials allow. This is a much safer default, and it fits normal cluster access control.

Helm itself is quiet, but the state of your releases matters. A few habits make failures visible early and easy to untangle.

What to watch

Some of these signals come from Helm’s own listing and history commands. Others come from the cluster’s normal monitoring, such as pod health and events. Community tools can also publish release information as metrics, so that dashboards and alerts can show failed releases beside the rest of your monitoring. GitOps tools report their own sync and health status, which is usually the best place to watch releases they manage.

Logs that help

Several logs tell the story of a release. The pipeline log shows what commands ran and what they printed. The logs of hook jobs show what a migration or setup step did. The application’s own logs show how it behaved after the change. The cluster’s audit log records who made each change to the API server, including Helm’s actions, which is essential when asking who changed what.

Untangling a failed release

Helm is the most widely used way to package Kubernetes applications, but it is not the only way, and it has real costs.

Thinking about cost honestly

The cost of Helm is mostly the cost of complexity and learning. Someone must learn the template language, understand how values layer, and keep charts tidy. Charts must be versioned, tested, and stored. A team that has three small applications may find plain manifests simpler than maintaining charts. A team that has thirty applications in five environments will find that the discipline pays back quickly.

The trap is treating every setting as a value. Each one adds a path that must be understood and tested. The best charts expose only the settings people actually need, and keep the rest fixed.

How Helm compares with other approaches

A few habits make charts easy to live with. A few shortcuts make them a burden for years.

Patterns that work well

Anti-patterns to avoid

A short field guide collected from teams that use Helm every day, and from the mistakes that repeat.

Best practices

• Render before you install — read the manifests that your values produce, every time you change something important.
• Lint and validate in the pipeline — catch structure errors, schema errors, and policy violations automatically.
• Keep values small and documented — comment each setting and give safe defaults.
• Add a values schema — reject wrong types and missing required values early.
• Pin chart and image versions — make every deployment reproducible.
• Use wait and atomic for upgrades — let failed upgrades report clearly and undo themselves.
• Diff before applying — show reviewers exactly what will change in the target environment.
• Sign and verify charts — especially those shared between teams or with customers.
• Keep secrets out of Git — use external secrets tools and reference them.
• Keep selectors and names stable — changing them across versions forces objects to be recreated.
• Manage custom definitions deliberately — plan how they are installed, upgraded, and removed.
• Choose one owner for each release — either a pipeline, or a GitOps tool, not both.

Common mistakes

Helm is used wherever teams need to install and manage applications on Kubernetes repeatedly and reliably.

Quick answers to the questions that come up most often when teams start using Helm.

No. You can use plain manifests, Kustomize, or other tools. Helm becomes valuable when you have many applications, many environments, or want to install and share packaged software.

Helm uses templates and values and adds packaging and release history. Kustomize patches plain manifests using overlays and has no templating language. Many teams use them together.

Tiller was the server component of Helm’s earlier design. It was removed in Helm’s third major version. Helm now runs as a client tool and uses your own permissions.

By default, in Secrets in the namespace of the release, one for each revision. Other storage options exist, but this is the usual one, and it means the records live in the cluster.

Yes. Each installation needs its own release name, and charts should be written so that two releases do not collide, for example by including the release name in object names.

Use an external secrets system or encrypted secrets tooling, and have the chart refer to a secret by name instead of holding its contents.

Changing a settings object does not change the Deployment, so Kubernetes sees nothing to roll. Add a checksum of the settings to the pod template so a change triggers a rollout.

The chart version describes the packaging. The application version describes the software inside. They change independently and are recorded in separate fields.

No. Rollback restores Kubernetes objects only. Data changes, including migrations run by hooks, remain, so plan for data separately.

With care, yes. Helm can adopt existing objects if they carry the labels and annotations that show which release owns them. Without these, Helm refuses to overwrite objects it did not create.

Both are protected on purpose. Storage volumes hold data that should not disappear by accident, and definitions, if removed, would delete every object of that kind across the cluster.

Lint it, render it, run a dry run, look at the diff against the current release, install it in a test environment, run the chart’s tests, and also test the upgrade from the previous version.

Helm packages a Kubernetes application as a chart, a folder of templates and default values. You provide your own values, Helm renders them into ordinary manifests, and each installed copy becomes a release with a numbered history. Upgrades compare the old manifests, the new ones, and the live state, and rollbacks return to an earlier revision. Around this core sit dependencies, hooks, tests, repositories, and registries, which together let teams share and reuse software reliably.

Helm is a strong tool, not a magic one. Templates can grow too complex, rollbacks do not undo data, custom definitions need special care, and third-party charts must be reviewed. Teams that keep charts small, pin versions, protect secrets, and check every change in a pipeline find that Helm turns messy deployments into steady, repeatable routines.