k8s-starter-pack/docs/glossary.md

# 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 three nodes.

**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 three nodes
deliberately blur that line, each acting as control plane and worker at
once — 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/09-growing-up.md`](09-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).

**iSCSI** — A protocol for accessing block storage over a network as if it
were a local disk. Longhorn's underlying engine uses it, which is why
nodes need the `iscsi-tools` Talos system extension (see below) baked
into their image before Longhorn will work — see
[`docs/01-prerequisites.md`](01-prerequisites.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).

**Longhorn** — Software installed in this repo (`apps/longhorn.yaml`) that
turns a plain disk on each node into one pool of storage, replicated
across nodes, so apps can request real persistent storage on bare metal —
a job a cloud provider's disk service would normally do. See
[`docs/06-longhorn.md`](06-longhorn.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.

**PersistentVolumeClaim (PVC)** — How an app asks Kubernetes for storage:
"I need this much space," without caring which disk or which node
provides it. Longhorn is what actually fulfills that request in this
repo — see [`docs/06-longhorn.md`](06-longhorn.md).

**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.

**quorum** — The minimum number of etcd members (a majority) that have to
agree before the cluster's control plane can do anything. This is why
control-plane node counts matter, and why 3 is a meaningfully different
number than 2 or 4 — see
[`docs/02-talos-bootstrap.md`](02-talos-bootstrap.md#three-nodes-each-both-control-plane-and-worker)
and [`docs/09-growing-up.md`](09-growing-up.md#why-not-a-fourth-control-plane-node).

**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).

**schematic** — A custom Talos boot image, built at
[factory.talos.dev](https://factory.talos.dev) by selecting which system
extensions (see below) it should include. This repo's nodes need one with
`iscsi-tools` and `util-linux-tools` for Longhorn to work — see
[`docs/01-prerequisites.md`](01-prerequisites.md).

**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/09-growing-up.md`](09-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).

**StorageClass** — A Kubernetes object describing a "kind" of storage
that's available (who provides it, how). Longhorn's chart registers itself
as the cluster's default StorageClass, so a plain
`PersistentVolumeClaim` with no class named gets Longhorn storage
automatically — see [`docs/06-longhorn.md`](06-longhorn.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).

**system extension** — An optional add-on baked into a Talos boot image at
build time (see "schematic," above), since Talos has no package manager to
install one onto an already-running node. This repo's nodes need
`iscsi-tools` and `util-linux-tools` for Longhorn.

**Talos Linux** — The operating system this repo's nodes 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.

**UserVolumeConfig** — A standalone Talos configuration resource (not part
of the normal `machine:`/`cluster:` structure) that tells Talos to find,
format, and mount a disk on its own, based on rules you give it (which
disk to pick, minimum size). Used in
[`talos/patch-longhorn.yaml`](../talos/patch-longhorn.yaml) to prepare
each node's storage for Longhorn.

**VIP (Virtual IP)** — One IP address that Talos keeps pointed at whichever
of several control-plane nodes is currently healthy, re-electing within
seconds if that node goes down. Everything that talks to this cluster
should use the VIP, not any one node's own address — see
[`docs/02-talos-bootstrap.md`](02-talos-bootstrap.md#the-vip-one-address-for-a-cluster-that-moves).