Skip to content

Kubernetes & Helm

Core · prereq 03 (Containers/Podman) · ~3–4 days — the deepest Core module (8 submodules covering workloads, networking, storage, config/secrets, scheduling, autoscaling, observability, and RBAC, plus Helm). Reality check: this is the 80/20 on-ramp; real fluency runs 100h+ of hands-on practice — Antoine spent ~400h across Kubernetes, Go, and AWS to reach production competence.

Podman gets one host reliably running containers. Production doesn't run on one host — workloads need to survive a node dying, get more replicas under load, and roll out changes without downtime. Kubernetes is the layer that does this: you declare the desired state (a Deployment, a Service) and a set of control-plane controllers continuously reconciles the cluster toward it, rather than you scripting each change by hand. Helm sits on top as the packaging layer — instead of hand-writing and hand-applying a stack of YAML, you install a chart as a versioned release you can upgrade and roll back as one unit.

TL;DR — in 30 seconds:

  • Kubernetes reconciles a declared desired state (a Deployment, a Service) via control-plane controllers, instead of you scripting each change by hand.
  • Helm packages a stack of K8s YAML into a versioned chart, installed as a release you can upgrade and roll back as one unit.
  • Core objects to know first: Pod, Deployment, Service, ConfigMap/Secret, plus RBAC for least-privilege access.

Learning objectives

By the end, the junior can:

  • Name the core K8s objects (Pod, Deployment, Service, ConfigMap/Secret) and what each is for.
  • Sketch the control plane (api-server, etcd, scheduler, controller-manager) + the node's kubelet/kube-proxy, and explain the control-plane/data-plane split.
  • Grant a workload least-privilege access with RBAC (Role/ClusterRole + binding + ServiceAccount).
  • Debug a broken Pod — read CrashLoopBackOff / ImagePullBackOff / Pending / OOMKilled from kubectl describe/logs.
  • Explain a Helm chart vs release vs revision, and install/upgrade/rollback a chart.
  • Read a chart's values.yaml and override a value for an environment.
Do it with Claude

Pair, Do and Prove run in Claude Code, with the onboarding-tutor skill. Click a button to copy the exact prompt, then paste it into Claude Code in this repo.

1. Learn · acquire the concept

Read (concepts first, then Helm): - Foundations: the kubernetes chapter — the object model (Pod, Deployment, Service, Ingress, Namespaces). - Core concepts: the kubernetes course — control plane, ConfigMap/Secret, RBAC, and debugging a broken Pod (the depth the gate expects). - Course: the helm course — focus §2 (mental model), §4 (chart anatomy), §5 (templates/values), §6 (install), §7–8 (releases & rollback). Skip for now: §13–14 (authoring/publishing your own chart) — revisit later. Glossary (beat 5): the module’s Anki deck Read next: Kubernetes documentation and Helm documentation (official docs — the full object model, chart authoring, and CLI reference).

Check yourself — what's the difference between what a Deployment does and what a Service does?

A Deployment keeps N replicas of a Pod template running and manages rollout/rollback when the template changes. A Service gives a stable virtual IP and DNS name in front of a set of Pods so callers never track individual Pod IPs — one manages "how many, and which version," the other "how traffic finds them."

Check yourself — name the control-plane components and what each does, in one line each.

api-server (the single front door — every read/write goes through it), etcd (the source of truth for cluster state), kube-scheduler (picks a node for each unscheduled Pod), and controller-manager (runs the reconcile loops that close the gap between desired and actual state).

2. Pair · passive → active

Drive onboarding-tutor:

  • "Explain Pod vs Deployment vs Service with a one-line job for each."
  • "3-line mental model: what does Helm add on top of raw K8s YAML?"
  • "Quiz me on chart vs release vs revision before I install anything."

Done when: you can explain what Helm buys you over kubectl apply, unprompted.

3. Do · produce an artifact

Exercise — install, upgrade, roll back a chart on a local cluster:

  1. Install the tools first (helm course §3): brew install kubectl helm plus a local-cluster tool (brew install kind, or minikube).
  2. Stand up a local cluster (kind or minikube).
  3. helm install a small public chart (e.g. a demo web app). Inspect the release and the objects it created (kubectl get all).
  4. helm upgrade overriding one value (e.g. replica count) via --set or a values file. Confirm the change landed.
  5. helm rollback to revision 1 and confirm the revert.

  6. helm template the chart and read the rendered manifests.

  7. The tutor hints; it does not run the cluster for you.

