Helm & GitOps (Argo CD)

1 · Why raw YAML doesn't scale

Picture the moment this bites you. You ship a service to dev with a hand-written deployment.yaml. It works, so you copy it to a staging/ folder, bump the replica count, and copy it again to prod/ with a different image tag and hostname. Three folders, three near-identical files, all happy. Then a real change arrives — add a liveness probe, tweak a resource limit — and now you must make that same edit in three places, perfectly, forever. Miss one and prod quietly diverges from staging. That divergence has a name — configuration drift — and it's the source of a huge share of "but it worked in staging!" incidents.

Here's the analogy that makes it click: hand-copied manifests are like retyping the same letter for a hundred recipients, changing only the name each time. Nobody does that — you write one form letter with a {{ name }} blank and mail-merge the differences. Helm is mail-merge for Kubernetes manifests. You write the shape of the Deployment once, leave blanks where environments differ, and fill those blanks from a small per-environment values file. The structure lives in exactly one place, so a change to the structure is one edit that every environment inherits automatically.

The common mistake to name up front: beginners reach for copy-paste-and-tweak because it feels faster on day one — and it is, for the first deploy. The cost is deferred and compounding. Every environment you add multiplies the edit burden, and the files slowly rot apart because the only thing keeping them in sync is human discipline. The fix isn't more discipline; it's removing the duplication so there's nothing to keep in sync. You want one templated definition plus per-environment values — the base shape shared, only the genuine differences (replica counts, image tags, hostnames) called out separately. That's Helm.

You have the same app in dev, staging, and prod — same shape, different replica counts, image tags, and hostnames. Copy-pasting three near-identical manifest sets means every change is three edits and a chance to drift. You need one templated definition plus per-environment values. That's Helm.

2 · A Helm chart, templated

If Helm is mail-merge, a chart is the reusable letter template plus its default answers, bundled so anyone can run it. That bundling matters more than it first sounds: a chart isn't just "a file with blanks in it," it's a self-contained, shareable, versioned package. Someone else can grab your chart, supply their own values, and get a working install without ever seeing the templates — the same way you helm install a Postgres or an nginx-ingress chart today without hand-writing a line of their YAML.

Think of the three pieces as a fill-in-the-blank form with a cover sheet. Chart.yaml is the cover sheet — the name and version, so Helm knows what this package is. values.yaml is the default answers already written into the blanks, so the form is usable out of the box. And templates/ holds the actual forms — ordinary Kubernetes manifests, except wherever a value should go you write a {{ }} placeholder like {{ .Values.replicaCount }} instead of a hardcoded number. When you install, Helm does the merge: it walks each template, substitutes the placeholders with real values, and emits plain Kubernetes YAML — the same YAML you'd have written by hand, just generated instead of typed.

The mental model to hold — and the mistake to avoid: a template is not valid Kubernetes YAML on its own. Those {{ }} braces are Helm's Go-template syntax; the cluster has never heard of them. Rendering happens on your machine (or in Argo CD), before anything reaches the cluster — the API server only ever sees the finished, substituted manifest. Newcomers sometimes try to kubectl apply a template directly and get a parse error, or they hardcode a value "just this once" and reintroduce the very drift the chart existed to prevent. The rule of thumb: anything that legitimately differs between environments belongs in a values file as a placeholder, never baked into the template. Keep that split clean and one chart genuinely serves every environment.

A chart is a directory: Chart.yaml (metadata), a values.yaml (defaults), and templates/ (manifests with {{ }} placeholders). Helm renders the templates against the values to produce plain Kubernetes YAML.

templates/deployment.yamlapiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}-web
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels: { app: {{ .Release.Name }}-web }
  template:
    metadata:
      labels: { app: {{ .Release.Name }}-web }
    spec:
      containers:
        - name: app
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          ports:
            - containerPort: {{ .Values.containerPort }}

values.yaml# values.yaml  (defaults)
replicaCount: 2
image:
  repository: ghcr.io/example/web
  tag: "1.2.0"
containerPort: 8000
---
# values-prod.yaml  (overrides only what differs)
replicaCount: 6
image:
  tag: "1.2.0"        # promote a tested tag to prod

3 · The helm lifecycle

Here's the shift in thinking that makes Helm worth learning past templating. A raw kubectl apply is fire-and-forget: you push some YAML, the cluster changes, and nothing remembers what it looked like before. If the new version is broken, "rolling back" means finding the old YAML (hope you kept it), figuring out exactly what changed, and applying it again by hand under pressure. Helm removes that whole scramble by treating your installed app as a release — a named, versioned thing with a history you can walk backwards through.

