Initial commit: GitOps Starter Pack
A teaching-first, single-cluster GitOps setup: Talos Linux + Argo CD with an app-of-apps layout, MetalLB pre-installed for real LoadBalancer IPs on bare metal, a demo app, and a progressive docs/ walkthrough with a CLAUDE.md tutor persona and guided bootstrap checklist. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Maxwell Morris
Claude Sonnet 5
@@ -0,0 +1,161 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user