Helm

Helm is the package manager for Kubernetes: it bundles the dozen-or-more YAML objects a real application needs into one versioned, parameterised artefact called a chart, and it remembers every version of that artefact it installed so you can upgrade or roll back with a single command. It solves the platform problem of distribution — how do a hundred teams install the same ingress controller, the same monitoring stack, the same internal service template, correctly, in five environments, without copy-pasting eight thousand lines of YAML that immediately drift apart?

What Helm is and the problem it solves

☺ Like you’re 10: It puts a whole app’s YAML in one labelled box with knobs on the front, so you can install it by turning knobs instead of writing YAML.

Kubernetes has no concept of “an application.” It has Deployments, Services, ConfigMaps, ServiceAccounts, Ingresses, PodDisruptionBudgets and HorizontalPodAutoscalers — and it happily lets you have some of them and not others. A realistic web service is eight to fifteen objects; a monitoring stack is several hundred. Helm invents the missing noun. A chart is a versioned directory containing all of those objects as templates plus a file of default settings, and Helm can fetch it from a repository, render it, install it, track it, upgrade it and remove it as one unit.

The problem before packaging

Without a package layer you get one of two failure modes, and most organisations get both. Either every team hand-writes near-identical YAML — so the security team’s “always set runAsNonRoot” lands in nine of eleven services — or someone copies the whole folder per environment, and within a quarter dev/ and prod/ have silently diverged. Helm answers both: one templated source of truth, many parameterised instantiations, and a versioned artefact other teams consume rather than fork.

Chart, release, revision — the three nouns

Almost every Helm misunderstanding is a confusion between these. A chart is the package: inert, versioned, distributable, like a .deb. A release is one installed instance of a chart, with a name and a namespace — you can install the same chart three times under three release names in one cluster. A revision is a numbered snapshot of that release: revision 1 is the install, each successful helm upgrade makes revision 2, 3, 4, and helm rollback re-applies an old one as a new revision. Say those three words correctly and the CLI stops feeling arbitrary.

What it is not

Helm is a renderer and a release tracker, not a reconciler. It does nothing between commands: if someone hand-edits a Deployment Helm installed, Helm neither notices nor cares until your next upgrade. Continuous correction is GitOps’ job, via Argo CD or Flux. It is also not a secret manager — templating a password into a chart still puts the plaintext in your values file, so see Secrets Management and External Secrets Operator. And it is not a competitor to Kustomize so much as a different answer to the same question, compared head-to-head in Configuration & Templating.

Where it fits in a platform

☺ Like you’re 10: Helm sits just before the cluster door: it turns your knob settings into real YAML that something else then delivers.

In the layered platform model Helm belongs to the configuration and delivery plane — specifically to the rendering step, upstream of whatever actually applies manifests to the Kubernetes substrate. It is the layer that turns “we want checkout, six replicas, prod resource limits” into concrete API objects. On most platforms it plays two quite different roles at once, and it is worth naming them separately.

Two jobs: consuming charts and publishing them

The first is consumption: nearly every platform component you install — the ingress controller, cert-manager, Prometheus, Grafana, Kyverno, Crossplane, Cilium, Velero — ships as an upstream chart, and installing it any other way means maintaining a fork of someone else’s YAML forever. The second is publication: the platform team writes one paved-road chart (or a library chart of shared helpers), publishes it internally, and every application team consumes it with a fifteen-line values file. That second job is a genuine self-service and developer-experience lever — the golden path arrives as a version number teams can bump.

Its neighbours

Upstream, CI builds an image and bumps a tag in a values file. Beside Helm sits Kustomize, often used to patch the output of a chart you don’t control. Downstream sit the reconcilers: Argo CD renders charts with helm template inside its repo-server, while Flux’s helm-controller drives the real Helm SDK through a HelmRelease — a distinction that produces one of the sharpest gotchas below. Admission policy from Kyverno or OPA Gatekeeper still inspects everything a chart emits, so a chart that omits resource limits is rejected regardless of how nicely it templates.

CNPE domain relevance

Helm is not on the official CNPE tool list — but it is everywhere in the material the list does cover, because it is how most platform components get installed. Expect it to show up as connective tissue in GitOps & Continuous Delivery (25%) and Platform Architecture & Infrastructure (15%) rather than as a task’s headline subject: a scenario may hand you a chart to render, a values file to correct, or a released component to inspect. The primary lesson on this site is Configuration & Templating; the exam guide has the full blueprint weighting.

How it works — anatomy and the render pipeline

☺ Like you’re 10: Helm reads your knob settings, fills in the blanks on the instruction sheets, and posts the finished pages to the cluster — then writes down what it posted.

Helm has no CRDs of its own and installs no controllers. Its “architecture” is a pipeline that runs entirely on your machine, plus one storage convention inside the cluster. Understanding that pipeline is most of the debugging skill.

The chart directory

A chart is a directory whose layout Helm knows by convention. Every file has a job, and the two that people forget — crds/ and values.schema.json — are the two that cause the most pain later.

checkout/
├── Chart.yaml            # name, version, appVersion, dependencies — the only mandatory file
├── values.yaml           # the DEFAULT knob settings; also your user-facing documentation
├── values.schema.json    # optional JSON Schema — rejects bad values BEFORE rendering
├── templates/
│   ├── deployment.yaml   # Go templates → rendered to manifests
│   ├── service.yaml
│   ├── configmap.yaml    # hashed into a pod annotation by the checksum trick below
│   ├── ingress.yaml
│   ├── _helpers.tpl      # leading underscore = NOT rendered as a manifest; named templates
│   ├── NOTES.txt         # templated; printed to the user after install/upgrade
│   └── tests/
│       └── connection.yaml   # a Pod annotated helm.sh/hook: test, run by `helm test`
├── crds/                 # PLAIN YAML (no templating). Installed first, NEVER upgraded.
├── charts/               # vendored subcharts, populated by `helm dependency update`
├── Chart.lock            # pinned dependency versions + digest
└── .helmignore           # what to exclude when packaging

The render pipeline and the built-in objects

Rendering is text substitution over Go’s text/template language, extended with the Sprig function library (default, quote, b64enc, sha256sum, trunc, randAlphaNum, and a hundred more) plus a short list of functions Helm itself adds (include, required, toYaml, tpl, lookup). Shared logic lives in _helpers.tpl as define blocks and is pulled in with include — never template, because only include returns a string you can pipe into nindent. Everything a template can see comes from six built-in objects:

Where a release actually lives

After a successful install or upgrade, Helm stores a gzipped, base64-encoded copy of the release — rendered manifests, supplied values, chart metadata, status — as a Kubernetes Secret of type helm.sh/release.v1 in the release’s namespace, named sh.helm.release.v1.<release>.v<revision>. That is the whole database. helm list is a Secret query; helm history lists those Secrets; helm rollback reads an old one and re-applies its manifests. Delete the Secrets and Helm forgets the release exists while the workloads keep running quite happily — which is exactly what makes the release history both useful and fragile.

Dependencies, subcharts and library charts

Charts compose. Declaring dependencies in Chart.yaml and running helm dependency update vendors those charts into charts/ and pins them in Chart.lock. Four knobs matter: condition (a values path — if it is false the subchart is skipped entirely, the usual “bundle Postgres in dev, use RDS in prod” switch), tags (turn groups of subcharts on and off together), alias (install the same subchart twice under different names), and import-values (lift a subchart’s values up into the parent). Values flow downward: a parent may set postgresql.auth.username to override its subchart, and anything under the reserved global: key is visible to every chart in the tree — the correct place for a shared image registry or environment name.

A library chart (type: library in Chart.yaml) is the composition move platform teams underuse. It renders nothing of its own — only defined templates — and other charts depend on it to inherit a house style: standard labels, security context, probe block. Bump its version and every consumer picks up the new standard on their next upgrade. That is how “always set runAsNonRoot” becomes a property of the platform rather than a code-review nag.

The resources you will actually write

☺ Like you’re 10: Three files do nearly all the work: the label on the box, the knobs, and one instruction sheet.

Here is a small but genuinely production-shaped chart. Read the comments — they mark the decisions reviewers actually argue about.

Chart.yaml and values.yaml

# Chart.yaml
apiVersion: v2                 # v2 = the Helm 3+ chart API. (v1 charts are the Helm 2 era format.)
name: checkout
description: The Acme checkout service
type: application              # or "library" for a helpers-only chart
version: 2.4.0                 # the CHART version — bump on every chart change (SemVer)
appVersion: "1.4.3"            # the APP version shipped by default; a string, always quote it
kubeVersion: ">=1.27.0-0"      # refuse to install on older clusters

