k8s-starter-pack/README.md

# GitOps Starter Pack

A minimal, real, working GitOps setup for a single 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.

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,
            and wherever you add new apps
docs/     → The numbered, progressive guide you should actually read
```

## Prerequisites

- One machine (physical or VM) to become your cluster node
- `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-your-first-change.md`](docs/06-your-first-change.md) — edit a file, push, watch it deploy itself
8. [`docs/07-adding-new-apps.md`](docs/07-adding-new-apps.md) — add something of your own
9. [`docs/08-growing-up.md`](docs/08-growing-up.md) — next steps: more nodes, ingress, secrets management
10. [`docs/glossary.md`](docs/glossary.md) — every term, plain English, for reference throughout
11. [`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/08-growing-up.md`](docs/08-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.