Oleks
8a28233417
Closes-part-of oleks/cluster#271. - integration-preflight: framed as the non-skippable step 0 of any multi-step rollout; new procedure step 6 requires ONE real authenticated request against every external endpoint FROM THE RUNTIME CONTEXT, with the allowManagementFrom case (oleks/armer#171) as the worked example; output now carries a dependency table alongside the layer table; description rewritten so the skill actually routes on rollout-shaped work. - onboard-host / integrate-service / finish-migration: each names integration-preflight as its step 0 entry gate. - failure-catalog: adds F12 (external dependency never smoke-tested from the runtime context, oleks/armer#171) and F13 (preflight treated as a judgment call, oleks/cluster#260 + oleks/armer#171). - README + plugin.json 1.0.0 -> 1.0.1.
49 lines
2.7 KiB
Markdown
49 lines
2.7 KiB
Markdown
# 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.
|