Helm: charts and values

The problem: raw YAML duplicates, and kubectl apply has no undo

Plain Kubernetes YAML has two structural gaps once you run the same app in more than one place. First, duplication: environments differ by a handful of values — replica count, image tag, resource limits, a hostname — but YAML has no parameters, so you copy the whole manifest set per environment and keep them in sync by hand. Drift is inevitable. Second, no release unit: kubectl apply -f pushes the current files to the cluster and forgets. It does not record “this is version 4 of my-api,” it cannot bundle a Deployment + Service + ConfigMap + Ingress as one atomic thing, and it has no concept of rolling back to the previous version. If you want to undo, you have to reconstruct the old YAML yourself.

Helm — the de-facto package manager for Kubernetes — closes both gaps. It introduces a packaging unit (the chart), a parameterisation mechanism (values), and a stateful, versioned deploy unit (the release).

A chart is a package: templates + default values + metadata

A chart is a directory (or a packaged .tgz) with a fixed layout. The three parts that matter day one:

my-api/
  Chart.yaml          # metadata: name, version, appVersion, dependencies
  values.yaml         # default values (the public API of the chart)
  templates/
    deployment.yaml   # K8s manifests, but with Go-template placeholders
    service.yaml
    _helpers.tpl      # reusable template snippets

templates/ holds ordinary Kubernetes manifests with Go-template placeholders punched into the spots that vary. Helm renders these templates against a values tree to produce final, plain YAML, then sends that to the cluster.

# templates/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}-api
spec:
  replicas: {{ .Values.replicaCount }}
  template:
    spec:
      containers:
        - name: api
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          resources:
            limits:
              memory: {{ .Values.resources.limits.memory }}

values.yaml ships the defaults — and doubles as the chart’s documented public interface:

# values.yaml (defaults)
replicaCount: 1
image:
  repository: registry.example.com/my-api
  tag: dev
resources:
  limits:
    memory: 256Mi

Values override the templates per environment

The same chart renders different manifests because you feed it different values. You keep one small file per environment and pass it at install/upgrade time with -f, or override single keys with --set. Precedence is layered: the chart’s values.yaml is the base, each -f file overrides it left-to-right, and --set flags win over everything.

# values-prod.yaml — only what differs from the defaults
replicaCount: 6
image:
  tag: "1.8.3"
resources:
  limits:
    memory: 1Gi

# one chart, three environments — values are the only difference
helm upgrade --install my-api ./my-api -f values-prod.yaml
helm upgrade --install my-api ./my-api -f values-staging.yaml --set image.tag=rc-42

This is the load-bearing idea: values are the environment boundary. The template encodes the shape of your deployment once; the values carry the per-environment facts. There is exactly one readiness-probe definition to maintain, and dev/staging/prod can no longer drift apart in the parts that should be identical.

Releases: install, upgrade, rollback as one versioned unit

When you helm install (or helm upgrade --install) a chart, Helm creates a named release and records a numbered revision of exactly what it deployed, stored as a Secret in the cluster. Every helm upgrade bumps the revision. Because Helm remembers each revision, helm rollback my-api 4 is a single command that re-applies a known-good past state — the “undo” kubectl apply never had. helm uninstall removes the whole release’s resources together. This turns a deploy from “a pile of YAML I shoved at the API server” into an atomic, versioned, revertible transaction over a named bundle.

helm upgrade --install my-api ./my-api -f values-prod.yaml  # -> revision 5
helm history my-api                                         # see all revisions
helm rollback my-api 4                                      # atomic undo to a known-good state

kubectl apply vs Helm, at a glance

Sharing and reuse: repositories and subcharts

Why write a Postgres StatefulSet from scratch when production-grade charts already exist, are battle-tested, and carry sensible defaults? This is where the chart ecosystem pays off.

Charts are distributable artifacts. Public chart repositories — Bitnami being the best-known — publish production-grade charts for off-the-shelf infrastructure (Postgres, Redis, nginx), so you do not hand-write a stateful-set for a database. You can also compose: a chart can declare dependencies (subcharts) in Chart.yaml, and a parent’s values can override a subchart’s values, so an umbrella chart wires your app together with its dependencies as one release.

Senior notes: never upgrade blind

Two practices separate a safe Helm workflow from a dangerous one. Preview before you apply. helm upgrade --dry-run renders the manifests without touching the cluster; the widely-used helm diff upgrade plugin shows the exact change against the live release, so you see “this will delete a PVC” before it happens, not after. Version everything. A chart carries two versions in Chart.yaml: version (the chart’s own version, bump on any chart change) and appVersion (the app it ships). Treat charts like code — pin the chart version your environments use, and bump it deliberately. And mind the upgrade-vs-recreate gotcha: editing an immutable field (a Job’s spec, a Service’s clusterIP, certain volume fields) cannot be patched in place; the upgrade fails or, depending on the resource, forces a recreate that can mean downtime. Read the diff, know which fields are immutable, and plan the rollout — helm rollback is your safety net, not your strategy.