ahmza.com/k8s-starter-pack
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Move to a three-node cluster with a Talos VIP; add Longhorn

Browse Source 
Every node is now both control plane and worker, giving real tolerance
for losing any single machine (etcd quorum needs 3, not 1). A Talos VIP
gives the cluster one stable address regardless of which node answers.

Also pre-installs Longhorn for replicated storage, backed by a Talos
UserVolume on each node's second disk (>=900GB, non-system) rather than
the default path — mirroring the pattern from the homescale repo.

Docs renumbered to make room for 06-longhorn.md; checklist, glossary,
network map, and CLAUDE.md's guided-bootstrap instructions updated to
match, including asking the user for node IPs, VIP, and disk info before
generating any Talos config.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Maxwell Morris
2026-08-22 18:25:38 +01:00
co-authored by Claude Sonnet 5
parent 92c3ad3191
commit 110bd97cca
26 changed files with 777 additions and 261 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/glossary.md
+61 -7
View File
@@ -29,7 +29,7 @@ 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.
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
@@ -42,9 +42,9 @@ 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).
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
@@ -74,13 +74,19 @@ 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).
[`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.
@@ -96,6 +102,12 @@ 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
@@ -116,19 +128,37 @@ 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/08-growing-up.md`](08-growing-up.md) for how to do this safely.
[`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
@@ -141,6 +171,12 @@ 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.
@@ -153,9 +189,27 @@ waits for a wave to be healthy before starting the next. Used in
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
**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).