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.

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.

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.

The path through this repo

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

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