Common gotchas

  • Treating STATUS: deployed as proof the app is healthy. Fix: that only means Helm successfully applied the manifests to the API server — confirm with kubectl get pods / kubectl rollout status that the new Pods are actually Running and Ready, not just that Helm didn't error.
  • Passing --set with a key that doesn't match the chart's actual values.yaml structure. Fix: Helm accepts almost any --set path without complaint — a typo'd or wrong-nested key silently does nothing to the rendered manifests. Check helm get values (or re-run helm template) after, not just that the --set command exited 0.
  • Editing a live object with kubectl edit instead of changing values and re-running helm upgrade. Fix: a direct edit drifts from what Helm thinks the release looks like — the next helm upgrade can silently overwrite (or fight) your manual change. Change values and upgrade through Helm.
  • Expecting helm rollback to also revert your local values.yaml/--set flags. Fix: rollback only reverts the release in the cluster to a previous revision's already-rendered state — it doesn't touch files on your machine; keep editing the same local file and your next upgrade can reintroduce what you just rolled back.
Check yourself — helm upgrade reports STATUS: deployed. Does that mean your app is healthy?

No — it means Helm's manifests were accepted by the API server, not that the resulting Pods are Running and Ready. Confirm separately with kubectl get pods or kubectl rollout status.

Check yourself — after helm rollback to revision 1, what actually changed, and what didn't?

The release's live objects in the cluster reverted to revision 1's rendered manifests, and Helm recorded a new revision documenting that rollback happened — but your local values.yaml/chart files on disk are untouched. The revision history is what let Helm compute the diff to revert.

Done when: you've installed → upgraded → rolled back a release and can show the revision history.

4. Prove · understanding gate

Mandatory. Pass bar in the Socratic gate.

  1. Walkthrough: From helm template output, point at a Deployment and a Service and explain each field you changed.
  2. Alternative: Overriding via --set vs a values file — when each? Why not just edit the rendered YAML directly?
  3. Failure & debug: A pod is CrashLoopBackOff after your upgrade. Walk me through diagnosing it (kubectl describe, logs).
  4. Provenance: Which values/commands did the agent suggest, and how did you verify the upgrade actually took effect (not just that Helm said "upgraded")?

Pass bar: you can defend the release lifecycle and read rendered manifests. "Helm said OK" without verification = back to Pair.

5. Retain · fight forgetting

Study the module deck SE Onboarding::04 Kubernetes & Helm — theme subdecks cover Kubernetes core (workloads/pods · control plane & scheduling · networking · config/storage · security/RBAC · debugging/ops) plus Helm. It syncs to your Anki automatically on pull (anki-sync).

Done when you can recall: Pod/Deployment/Service, the control-plane components, RBAC, common failure modes (CrashLoopBackOff etc.), and Helm chart/release/values.

Key takeaways

  • Kubernetes reconciles declared state. You describe a Deployment/Service; the control plane's controllers keep nudging the cluster toward it instead of you scripting each change.
  • The control-plane/data-plane split matters for debugging. api-server, etcd, scheduler, controller-manager decide what should run; kubelet and kube-proxy on each node make it actually run there.
  • A Deployment and a Service do different jobs. One manages how many replicas and which version; the other gives callers a stable address so they never track individual Pod IPs.
  • RBAC is least-privilege by composition: a Role/ClusterRole grants permissions, a binding attaches it to a subject, a ServiceAccount is the subject a workload runs as.
  • kubectl describe/logs is the first move on a broken Pod, not a guess — CrashLoopBackOff, ImagePullBackOff, Pending, and OOMKilled each point at a different layer.
  • Helm's STATUS: deployed only proves the API server accepted the manifests — confirm Pods are actually Running/Ready separately, and prefer helm upgrade/rollback over editing live objects so the release history stays true.

Go deeper — curated resources

Hand-picked external material to take this topic further — the best books, courses, talks, and writing. Cost is tagged Free, Free online (full text/course free on the web), or Paid.

Gate log (mentor fills on pass)

  • Date passed: / Passed by: / checked by: / Weak spots: