Skip to content
Tutorials Center
My learning

Topics

Lesson 52 of 78 ยท Packaging and Delivery

Helm: Charts and Releases

Learn how Helm packages Kubernetes manifests into charts, how values customize them, and how install, upgrade and rollback create release history.

A real application is rarely one manifest. A web service needs a Deployment, a Service, an Ingress, a ConfigMap, maybe a HorizontalPodAutoscaler, and every one of them contains values that differ between your laptop, staging and production. Copying folders of YAML and editing them by hand works for a week and then drifts apart. Kustomize solves this by patching plain YAML. Helm solves it differently: it treats the YAML as a template and fills in the blanks from a values file.

Helm is often called the package manager for Kubernetes. A package is called a chart, a running installation of a chart in your cluster is a release, and the place charts are published is a repository (or an OCI registry). This lesson covers how to use charts. The next lesson, Writing Helm Charts, shows how to build your own.

Helm and a cluster cannot run inside this web page. The helm and kubectl commands below are read-only, and the Python programs are honest stand-ins: they model how values are merged, how templates are filled in and how release revisions behave, but they are not the real Helm.

Three words to know

Chart A package of templates plus default values.
Release One named installation of a chart in a namespace.
Repository A place that hosts charts, HTTP or OCI.

One chart can be installed many times as different releases.

1 / 2

What is inside a chart

A chart is a folder (or a .tgz archive of one) with a fixed layout.

TEXT
shop-web/
  Chart.yaml          # name, version, appVersion, dependencies
  values.yaml         # default configuration values
  values.schema.json  # optional: validates the values
  templates/          # YAML with {{ }} placeholders
    deployment.yaml
    service.yaml
    NOTES.txt         # message printed after install
  charts/             # packaged dependencies

Chart.yaml is the identity card:

YAML
apiVersion: v2
name: shop-web
description: The web front end of the shop
type: application
version: 1.4.0        # version of the chart itself
appVersion: "2.7.1"   # version of the app it deploys (informational)

Two version numbers confuse everyone at first. version changes whenever the chart changes (a new template, a new default). appVersion describes the application inside it, usually the image tag. They move independently.

values.yaml holds defaults, and the templates read them through .Values:

YAML
replicaCount: 2
image:
  repository: registry.example.com/shop-web
  tag: "2.7.1"
service:
  port: 80

A template line such as replicas: {{ .Values.replicaCount }} becomes replicas: 2 when Helm renders it.

Using a chart from a repository

Everyday Helm work is mostly these commands. They are shown read-only.

Terminal
# add a repository and refresh its index
helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update

# find charts and read their default values
helm search repo nginx
helm show values bitnami/nginx > nginx-defaults.yaml

# install a chart as a release named "web" in namespace "shop"
helm install web bitnami/nginx --namespace shop --create-namespace \
  --version 22.0.0 -f my-values.yaml --set replicaCount=3

# see what is installed
helm list --namespace shop
helm status web --namespace shop

Always pin --version. Without it Helm installs the newest chart, and your "same" command produces different results next month. Charts can also live in OCI registries, the same kind of registry that stores container images:

Terminal
helm install web oci://registry.example.com/charts/shop-web --version 1.4.0

Before installing anything unfamiliar, look at what it would do:

Terminal
helm template web bitnami/nginx -f my-values.yaml   # print rendered YAML, no cluster needed
helm install web bitnami/nginx --dry-run            # ask the API server to validate, change nothing
helm lint ./shop-web                                # check your own chart

helm template is a pure function: chart and values in, YAML out. That makes it the favorite of CI pipelines and GitOps tools.

How values are merged

Helm builds the final values from several layers. Later layers win:

  1. the chart's own values.yaml (the defaults);
  2. every file passed with -f or --values, in the order given;
  3. every --set flag, in the order given.

Maps are merged key by key, so overriding image.tag leaves image.repository alone. Lists are different: a list in a later layer replaces the earlier list completely, it is not appended. The stand-in below implements these rules.

Python Merging values in layers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice that image.repository survived the image.tag override, while hosts was replaced as a whole list. In real Helm, --set has its own syntax for list items (hosts[0]=a.example.com) and for escaping dots, and values from --set are always typed by Helm's parser: --set-string forces a string when true or 123 should stay text.

Install, upgrade and rollback

Every change you make with Helm is a numbered revision of the release. Helm stores each revision in the cluster as a Secret in the release's namespace, named like sh.helm.release.v1.web.v3. That Secret holds the rendered manifest and the values used, which is what makes history and rollback possible.

