vps-k8s/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.

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.

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.

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 — see docs/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.

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.

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.

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.

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 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 and docs/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.

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.

talosconfig — The credentials file talosctl uses to talk to a Talos node's API — the Talos-level equivalent of a kubeconfig.