docs: WireGuard vs SSH, Flux GitOps, CONTRIBUTING with TDD-first

Document why WireGuard and SSH are complementary layers, add Flux boundaries for the ground segment, shared var/ data paths in docs/06, and a contributor guide with the required test-first workflow.
2026-07-08 20:17:34 +01:00
parent cb4664f5ee
commit ad7e0a5cbe
6 changed files with 191 additions and 6 deletions
@@ -97,6 +97,39 @@ config:
 2. Docked drones fetch the manifest, verify digests/signatures ([05](05-network-security.md)), stage the new Compose bundle, and switch on the next boot cycle.
 3. **Never mid-flight.** Updates are a dock-only operation by construction — the update endpoint does not exist in the flight radio profile.

+## GitOps on the ground segment
+
+The fleet release manifest handles **drones** (atomic, digest-pinned, dock-only). The **ground k3s segment** uses a different tool: [Flux](https://fluxcd.io/) reconciles long-lived configuration from git — dashboard bundles, Prometheus rules, offload schedules, policy labels — without reprovisioning PVCs or re-running full Terraform applies for every label change.
+
+```mermaid
+graph LR
+    subgraph git [Git, on-prem]
+        REPO["service repos"]
+        GITOPS["infra/gitops/<br/>ground overlay"]
+    end
+    subgraph ground_k3s [Ground k3s]
+        FLUX["Flux controllers"]
+        WH["warehouse workloads<br/>(Terraform-provisioned)"]
+        CFG["policy ConfigMaps<br/>dashboard bundles"]
+    end
+    subgraph drones [Fleet]
+        MAN["fleet release manifest"]
+        DOCK["dock: verify + apply"]
+    end
+    REPO --> CI
+    GITOPS --> FLUX
+    FLUX --> CFG
+    MAN --> DOCK
+```
+
+| Segment | Delivery mechanism | Reconciler in production? |
+| --- | --- | --- |
+| Drones | Fleet release manifest via registry mirror | **No** — no API server mid-flight; dock applies once |
+| Ground k3s (warehouse, dashboards, CI runners) | Terraform for shape + **Flux** for ongoing config | **Yes** — stationary cluster, wired network, git is the source of truth |
+| Dev simulation (k3d) | Ansible creates cluster; Terraform applies workloads; Flux CRs installed from [`infra/gitops/`](../infra/gitops/) | Yes (miniature of ground) |
+
+Boundary: **Terraform provisions** (namespaces, PVCs, Deployments, CronJobs); **Flux reconciles** policy and observability overlays on top. Neither replaces the fleet manifest on the drone.
+
 ## Developer experience

 - **Dev Containers** define the full toolchain (Python data tooling, DuckDB, compose, linters) — identical on any machine, onboarding in minutes.