So far we have applied manifests by hand. It works for learning, but it doesn’t scale: each environment becomes a copy with invisible differences, and no one knows which version is running.

Helm solves the problem of packaging and versioning the deployment. It’s not magic — it’s template + values + a release registry.

Course seal: tested on Kubernetes 1.35 with Helm 3.

The real problem

Without Helm, three environments usually become three folders:

k8s/
  homolog/deployment.yaml
  prod/deployment.yaml
  staging/deployment.yaml

Differences: image, replicas, resources, variables. One day someone fixes only in prod and the rest stays wrong. It’s the beginning of drift.

With Helm:

chart/
  Chart.yaml
  values.yaml
  values-homolog.yaml
  values-prod.yaml
  templates/
    deployment.yaml
    service.yaml
    ingress.yaml
    _helpers.tpl

One template, three sets of values.

Minimal structure

Chart.yaml:

apiVersion: v2
name: portal
description: Portal Nyverra
type: application
version: 1.4.0
appVersion: "v5"

• version: version of the chart.
• appVersion: version of the application (image).

They are different things. Mix them up and you lose traceability.

Templates and values

values.yaml (defaults):

replicaCount: 2
image:
  repository: ghcr.io/example/portal-backend
  tag: v5
  pullPolicy: IfNotPresent
resources:
  requests:
    cpu: 100m
    memory: 256Mi
  limits:
    cpu: "1"
    memory: 512Mi
env:
  LOG_LEVEL: info

templates/deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "portal.fullname" . }}
  labels:
    {{- include "portal.labels" . | nindent 4 }}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      {{- include "portal.selectorLabels" . | nindent 6 }}
  template:
    metadata:
      labels:
        {{- include "portal.selectorLabels" . | nindent 8 }}
    spec:
      containers:
        - name: backend
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          imagePullPolicy: {{ .Values.image.pullPolicy }}
          resources:
            {{- toYaml .Values.resources | nindent 12 }}
          env:
            {{- range $k, $v := .Values.env }}
            - name: {{ $k }}
              value: {{ $v | quote }}
            {{- end }}

_helpers.tpl centralizes names and labels. Without it, each template invents a different name and kubectl get becomes archaeology.

Values per environment

values-prod.yaml:

replicaCount: 4
image:
  tag: v5
resources:
  requests:
    cpu: 500m
    memory: 512Mi
  limits:
    cpu: "2"
    memory: 1Gi

Render without applying:

helm template portal ./chart -f values-prod.yaml
helm template portal ./chart -f values-prod.yaml --show-only templates/deployment.yaml

Always review the render before install. It’s Helm’s --dry-run.

Install, upgrade, rollback

helm upgrade --install portal ./chart -n portal --create-namespace -f values-prod.yaml
helm list -n portal
helm status portal -n portal
helm history portal -n portal
helm rollback portal 3 -n portal

Helm stores releases as Secrets in the namespace (sh.helm.release.v1.portal.v1). Don’t delete them by hand.

Hooks

Hooks run at moments of the cycle:

• pre-install / pre-upgrade: database migrations.
• post-install / post-upgrade: smoke test.
• pre-delete: cleanup.

metadata:
  annotations:
    "helm.sh/hook": pre-upgrade
    "helm.sh/hook-weight": "-5"
    "helm.sh/hook-delete-policy": before-hook-creation

Careful: a migration hook runs before the rollout. If the new code version depends on the migration, that’s fine. If the migration breaks the old version, you have an error window.

What not to put in the chart

• Real secrets in values.yaml (use External Secrets or a secret manager).
• Registry credentials in plain text.
• Configuration that changes per cluster and should be GitOps (chapter 22).

Lab

1. Create the chart:

helm create portal
rm -rf portal/templates/tests

2. Adjust values.yaml, _helpers.tpl, and the templates.
3. Render and compare environments:

helm template portal ./portal -f values-homolog.yaml > /tmp/homolog.yaml
helm template portal ./portal -f values-prod.yaml > /tmp/prod.yaml
diff /tmp/homolog.yaml /tmp/prod.yaml

4. Install in homolog and upgrade with --atomic:

helm upgrade --install portal ./portal -n portal --create-namespace \
  -f values-homolog.yaml --atomic --timeout 5m

5. Force a failure (nonexistent image) and observe --atomic revert by itself.
6. Manual helm rollback and check helm history.

Common errors

Symptom	Cause
rendered manifests contain a resource that already exists	resource created outside Helm
Upgrade stuck in pending-upgrade	hook/rollout failed without timeout
Ignored values	-f in wrong order or typo in key
nil pointer evaluating interface	missing key in values
Silent drift	resource edited by hand after install
Rollback doesn't revert image	appVersion diverging from tag
Secret leaked to Git	sensitive value in values.yaml

Checklist

• [ ] Chart.yaml with coherent version and appVersion.
• [ ] _helpers.tpl for names and labels.
• [ ] values-<env>.yaml per environment.
• [ ] helm template reviewed before upgrade.
• [ ] --atomic and --timeout on upgrade.
• [ ] Resources (requests/limits) coming from values.
• [ ] No plain-text secrets in the chart.
• [ ] helm history and rollback tested.

Glossary

• chart: Helm package.
• release: instance of a chart in the cluster.
• values: template parameters.
• hook: resource executed at a phase of the cycle.
• atomic: automatically reverts on failure.
• drift: difference between what is declared and what runs.

Next

Chart packaged. Now who applies the chart to the cluster? In the next chapter, GitOps with ArgoCD: Git as the source of truth and the cluster self-correcting.

Next: Kubernetes Course 22 — GitOps with ArgoCD