Initial commit: GitOps Starter Pack

A teaching-first, single-cluster GitOps setup: Talos Linux + Argo CD with an app-of-apps layout, MetalLB pre-installed for real LoadBalancer IPs on bare metal, a demo app, and a progressive docs/ walkthrough with a CLAUDE.md tutor persona and guided bootstrap checklist. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-22 17:30:45 +01:00
commit 92c3ad3191
29 changed files with 2083 additions and 0 deletions
@@ -0,0 +1,87 @@
+# 07 — Adding a new app
+
+This is the payoff for the app-of-apps structure: adding something new is
+"drop a file here," not a special procedure.
+
+## The pattern
+
+Every app in this repo is two things sitting side by side in
+[`apps/`](../apps):
+
+```
+apps/
+  demo.yaml     ← the Application (tells Argo CD where to look)
+  demo/         ← the actual manifests (what gets deployed)
+```
+
+To add a new app called, say, `whoami`:
+
+1. Create `apps/whoami/` and put its Kubernetes manifests in there — a
+   Deployment, a Service, whatever it needs. Use `apps/demo/` as a
+   template for structure and comment style.
+
+2. Create `apps/whoami.yaml`, copied from [`apps/demo.yaml`](../apps/demo.yaml)
+   with the names changed: `metadata.name`, `spec.source.repoURL` (still
+   your fork — see [`docs/04-app-of-apps.md`](04-app-of-apps.md#every-application-needs-its-own-repourl)
+   for why every Application needs this set individually), `spec.source.path`
+   (→ `apps/whoami`), and `spec.destination.namespace`.
+
+3. Commit and push both. That's it — no `kubectl apply`. The app-of-apps
+   (already watching `apps/` — see
+   [`docs/04-app-of-apps.md`](04-app-of-apps.md)) notices the new
+   `whoami.yaml`, creates the `whoami` Application, which in turn deploys
+   everything in `apps/whoami/`.
+
+4. Confirm: `argocd app list` should show `whoami` alongside `demo` and
+   `metallb`.
+
+## Manifest-based vs. Helm-based apps
+
+`apps/demo/` is plain Kubernetes manifests — no templating, nothing to
+render — which is why it's the easiest one to read start to finish while
+you're still learning what each field does.
+
+An app's folder can be a **Helm chart** instead. Argo CD detects this
+automatically: if it finds a `Chart.yaml` at the source path, it treats
+that app as a Helm chart rather than plain manifests. This matters most
+when you want to pull in a *third-party* chart — a database, an ingress
+controller, anything with a public Helm chart already maintained by
+someone else — without copying their manifests into your repo by hand. You
+declare it as a dependency and let Helm (via Argo CD) resolve it.
+
+You don't have to imagine this one — it's already running.
+[`apps/metallb/`](../apps/metallb) is exactly this pattern, for real: its
+[`Chart.yaml`](../apps/metallb/Chart.yaml) declares a dependency on the
+upstream MetalLB chart, and it even goes a step further by also carrying
+its own templates ([`apps/metallb/templates/`](../apps/metallb/templates))
+for two custom resources that configure MetalLB once it's installed —
+useful to see if you ever need an app that's *mostly* someone else's chart
+but with a couple of your own resources layered on top. See
+[`docs/05-metallb.md`](05-metallb.md) for the full walkthrough, and
+[`apps/metallb.yaml`](../apps/metallb.yaml) for the matching Application —
+notice it's structurally identical to `apps/demo.yaml`; Argo CD figures out
+it's a Helm chart on its own from the presence of `Chart.yaml`, no new
+syntax required in the Application resource itself.
+
+> **Ask Claude:** "walk me through how I'd bring in [some real chart you
+> have in mind] as a Helm-based app in this structure" whenever you're
+> ready to try one of your own — `apps/metallb/` is a real template to
+> copy from.
+
+If the new app has its own `LoadBalancer` Service (see
+[`docs/05-metallb.md`](05-metallb.md)), pick its address from the free
+addresses listed in [`docs/network.md`](network.md), and add a row for it
+there once it's up — that file only stays useful if every app that gets an
+address shows up in it.
+
+## Checklist
+
+- [ ] New app's manifests live in `apps/<name>/`
+- [ ] New `apps/<name>.yaml` Application created, modeled on `demo.yaml`
+- [ ] `repoURL` set to your fork, not left as a placeholder
+- [ ] Pushed to Git
+- [ ] `argocd app list` shows the new app, `Synced`/`Healthy`
+- [ ] If it has a `LoadBalancer` Service, its address is recorded in `docs/network.md`
+
+Continue to [`docs/08-growing-up.md`](08-growing-up.md) for what to add
+next as this cluster grows beyond a learning setup.