# Service Mesh Platform

**Solution Architecture v1.0 · open source, fully on-premises · Platform Networking Architecture · 2026-09 · 31 views · 32 architecture decision records**

A service mesh for 2,000 services and 40,000 proxies across 20 Kubernetes clusters in three data centres the organisation owns. It is built from open-source software: Istio with Envoy sidecars for the data plane and configuration compiler, SPIRE for attested workload identity under an offline HSM root with per-cluster intermediates in OpenBao, Cilium for pod networking and a second enforcement plane, Argo CD and Argo Rollouts for intent and weights, and Prometheus, Thanos, Tempo and ClickHouse for telemetry.

A mesh puts a proxy on every request the organisation serves. The design is arranged around one rule: the control plane compiles configuration ahead of time and is never asked anything while a request is being forwarded.

The decisions that carry the design:

- **Proxies forward on what they already hold.** Each proxy has its last acknowledged configuration, a trust bundle and an unexpired certificate. If the control plane goes down entirely, traffic keeps flowing on the last configuration and new intent waits.
- **Certificate lifetime is also the outage budget.** SVIDs last 24 hours and are renewed at 12. The fleet survives 12 hours without an issuer and degrades only after that. A stolen key is useless within a day, and there are no revocation lists.
- **Identity is attested.** SPIRE derives each identity from an attested node and the pod the kubelet reports. Each cluster's intermediate is name-constrained to that cluster's trust domain, so a cluster can mint only its own identities.
- **Authorisation is decided in the destination proxy.** Rules default to deny and run in dry-run before enforcement. A change that would deny more than 0.5% of a service's current traffic is refused at merge unless someone approves an override.
- **Weights and reverts are fast.** Argo Rollouts is the only writer of canary weights, and it judges the traffic share the mesh actually applied. A revert pins a signed bundle that was rendered earlier, ahead of Git.
- **Retries are budgeted.** Every route needs a timeout. Retries apply only to idempotent methods, within 20% of active requests per destination, and deadlines travel with the call.
- **Configuration is scoped and delivered as deltas.** Each proxy gets only the configuration for what its workload declares it calls, so proxy memory tracks the workload rather than the mesh.
- **Every failure is attributed.** Failures are labelled as application, mesh or network, which makes the 99.99% mesh availability target measurable.

The architecture one-pager (including why the design holds up over time) and the full decision record appear on the landing page of the diagram set, directly below the index of views. The same content is published as [docs/architecture-one-pager.md](docs/architecture-one-pager.md) (~12 min) and [docs/decision-record.md](docs/decision-record.md) (~94 min).

---

## What is here

| Path | Contents |
|---|---|
| `diagrams/index.html` | The landing page: 31 views in seven acts with every format linked, then the **architecture one-pager** and the **decision record** |
| `diagrams/*.html` | One self-contained page per view: the inlined diagram plus the reasoning cards, with copy / PNG / PDF export |
| `diagrams/svg/*.svg` | The same views as SVG with the diagram XML embedded; they re-open fully editable in diagrams.net |
| `diagrams/drawio/*.drawio` | draw.io source |
| `docs/architecture-one-pager.md` | The one-pager as markdown |
| `docs/decision-record.md` | The 32 decision records, the technology table and the package glossary as markdown |
| `specs/part-a..d.json` | Diagram specifications, the source of truth for every view |
| `specs/manifest-a..b.json` | Acts, page titles, subtitles and reasoning cards |
| `specs/adr-onepager.json`, `specs/adr-records-a..b.json` | The one-pager, the decision records, the capability-to-technology table and the glossary |
| `scripts/build.sh` | Rebuilds every deliverable from the specs (Node only) |
| `ask.md` | The requirement |

## Rebuild

```bash
bash scripts/build.sh
```

The build needs Node 20+ and the `architecture-diagram-web` skill. Every view passes the geometry check (0 errors, 0 warnings) and the routing check (174 edges, 0 errors, 0 warnings). Every icon resolves (446 nodes, none unresolved or weak), and every relative link and in-page anchor resolves.

## Notes on the requirement

- **Stack.** The requirement targets AWS: EKS, a private CA service, network load balancers and an Envoy-family proxy. As requested, this package runs on-premises with open source. EKS becomes upstream Kubernetes across three sites with three rooms each. The private CA becomes an offline HSM root with per-cluster intermediates in OpenBao, issued to workloads by SPIRE (ADR-07, ADR-09). Network load balancers become gateway addresses announced over BGP by Cilium (ADR-21). Accounts and regions become clusters and sites.
- **A crashed proxy during a total control-plane outage.** The requirement asks that a crashed proxy restart from a local configuration cache. Envoy keeps configuration in memory, and persisting it would mean maintaining a fork of the mesh's agent. The design does not do that. A pod whose sidecar crashes during a total outage stays unready until istiod returns, and its peers carry the load (ADR-04, view 21).
- **A deny while the control plane is down.** A deny lands within 15 s p99 while the control plane is up, and not at all while it is down. Emergency blocks during an outage use Cilium network policy, which does not depend on istiod (ADR-04).
- **Version skew in both directions.** Istio does not support a newer proxy on an older control plane. The requirement is met by running two control-plane revisions side by side, each serving its own proxies, rather than by cross-version compatibility (ADR-26).
- **Scoping.** Namespace-level configuration scoping ships with the MVP. Dependency-level scoping stays in Phase 2, as the requirement sets it (ADR-24, view 27).
- **Features reached through EnvoyFilter.** Envoy's retry budget and deadline handling are not exposed by Istio's API on every release. Both are applied through one generated filter, pinned per revision and covered by the upgrade conformance suite (ADR-17).
- **Unproven product behaviours.** Seven product behaviours must be confirmed on the chosen releases before production depends on them. They are listed in the decision record's status note, and each has a matching proof-phase item in the one-pager.