# Cluster lifecycle

## Purpose and scope

This diagram records the order and gates for controlled k3s shutdown and
startup. It is a procedure map; it does not assert that a lifecycle operation
was executed during the review.

- **Source:** `sources/cluster-lifecycle.mmd`
- **Generated output:** `generated/cluster-lifecycle.svg`

![Sanitized cluster lifecycle](generated/cluster-lifecycle.svg)

## Components and ownership boundaries

The operator owns approval, preflight checks, application scale, and escalation.
Kubernetes owns scheduling and readiness; etcd/control-plane nodes own cluster
state; workers own placement capacity; Longhorn and service controllers own
storage and ingress recovery. Host power and Wake-on-LAN sit outside the
Kubernetes trust boundary.

## Data flow and failure paths

Shutdown proceeds through preflight → backup/storage checks → approved scale
changes → worker cordon/drain → worker stop → quorum-aware control-plane stop →
out-of-band stopped-state verification. Startup follows the dependency order:
control plane → API and etcd → workers → CNI/CSI and storage readiness →
application scale → ingress/services → monitoring.

Wake failure, API timeout, node-address mismatch, unhealthy storage, unscheduled
workloads, missing DNS, or an unrestored route stops progression and routes the
operator to the applicable rollback or escalation step.

## Omissions and verification

Schedules, hostnames, addresses, credentials, commands, and live output are
omitted. The runbooks and cluster scripts were reviewed on 16 July 2026. A
read-only snapshot showed five nodes Ready and API/etcd readiness on that date;
it does not prove shutdown, restart, drain, or host-power behavior.

Follow the [startup runbook](../runbooks/cluster-startup.md) and
[shutdown runbook](../runbooks/cluster-shutdown.md) for commands, rollback,
and escalation points.

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