The analogy is the package manager already on your laptop. When you apt install or brew install something, you don't think in individual files — you think "install this package," "upgrade it," "remove it," and the tool tracks what's installed and at what version. Helm brings that exact experience to a running app in Kubernetes: helm install creates release revision 1, each helm upgrade stamps a new numbered revision, helm history lists them, and helm rollback web 1 re-applies a known-good revision in a single command — no rebuild, no hunting for old manifests. Every revision is immutable, so revision 1 still means exactly what it meant when you installed it.

The trap that surprises people: because upgrades feel this easy, it's tempting to tweak a live release with an ad-hoc --set image.tag=1.3.0 from your terminal whenever something needs changing. It works, and the demo below shows it precisely because you'll see it in the wild — but reach for it and you've quietly created a problem. That flag changes what's running without changing what's written down anywhere: the new tag lives only in your shell history, so no reviewer saw it and no repo records it. Fine for a throwaway demo, genuinely dangerous for prod, and the exact seam where environments start drifting from their definitions. Hold that tension as you read — it's the precise gap the GitOps sections ahead are built to close.

Helm manages a release like a package manager: install it, upgrade it, and roll it back — with history.

helm.shhelm install web ./web-chart                       # release named "web"
helm install web ./web-chart -f values-prod.yaml   # prod values
helm upgrade web ./web-chart --set image.tag=1.3.0 # change one value
helm history web                                   # revisions
helm rollback web 1                                # back to revision 1
helm uninstall web

REVISION  UPDATED    STATUS      CHART        APP VERSION
1         ...        superseded  web-0.1.0    1.2.0
2         ...        deployed    web-0.1.0    1.3.0

4 · GitOps — git as the source of truth

Ask a room of engineers "what's actually running in prod right now?" and watch the pause. With push-based deploys the honest answer is "whatever the last pipeline run, or the last person with kubectl, happened to apply" — and to be sure you'd have to go read the live cluster. That uncertainty is the disease GitOps cures. The core move is almost philosophical: stop treating the cluster as the thing you change, and start treating it as a projection of a text file you can read, review, and version. The cluster becomes a screen showing what git says; git becomes the thing you actually edit.

The analogy is a thermostat. You don't walk around the house adjusting each radiator by hand — you set a target temperature, and a controller continuously compares the room to that target and nudges reality until they match. GitOps works the same way: git holds the desired state (the target), and a controller running inside the cluster continuously compares the live cluster to git and reconciles any difference. Note the direction — the controller pulls from git; nothing outside the cluster pushes into it. This flips the model you built in CD5, where a pipeline reached in with kubectl apply. Now the pipeline's job ends at a git commit, and the cluster comes and fetches its own instructions.

Two consequences fall out for free, and they're the reason teams adopt this. First, everything is a git commit — reviewed in a PR, attributed to an author, and instantly revertable, so "roll back prod" becomes git revert and your deploy history is your git log. Second, the credential boundary inverts: because the controller pulls from inside, no external CI system or engineer's laptop needs cluster credentials, shrinking the attack surface dramatically. The common misconception to clear up: GitOps is not "using git to store YAML" — plenty of push pipelines already do that. The defining ingredient is the in-cluster controller that continuously reconciles, so the cluster actively self-heals toward git rather than only changing when someone runs a pipeline. Storing manifests in git is necessary; the reconciliation loop is what makes it GitOps.

GitOps flips the delivery model. Instead of a pipeline pushing kubectl apply into the cluster, a controller inside the cluster pulls the desired state from a git repo and continuously makes the cluster match it. The repo is the single source of truth; every change is a git commit (reviewed, audited, revertable); and the cluster self-heals toward git.

5 · Argo CD Applications, sync & drift

GitOps is the idea; Argo CD is the thermostat that actually runs the loop. Everything in the previous section — desired state in git, continuous reconciliation, self-healing — needs a concrete piece of software living in the cluster to do the watching and the nudging. Argo CD is the most widely used one, and the beautiful part is that you configure it the same way you configure everything else in Kubernetes: with a YAML object. You don't script the reconciliation; you declare what "in sync" means and let the controller enforce it.

That object is an Application, and reading it is just answering three questions: what do I want (a repo URL, a branch, a path, and which values file), where should it run (a target cluster and namespace), and how aggressively should Argo CD keep them matched (the sync policy). With that in hand, Argo CD renders the manifests from git, diffs them against what's actually live, and paints every resource Synced (git and cluster agree) or OutOfSync (they've diverged) — that diff is drift detection, made continuous and visible instead of discovered during an outage. Think of it as a spell-checker for your cluster: it constantly underlines the moment reality stops matching the source of truth.

