k8s-starter-pack/docs/07-your-first-change.md

07 — Your first change

Everything so far proved Argo CD can deploy what's in Git. This doc proves the part that actually matters day to day: changing what's in Git and watching the cluster follow, with no kubectl apply from you at all.

Steps

1. Open apps/demo/configmap.yaml and edit the HTML — change the <h1> text to something of your own.

2. Commit and push, exactly like any other Git change:

   git add apps/demo/configmap.yaml
   git commit -m "Personalize the demo page"
   git push
   

3. By default, Argo CD polls Git every three minutes, so your change will show up on its own — but you can force it immediately:

   argocd app sync demo
   

4. Watch it happen:

   argocd app get demo
   

   You'll see Argo CD detect that the live ConfigMap no longer matches Git, and correct it.

5. Refresh http://<your-demo-app-IP> (the MetalLB address you gave it in docs/05-metallb.md). Your new text should be there. Note that nginx itself never restarted — Kubernetes noticed the mounted ConfigMap changed and updated the file inside the running Pod's filesystem automatically. (This is specific to volume-mounted ConfigMaps; not every kind of change is this seamless — a change to the Deployment's image, for instance, does trigger a Pod restart, by design.)

   Give it up to a minute if the page doesn't look different yet. argocd app get demo shows the ConfigMap object updating right away, but kubelet — the agent on the node that actually keeps a Pod's mounted files in sync — only re-checks mounted ConfigMaps on its own periodic cycle, not instantly. A blank refresh isn't a sign anything's wrong; give it a moment and refresh again.

What just proved itself

You changed a file, pushed it, and never touched the cluster directly. That gap between "commit" and "running" being closed automatically, without you doing the applying, is GitOps. Everything from here on — every future app you add — works exactly this way: edit, commit, push, done.

Try triggering self-healing

Optional, but worth seeing once. Reintroduce drift by hand:

kubectl -n demo patch configmap demo-page --type merge \
  -p '{"data":{"index.html":"<h1>hand-edited, not from Git</h1>"}}'

Watch the ConfigMap object itself, not the browser, for this one — it's the more reliable way to see the timing: Argo CD's self-heal typically reverts a hand-edit within a second or two, which is faster than kubelet's own mount-sync cycle usually gets around to reflecting a change in the served page at all (see the note above). Check the object directly:

kubectl -n demo get configmap demo-page -o jsonpath='{.data.index\.html}'

Run that once right after the patch above and you may catch your hand-edited text; run it again a couple of seconds later and it'll already be back to what's in Git — with no action from you. That's selfHeal: true from apps/demo.yaml in action. See docs/00-what-is-all-this.md for the loop that just ran.

Ask Claude: "if selfHeal is on, how would I ever safely debug something by changing it live in the cluster first?" — a real question people run into once this clicks, and worth understanding before you hit it for real.

Checklist

• Edited apps/demo/configmap.yaml, committed, pushed
• Saw the change reflected in argocd app get demo
• Saw the new text in the browser
• (Optional) Watched self-healing revert a hand-made change

Continue to docs/08-adding-new-apps.md to add something of your own.