dependencies:
  - name: postgresql
    version: "~15.5.0"                # a SemVer RANGE; Chart.lock pins the exact resolved version
    repository: https://charts.example.com   # whichever upstream chart repo you use
    condition: postgresql.enabled     # false in prod → subchart skipped entirely
  - name: acme-common                 # a LIBRARY chart of shared labels/securityContext
    version: "1.2.0"
    repository: oci://ghcr.io/acme/charts
---
# values.yaml — the defaults, and your user-facing documentation. Comment every knob.
replicaCount: 2
image:
  repository: ghcr.io/acme/checkout
  tag: ""                      # empty → falls back to .Chart.AppVersion
  pullPolicy: IfNotPresent
logLevel: info
resources:
  requests: { cpu: 100m, memory: 128Mi }
  limits:   { memory: 512Mi }  # no CPU limit on purpose — avoids throttling surprises
podSecurityContext:
  runAsNonRoot: true
  seccompProfile: { type: RuntimeDefault }
ingress:
  enabled: false
  host: ""
postgresql:
  enabled: false               # dev overrides this to true; prod uses the managed DB
global:
  environment: dev             # visible to EVERY chart in the dependency tree

A template that survives review

Two habits separate charts that age well from charts that rot: pipe structured values through toYaml | nindent instead of hand-indenting, and put every name and label behind a named template so you can change the convention in one place.

# templates/_helpers.tpl
{{- define "checkout.fullname" -}}
{{- printf "%s-%s" .Release.Name .Chart.Name | trunc 63 | trimSuffix "-" -}}
{{- end -}}

{{- define "checkout.labels" -}}
app.kubernetes.io/name: {{ .Chart.Name }}
app.kubernetes.io/instance: {{ .Release.Name }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
acme.io/environment: {{ .Values.global.environment }}
{{- end -}}
---
# templates/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "checkout.fullname" . }}
  labels: {{- include "checkout.labels" . | nindent 4 }}   # include+nindent, never `template`
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      app.kubernetes.io/name: {{ .Chart.Name }}
      app.kubernetes.io/instance: {{ .Release.Name }}
  template:
    metadata:
      annotations:
        # roll the pods whenever the ConfigMap content changes — the classic checksum trick
        checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}
      labels: {{- include "checkout.labels" . | nindent 8 }}
    spec:
      securityContext: {{- toYaml .Values.podSecurityContext | nindent 8 }}
      containers:
        - name: checkout
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
          imagePullPolicy: {{ .Values.image.pullPolicy }}
          ports:
            - name: http
              containerPort: 8080
          env:
            - name: LOG_LEVEL
              value: {{ .Values.logLevel | quote }}          # quote, or `false`/`on` become booleans
            - name: DB_HOST
              value: {{ required "dbHost is required in prod" .Values.dbHost | quote }}
          readinessProbe:
            httpGet: { path: /healthz, port: http }
          resources: {{- toYaml .Values.resources | nindent 12 }}
      {{- with .Values.nodeSelector }}
      nodeSelector: {{- toYaml . | nindent 8 }}              # `with` skips the key entirely if empty
      {{- end }}

values.schema.json and NOTES.txt

A chart consumed by other teams should refuse bad input rather than emit broken YAML. values.schema.json is plain JSON Schema — draft-07 is the dialect Helm 3’s validator understands, so target that unless you know your Helm build supports a newer one. Helm validates the merged values against it during install, upgrade, lint and template, and fails with a readable error instead of a 400 from the API server three seconds later. NOTES.txt is the other half of the contract — it is rendered with the same values and printed after install, so use it to tell the user what to do next rather than to congratulate them.

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["image", "replicaCount"],
  "properties": {
    "replicaCount": { "type": "integer", "minimum": 1, "maximum": 50 },
    "logLevel":     { "type": "string", "enum": ["debug", "info", "warn", "error"] },
    "image": {
      "type": "object",
      "required": ["repository"],
      "properties": {
        "repository": { "type": "string", "pattern": "^ghcr\\.io/acme/" },
        "tag":        { "type": "string" }
      }
    }
  }
}

Day-to-day commands

☺ Like you’re 10: Six commands cover almost everything: add, update, install, see-what-would-change, upgrade, undo.

Repositories, search and OCI charts

# classic HTTP repositories (an index.yaml over HTTP)
$ helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
$ helm repo update                       # refresh every repo's index — forget this and you get stale versions
$ helm search repo prometheus --versions # what's available locally
$ helm search hub ingress-nginx          # search Artifact Hub instead
$ helm show values prometheus-community/kube-prometheus-stack > /tmp/defaults.yaml
$ helm show chart prometheus-community/kube-prometheus-stack   # metadata only

