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.
This commit is contained in:
@@ -15,8 +15,13 @@ Rules for anyone (human or tooling) contributing to this repository.
|
||||
docs/ Design documentation (Markdown + Mermaid)
|
||||
simulator/ Virtual drone fleet — Python data generator (Parquet/DuckDB pipeline)
|
||||
prototype/ 2D swarm visualization — React + TypeScript (Vite)
|
||||
infra/ Ansible host prep, Terraform workloads, Flux GitOps overlays
|
||||
var/t1/ Shared T1 live lake (gitignored runtime data)
|
||||
var/t3/ Shared T3 warehouse (gitignored runtime data)
|
||||
```
|
||||
|
||||
See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the development workflow and TDD requirements.
|
||||
|
||||
## Conventions
|
||||
|
||||
- Markdown: ATX headings, fenced code blocks with language tags, pipe tables.
|
||||
|
||||
@@ -0,0 +1,90 @@
|
||||
# Contributing
|
||||
|
||||
Thank you for helping improve Swarm House. This repository is a self-contained
|
||||
design proposal for an on-prem data platform for autonomous drone swarms — all
|
||||
contributions must follow the rules in [`AGENTS.md`](AGENTS.md).
|
||||
|
||||
## TDD first (required)
|
||||
|
||||
Every change to executable code ships with tests **before** or **alongside** the
|
||||
implementation — never as an afterthought.
|
||||
|
||||
1. **Red:** write or extend a failing test that captures the behaviour you need.
|
||||
2. **Green:** implement the smallest change that makes it pass.
|
||||
3. **Refactor:** clean up without weakening the test.
|
||||
|
||||
The CI pipeline enforces this:
|
||||
|
||||
| Gate | When it runs |
|
||||
| --- | --- |
|
||||
| `pytest tests/` | Every push/PR (`verify` job) |
|
||||
| `RUN pytest tests/` in the simulator Docker build | Every `docker build` — a red test blocks the image |
|
||||
| Smoke flight + DuckDB assertion | Every push/PR |
|
||||
| Trivy scan | After verify passes |
|
||||
|
||||
Test locations:
|
||||
|
||||
- `simulator/tests/` — Python unit tests (SQL gate, broadcast codec, writer layout, flight kinematics)
|
||||
- Prototype: `npm run build` / `tsc --noEmit` before UI changes
|
||||
|
||||
## Local development
|
||||
|
||||
### Fast inner loop (Compose)
|
||||
|
||||
```bash
|
||||
cd simulator
|
||||
pip install -r requirements.txt
|
||||
pytest tests/ -q # run tests first
|
||||
DRONE_COUNT=5 docker compose up --build # writes to ../var/t1
|
||||
```
|
||||
|
||||
### Full ground miniature (k3d + Terraform + Flux)
|
||||
|
||||
```bash
|
||||
ansible-playbook infra/ansible/sim-cluster.yml
|
||||
cd infra/terraform/sim-env && terraform init && terraform apply
|
||||
cd ../ground && terraform init && terraform apply
|
||||
cd ../../prototype && npm install && npm run dev # press "go live"
|
||||
```
|
||||
|
||||
Shared data directories (gitignored, created automatically):
|
||||
|
||||
| Path | Tier | Contents |
|
||||
| --- | --- | --- |
|
||||
| `var/t1/` | T1 live lake | In-flight Parquet from Compose or k3d fleet |
|
||||
| `var/t3/` | T3 warehouse | Offloaded historical partitions |
|
||||
|
||||
Override with `SWARM_T1_DIR` / `SWARM_WAREHOUSE_DATA` / `SWARM_SIM_DATA` env vars.
|
||||
|
||||
### Prototype only
|
||||
|
||||
```bash
|
||||
cd prototype && npm install && npm run dev
|
||||
```
|
||||
|
||||
## Commit messages
|
||||
|
||||
Conventional Commits only:
|
||||
|
||||
```
|
||||
feat: add warehouse offload cron schedule variable
|
||||
fix: reject COPY statements in the SQL gate
|
||||
docs: clarify WireGuard vs SSH layering
|
||||
test: cover broadcast frame roundtrip
|
||||
```
|
||||
|
||||
Never include AI tool references, `Co-authored-by` trailers for assistants, or
|
||||
identifying names of people, companies, or locations.
|
||||
|
||||
## Pull request checklist
|
||||
|
||||
- [ ] Tests added or updated; `pytest tests/ -q` passes locally
|
||||
- [ ] `docker build` in `simulator/` succeeds (test stage included)
|
||||
- [ ] Documentation updated if behaviour or boundaries changed
|
||||
- [ ] English only; no identifying references
|
||||
- [ ] Conventional commit message
|
||||
|
||||
## Questions
|
||||
|
||||
Open design questions live in [`docs/09-open-questions.md`](docs/09-open-questions.md).
|
||||
Architecture boundaries are documented in [`docs/06-environments.md`](docs/06-environments.md#iac-boundaries).
|
||||
@@ -39,18 +39,37 @@ This repository describes how to build, deliver, test, and operate that platform
|
||||
| Component | Purpose | Stack |
|
||||
| --- | --- | --- |
|
||||
| [`simulator/`](simulator/) | Virtual drone fleet: generates realistic telemetry through the same Parquet/DuckDB pipeline a real drone would use; N drones via Docker Compose | Python, pyarrow, DuckDB |
|
||||
| [`prototype/`](prototype/) | 2D top-down swarm visualization: drones, obstacles, inter-drone links with live transfer metrics | React, TypeScript, Vite, SVG |
|
||||
| [`prototype/`](prototype/) | 2D top-down swarm visualization: drones, obstacles, inter-drone links with live transfer metrics; **live mode** renders real positions from the k3d fleet | React, TypeScript, Vite, SVG |
|
||||
| [`infra/ansible/`](infra/ansible/) | Host preparation: drone bench provisioning (keys, forced commands, WireGuard, Compose bundle) and local k3d simulation cluster | Ansible |
|
||||
| [`infra/terraform/`](infra/terraform/) | Declared workloads on the sim cluster: virtual fleet + observability ([`sim-env`](infra/terraform/sim-env/)), warehouse + T1→T3 offload ([`ground`](infra/terraform/ground/)) | Terraform, kubernetes provider |
|
||||
| [`infra/gitops/`](infra/gitops/) | Flux overlays for the ground segment — policy labels, dashboard bundles; drones stay on the fleet manifest | Flux, Kustomize |
|
||||
|
||||
Shared runtime data (gitignored): `var/t1/` (live lake), `var/t3/` (warehouse). See [`CONTRIBUTING.md`](CONTRIBUTING.md).
|
||||
|
||||
## Quick start
|
||||
|
||||
```bash
|
||||
# Spin up a virtual swarm of 10 drones
|
||||
# Spin up a virtual swarm of 10 drones (Compose, no cluster needed)
|
||||
cd simulator && DRONE_COUNT=10 docker compose up
|
||||
|
||||
# Run the visualization
|
||||
cd prototype && npm install && npm run dev
|
||||
```
|
||||
|
||||
Or run the full miniature of the ground segment — k3d cluster, fleet as
|
||||
StatefulSet, Grafana, explorer, warehouse with post-flight offload:
|
||||
|
||||
```bash
|
||||
ansible-playbook infra/ansible/sim-cluster.yml
|
||||
cd infra/terraform/sim-env && terraform init && terraform apply
|
||||
cd ../ground && terraform init && terraform apply
|
||||
# then press "go live" in the prototype header
|
||||
```
|
||||
|
||||
See [06 — Environments → IaC boundaries](docs/06-environments.md#iac-boundaries) for why Ansible owns hosts, Terraform owns the ground segment, and neither flies on the drone.
|
||||
|
||||
Contributing (TDD-first workflow): [`CONTRIBUTING.md`](CONTRIBUTING.md).
|
||||
|
||||
## CI & releases
|
||||
|
||||
Every push runs the pipeline in [`.github/workflows/release.yaml`](.github/workflows/release.yaml): a compile check, a 10-second virtual smoke flight verified with DuckDB, unit tests for the read-only SQL gate, and a Trivy vulnerability/misconfiguration scan. Pushes to `main` then cut a semantic version from the conventional-commit type (`feat:` → minor, `!`/`BREAKING CHANGE` → major, else patch), tag the commit, and publish a release with a **fleet release manifest** (versioned artifact list with checksums — the delivery unit described in [11 — CI/CD & delivery](docs/11-cicd-delivery.md)) plus a source bundle.
|
||||
Every push runs the pipeline in [`.github/workflows/release.yaml`](.github/workflows/release.yaml): **pytest unit tests**, a compile check, a 10-second virtual smoke flight verified with DuckDB, and a Trivy vulnerability/misconfiguration scan. The simulator Docker build also runs `pytest` — a failing test blocks the image. Pushes to `main` then cut a semantic version from the conventional-commit type (`feat:` → minor, `!`/`BREAKING CHANGE` → major, else patch), tag the commit, and publish a release with a **fleet release manifest** (versioned artifact list with checksums — the delivery unit described in [11 — CI/CD & delivery](docs/11-cicd-delivery.md)) plus a source bundle.
|
||||
|
||||
@@ -36,6 +36,21 @@ graph TB
|
||||
- **RSSI is data.** Per-peer signal strength is captured into `telemetry` like any other sensor — it feeds relative-positioning estimates and post-flight link-quality analysis, and it is free.
|
||||
- Electromagnetic environment sensing (whatever the radio can observe) is likewise recorded — cheap in flight, valuable in replay.
|
||||
|
||||
## Why not SSH alone?
|
||||
|
||||
SSH and WireGuard solve different problems. SSH is the **authorization layer** for narrow, point-to-point operations (bulk sync, read-only SQL). WireGuard is the **membership and transport encryption layer** for everything on the mesh, including traffic SSH cannot carry.
|
||||
|
||||
| Concern | SSH alone | WireGuard + SSH (this design) |
|
||||
| --- | --- | --- |
|
||||
| Pose broadcast (UDP, ~5 Hz, compact frame) | Cannot carry subnet broadcast; would need a separate app protocol | Encrypted inside the mesh overlay; any peer on the tunnel can receive |
|
||||
| Broadcast confidentiality without WG | Payloads traverse the radio **in cleartext** — any receiver in range reads swarm positions | Only provisioned fleet members complete a handshake; outsiders see noise |
|
||||
| Lossy ad-hoc links | TCP head-of-line blocking; sessions stall and reconnect on packet loss | UDP transport survives loss and roaming; SSH sessions **over** WG are more stable than SSH directly on Wi-Fi |
|
||||
| Network membership | Any host that reaches the port gets an SSH banner — a probe surface | Devices without a provisioned key get **no handshake response**; the port is effectively silent |
|
||||
|
||||
**Rejected alternative:** encrypt each broadcast frame in application code with a fleet-wide AEAD key. That reinvents a crypto layer the OS already provides, still leaves TCP head-of-line blocking for peer queries, and does not answer the membership question (who is allowed on the mesh at all).
|
||||
|
||||
Keep both layers: WireGuard for *who is on the network and whether the wire is readable*; SSH forced commands for *what a peer is allowed to do once connected* ([04](04-swarm-sync.md)).
|
||||
|
||||
## Key lifecycle
|
||||
|
||||
| Phase | Action |
|
||||
|
||||
@@ -61,6 +61,29 @@ The environment engineers live in daily — and deliberately the first thing to
|
||||
- **T4 data slices**: a thin tool pulls partition subsets from T3 (`flight=X, drone=Y, hour=Z`) for local work — layout-identical, so every query and pipeline runs unmodified.
|
||||
- The same simulator images scale out on the ground k3s farm for CI regression runs: every merge request replays canonical scenarios and asserts on the resulting Parquet output (row counts, coverage, staleness budgets).
|
||||
|
||||
## IaC boundaries
|
||||
|
||||
Infrastructure as code follows the same discipline as the data plane: each tool owns the layer it is actually good at, and nothing owns a layer it can't reach.
|
||||
|
||||
| Layer | Tool | Why |
|
||||
| --- | --- | --- |
|
||||
| Host preparation (drone bench provisioning, sim cluster creation) | **Ansible** ([`infra/ansible/`](../infra/ansible/)) | Idempotent, agentless, works over the same SSH channel the platform already trusts. Keys, forced commands, WireGuard, Compose bundles — all host-level state. |
|
||||
| Declared workloads (simulated fleet, ground warehouse) | **Terraform** ([`infra/terraform/`](../infra/terraform/)) | The ground segment is stationary, long-lived, and cluster-shaped — classic Terraform territory. Fleet size, offload schedule, and explorer endpoints are variables, not YAML edits. |
|
||||
| Ongoing ground configuration | **Flux** ([`infra/gitops/`](../infra/gitops/)) | Policy labels, dashboard bundles, offload knobs — reconciled from git without reprovisioning PVCs. Drones stay on the fleet manifest, not GitOps. |
|
||||
| On-board runtime | **Compose bundle from the fleet release manifest** | Terraform is deliberately *not* on the drone: there is no API server to reconcile against mid-flight, and the release manifest already gives atomic, versioned, rollback-able delivery ([11](11-cicd-delivery.md)). |
|
||||
|
||||
Shared local data paths (same layout everywhere): **`var/t1/`** (live lake, T1) and **`var/t3/`** (warehouse, T3). Compose, k3d, and DuckDB on the host all read the same Parquet tree.
|
||||
|
||||
Two Terraform modules, two states, one deliberate split: [`sim-env`](../infra/terraform/sim-env/) (the disposable virtual fleet) and [`ground`](../infra/terraform/ground/) (the warehouse that must survive every `destroy` of the fleet). They never share a lifecycle.
|
||||
|
||||
### k3d: the ground segment as an executable miniature
|
||||
|
||||
`ansible-playbook infra/ansible/sim-cluster.yml` creates a local k3d cluster (k3s in Docker — the same distribution as the real ground segment) and `terraform apply` populates it: virtual drones as StatefulSet replicas over a shared Parquet lake, the exporter/Prometheus/Grafana stack, the data-plane explorer, MinIO, and the T1→T3 offload CronJob. The whole diagram at the top of this page runs on one workstation, and the prototype's **live mode** renders real drone positions straight from the explorer's read-only SQL API.
|
||||
|
||||
### Next fidelity step: microVMs
|
||||
|
||||
The k3d fleet shares one kernel and one network namespace tree — good enough to exercise the data plane, not good enough to demo the *peer* plane (real SSH sessions between isolated machines, WireGuard handshakes, packet loss injection). The next step, when that fidelity is needed, is one **Firecracker microVM per drone**: a real kernel, a real network interface, and the actual `authorized_keys` forced-command path between virtual drones — on any KVM-capable workstation, still with no cloud dependency. The process-level simulator stays as the fast inner loop; microVMs become the pre-flight integration rig.
|
||||
|
||||
## Why identical layouts matter (the payoff)
|
||||
|
||||
| Operation | What it costs with one layout everywhere |
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user