Maxwell MorrisandClaude Sonnet 5
92c3ad3191
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>
88 lines
4.0 KiB
Markdown
88 lines
4.0 KiB
Markdown
# 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.
|