# k3s platform topology

## Purpose and scope

This internal-safe diagram maps the logical request, control-plane, runtime,
workload, storage, observability, backup, and delivery relationships in the
self-managed k3s environment. Runtime statements below are a point-in-time
snapshot, not continuous monitoring.

- **Source:** `sources/k3s-platform.mmd`
- **Generated output:** `generated/k3s-platform.svg`

![Sanitized k3s platform topology](generated/k3s-platform.svg)

## Components and trust boundaries

External/local clients, DNS, MetalLB, and Traefik sit at the ingress boundary.
Inside the cluster, three server nodes own control-plane/etcd state, two
labeled workers add placement capacity, and one additional node remains an
integration boundary. k3s/containerd, Services/EndpointSlices, Pods,
Longhorn-backed storage, monitoring workloads, and the backup CronJob have
separate controllers and failure modes. Flux or direct manifests cross the
source-to-cluster ownership boundary.

## Data flow and failure paths

Requests flow client → DNS → MetalLB → Traefik → Service/EndpointSlice → Pod,
with persistent I/O continuing to storage. Desired state flows from Git or
manifests to the Kubernetes API and controllers. DNS/address allocation,
ingress routing, endpoint readiness, scheduling, storage attachment/replication,
controller reconciliation, and node/control-plane health can each stop progress.

The backup node represents a separate allowlisted configuration export. It does
not mean persistent volumes, databases, or application data are included.

## Omissions and verification

Node names, IPs, kubeconfig material, configuration values, and workload data
are omitted. On 24 July 2026, a read-only snapshot showed 6/6 nodes Ready on
k3s v1.36.2+k3s1: three control-plane/etcd nodes, two labeled workers, and one
integration node. All 12 Helm releases and the Kustomization were Ready from a
stored source artifact, while the Git source itself was retrying an internal
DNS dependency. All 10 PVCs were Bound, but the integration node had an
incomplete Longhorn shared-mount path. Those degraded signals are part of the
snapshot rather than excluded as inconvenient findings.

Use this map before the [cluster startup runbook](../runbooks/cluster-startup.md),
[shutdown runbook](../runbooks/cluster-shutdown.md), or
[ingress troubleshooting runbook](../runbooks/ingress-troubleshooting.md).

Regenerate and validate with `npm run diagrams && npm run diagrams:check`.