feat(deploy): multi-agent deployment scaffold (TODO #1) - #168
Merged
Merged
Conversation
Ships the topology + config scaffolding that backs paper §6's
N ∈ {1, 10, 100} scale sweep. Two flavours — docker-compose
for single-machine dev/small-scale, Helm for K8s scale.
## Files
```
deploy/
├── docker-compose/
│ ├── base.yml # backend + gateway + controller +
│ │ # MinIO + Prometheus + Grafana +
│ │ # fake-exporter
│ ├── agents-N1.yml # overlay: 1 agent
│ ├── agents-N10.yml # overlay: 10 agents
│ ├── agents-N100.yml # overlay: 100 agents (generated)
│ └── gen-agents.sh # regenerate agents-N<K>.yml
├── helm/asap/
│ ├── Chart.yaml
│ └── values.yaml # scale dials: agents.count +
│ # cold.endpoint + resources
├── configs/
│ ├── prometheus.yml # scrape config for every node
│ ├── grafana-datasources.yml
│ └── gateway.yaml # OTel collector pipeline
├── docker/
│ └── Dockerfile.controller # multi-stage Rust build
├── README.md # run + paper §6 metric mapping
└── TODO.md # what's still missing
```
## Scale dial
`agents.count` (Helm) / pick `agents-N<K>.yml` (compose). The
paper's x-axis is exactly this dial; all other components stay
at one replica.
```bash
# compose
docker compose -f deploy/docker-compose/base.yml \
-f deploy/docker-compose/agents-N10.yml up
# helm
helm install asap deploy/helm/asap --set agents.count=100
```
## Controller Dockerfile works today
Multi-stage Rust build from the top-level repo:
```
docker build -f deploy/docker/Dockerfile.controller -t asap/controller:dev .
```
Used by `base.yml`'s `build:` block — bringing up just the
controller + MinIO + Prom + Grafana services works out-of-the-
box on any Docker host. Backend, gateway, agents, fake-exporter
still need image builds (tracked in `deploy/TODO.md`).
## What's intentionally NOT here
* K8s `templates/` — writing them properly wants a first-pass
against a real cluster (readiness probes, network policies,
PVC sizing). Values + Chart land; templates are next.
* `asap/sketchcol` / `asap/query-backend` / `asap/fake-exporter`
images — supply chain work tracked in `deploy/TODO.md`.
* Grafana dashboards for paper figures — comes with DC TODO #2
(Instrumentation) next.
* B0-B3 baseline overlays — DC TODO #3, cleaner once sketchcol
image is buildable.
## Paper §6 metric mapping in README.md
The README enumerates which Prometheus metric feeds which paper
figure — `container_cpu_usage_seconds_total{name=~"agent-.*"}`
for §6.2 CPU reduction, `gateway_forwarded_bytes_total` for
§6.2 bandwidth, `queryengine_cold_bytes_served_total` +
`accuracy.epsilon` for §6.4 Pareto, `time_to_plan_ready` for
§6.5 drift response. All scraped off the compose stack.
zzylol
added a commit
that referenced
this pull request
Apr 23, 2026
Top-level TODO, deploy/README, deploy/TODO all predated the multi-agent scaffold (#168–#185) and no longer matched the code. Realities the docs now reflect: - deploy scaffold (compose base + N∈{1,10,100} overlays, 7 baselines, 5 Dockerfiles, Helm values, sweep driver) is in. - PR #185 surfaced a system-wide throughput collapse at N=10 (all baselines throttled to ~2k pts/s, agents near-idle) — now called out as the P0 paper blocker instead of "build multi-agent scaffold". - Sweep CSV has nan cells for bandwidth / gateway / backend metrics on some baselines, and backend_query_p99_ms is nan everywhere (no query-side driver yet) — captured as the P1 instrumentation gap. - Grafana dashboards and Helm templates are still unwritten — surfaced honestly rather than hidden under "done". No code changes, docs only. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Lands the topology + config scaffolding for paper §6's N ∈ {1, 10, 100} scale sweep.
What ships
What's intentionally not here
Validated
`docker compose -f base.yml -f agents-N1.yml config` parses clean; `agents-N100.yml` regenerated from `gen-agents.sh` (918 lines).
🤖 Generated with Claude Code