Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 38 ยท Getting Started

Helm Concepts: Charts, Releases, Repositories and Revisions

Understand the vocabulary of Helm: chart, values, release, revision, repository, namespace and the client-side architecture, with a runnable release model.

Helm has a small vocabulary, and nearly every confusing error message or tutorial step becomes clear once these words are exact. This lesson defines them, shows how they relate, and builds a tiny model of releases and revisions that you can run.

The core terms

  • Chart: a directory (or a .tgz archive of it) containing templates, default values and metadata. A chart is a recipe, not a running thing.
  • Values: the configuration that fills the chart's templates. A chart ships with defaults in values.yaml; you override them with files (-f) or --set flags.
  • Release: one installation of a chart into a cluster, with a name. You can install the same chart many times; each install is a separate release with its own name and values.
  • Revision: the version number of a release. The first install is revision 1, every upgrade or rollback adds a new revision.
  • Repository: a place that serves charts, either a classic HTTP index or an OCI registry (covered in the Repositories and OCI chapter later in the course).
  • Namespace: the Kubernetes namespace a release lives in. Release names are unique per namespace, not per cluster.
flowchart LR
  R["Repository (chart storage)"] -->|"helm pull / install"| C["Chart + default values"]
  V["Your values (-f, --set)"] --> H(("Helm client"))
  C --> H
  H -->|"rendered manifests"| K["Kubernetes API"]
  H -->|"stores release record"| S[("Secret in the release namespace")]

Helm combines chart and values on your machine, applies the result and records the release as a Secret.

Chart versus release

The same chart can produce many releases. Think of a class and its objects:

Terminal
helm install blog-prod ./webapp --namespace prod
helm install blog-staging ./webapp --namespace staging --set replicaCount=1
helm install docs ./webapp --namespace prod

Here one chart creates three releases. blog-prod and docs share a namespace but need different names; blog-staging could even reuse the name blog-prod in another namespace. Because a release is the unit Helm manages, commands such as helm upgrade, helm rollback and helm uninstall all take a release name.

Revisions: history as a first-class feature

Helm never edits a release in place and forgets the old state. Each change stores a new numbered record that holds the chart version, the final values and the rendered manifest. That record is what makes helm rollback possible, and also what helm history prints.

Two details trip up beginners:

  1. A rollback does not delete the newer revisions. Rolling back from revision 3 to revision 1 creates revision 4, whose content equals revision 1.
  2. Failed upgrades also create revisions (with status failed), so the numbers can jump.

The model below keeps a list of records for each release and implements install, upgrade and rollback exactly as described.

Python Stand-in: a release with revisions

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.

Run it and compare the output with helm history blog: four lines, only the last one deployed, and the rollback appearing as revision 4.

Where Helm stores releases

Helm needs no server because it stores each revision inside the cluster, as a Secret named sh.helm.release.v1.<release>.v<revision> in the release's namespace. You can see them with kubectl get secrets. The drivers are configurable (HELM_DRIVER=configmap or memory), but Secrets are the default and the right choice for production. Chapter 2 (Release Lifecycle Commands) opens one up.

The client-only architecture

Everything happens on the machine where you run helm:

  1. Read the chart (from a directory, archive, repository or OCI reference).
  2. Merge values: chart defaults, then your files, then --set flags.
  3. Render templates into manifests.
  4. Send the manifests to the Kubernetes API using your kubeconfig credentials.
  5. Store the release record.

Since Helm uses your credentials, it can only do what your account is allowed to do. There is no hidden super-user, which is the main security improvement over Helm 2.

Names that must stay unique

A release name must be a valid DNS label-ish string: lowercase letters, digits and hyphens, starting with a letter, at most 53 characters (Helm leaves room for suffixes that charts append). The next TryIt checks names the way Helm does.

Python Stand-in: validate a release name

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.

Helm can also generate a release name for you with helm install ./chart --generate-name, which produces something like webapp-1718112345.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. You install the same chart twice in one namespace. What must differ?

    Each install is a separate release, and release names are unique within a namespace.
  2. 2. A release is at revision 3. You run helm rollback to revision 1. What is the new revision number?

    Rollback creates a new revision (4) whose content copies revision 1; history is never rewritten.
  3. 3. Where does Helm 3 store release information by default?

    Secrets named sh.helm.release.v1.NAME.vN hold each revision.
  4. 4. Which describes a chart?

    A chart is the recipe; the installed result is a release.

Summary

  • Chart = package, values = configuration, release = one named installation, revision = its version number.
  • Many releases can come from one chart; names are unique per namespace.
  • Rollbacks and failed upgrades add revisions, they never rewrite history.
  • Helm is client-side and stores releases as Secrets using your own Kubernetes permissions.

Next: Installing Helm and Setting Up Your Environment