# OCI registries (stable since Helm 3.8) — charts live beside your images
$ helm registry login ghcr.io -u acme-bot            # credentials, not `repo add`
$ helm package ./checkout                            # → checkout-2.4.0.tgz
$ helm push checkout-2.4.0.tgz oci://ghcr.io/acme/charts
$ helm pull oci://ghcr.io/acme/charts/checkout --version 2.4.0 --untar
# NOTE: with OCI there is no `helm repo add` and no index.yaml. The URL IS the address:
$ helm upgrade --install checkout oci://ghcr.io/acme/charts/checkout --version 2.4.0

Render, lint, install, upgrade

$ helm lint ./checkout -f values-prod.yaml       # schema + chart structure checks, no cluster needed
$ helm dependency update ./checkout             # resolve deps into charts/ and write Chart.lock
# RENDER LOCALLY — the single most useful command: no cluster contact, no release created
$ helm template checkout ./checkout \
    -f values-prod.yaml | less
$ helm template checkout ./checkout -f values-prod.yaml | kubectl apply --dry-run=server -f -

# the idempotent workhorse: install if absent, upgrade if present. Use this, not `helm install`.
# precedence: later -f files beat earlier ones, and --set beats every -f file.
# --atomic rolls the release back automatically if the upgrade fails or times out.
$ helm upgrade --install checkout ./checkout \
    --namespace checkout --create-namespace \
    -f values.yaml -f values-prod.yaml \
    --set image.tag=1.4.4 \
    --atomic --timeout 5m

$ helm upgrade --install checkout ./checkout -f values-prod.yaml --dry-run --debug  # see the plan
$ helm test checkout                            # run the chart's test hooks

Inspect, diff, roll back, remove

$ helm list -A                                   # every release in every namespace
$ helm status checkout -n checkout               # current revision, status, NOTES.txt
$ helm history checkout -n checkout              # every revision, with the reason it exists
$ helm get values checkout -n checkout           # the values YOU supplied
$ helm get values checkout -n checkout -a        # ALL computed values incl. chart defaults
$ helm get manifest checkout -n checkout         # exactly what Helm applied — the ground truth
$ helm get hooks checkout -n checkout            # hook resources, often the cause of a stuck upgrade

# helm-diff is a PLUGIN, not built in — install it on day one
$ helm plugin install https://github.com/databus23/helm-diff
$ helm diff upgrade checkout ./checkout -f values-prod.yaml   # review before you ship

$ helm rollback checkout 6 -n checkout           # re-apply revision 6's manifests AS A NEW REVISION
$ helm rollback checkout -n checkout             # omit the number → previous revision
$ helm uninstall checkout -n checkout            # deletes resources; NOT CRDs, NOT PVCs
$ helm uninstall checkout -n checkout --keep-history   # leaves history so you can roll back later

Gotchas and failure modes

☺ Like you’re 10: Helm is cutting and pasting text, so spaces matter enormously — and a few things it installs, it never cleans up.

It is string surgery, not YAML surgery

The engine has no idea it is producing YAML. It concatenates text, and only the API server ever finds out the result was malformed. Hence the indentation rules that define most of the debugging experience: indent N pads every line by N spaces, while nindent N emits a newline first and then pads — which is what you want after key:. Get it wrong and a whole block silently becomes a sibling of the key it should have nested under. Whitespace chomping ({{- eats preceding whitespace, -}} eats following) keeps control structures from leaving blank-line debris. Unquoted scalars are the other classic: value: {{ .Values.logLevel }} yielding on or 1.10 produces a boolean and a float, and a Deployment that rejects both. Pipe through | quote by reflex. When output looks insane, stop guessing — run helm template, or --debug for the failing render.

CRDs in crds/ are a one-way door

This is the single highest-impact Helm behaviour to memorise. Files in crds/ are installed before anything in templates/, are not templated (no {{ }} at all), and — critically — are never upgraded and never deleted. helm upgrade leaves an existing CRD exactly as it was, so a chart that adds a field to its CRD in v3 will render v3 custom resources against a v2 CRD, and the API server will strip or reject the new fields. helm uninstall leaves the CRDs behind forever. The fix is operational, not clever: upgrade CRDs yourself with kubectl apply -f from the new chart version before running the Helm upgrade, and read the chart’s upgrade notes every time. Symptoms of getting this wrong land in workload triage looking like a mysteriously ignored spec field.

Stuck releases, lost values and history limits

