vps-k8s/README.md

# GitOps Starter Pack

A minimal, real, working GitOps setup for a three-node Kubernetes cluster
— built to teach, not just to run. If you've never touched Kubernetes,
GitOps, Talos, or Argo CD before, this is meant to get you from a bare
machine to a working cluster you actually understand, not just one you
copy-pasted into existence.

## Who this is for

You're comfortable with computers: the command line, SSH, servers,
networking, editing config files. You have **never** used Kubernetes,
GitOps, Argo CD, or Talos, and none of the jargon is familiar yet. This
repo assumes that, exactly. Every cloud-native term is defined in plain
English the first time it appears, and a full glossary lives at
[`docs/glossary.md`](docs/glossary.md).

## The mental model, briefly

Traditionally, you configure a server by SSHing in and changing things by
hand. Nothing records *why* it looks the way it does except your memory and
shell history. This repo takes a different approach:

1. **Kubernetes** runs your applications, and you tell it the state you
   want ("one copy of this running") rather than the steps to get there —
   it keeps making that true, continuously.
2. **Talos Linux** is the operating system underneath — built for nothing
   but running Kubernetes, configured the same declarative way, with no
   SSH or shell to log into.
3. **Argo CD** watches this Git repository and keeps the cluster matching
   whatever it finds here. You stop running `kubectl apply` by hand; you
   edit a file, commit, push, and Argo CD applies it for you.
4. **App-of-apps** is how this repo is organized so that adding a new app
   later is "add a file," never a new procedure.
5. **MetalLB** gives apps in this cluster real IP addresses on your own
   network — something a cloud provider would normally do for you, and
   bare metal doesn't have on its own.
6. **Longhorn** does the same for storage — turning a spare disk on each
   node into one pool of storage that's replicated across all three
   nodes, so losing a machine doesn't mean losing its data.

Git becomes the one place that's actually true. If you want the full
picture with diagrams before doing anything, start with
[`docs/00-what-is-all-this.md`](docs/00-what-is-all-this.md).

## What's in here

```
talos/    → Talos machine config + bootstrap guide (the OS layer)
argocd/   → Argo CD install + the one manifest you apply by hand
apps/     → Everything Argo CD manages from here on — demo app, MetalLB,
            Longhorn, and wherever you add new apps
docs/     → The numbered, progressive guide you should actually read
```

## Prerequisites

- Three machines (physical or VM), each with a second disk ≥900GB, to
  become your cluster's three nodes
- `talosctl`, `kubectl`, and the `argocd` CLI installed locally
- A GitHub account, and your own fork of this repo

Full detail, with install commands: [`docs/01-prerequisites.md`](docs/01-prerequisites.md).

## The path through this repo

Read these in order. Each is short — one concept per file.

1. [`docs/00-what-is-all-this.md`](docs/00-what-is-all-this.md) — the mental model and architecture, before touching a terminal
2. [`docs/01-prerequisites.md`](docs/01-prerequisites.md) — install the tools, get a target machine ready
3. [`docs/02-talos-bootstrap.md`](docs/02-talos-bootstrap.md) — turn that machine into a Kubernetes node
4. [`docs/03-installing-argocd.md`](docs/03-installing-argocd.md) — install Argo CD into the cluster
5. [`docs/04-app-of-apps.md`](docs/04-app-of-apps.md) — apply the one manifest that hands control to Git
6. [`docs/05-metallb.md`](docs/05-metallb.md) — give apps real IP addresses on your network
7. [`docs/06-longhorn.md`](docs/06-longhorn.md) — give apps real, replicated storage
8. [`docs/07-your-first-change.md`](docs/07-your-first-change.md) — edit a file, push, watch it deploy itself
9. [`docs/08-adding-new-apps.md`](docs/08-adding-new-apps.md) — add something of your own
10. [`docs/09-growing-up.md`](docs/09-growing-up.md) — next steps: more nodes, ingress, secrets management
11. [`docs/glossary.md`](docs/glossary.md) — every term, plain English, for reference throughout
12. [`docs/network.md`](docs/network.md) — the running log of every real IP address in your cluster, kept current as you go

Prefer a single condensed list you can work through step by step with
Claude, checking items off as you go? Use
[`docs/checklist.md`](docs/checklist.md) instead — see the next section.

## Learning this with Claude

This repo is meant to be read with an AI assistant open alongside it. The
root [`CLAUDE.md`](CLAUDE.md) primes Claude to act as a patient tutor for
this exact repo — teaching concepts in order, explaining *why* before
*how*, and checking your understanding rather than just handing you
commands. Throughout the docs, you'll see call-outs like:

> **Ask Claude:** ...

Take those. They mark places where pausing to ask a follow-up question
pays off more than plowing ahead.

If you'd rather be walked through the whole bootstrap interactively,
start a conversation with Claude in this repo and say something like
*"walk me through the checklist in docs/checklist.md"* — it will go
step by step, wait for your output at each one, and help you debug before
moving on.

## A note on scope

This repo deliberately does **not** ship ingress, TLS/cert-manager, or
secrets management in v1 — they're real next steps, documented in
[`docs/09-growing-up.md`](docs/09-growing-up.md), left out so the core
loop stays small enough to fully understand first. This repo is also
**public** — never commit plaintext secrets, credentials, or private keys
to it; see that same doc for how to handle secrets properly once you need
them.