# fleet-integration

Integration playbooks for the oleks fleet, distilled from the 2026-07-21
k3s-over-ZeroTier connectivity research (27 incidents across 12 repos; full
evidence on the **oleks/cluster wiki → K3s-over-ZeroTier-Connectivity** page).

**Core finding:** the fleet's failures were *integration-shaped, not
platform-shaped*. A different overlay, cluster, or cloud would have failed the
same way — through undeclared state, half-finished migrations, hardcoded
environment assumptions, half-implemented lifecycles, and watchdogs that
amplify. These playbooks encode the failure classes (durable) rather than
current fleet facts (which rot — stale docs were themselves failure class F9).
Where a current value matters, the playbooks point at the live source of truth
(`fleet-modules/cluster-topology.nix`, the wiki) instead of restating it.

## Skills

| Skill | When | Closes |
| --- | --- | --- |
| `integration-preflight` | **Step 0 of every multi-step rollout (mandatory)** — diff declared vs live per layer, then smoke-test every external dependency from the runtime context | F1 F2 F3 F9 F12 F13 |
| `onboard-host` | New host into the fleet network and/or k3s | F1 F3 F4 F8 F10 |
| `integrate-service` | New workload end to end: chart, Flux, ingress, DNS, secrets, DB, TLS, tracking | F3 F8 F9 F11 |
| `ephemeral-lifecycle` | Scale-to-zero nodes: credentials, admission, allocation, reaping | F5 F6 F11 |
| `add-watchdog` | Any health-check/auto-restart mechanism, new or under review | F7 F10 |
| `finish-migration` | Cutovers — planning them, and auditing half-done ones | F1 F2 F9 F10 |

## The failure catalog

`references/failure-catalog.md` defines F1–F13 with the real incidents behind
each (issue refs in full `owner/repo#N` form). Read it once; the skills cite
it by class.

- **F1** Undeclared state · **F2** Half-finished migrations · **F3** Hardcoded
  environment assumptions · **F4** MTU/encapsulation budget ignored · **F5**
  Half-implemented lifecycle · **F6** Control plane on its own data path ·
  **F7** Watchdog amplification · **F8** Multi-layer firewalls changed
  separately · **F9** Stale documentation as active misinformation · **F10**
  Guard drift · **F11** Read-modify-write without exclusion · **F12** External
  dependency never smoke-tested from the runtime context · **F13** Preflight
  treated as a judgment call

## Provenance

Built from: the tracker sweep (oleks/armer, oleks/cluster, oleks/fleet,
oleks/builder-arbitrage, oleks/matrix-moq and others), a file:line code sweep
of `~/projects/servers` and `builder-arbitrage`, live fleet verification, and
session memory. Defects discovered during the research were filed as
oleks/armer#166 and oleks/cluster#260 before this plugin cited them.