Terminal
helm install web ./shop-web -f prod.yaml          # revision 1
helm upgrade web ./shop-web -f prod.yaml \
  --set image.tag=2.8.0                           # revision 2
helm history web                                  # all revisions with status
helm rollback web 1                               # revision 3, with revision 1's content
helm uninstall web                                # delete the release

Three facts are worth memorizing.

  • A rollback is a new revision. Rolling back to revision 1 creates revision 3 containing revision 1's manifest. History only grows, up to --history-max (10 by default for upgrade).
  • helm upgrade --install installs if the release does not exist and upgrades if it does. It is the idempotent command that CI pipelines use.
  • Values are not remembered by default. On helm upgrade, values you do not pass again fall back to the chart defaults. --reuse-values keeps the previous ones but also keeps stale keys from old chart versions, which is a classic source of surprises. Keeping your values in a file under version control and passing it every time is safer.

Helm also offers --wait (do not call the upgrade finished until the pods are ready) and --atomic (roll back automatically if the upgrade fails; Helm 4 calls this behavior --rollback-on-failure). These make a failed deploy loud instead of silent.

Helm does not replace the Deployment controller. It sends objects to the API server and the usual controllers do the work, so rolling updates happen exactly as before. Helm's job ends at which objects exist.

Here is a stand-in that renders a tiny template and records revisions the way a release does.

Python A mini release with rollback

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The output shows what helm history shows in real life: revision 3 is deployed, and its content equals revision 1. The quote and default functions are real Helm template functions; the next lesson covers many more.

How Helm works, and a note on Tiller

The Helm 3 client talks to the Kubernetes API directly with your kubeconfig credentials, renders the chart's templates locally and applies the result, then stores the release record (chart version, values, manifest) as a Secret in the release's namespace. Nothing runs inside the cluster for Helm itself.

Older material mentions Tiller. Helm 2 had a server-side component called Tiller that ran in the cluster, usually with very broad permissions, and received requests from the client. That was a security problem, because anyone who could reach Tiller could do nearly anything. Helm 3 (2019) removed Tiller, so RBAC now applies to the person running helm exactly as it does for kubectl. If a guide tells you to run helm init or install Tiller, it is out of date.

What you gain: one command installs, upgrades and rolls back a whole application; templates and values remove copy-and-paste between environments; charts are versioned and shareable, with a large public ecosystem; releases can be listed, inspected and removed cleanly.

What it costs: templates are text generation, so mistakes surface as broken YAML; charts with many options get complex to read and maintain; third-party charts can create powerful objects, so read what you install; and Helm's release history is one more state to understand next to your Git history.

When Helm fits and when it hurts

Helm is excellent for consuming software other people publish: ingress controllers, databases, monitoring stacks. You install a well-maintained chart, tune a values file and upgrade when new versions appear. For your own applications it is a trade-off. Templates are text generation, so a missing space or a wrong indent produces broken YAML, and large charts with dozens of toggles become hard to read. Many teams use Helm for third-party software and plain manifests or Kustomize for their own services; others standardize on one internal chart for all services. Both are reasonable.

Two safety notes. A chart can create any object, including ClusterRoles, so read what you install (helm template first). And values that are secrets should not sit in a values file in Git; see Secrets and GitOps for options.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is a Helm release?

    A chart is the package; a release is one installation of it. You can install the same chart several times under different release names.
  2. 2. Values come from the chart defaults, a -f file and a --set flag. Which one wins when they all set the same key?

    Later layers override earlier ones: chart defaults, then -f files in order, then --set flags in order.
  3. 3. You run helm rollback web 1 when the release is at revision 2. What does history look like afterwards?

    A rollback never rewrites history. Helm creates a new revision whose manifest and values match the old one.
  4. 4. Which command shows the rendered YAML without touching a cluster?

    helm template renders the chart with the given values and prints the Kubernetes manifests locally, which makes it ideal for CI and review.

Summary

  • A chart is a package of templates and default values; a release is one named installation; a repository (HTTP or OCI) hosts charts.
  • Final values are merged in layers: chart defaults, -f files, then --set. Maps merge key by key, lists are replaced.
  • Every install, upgrade and rollback creates a numbered revision stored as a Secret; a rollback adds a new revision.
  • Pin chart versions, keep values in version-controlled files, and use helm template or --dry-run to preview.
  • Helm decides which objects exist; ordinary Kubernetes controllers still do the running.

Next, learn to build your own: Writing Helm Charts.