Opscraft
Helm & Kustomize · Lesson 2 of 7 · 4 min read

Helm fundamentals

Concepts

  • Chart — a package of templates plus default values.
  • Release — an installed instance of a chart in a namespace with a name; each upgrade creates a new revision.
  • Repository — where charts are published: classic HTTP repos (index.yaml) or OCI registries (ECR, GHCR, Harbor).
  • Helm 3 removed the old in-cluster Tiller server; Helm talks to the API server with your kubeconfig credentials and stores release state as Secrets (type helm.sh/release.v1) in the release namespace.
  • Helm 4 (released November 2025) keeps the same chart format and commands, and adds Kubernetes server-side apply support (--server-side), more accurate readiness waiting (kstatus) and a rebuilt plugin system (including WebAssembly plugins). Most material on Helm 3 still applies; check plugin and CI flags when upgrading.
Enlarge diagramChart orders 1.6.0from an OCI registryRelease ordersnamespace shoprevision 1supersededrevision 2supersededrevision 3deployedinstallRelease state is stored as Secrets in the release namespace.
Figure 1. Helm words: a chart is the package; a release is one installed copy of it; each upgrade adds a revision you can roll back to.
Swipe sideways to see all of it, or tap to open it full screen.

Chart layout

orders/
  Chart.yaml            # name, version (chart), appVersion (app), dependencies
  values.yaml           # defaults
  values.schema.json    # optional JSON schema to validate values
  templates/
    _helpers.tpl        # named templates (labels, names)
    deployment.yaml
    service.yaml
    ingress.yaml
    hpa.yaml
    NOTES.txt           # printed after install
    tests/test-connection.yaml
  charts/               # vendored dependency charts
# Chart.yaml
apiVersion: v2
name: orders
version: 1.6.0          # chart version — bump on any chart change (semver)
appVersion: "2.14.3"    # version of the app it deploys (informational, often default image tag)
type: application
dependencies:
  - name: redis                     # a subchart, installed only when redis.enabled is true
    version: 1.x.x
    repository: oci://123456789012.dkr.ecr.ap-south-1.amazonaws.com/charts
    condition: redis.enabled

Everyday commands

helm repo add jetstack https://charts.jetstack.io
helm repo update
helm search repo jetstack/cert-manager --versions
helm show values jetstack/cert-manager > defaults.yaml

helm upgrade --install orders ./orders -n orders --create-namespace \
  -f values-prod.yaml --set image.tag=2.14.3 \
  --atomic --wait --timeout 10m

helm list -A
helm status orders -n orders
helm history orders -n orders
helm get values orders -n orders          # user-supplied values
helm get manifest orders -n orders        # what was actually applied
helm rollback orders 7 -n orders
helm uninstall orders -n orders

helm template orders ./orders -f values-prod.yaml   # render locally, no cluster
helm lint ./orders
helm diff upgrade orders ./orders -f values-prod.yaml   # helm-diff plugin
  • upgrade --install is idempotent — the standard CI form.
  • --atomic rolls back automatically if the upgrade fails (implies --wait).
  • --wait waits for resources to be ready; --timeout bounds it.

Values precedence

From lowest to highest:

Enlarge diagram--set image.tag=4a1b9c0command line: wins-f values-prod.yamllater -f files override earlier ones-f values-common.yamlchart's values.yamldefaults
Figure 2. Helm values precedence, highest at the top. Maps merge; lists are replaced whole.
Swipe sideways to see all of it, or tap to open it full screen.
  1. The chart's values.yaml (and dependency charts' values).
  2. Parent chart values for subcharts (redis: key in the parent).
  3. -f/--values files, in order — later files override earlier.
  4. --set, --set-string, --set-file, --set-json — highest.

Maps merge deeply; lists are replaced, not merged. Setting a key to null removes a default.

--reuse-values reuses the previous release's values and merges --set; --reset-values goes back to chart defaults. Relying on reused values makes state implicit — prefer always passing the full values files from Git.