An interrupted helm upgrade leaves the release in pending-upgrade, and every later attempt fails with “another operation (install/upgrade/rollback) is in progress.” There is no lock to break — the state is in the release Secret. helm rollback to the last good revision normally clears it; in the worst case you delete the pending sh.helm.release.v1.* Secret. Related traps: Helm keeps only the last ten revisions by default (--history-max), so your rollback target may have aged out; and because each revision is a Secret holding the full rendered manifest, very large charts can bump into etcd’s ~1 MiB object limit. Meanwhile helm upgrade computes a three-way merge across the old manifest, the new manifest and live state — which is what lets it leave alone a field an HPA owns, but also means a hand-edited resource produces a surprising diff. Delivery-side symptoms belong in delivery triage; the broader method is in the troubleshooting playbook.

Why GitOps setups render charts to plain manifests

Helm’s release model and a reconciler’s desired-state model overlap awkwardly. Argo CD runs helm template internally and owns the resulting objects itself — so no Helm release exists, helm list shows nothing, and helm rollback is unavailable; you roll back by reverting a commit. Flux’s helm-controller instead drives the real Helm SDK from a HelmRelease, so genuine releases and revisions do exist. A third camp commits the rendered output (the “rendered manifests pattern”): CI runs helm template and commits plain YAML to an environment branch, which the reconciler applies. It costs a build step and buys reviewable diffs in pull requests, no template surprises at apply time, and immunity to non-deterministic charts — the last trap here. Charts using randAlphaNum, now or lookup render differently every pass: under Argo CD that is permanent meaningless drift, and under helm template lookup always returns empty because nothing contacts the cluster.

Alternatives and when to choose it

☺ Like you’re 10: Other tools also turn settings into YAML — they just make different trades between power and safety.

The real question is rarely “Helm or not.” You will consume Helm charts regardless, because that is how third-party software ships. The question is what you use to configure your own workloads.

The comparison that decides it

A practical rule

Use Helm when the artefact must travel — across teams, clusters or organisations — and when you want a version number to be the unit of change. Use Kustomize when the config is yours, lives next to the code, and benefits from being plain readable YAML. Most mature platforms do exactly that: upstream Helm charts for infrastructure, one internal Helm or library chart as the paved road, Kustomize overlays for per-environment app config. See The Tool Landscape for how this sits among the named projects, and Configuration & Templating for the full head-to-head.

Exam relevance and going further

☺ Like you’re 10: Helm isn’t the star of the exam, but it’s how everything else gets installed — and its website is locked on exam day.

Helm does not appear on the official CNPE tool list, so no task is likely to be titled “Helm.” It shows up as plumbing: the way a platform component was installed, a chart you must render and inspect, a values file with a mistake in it, a released component you must identify. Read it as background competence rather than a headline skill, and spend your revision minutes accordingly — the named tools in the tool landscape earn more marks per minute.

The documentation allowlist — read this twice

⚖ CNPA vs CNPE — That allowlist is a CNPE-only mechanic: CNPA has no allowlist at all, because it is a fully closed-book multiple-choice exam — zero external resources, zero lookups of any kind, on anything. That’s stricter than CNPE, not looser. Even so, the chart/release/revision model and the values-precedence rules on this page are worth knowing cold, since this concept-level knowledge still matters for CNPA’s closed-book recall.

What to be able to do without notes

Write a minimal Chart.yaml from an empty file (apiVersion: v2, name, version, and the version-vs-appVersion distinction). Explain chart / release / revision in a sentence each. State the values precedence order, and that upgrades do not remember values. Render with helm template and say why that is the safe first move. Name where release state lives (a Secret in the release namespace, one per revision). Say what crds/ does and — more importantly — what it refuses to do on upgrade. And know the CLI spine cold: helm repo add/update, search repo, show values, template, lint, upgrade --install, list -A, history, get values -a, get manifest, rollback, uninstall — all collected in the command reference, with any unfamiliar term in the glossary.

Official resources for after the exam

When you are not sitting the exam, the canonical sources are the Helm documentation at helm.sh/docs — the Chart Template Guide and Chart Best Practices pages repay reading end to end — the chart index at artifacthub.io, the Sprig function reference at masterminds.github.io/sprig, the source at github.com/helm/helm, and the CNCF project page at cncf.io/projects/helm. Pair this page with Configuration & Templating for the comparison against Kustomize, GitOps Workflows for how charts get delivered, and Platform Best Practices for the chart conventions worth enforcing.