# Glossary Every term this repo uses, in plain English. If you hit a word in the docs or a YAML comment that isn't here, ask Claude to add it. **API server** — The part of Kubernetes every other piece (and every `kubectl` command) talks to. It's the front door: all reads and writes to the cluster's state go through it. **Application (Argo CD)** — A Custom Resource (see CRD, below) that Argo CD adds to Kubernetes. It tells Argo CD "watch this path in this Git repo, and keep the cluster matching it." Not a Kubernetes-native concept — it only exists once Argo CD is installed. **app-of-apps** — The pattern this repo uses: one Application (itself called the app-of-apps) watches a folder of *other* Application manifests, so adding a new app is "add a file," not "run a new command." See [`docs/04-app-of-apps.md`](04-app-of-apps.md). **ARP (Address Resolution Protocol)** — How devices on the same local network find each other's hardware addresses. MetalLB's L2 mode works by answering ARP requests for whichever IP address it's handed out, which is what makes that address reachable from the rest of your LAN. **bootstrap** — The one-time setup that has to happen *before* the normal system can take over and manage itself. Used here for `talosctl bootstrap` (initializes etcd, once, ever) and more generally for the handful of manual steps — installing Argo CD, applying the app-of-apps — that get the GitOps loop started before Git takes over. **cluster** — A group of one or more machines (nodes) working together as one Kubernetes system. This repo's cluster starts as a single node. **CNI (Container Network Interface)** — The plugin responsible for giving Pods network connectivity and IP addresses. Talos ships Flannel, a CNI, by default — you don't install one yourself in this setup. **ConfigMap** — A Kubernetes object that holds configuration data (text, small files) as its own resource, separate from the Pod that uses it. Lets you change configuration without rebuilding a container image. Used for the demo app's HTML page. **control plane** — The set of components that run the cluster itself (API server, scheduler, etcd) as opposed to your applications. Normally kept on separate machines from your workloads; this repo's single-node setup deliberately blurs that line for simplicity — see [`talos/patch-controlplane.yaml`](../talos/patch-controlplane.yaml). **CRD (Custom Resource Definition)** — A way to teach Kubernetes about a new *kind* of object beyond its built-ins (Pod, Service, etc.). Argo CD's install adds a CRD for `Application`, which is what lets you write `kind: Application` in YAML at all. **declarative** — Describing the state you want ("one copy of nginx running"), and letting software figure out and continuously enforce the steps to get and stay there — as opposed to **imperative**, where you issue the individual commands yourself ("start this container now"). Kubernetes, Talos, and Argo CD are all declarative; the one-time install steps in this repo (installing Argo CD itself, applying the app-of-apps) are the deliberate imperative exceptions that get the declarative system started. **Deployment** — A Kubernetes object describing how many copies of a container should run and how to run them. You manage Deployments; they, in turn, manage the actual Pods. **etcd** — The database Kubernetes' control plane uses to store all cluster state. `talosctl bootstrap` initializes it, once, on cluster creation. **GitOps** — Using a Git repository as the source of truth for a system's desired state, with automation (here, Argo CD) continuously reconciling the real system to match it. The core idea this whole repo demonstrates. **Ingress** — A Kubernetes object that routes external HTTP(S) traffic to services inside the cluster by hostname/path, via an Ingress controller. Not used in this repo's v1 — see [`docs/08-growing-up.md`](08-growing-up.md). **IPAddressPool** — A MetalLB custom resource (see CRD) declaring which IP addresses it's allowed to hand out to `LoadBalancer` Services. Configured in [`apps/metallb/templates/ipaddresspool.yaml`](../apps/metallb/templates/ipaddresspool.yaml) — see [`docs/05-metallb.md`](05-metallb.md). **kubeconfig** — A file holding the credentials and connection info `kubectl` (and other Kubernetes tools) use to talk to a specific cluster. Retrieved with `talosctl kubeconfig` in this setup. **L2Advertisement** — A MetalLB custom resource that tells it to advertise addresses from a given `IPAddressPool` using ARP (see above) — "Layer 2 mode," MetalLB's simplest mode and the one this repo uses. Configured in [`apps/metallb/templates/l2advertisement.yaml`](../apps/metallb/templates/l2advertisement.yaml). **LoadBalancer (Service type)** — A Service that requests a real, dedicated external IP address, reachable directly from outside the cluster. On a cloud provider this provisions an actual cloud load balancer; on bare metal (this repo) MetalLB fills that role instead — see [`docs/05-metallb.md`](05-metallb.md). **machine config** — Talos's equivalent of a Kubernetes manifest, but for the operating system itself: a declarative file describing how a node should be configured, generated with `talosctl gen config` and sent to the node with `talosctl apply-config`. **manifest** — A YAML (or JSON) file describing a Kubernetes object's desired state. Every `.yaml` file in `apps/` is a manifest. **MetalLB** — Software installed in this repo (`apps/metallb.yaml`) that gives bare-metal Kubernetes clusters the ability to hand out real IP addresses to `LoadBalancer` Services — a job a cloud provider would normally do. See [`docs/05-metallb.md`](05-metallb.md). **namespace** — A way to group related objects inside a cluster, like a folder. Lets you keep different apps' resources organized and manageable independently. **node** — A single machine (physical or virtual) that's part of a Kubernetes cluster. **Pod** — The smallest deployable unit in Kubernetes: one or more containers that run together, sharing network and storage. You'll rarely create Pods directly — a Deployment creates and manages them for you. **reconciliation** — The repeating process of comparing desired state (Git, for Argo CD) against actual state (the live cluster) and correcting any difference. See the diagram in [`docs/00-what-is-all-this.md`](00-what-is-all-this.md#the-reconciliation-loop). **Secret** — A Kubernetes object for holding sensitive data. Its values are only base64-*encoded*, not encrypted — never commit a raw Secret manifest containing real credentials to Git. See [`docs/08-growing-up.md`](08-growing-up.md) for how to do this safely. **selfHeal** — An Argo CD sync policy setting: if the live cluster drifts from what's in Git (e.g. someone runs `kubectl edit`), Argo CD reverts it back to match Git on its next pass, rather than only fixing drift when you manually trigger a sync. **Service** — A Kubernetes object giving a stable network address for a set of Pods, even as individual Pods are created and destroyed. This repo uses a `LoadBalancer` Service for the demo app, backed by MetalLB — see [`apps/demo/service.yaml`](../apps/demo/service.yaml) and [`docs/05-metallb.md`](05-metallb.md). **sync** — Argo CD's term for actually applying a change (a reconciliation pass that found and fixed a difference). "Synced" means the cluster currently matches Git. **sync-wave** — An Argo CD annotation (`argocd.argoproj.io/sync-wave`) that stages the order resources are applied within one Application's sync: lower numbers first, and Argo CD waits for a wave to be healthy before starting the next. Used in `apps/metallb/templates/` so MetalLB's own resources (including its CRDs) apply before the `IPAddressPool`/`L2Advertisement` that depend on them — see [`docs/05-metallb.md`](05-metallb.md). **Talos Linux** — The operating system this repo's node(s) run: built only to run Kubernetes, configured entirely declaratively over the network, with no SSH or shell. See [`docs/02-talos-bootstrap.md`](02-talos-bootstrap.md). **talosconfig** — The credentials file `talosctl` uses to talk to a Talos node's API — the Talos-level equivalent of a kubeconfig.