Two policy switches turn that passive diff into active enforcement, and they're worth understanding precisely because they change how your whole team operates. auto-sync means Argo CD doesn't just report drift, it corrects it — a new commit lands and the cluster updates without anyone clicking "deploy." self-heal extends that to changes made on the cluster side: run a manual kubectl edit and Argo CD treats it as drift from git and reverts it. And here's the mistake that catches every team new to GitOps — someone SSHes in, hand-patches a Deployment to fix a fire, walks away satisfied, and minutes later their fix has silently vanished. That's not Argo CD malfunctioning; it's Argo CD doing its one job. The lesson to internalize: with self-heal on, the cluster is read-only to humans — the only durable way to change it is to change git. (The prune option, which you'll see below, is the matching rule for deletions: remove a resource from git and Argo CD removes it from the cluster.)

Argo CD is the leading GitOps controller. You define an Application that points at a repo path and a target cluster/namespace. Argo CD compares the rendered manifests in git to what's live and reports Synced or OutOfSync; it can auto-sync, and with self-heal it reverts manual kubectl changes back to git.

application.yamlapiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: web
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/example/deploy.git
    targetRevision: main
    path: web-chart
    helm:
      valueFiles: [values-prod.yaml]
  destination:
    server: https://kubernetes.default.svc
    namespace: web
  syncPolicy:
    automated:
      prune: true        # delete resources removed from git
      selfHeal: true     # revert manual drift back to git

6 · Closing the loop with CI (CD5 → here → ch08)

Every piece you've met has been half of one machine; this section bolts them together. CD5 gave you continuous integration — build the image, test it, scan it, push it to a registry. This lesson gave you continuous delivery the GitOps way — a cluster that pulls its desired state from git. The question that's been hanging in the air is the handoff: how does a passing test on a code push actually become a new version running in prod, without anyone typing kubectl? The answer is a clean seam, and knowing exactly where that seam sits is what separates people who "use CI/CD" from people who can design it.

Here's the relay-race analogy. CI runs the first leg and carries the baton only as far as a git commit: it builds and verifies the image, pushes it to the registry with an immutable tag, then commits that tag into the deploy repo — bumping image.tag in the right values file. Then it hands off. Argo CD runs the second leg: it sees the new commit and reconciles the cluster to match. The baton is the commit; the two runners never occupy the same track. This is why the earlier warning about --set from a laptop mattered — that was a runner trying to sprint the whole race alone, skipping the git handoff that makes everything auditable.

The insight worth carrying out of this whole chapter: CI and CD have genuinely different jobs, and conflating them is the common design error. CI produces artifacts and proposes desired state; CD (GitOps) makes reality match desired state. Draw that line cleanly and three good things fall out automatically — the pipeline never needs cluster credentials (only the in-cluster controller changes the cluster), every deploy is a reviewed commit you can read in git log, and rollback collapses to git revert. It also explains why your ch08 DevOps agent fits so naturally here: an agent that opens a PR to bump a tag is just another well-behaved producer of proposed desired state — it plays CI's role, and GitOps delivers its proposal exactly like any human's. That is the delivery backbone the ch08 capstone is built on.

Put it together and you get the full delivery pipeline this course has been building toward: CI (CD5) builds and tests the image and pushes it to a registry, then commits the new tag to the deploy repo; Argo CD sees the commit and syncs the cluster. Your ch08 DevOps agent can even be the thing that opens that PR. CI's job ends at git; delivery is the cluster pulling from git.

apiVersion: apps/v1
kind: Deployment
metadata: { name: {{ .Release.Name }}-web }
spec:
  replicas: {{ .Values.replicaCount }}
  selector: { matchLabels: { app: {{ .Release.Name }}-web } }
  template:
    metadata: { labels: { app: {{ .Release.Name }}-web } }
    spec:
      containers:
        - name: app
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          ports: [ { containerPort: {{ .Values.containerPort }} } ]

replicaCount: 2
image: { repository: ghcr.io/example/web, tag: "1.2.0" }
containerPort: 8000

replicaCount: 6        # dev default was 2
image: { tag: "1.2.0" } # the promoted, tested tag

helm install web ./web-chart                       # dev (defaults)
helm install web-prod ./web-chart -f values-prod.yaml   # prod (overrides)

helm install web ./web-chart
helm upgrade web ./web-chart --set image.tag=1.3.0
helm history web         # revision 1 superseded, revision 2 deployed
helm rollback web 1      # instantly return to revision 1

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata: { name: web, namespace: argocd }
spec:
  project: default
  source:
    repoURL: https://github.com/example/deploy.git
    targetRevision: main
    path: web-chart
    helm: { valueFiles: [values-prod.yaml] }
  destination: { server: https://kubernetes.default.svc, namespace: web }
  syncPolicy: { automated: { prune: true, selfHeal: true } }