vps-k8s/docs/00-what-is-all-this.md

00 — What is all this?

You're comfortable with servers, SSH, config files, and the command line. You've probably never touched Kubernetes. This doc gives you the mental model before you type a single command — everything after this builds on it.

The problem this stack solves

Say you run a few services on a server. The traditional way: SSH in, install things, edit config files by hand, restart services, and remember what you did (or don't, and regret it later). It works, but nothing records why the server looks the way it does — the truth lives only on that one machine, in your head, and in shell history if you're lucky.

This stack solves that by making a Git repository the single source of truth for "what should be running," and using software to continuously make the real cluster match it. You stop making changes by hand. You edit a file, push it, and a robot applies it for you — the same way every time, with a record of every change in git log.

The five pieces, in plain terms

Kubernetes is software that runs on one or more machines and manages containers for you: starts them, restarts them if they crash, and moves them to a different machine if one dies (once you have more than one — see docs/08-growing-up.md). You describe the end state you want ("run one copy of this"); Kubernetes' job is to make that true and keep it true. This is what people mean by declarative: you state the destination, not the steps to get there.

Talos Linux is the operating system your machine runs. It's built for exactly one purpose — running Kubernetes — and nothing else. There's no SSH, no shell, no package manager to fiddle with by hand. You configure it by sending it a config file over the network (a "machine config"), the same declarative idea as Kubernetes itself, just one layer lower. Less to install, less to secure, less that can drift out of a known state.

Argo CD is the piece that watches a Git repository — this one — and continuously makes the cluster match whatever it finds there. This is called GitOps: Git isn't just where your config lives, it's where change happens. You don't run kubectl apply for day-to-day changes; you edit a file, commit, push, and Argo CD does the applying.

App of apps is the pattern this repo uses to organize what Argo CD manages. Rather than one Application resource pointing at everything, one Application — the app-of-apps — watches a folder (apps/) full of other Application definitions, each pointing at its own small piece. Add a new app by adding a new file — see docs/07-adding-new-apps.md.

MetalLB solves a specific problem: on a cloud provider, asking for a public IP address for a service is one API call away; on your own bare metal machine, nothing hands those out automatically. MetalLB runs inside the cluster and fills that gap, so apps here can get a real, dedicated IP address on your network instead of an awkward fixed port. It's pre-installed in this repo, not a "next step" — see docs/05-metallb.md.

Architecture — the shape of what you'll build

┌─────────────────────────┐
│   Git repository (this  │
│   repo, on GitHub)      │
│                         │
│   apps/demo.yaml        │
│   apps/demo/*.yaml      │──┐
│   apps/metallb.yaml     │  │  watched by
│   apps/metallb/*        │  │
└─────────────────────────┘  │
                              ▼
                    ┌───────────────────┐
                    │      Argo CD       │  runs inside the cluster
                    │  (installed once,  │
                    │   imperatively)    │
                    └─────────┬──────────┘
                              │ applies manifests
                              ▼
                 ┌─────────────────────────────┐
                 │   Talos Linux node           │
                 │   (control plane + worker,   │
                 │    single node)               │
                 │                               │
                 │  ┌────────────┐ ┌──────────┐  │
                 │  │demo         │ metallb-   │  │
                 │  │namespace:   │ system:    │  │
                 │  │nginx Pod ⇄  │ hands out  │  │
                 │  │Service      │ a real IP  │  │
                 │  │(LoadBalancer)◄─address to │  │
                 │  │             │ that Service│  │
                 │  └────────────┘ └──────────┘  │
                 └─────────────────────────────┘

Everything below the Git repo is a consequence of what's in Git. If the box labelled "Talos Linux node" burned to the ground and you rebuilt it from scratch, replaying this repo against it would recreate everything except the raw OS bootstrap (docs/02), the one-time Argo CD install (docs/03), and the handful of network-specific addresses you choose in docs/05 — all deliberately kept outside the loop, since something has to start it and nothing in Git can know your LAN's IP layout for you.

The reconciliation loop

This is the mechanism that makes GitOps actually work, not just a nice diagram. Argo CD repeats this forever, by default every few minutes (and instantly, if you ask it to):

   ┌────────────────────────────────────────────────┐
   │                                                  │
   │   1. Read desired state from Git                │
   │              │                                   │
   │              ▼                                   │
   │   2. Read actual state from the cluster          │
   │              │                                   │
   │              ▼                                   │
   │   3. Diff them                                   │
   │              │                                   │
   │         ┌────┴────┐                              │
   │         │          │                              │
   │    no diff    diff found                          │
   │         │          │                              │
   │         │          ▼                              │
   │         │   4. Apply the change so the             │
   │         │      cluster matches Git                │
   │         │          │                              │
   │         └────┬─────┘                              │
   │              ▼                                   │
   │        wait, then repeat                          │
   │                                                  │
   └────────────────────────────────────────────────┘

"Reconciliation" just means step 3 and 4: noticing a difference between what should exist and what does, and fixing it. This loop is also what makes Argo CD self-healing — if someone changes the cluster by hand (kubectl edit during an emergency, say), the very next loop notices the drift from Git and reverts it. Git wins, always. That's the whole point.

Ask Claude: before moving on, try asking "why does Git winning matter — what goes wrong without it?" It's worth being able to answer in your own words before you start building.

What's next

Continue to docs/01-prerequisites.md, or jump straight to docs/checklist.md if you'd rather work through a condensed step-by-step list with Claude alongside you.