# k8s-synth
**Eurorack × Kubernetes** — a modular hardware system where the patch is the cluster.
Each module is a Kubernetes primitive (Pod, Service, Deployment, Node, etcd, …) behind a Eurorack faceplate. Patch cables define the cluster's networking and ownership topology; pulling a cable is equivalent to editing YAML. The reconciliation loop becomes something you can see, hear, and perform.
Read the full pitch in [`docs/concept.md`](docs/concept.md).
| Backplane architecture | POD spec sheet |
| --- | --- |
| [](design/backplane-architecture.html) | [](design/pod-spec-sheet.html) |
## Repo layout
```
.
├── README.md
├── docs/
│ └── concept.md # the core idea, module set, MVP rack
├── vcv/ # VCV Rack 2 plugin (software prototype)
│ ├── README.md
│ ├── PROTOCOL.md # inter-module signal protocol (v0)
│ ├── plugin.json
│ ├── Makefile
│ ├── src/ # Pod, Deployment, Service (more WIP)
│ └── res/ # SVG panels
├── eno/ # Eno integration (synthesis + reconciliation)
│ ├── README.md
│ ├── topology-schema.md # ConfigMap shape consumed by the Synthesizer
│ ├── synthesizer.sh # KRM function: topology → Deployment/Service/Ingress
│ ├── bridge/topology-to-configmap.sh # apply a topology.json file as a ConfigMap
│ ├── manifests/ # Eno Synthesizer + Composition CRDs
│ ├── examples/ # sample topologies
│ └── test-synth.sh # smoke test (no cluster needed)
├── design/
│ ├── hero.html # landing / hero page
│ ├── backplane-architecture.html # control-plane bus + apiserver design
│ ├── pod-spec-sheet.html # POD module spec sheet
│ └── screenshots/ # auto-generated PNGs of the above
└── scripts/
└── screenshot.sh # render design/*.html -> design/screenshots/
```
Open the HTML files directly in a browser — they're self-contained design pages.
### Regenerating screenshots
```sh
./scripts/screenshot.sh
```
Uses headless Chrome. Defaults to Windows Chrome via WSL
(`/mnt/c/Program Files/Google/Chrome/Application/chrome.exe`); override with
`CHROME=/path/to/chrome` or `SIZE=1920,1200`.
## Software prototype: VCV Rack plugin
Before any soldering we're prototyping the modules as a [VCV Rack 2](https://vcvrack.com/) plugin in [`vcv/`](vcv/). This lets us nail the inter-module signal protocol (CV ranges, gate semantics, bus topology) and lets anyone clone-and-patch without hardware. Build instructions: [`vcv/README.md`](vcv/README.md).
Modules so far:
| Module | Status | Description |
| --- | --- | --- |
| Pod | scaffold | lifecycle in, ready+load gates out, CPU knob |
| Deployment | scaffold | replicas knob, 6 claim outs + ready ins, ready-count CV |
| Service | scaffold | poly selector in, request in, 4 round-robin endpoint outs |
| Node | scaffold | poly load in, capacity knob, utilization CV + bargraph, cordon switch + gate |
| etcd | scaffold | write trigger in, idle heartbeat, audio out (sine ticks with pitch jitter) |
| Ingress, Controller | TODO | — |
A search of GitHub and the VCV plugin library turned up no prior k8s-themed Rack modules, so this appears to be greenfield.
## Synthesis engine: Eno
We plan to use [Azure/Eno](https://github.com/Azure/eno) as the synthesis + reconciliation backend. The apiserver module publishes the live patch topology as a `ConfigMap`; an Eno `Synthesizer` consumes it and emits the corresponding Kubernetes resources. Pulling a cable mutates the input, Eno re-synthesizes, the controller reconciles, the rack updates. See [`docs/concept.md`](docs/concept.md#implementation-eno-as-the-synthesis-engine) for details.
## Status
Concept stage. Two workload modes are planned:
1. **Simulated** — Pods run synthetic load you dial in with a knob. Built first; ideal for teaching and demos.
2. **Real containers** — each Pod module runs an actual containerd instance, patches gate real network traffic. Added later for hero modules.
See the *Open Questions* section at the bottom of [`docs/concept.md`](docs/concept.md) for the current unknowns (cable sensing scheme, etcd sonification, power budget, controller programmability).
## Roadmap
Work is tracked with [beads](https://github.com/steveyegge/beads) (`bd ready` to see the live queue). Four parallel epics:
| Epic | ID | What it covers |
| --- | --- | --- |
| VCV Rack plugin — software prototype | `k8s-synth-v8a` | Pod / Deployment / Service scaffolded; Node, etcd, Ingress, Controller, real label-selector, signal-protocol spec, panel art still TODO |
| Eno-backed synthesis pipeline | `k8s-synth-fmv` | Topology ConfigMap schema → Synthesizer → VCV-state bridge → end-to-end demo on kind |
| Hardware MVP rack | `k8s-synth-uoe` | Cable-sensing decision, power-budget audit, control-plane backplane, hardware Pod v0 |
| Design + storytelling | `k8s-synth-dei` | VCV+Eno hero render, real VCV patch screenshots, architecture diagram |
**Ready-to-work P1s** (no blockers):
- `k8s-synth-v8a.1` Verify VCV plugin builds against Rack-SDK 2.x
- `k8s-synth-v8a.2` Define inter-module signal protocol spec (CV ranges, gate semantics, bus topology)
- `k8s-synth-fmv.1` Design topology ConfigMap schema
These three unblock most of the rest of the graph. `bd ready` for the full list, `bd show <id>` for details.