[ { "id": "01-system-context", "title": "Service Mesh Platform — System Context", "layout": "context", "colWidth": 280, "system": { "label": "Service Mesh Platform", "sub": "20 clusters · 40k proxies", "icon": "istio" }, "groups": [ { "side": "top", "title": "Traffic it carries", "nodes": [ { "id": "c-wl", "label": "Meshed workloads", "sub": "2,000 services", "kind": "external", "rel": "east-west calls", "dir": "in", "icon": "kubernetes" }, { "id": "c-edge", "label": "North-south ingress", "sub": "edge gateways", "kind": "external", "rel": "admitted", "dir": "in", "icon": "fa5_door_closed" } ] }, { "side": "left", "title": "People who change what it does", "nodes": [ { "id": "c-team", "label": "Service team", "kind": "actor", "rel": "routes · dependencies", "dir": "in", "icon": "fa5_users" }, { "id": "c-rel", "label": "Release engineer", "kind": "actor", "rel": "rollouts · revert", "dir": "in", "icon": "fa5_user_tie" }, { "id": "c-sec", "label": "Security engineer", "kind": "actor", "rel": "authz · identity", "dir": "in", "icon": "fa5_user_shield" }, { "id": "c-sre", "label": "Mesh SRE", "kind": "actor", "rel": "upgrades · drift", "dir": "in", "icon": "fa5_user_cog" } ] }, { "side": "right", "title": "What it stands on and reaches", "nodes": [ { "id": "c-k8s", "label": "Kubernetes clusters", "sub": "scheduling · endpoints", "kind": "external", "rel": "pods · endpoints", "dir": "in", "icon": "kubernetes" }, { "id": "c-root", "label": "Offline root CA", "sub": "HSM · ceremony", "kind": "security", "rel": "signs intermediates", "dir": "in", "kind2": "batch", "icon": "fa5_microchip" }, { "id": "c-ext", "label": "External APIs", "sub": "declared egress only", "kind": "external", "rel": "controlled egress", "icon": "fa5_globe" }, { "id": "c-cd", "label": "Delivery pipeline", "sub": "CI · image builds", "kind": "external", "rel": "rollout intent", "dir": "in", "icon": "fa5_shipping_fast" } ] }, { "side": "bottom", "title": "Records and reporting", "nodes": [ { "id": "c-git", "label": "Git service", "sub": "intent repositories", "kind": "external", "rel": "declared intent", "dir": "in", "icon": "git" }, { "id": "c-fin", "label": "Team cost owners", "sub": "monthly report", "kind": "external", "rel": "mesh cost", "kind2": "batch", "icon": "fa5_file_invoice_dollar" } ] } ], "meta": { "v": "1.0", "owner": "Platform Networking Architecture", "date": "2026-09" } }, { "id": "02-high-level-architecture", "title": "High-Level Architecture — Intent In, Local Enforcement Out", "layout": "flow", "chain": true, "stages": [ { "title": "Declare", "nodes": [ { "id": "h-git", "label": "Intent repositories", "sub": "Forgejo · 3 repos", "kind": "store", "icon": "git" }, { "id": "h-roll", "label": "Argo Rollouts", "sub": "owns canary weights", "kind": "app", "icon": "argocd" } ] }, { "title": "Admit", "nodes": [ { "id": "h-ci", "label": "Policy checks", "sub": "OPA · impact replay", "kind": "decision", "icon": "opa" }, { "id": "h-adm", "label": "Admission guards", "sub": "Gatekeeper · VAP", "kind": "security", "icon": "opa" } ] }, { "title": "Compile", "nodes": [ { "id": "h-istiod", "label": "istiod", "sub": "scoped · delta xDS", "kind": "app", "icon": "istio" }, { "id": "h-spire", "label": "SPIRE server", "sub": "attested SVIDs", "kind": "security", "icon": "fa5_id_badge" } ] }, { "title": "Enforce locally", "nodes": [ { "id": "h-envoy", "label": "Envoy sidecar", "sub": "mTLS · authz · routes", "kind": "integration", "icon": "envoy" }, { "id": "h-ewgw", "label": "East-west gateway", "sub": "SNI passthrough", "kind": "integration", "icon": "envoy" } ] }, { "title": "Observe", "nodes": [ { "id": "h-otel", "label": "OTel collector", "sub": "bounded buffers", "kind": "platform", "icon": "opentelemetry" }, { "id": "h-drift", "label": "Drift exporter", "sub": "intent sha per proxy", "kind": "platform", "icon": "fa5_code_branch" } ] } ], "edges": [ { "from": "h-drift", "to": "h-roll", "label": "effective weights", "kind": "async", "route": "gutter" } ], "note": "Nothing left of the data plane is consulted while a request is forwarded. Every arrow into it is a push that can stop without stopping traffic.", "meta": { "v": "1.0", "owner": "Platform Networking Architecture", "date": "2026-09" } }, { "id": "03-actors-and-journeys", "title": "Actors — Who the Mesh Is For and What They Get to Do", "layout": "actors", "cardWidth": 280, "groups": [ { "title": "Teams that own services", "kind": "boundary", "actors": [ { "id": "a-team", "label": "Service team", "sub": "≈ 250 teams", "goal": "Get mTLS, retries and a canary without writing any of it into my service.", "journeys": [ { "id": "j-strict", "label": "Move a service to strict mTLS" }, { "label": "Declare a new dependency" }, { "label": "Read what my mesh costs" } ], "icon": "fa5_users" }, { "id": "a-rel", "label": "Release engineer", "sub": "≈ 900 releases a week", "goal": "Ship to 1% of traffic, and get back in one step if it is wrong.", "journeys": [ { "id": "j-canary", "label": "Canary a release at 1%" }, { "label": "Mirror traffic to a new version" }, { "label": "Abort a rollout" } ], "icon": "fa5_user_tie" } ] }, { "title": "Platform and security", "kind": "onprem", "actors": [ { "id": "a-sre", "label": "Mesh SRE", "sub": "on call for 20 clusters", "goal": "Upgrade 40,000 proxies without anyone noticing, and see drift before users do.", "journeys": [ { "label": "Upgrade the proxy fleet in waves" }, { "label": "Ride out a control-plane outage" }, { "label": "Explain one failed call" } ], "icon": "fa5_user_cog" }, { "id": "a-sec", "label": "Security engineer", "sub": "owns authz and PKI", "goal": "Know who called what, and make a stolen identity useless within minutes.", "journeys": [ { "id": "j-contain", "label": "Contain a compromised workload" }, { "label": "Dry-run an authorisation policy" }, { "label": "Rehearse a root rotation" } ], "icon": "fa5_user_shield" } ] }, { "title": "Machines and reviewers", "kind": "plain", "actors": [ { "id": "a-cd", "label": "Rollout controller", "kind": "platform", "sub": "Argo Rollouts", "goal": "Read the weights the mesh actually applied, not the ones I asked for.", "journeys": [ { "label": "Step weights on analysis" }, { "label": "Abort on SLO breach" } ], "icon": "argocd" }, { "id": "a-aud", "label": "Auditor", "kind": "external", "sub": "13-month lookback", "goal": "Show me every certificate issued and every policy change, with who did it.", "journeys": [ { "label": "Query issuance records" }, { "label": "Trace a change to its author" } ], "icon": "fa5_search" } ] } ], "meta": { "v": "1.0", "owner": "Platform Networking Architecture", "date": "2026-09" } }, { "id": "04-journey-move-a-service-to-strict-mtls", "title": "Journey — A Service Team Refuses Plaintext Without Breaking a Caller", "layout": "journey", "actor": { "label": "Service team", "sub": "payments-ledger", "goal": "Refuse plaintext without breaking a caller", "trigger": "Audit finding: 3% of calls still plaintext", "success": "Strict mode, no legitimate call denied", "icon": "fa5_users" }, "phases": [ { "title": "Find callers" }, { "title": "Mesh them" }, { "title": "Write allow" }, { "title": "Dry run" }, { "title": "Go strict", "moment": true }, { "title": "Hold" } ], "lanes": [ { "title": "What they do", "kind": "step", "cells": [ [ { "label": "Opens plaintext report" } ], [ { "label": "Meshes two batch jobs" } ], [ { "label": "Writes allow by identity" } ], [ { "label": "Runs policy in dry-run" } ], [ { "label": "Merges the strict flip" } ], [ { "label": "Watches denials 7 days" } ] ] }, { "title": "System behind it", "kind": "system", "cells": [ [ { "label": "Plaintext report", "icon": "grafana" } ], [ { "label": "Injection policy", "icon": "fa5_syringe" } ], [ { "label": "Security intent repo", "icon": "git" } ], [ { "label": "Shadow rules", "icon": "fa5_eye" } ], [ { "label": "Config waves", "icon": "argocd" } ], [ { "label": "Denial dashboard", "icon": "grafana" } ] ] }, { "title": "How it feels", "kind": "emotion", "levels": [ "Confident", "Unsure", "Anxious" ], "points": [ "Unsure", "Anxious", "Unsure", "Confident", "Anxious", "Confident" ] }, { "title": "Where it hurts", "kind": "pain", "cells": [ [ { "label": "Who are the 3%?" } ], [ { "label": "Legacy job resists" } ], [ { "label": "Which principals?" } ], [], [ { "label": "Feels one-way" } ], [] ] }, { "title": "What the platform gives", "kind": "gain", "cells": [ [ { "label": "Callers named" } ], [ { "label": "Opt-out per workload" } ], [ { "label": "Survives rescheduling" } ], [ { "label": "Would-deny list, live" } ], [ { "label": "Impact gate at 0.5%" } ], [ { "label": "Revert in one step" } ] ] } ], "chain": true, "meta": { "v": "1.0", "owner": "Platform Networking Architecture", "date": "2026-09" } }, { "id": "05-journey-canary-a-release-at-one-percent", "title": "Journey — A Release Engineer Canaries checkout v2.14 at 1%", "layout": "journey", "actor": { "label": "Release engineer", "sub": "checkout v2.14", "goal": "Find a bad build on 1% of traffic", "trigger": "Merged change to the pricing path", "success": "Promoted, or reverted inside 60 s", "icon": "fa5_user_tie" }, "phases": [ { "title": "Declare" }, { "title": "Mirror" }, { "title": "Cohort" }, { "title": "1% live", "moment": true }, { "title": "Widen" }, { "title": "Promote" } ], "lanes": [ { "title": "What they do", "kind": "step", "cells": [ [ { "label": "Opens the rollout" } ], [ { "label": "Mirrors reads to v2.14" } ], [ { "label": "Routes staff by header" } ], [ { "label": "Starts general 1%" } ], [ { "label": "Steps 5 → 25 → 50%" } ], [ { "label": "Promotes to 100%" } ] ] }, { "title": "System behind it", "kind": "system", "cells": [ [ { "label": "Argo Rollouts", "icon": "argocd" } ], [ { "label": "Mirror route", "icon": "fa5_clone" } ], [ { "label": "Header match", "icon": "fa5_user_friends" } ], [ { "label": "Weighted route", "icon": "fa5_random" } ], [ { "label": "Analysis on Thanos", "icon": "prometheus" } ], [ { "label": "Stable subset retired" } ] ] }, { "title": "How it feels", "kind": "emotion", "levels": [ "Confident", "Unsure", "Anxious" ], "points": [ "Confident", "Unsure", "Confident", "Anxious", "Unsure", "Confident" ] }, { "title": "Where it hurts", "kind": "pain", "cells": [ [], [ { "label": "Mirror writes twice?" } ], [], [ { "label": "Did 1% really apply?" } ], [ { "label": "p99 up 40 ms at 25%" } ], [] ] }, { "title": "What the platform gives", "kind": "gain", "cells": [ [ { "label": "One owner of weights" } ], [ { "label": "Only GET mirrored" } ], [ { "label": "Named cohort first" } ], [ { "label": "Applied share read back" } ], [ { "label": "Auto abort ≤ 60 s", "icon": "fa5_clock" } ], [ { "label": "Every step revertible" } ] ] } ], "chain": true, "meta": { "v": "1.0", "owner": "Platform Networking Architecture", "date": "2026-09" } }, { "id": "06-journey-contain-a-compromised-workload", "title": "Journey — A Security Engineer Makes a Stolen Identity Useless", "layout": "journey", "actor": { "label": "Security engineer", "sub": "on call", "goal": "Make a stolen workload identity useless", "trigger": "report-gen calling payments, never seen before", "success": "Cut off in minutes, dead in 24 h, audit complete", "icon": "fa5_user_shield" }, "phases": [ { "title": "Detect" }, { "title": "Attribute" }, { "title": "Cut off", "moment": true }, { "title": "Evict" }, { "title": "Expire" }, { "title": "Report" } ], "lanes": [ { "title": "What they do", "kind": "step", "cells": [ [ { "label": "Gets undeclared-call alert" } ], [ { "label": "Queries access logs" } ], [ { "label": "Merges emergency deny" } ], [ { "label": "Bans node · kills pod" } ], [ { "label": "Waits out the SVID" } ], [ { "label": "Pulls issuance record" } ] ] }, { "title": "System behind it", "kind": "system", "cells": [ [ { "label": "Alertmanager", "icon": "prometheus" } ], [ { "label": "Access logs", "icon": "clickhouse" } ], [ { "label": "Deny policy · Cilium", "icon": "fa5_ban" } ], [ { "label": "SPIRE agent ban", "icon": "fa5_ban" } ], [ { "label": "24 h lifetime", "icon": "fa5_hourglass_half" } ], [ { "label": "Issuance records", "icon": "clickhouse" } ] ] }, { "title": "How it feels", "kind": "emotion", "levels": [ "Calm", "Tense", "Alarmed" ], "points": [ "Alarmed", "Tense", "Alarmed", "Tense", "Calm", "Calm" ] }, { "title": "Where it hurts", "kind": "pain", "cells": [ [], [ { "label": "Pod IP already reused" } ], [ { "label": "Deny rides a config push" } ], [ { "label": "Stolen cert still valid" } ], [], [] ] }, { "title": "What the platform gives", "kind": "gain", "cells": [ [ { "label": "Caller named by identity" } ], [ { "label": "Peer identity per hop" } ], [ { "label": "L3 block, second plane" } ], [ { "label": "Key proves one identity" } ], [ { "label": "Useless after ≤ 24 h", "icon": "fa5_clock" } ], [ { "label": "Attestation per cert" } ] ] } ], "chain": true, "meta": { "v": "1.0", "owner": "Platform Networking Architecture", "date": "2026-09" } }, { "id": "07-layered-architecture", "title": "Layered Architecture", "layout": "bands", "layerHeaderWidth": 170, "bands": [ { "name": "Intent and governance", "nodes": [ { "id": "l-git", "label": "Intent repositories", "sub": "Forgejo · signed", "kind": "store", "icon": "git" }, { "id": "l-ci", "label": "Policy checks", "sub": "OPA · impact replay", "kind": "decision", "icon": "opa" }, { "id": "l-argo", "label": "Argo CD", "sub": "one per site · waves", "kind": "app", "icon": "argocd" }, { "id": "l-roll", "label": "Argo Rollouts", "sub": "weights owner", "kind": "app", "icon": "argocd" } ] }, { "name": "Control plane", "nodes": [ { "id": "l-api", "label": "Kubernetes API", "sub": "etcd · per cluster", "kind": "platform", "icon": "kubernetes" }, { "id": "l-adm", "label": "Admission guards", "sub": "Gatekeeper · VAP", "kind": "security", "icon": "opa" }, { "id": "l-istiod", "label": "istiod", "sub": "compile · delta xDS", "kind": "app", "icon": "istio" } ] }, { "name": "Identity plane", "nodes": [ { "id": "l-root", "label": "Offline root", "sub": "HSM · 10 years", "kind": "security", "icon": "fa5_microchip" }, { "id": "l-bao", "label": "OpenBao PKI", "sub": "cluster intermediates", "kind": "security", "icon": "fa5_key" }, { "id": "l-spire", "label": "SPIRE server", "sub": "7-day signing CA", "kind": "security", "icon": "fa5_id_badge" }, { "id": "l-agent", "label": "SPIRE agent", "sub": "per node · attests", "kind": "security", "icon": "fa5_id_badge" } ] }, { "name": "Data plane", "nodes": [ { "id": "l-cil", "label": "Cilium", "sub": "L3/L4 policy · BGP", "kind": "platform", "icon": "fa5_network_wired" }, { "id": "l-eg", "label": "Egress gateway", "sub": "declared hosts", "kind": "integration", "icon": "fa5_sign_out_alt" }, { "id": "l-ew", "label": "East-west gateway", "sub": "SNI passthrough", "kind": "integration", "icon": "envoy" }, { "id": "l-envoy", "label": "Envoy sidecar", "sub": "native sidecar", "kind": "integration", "icon": "envoy" } ] }, { "name": "Observability and cost", "nodes": [ { "id": "l-cost", "label": "OpenCost", "sub": "per-team report", "kind": "platform", "icon": "fa5_file_invoice_dollar" }, { "id": "l-thanos", "label": "Thanos", "sub": "15 d · 13 mo", "kind": "store", "icon": "prometheus" }, { "id": "l-tempo", "label": "Tempo", "sub": "traces · 7 d", "kind": "store", "icon": "tempo" }, { "id": "l-otel", "label": "OTel collector", "sub": "node · bounded", "kind": "platform", "icon": "opentelemetry" }, { "id": "l-ch", "label": "ClickHouse", "sub": "access · issuance", "kind": "store", "icon": "clickhouse" } ] } ], "edges": [ { "from": "l-argo", "to": "l-api", "label": "apply" }, { "from": "l-istiod", "to": "l-envoy", "label": "delta xDS", "kind": "async" }, { "from": "l-agent", "to": "l-envoy", "label": "SVID · SDS" }, { "from": "l-envoy", "to": "l-otel", "label": "telemetry", "kind": "async" } ], "note": "Each layer depends only on the layers above it for change, and on nothing above it for forwarding a request.", "meta": { "v": "1.0", "owner": "Platform Networking Architecture", "date": "2026-09" } }, { "id": "08-container-architecture", "title": "Container Architecture — One Workload Cluster", "layout": "nested", "boxes": [ { "title": "Cluster c07 · site A · Kubernetes", "kind": "onprem", "dir": "row", "children": [ { "title": "Platform node pool", "kind": "boundary", "dir": "col", "children": [ { "title": "Control plane", "kind": "plain", "dir": "row", "nodes": [ { "id": "k-api", "label": "Kubernetes API", "sub": "3 × etcd", "kind": "platform", "icon": "kubernetes" }, { "id": "k-istiod", "label": "istiod", "sub": "3 replicas · HPA", "kind": "app", "icon": "istio" }, { "id": "k-adm", "label": "Admission guards", "sub": "Gatekeeper · VAP", "kind": "security", "icon": "opa" } ] }, { "title": "Identity", "kind": "trust", "dir": "row", "nodes": [ { "id": "k-spire", "label": "SPIRE server", "sub": "3 replicas", "kind": "security", "icon": "fa5_id_badge" }, { "id": "k-pg", "label": "SPIRE datastore", "sub": "CloudNativePG", "kind": "store", "icon": "postgresql" } ] } ] }, { "title": "Workload node", "kind": "boundary", "dir": "col", "children": [ { "title": "Pod · checkout", "kind": "plain", "dir": "row", "nodes": [ { "id": "k-app", "label": "checkout app", "sub": "unaware of mesh", "kind": "app", "icon": "fa5_cube" }, { "id": "k-envoy", "label": "Envoy sidecar", "sub": "native sidecar", "kind": "integration", "icon": "envoy" } ] }, { "title": "Node agents · DaemonSets", "kind": "plain", "dir": "row", "nodes": [ { "id": "k-agent", "label": "SPIRE agent", "sub": "Workload API", "kind": "security", "icon": "fa5_id_badge" }, { "id": "k-otel", "label": "OTel collector", "sub": "bounded queue", "kind": "platform", "icon": "opentelemetry" }, { "id": "k-cil", "label": "Cilium agent", "sub": "eBPF · policy", "kind": "platform", "icon": "fa5_network_wired" } ] } ] }, { "title": "Gateway node pool", "kind": "boundary", "dir": "col", "nodes": [ { "id": "k-ew", "label": "East-west gateway", "sub": "BGP VIP · passthrough", "kind": "integration", "icon": "envoy" }, { "id": "k-eg", "label": "Egress gateway", "sub": "declared hosts", "kind": "integration", "icon": "fa5_sign_out_alt" } ] } ] } ], "outside": [ { "id": "k-bao", "label": "OpenBao PKI", "sub": "site A", "kind": "security", "icon": "fa5_key" }, { "id": "k-tel", "label": "Telemetry stores", "sub": "Thanos · Tempo · ClickHouse", "kind": "store", "icon": "fa5_database" }, { "id": "k-remote", "label": "Remote clusters", "sub": "their east-west gateways", "kind": "external", "icon": "kubernetes" } ], "edges": [ { "from": "k-api", "to": "k-istiod", "label": "watch" }, { "from": "k-istiod", "to": "k-envoy", "label": "delta xDS", "kind": "async" }, { "from": "k-spire", "to": "k-agent", "label": "SVIDs" }, { "from": "k-app", "to": "k-envoy", "label": "localhost" }, { "from": "k-spire", "to": "k-bao", "label": "CA renewal" }, { "from": "k-otel", "to": "k-tel", "label": "OTLP", "kind": "async" }, { "from": "k-ew", "to": "k-remote", "label": "mTLS · SNI" } ], "note": "Omitted for legibility: Argo CD applying to the API (view 14), sidecar to agent over SDS (view 16), sidecar to collector (view 15).", "meta": { "v": "1.0", "owner": "Platform Networking Architecture", "date": "2026-09" } }, { "id": "09-trust-hierarchy", "title": "Trust Hierarchy — Four Lifetimes, Each Shorter Than the One Above", "layout": "flow", "chain": false, "stages": [ { "title": "Offline · 10 years", "nodes": [ { "id": "t-root", "label": "Mesh root", "sub": "HSM · air-gapped", "kind": "security", "icon": "fa5_microchip" } ] }, { "title": "Site OpenBao · 1 year", "nodes": [ { "id": "t-i07", "label": "Intermediate c07", "sub": "name-constrained", "kind": "security", "icon": "fa5_certificate" }, { "id": "t-i12", "label": "Intermediate c12", "sub": "name-constrained", "kind": "security", "icon": "fa5_certificate" } ] }, { "title": "In cluster · 7 days", "nodes": [ { "id": "t-s07", "label": "SPIRE CA c07", "sub": "renews at 3.5 d", "kind": "security", "icon": "fa5_id_badge" }, { "id": "t-s12", "label": "SPIRE CA c12", "sub": "renews at 3.5 d", "kind": "security", "icon": "fa5_id_badge" } ] }, { "title": "Per pod · 24 hours", "nodes": [ { "id": "t-w07", "label": "SVID checkout", "sub": "rotated at 12 h", "kind": "app", "icon": "fa5_id_card" }, { "id": "t-w12", "label": "SVID ledger", "sub": "rotated at 12 h", "kind": "app", "icon": "fa5_id_card" } ] }, { "title": "Every proxy", "nodes": [ { "id": "t-bundle", "label": "Trust bundle", "sub": "roots only · sent ahead", "kind": "store", "icon": "fa5_stamp" } ] } ], "edges": [ { "from": "t-root", "to": "t-i07", "label": "ceremony", "kind": "batch" }, { "from": "t-root", "to": "t-i12", "label": "ceremony", "kind": "batch" }, { "from": "t-i07", "to": "t-s07", "label": "signs" }, { "from": "t-i12", "to": "t-s12", "label": "signs" }, { "from": "t-s07", "to": "t-w07", "label": "signs" }, { "from": "t-s12", "to": "t-w12", "label": "signs" }, { "from": "t-w07", "to": "t-bundle", "label": "verified against" } ], "note": "Intermediate c07 can sign only spiffe://c07.mesh.corp identities. A proxy trusts roots, never an intermediate.", "meta": { "v": "1.0", "owner": "Security Architecture", "date": "2026-09" } }, { "id": "10-integration-surface", "title": "Integration Surface — Every Interface", "layout": "hub", "left": { "title": "What changes it", "nodes": [ { "id": "i-git", "label": "Intent repos · Argo CD", "kind": "store", "rel": "GitOps apply", "icon": "git" }, { "id": "i-roll", "label": "Argo Rollouts", "kind": "app", "rel": "weight steps", "icon": "argocd" }, { "id": "i-k8s", "label": "Kubernetes API", "kind": "platform", "rel": "watch", "icon": "kubernetes" } ] }, "centre": { "title": "Platform", "nodes": [ { "id": "i-core", "label": "Service Mesh Platform", "sub": "compile · issue · enforce", "icon": "istio" } ] }, "right": { "title": "What it serves and reaches", "nodes": [ { "id": "i-wl", "label": "Workloads · peer clusters", "kind": "external", "rel": "mTLS · xDS", "dir": "out", "icon": "kubernetes" }, { "id": "i-tel", "label": "Telemetry stores", "kind": "store", "rel": "OTLP", "dir": "out", "kind2": "async", "icon": "fa5_database" }, { "id": "i-pki", "label": "OpenBao · root ceremony", "kind": "security", "rel": "CA renewal", "dir": "out", "icon": "fa5_key" } ] }, "note": "Only mTLS between proxies is on a request path. External APIs sit behind the egress gateway on view 29.", "meta": { "v": "1.0", "owner": "Platform Networking Architecture", "date": "2026-09" } }, { "id": "11-anatomy-of-a-meshed-call", "title": "Anatomy of One Meshed Call — Every Decision Reads Local State", "layout": "flow", "chain": true, "stages": [ { "title": "Caller pod", "nodes": [ { "id": "n-app", "label": "checkout app", "sub": "forwards trace · deadline", "kind": "app", "icon": "fa5_cube" } ] }, { "title": "Outbound proxy", "nodes": [ { "id": "n-route", "label": "Route match", "sub": "subset · weight", "kind": "integration", "icon": "fa5_random" }, { "id": "n-retry", "label": "Timeout · retry budget", "sub": "GET only · 20%", "kind": "decision", "icon": "fa5_stopwatch" }, { "id": "n-lb", "label": "Outlier · limits", "sub": "locality first", "kind": "integration", "icon": "fa5_filter" } ] }, { "title": "On the wire", "nodes": [ { "id": "n-mtls", "label": "mTLS", "sub": "SVID · TLS 1.3", "kind": "security", "icon": "fa5_lock" } ] }, { "title": "Inbound proxy", "nodes": [ { "id": "n-verify", "label": "Identity verify", "sub": "chain + expected SAN", "kind": "security", "icon": "fa5_fingerprint" }, { "id": "n-authz", "label": "Authorisation", "sub": "in-proxy · 0.2 ms", "kind": "security", "icon": "fa5_user_shield" }, { "id": "n-conc", "label": "Concurrency limit", "sub": "shed, never queue", "kind": "decision", "icon": "fa5_hand_paper" } ] }, { "title": "Callee pod", "nodes": [ { "id": "n-callee", "label": "ledger app", "sub": "sees caller identity", "kind": "app", "icon": "fa5_cube" } ] } ], "note": "Three local inputs decide everything here: last-good config, the trust bundle and an unexpired SVID. None is fetched per request.", "meta": { "v": "1.0", "owner": "Platform Networking Architecture", "date": "2026-09" } }, { "id": "12-five-stores", "title": "Five Stores, Five Recovery Obligations", "layout": "nested", "boxes": [ { "title": "Mesh state, by what losing it costs", "kind": "plain", "dir": "row", "children": [ { "title": "Intent · source of truth · RPO 0", "kind": "boundary", "dir": "col", "nodes": [ { "id": "d-git", "label": "Intent repositories", "sub": "Forgejo · signed commits", "kind": "store", "icon": "git" }, { "id": "d-etcd", "label": "Applied objects", "sub": "etcd · per cluster", "kind": "store", "icon": "kubernetes" } ] }, { "title": "Identity · RPO 0", "kind": "trust", "dir": "col", "nodes": [ { "id": "d-bao", "label": "OpenBao Raft", "sub": "intermediates", "kind": "store", "icon": "fa5_key" }, { "id": "d-spire", "label": "SPIRE datastore", "sub": "entries · agents", "kind": "store", "icon": "postgresql" }, { "id": "d-iss", "label": "Issuance records", "sub": "ClickHouse · 13 mo", "kind": "store", "icon": "clickhouse" } ] }, { "title": "Derived · rebuildable", "kind": "boundary", "dir": "col", "nodes": [ { "id": "d-snap", "label": "xDS snapshots", "sub": "istiod memory · ≤ 5 min", "kind": "store", "icon": "fa5_memory" }, { "id": "d-bundle", "label": "Rendered bundles", "sub": "Harbor OCI · cosign", "kind": "store", "icon": "fa5_file_signature" } ] }, { "title": "Discovery · current only", "kind": "boundary", "dir": "col", "nodes": [ { "id": "d-eps", "label": "EndpointSlices", "sub": "per cluster", "kind": "store", "icon": "kubernetes" }, { "id": "d-remote", "label": "Remote endpoints", "sub": "declared exports only", "kind": "store", "icon": "fa5_network_wired" } ] }, { "title": "Telemetry · loss-tolerant", "kind": "boundary", "dir": "col", "nodes": [ { "id": "d-met", "label": "Thanos", "sub": "15 d raw · 13 mo", "kind": "store", "icon": "prometheus" }, { "id": "d-tr", "label": "Tempo", "sub": "traces · 7 d", "kind": "store", "icon": "tempo" }, { "id": "d-log", "label": "Access logs", "sub": "ClickHouse · 30 d", "kind": "store", "icon": "clickhouse" } ] } ] } ], "note": "Only the first two columns need backups that are restored in drills. The third is rebuilt by a restart, the fourth by the clusters themselves.", "meta": { "v": "1.0", "owner": "Platform Networking Architecture", "date": "2026-09" } }, { "id": "13-intent-data-model", "title": "Intent and Evidence — Data Model", "layout": "er", "canvas": { "width": 1640, "cols": 4 }, "rowGap": 150, "entities": [ { "id": "e-iv", "name": "intent_version", "kind": "store", "row": 0, "col": 1, "attrs": [ "commit_sha PK", "repo routes|security|identity", "author", "signed_by", "bundle_digest", "merged_at" ] }, { "id": "e-chg", "name": "change_record", "kind": "store", "row": 0, "col": 0, "attrs": [ "change_id PK", "commit_sha FK", "actor", "before_digest", "after_digest", "applied_at per cluster" ] }, { "id": "e-svc", "name": "service", "kind": "store", "row": 1, "col": 2, "attrs": [ "service_id PK", "namespace", "owner_team", "mtls_mode permissive|strict", "sampling_rate" ] }, { "id": "e-sub", "name": "subset", "kind": "store", "row": 0, "col": 3, "attrs": [ "subset_id PK", "service_id FK", "selector version, region", "backing_service" ] }, { "id": "e-dep", "name": "dependency", "kind": "store", "row": 2, "col": 2, "attrs": [ "caller_id FK -> service", "callee_id FK -> service", "declared_in FK -> intent_version" ] }, { "id": "e-route", "name": "route", "kind": "store", "row": 1, "col": 3, "attrs": [ "route_id PK", "service_id FK", "match header, path, method", "timeout_ms NOT NULL", "retry_on, attempts", "commit_sha FK" ] }, { "id": "e-back", "name": "route_backend", "kind": "store", "row": 2, "col": 3, "attrs": [ "route_id FK", "subset_id FK", "weight 0-100", "mirror_percent" ] }, { "id": "e-authz", "name": "authz_policy", "kind": "store", "row": 0, "col": 2, "attrs": [ "policy_id PK", "service_id FK", "action allow|deny", "mode enforce|dry_run", "principals", "commit_sha FK" ] }, { "id": "e-wid", "name": "workload_identity", "kind": "store", "row": 1, "col": 1, "attrs": [ "spiffe_id PK", "trust_domain cluster", "namespace", "service_account" ] }, { "id": "e-iss", "name": "issuance_record", "kind": "store", "row": 1, "col": 0, "attrs": [ "serial PK", "spiffe_id FK", "node_attestation", "workload_selectors", "issuer_ca", "not_before, not_after" ] }, { "id": "e-px", "name": "proxy_status", "kind": "store", "row": 2, "col": 1, "attrs": [ "proxy_id PK", "spiffe_id FK", "commit_sha FK effective", "xds_nonce, acked_at", "proxy_version" ] } ], "relations": [ { "from": "e-iv", "to": "e-chg", "label": "1 : N", "from_side": "w", "to_side": "e" }, { "from": "e-svc", "to": "e-authz", "label": "1 : N", "from_side": "n", "to_side": "s" }, { "from": "e-svc", "to": "e-dep", "label": "1 : N", "from_side": "s", "to_side": "n" }, { "from": "e-svc", "to": "e-route", "label": "1 : N", "from_side": "e", "to_side": "w" }, { "from": "e-sub", "to": "e-route", "label": "N : M", "from_side": "s", "to_side": "n", "kind": "optional" }, { "from": "e-route", "to": "e-back", "label": "1 : N", "from_side": "s", "to_side": "n" }, { "from": "e-wid", "to": "e-iss", "label": "1 : N", "from_side": "w", "to_side": "e" }, { "from": "e-wid", "to": "e-px", "label": "1 : N", "from_side": "s", "to_side": "n" } ], "note": "proxy_status.commit_sha is observed, route.commit_sha is intended; drift is the rows where they differ.", "meta": { "v": "1.0", "owner": "Platform Networking Architecture", "date": "2026-09" } }, { "id": "14-config-distribution-pipeline", "title": "Configuration Distribution — From Merge to Acknowledged", "layout": "flow", "chain": true, "stages": [ { "title": "Author", "nodes": [ { "id": "p-pr", "label": "Intent change", "sub": "one of three repos", "kind": "store", "icon": "git" } ] }, { "title": "Check", "nodes": [ { "id": "p-lint", "label": "Schema + lint", "sub": "timeout required", "kind": "decision", "icon": "opa" }, { "id": "p-sim", "label": "Impact replay", "sub": "24 h of access logs", "kind": "decision", "icon": "fa5_history" } ] }, { "title": "Package", "nodes": [ { "id": "p-bundle", "label": "Rendered bundle", "sub": "OCI · cosign", "kind": "store", "icon": "fa5_file_signature" } ] }, { "title": "Apply", "nodes": [ { "id": "p-argo", "label": "Argo CD wave", "sub": "canary cluster first", "kind": "app", "icon": "argocd" }, { "id": "p-adm", "label": "Admission guards", "sub": "second line", "kind": "security", "icon": "opa" } ] }, { "title": "Compile", "nodes": [ { "id": "p-istiod", "label": "istiod", "sub": "scoped per workload", "kind": "app", "icon": "istio" } ] }, { "title": "Deliver", "nodes": [ { "id": "p-envoy", "label": "Envoy sidecar", "sub": "delta · ACK or NACK", "kind": "integration", "icon": "envoy" } ] }, { "title": "Verify", "nodes": [ { "id": "p-drift", "label": "Drift exporter", "sub": "sha per proxy", "kind": "platform", "icon": "fa5_code_branch" } ] } ], "edges": [ { "from": "p-drift", "to": "p-argo", "label": "halt wave", "kind": "error", "route": "gutter" } ], "note": "A push is finished when proxies acknowledge it and the drift exporter sees the new sha, not when Argo CD reports Synced.", "meta": { "v": "1.0", "owner": "Platform Networking Architecture", "date": "2026-09" } }, { "id": "15-telemetry-pipeline", "title": "Telemetry Pipeline — Never on the Request Path", "layout": "flow", "chain": true, "stages": [ { "title": "Emit", "nodes": [ { "id": "o-envoy", "label": "Envoy sidecar", "sub": "stats · spans · ALS", "kind": "integration", "icon": "envoy" } ] }, { "title": "Node", "nodes": [ { "id": "o-otel", "label": "OTel collector", "sub": "drop-oldest · counted", "kind": "platform", "icon": "opentelemetry" } ] }, { "title": "Shape", "nodes": [ { "id": "o-samp", "label": "Sampling policy", "sub": "per namespace", "kind": "decision", "icon": "fa5_filter" }, { "id": "o-tag", "label": "Failure origin tag", "sub": "app · mesh · network", "kind": "app", "icon": "fa5_tags" } ] }, { "title": "Keep", "nodes": [ { "id": "o-thanos", "label": "Prometheus + Thanos", "sub": "15 d · 13 mo", "kind": "store", "icon": "prometheus" }, { "id": "o-tempo", "label": "Tempo", "sub": "7 d", "kind": "store", "icon": "tempo" }, { "id": "o-ch", "label": "Access logs", "sub": "ClickHouse · 30 d", "kind": "store", "icon": "clickhouse" } ] }, { "title": "Use", "nodes": [ { "id": "o-graf", "label": "Grafana", "sub": "per-service views", "kind": "platform", "icon": "grafana" }, { "id": "o-roll", "label": "Rollout analysis", "sub": "Argo Rollouts", "kind": "app", "icon": "argocd" }, { "id": "o-cost", "label": "OpenCost", "sub": "team attribution", "kind": "platform", "icon": "fa5_file_invoice_dollar" } ] } ], "note": "Default capture: all denials and 5xx, 1% of successes, no header values and no payloads. Namespaces raise it by a reviewed change.", "meta": { "v": "1.0", "owner": "Platform Networking Architecture", "date": "2026-09" } }, { "id": "16-certificate-issuance-and-rotation", "title": "Certificate Issuance and Rotation — Attested, Never Asserted", "layout": "sequence", "lifelines": [ { "id": "q-envoy", "label": "Envoy sidecar", "kind": "integration", "icon": "envoy" }, { "id": "q-agent", "label": "SPIRE agent", "kind": "security", "icon": "fa5_id_badge" }, { "id": "q-kubelet", "label": "kubelet", "kind": "platform", "icon": "kubernetes" }, { "id": "q-server", "label": "SPIRE server", "kind": "security", "icon": "fa5_id_badge" }, { "id": "q-bao", "label": "OpenBao PKI", "kind": "security", "icon": "fa5_key" }, { "id": "q-peer", "label": "Peer proxy", "kind": "integration", "icon": "envoy" } ], "messages": [ { "from": "q-envoy", "to": "q-agent", "label": "SDS: fetch SVID (Workload API)", "kind": "call" }, { "from": "q-agent", "to": "q-kubelet", "label": "which pod owns this PID?", "kind": "call" }, { "from": "q-kubelet", "to": "q-agent", "label": "namespace · service account · labels", "kind": "return" }, { "from": "q-agent", "to": "q-server", "label": "CSR for attested selectors", "kind": "call" }, { "from": "q-server", "to": "q-server", "label": "match entry · write issuance record", "kind": "self" }, { "from": "q-server", "to": "q-agent", "label": "SVID 24 h + trust bundle", "kind": "return", "icon": "fa5_clock" }, { "from": "q-agent", "to": "q-envoy", "label": "push SVID and bundle", "kind": "return" }, { "from": "q-envoy", "to": "q-peer", "label": "mTLS handshake", "kind": "call" }, { "from": "q-agent", "to": "q-agent", "label": "t + 12 h: renew", "kind": "self", "icon": "fa5_clock" }, { "from": "q-agent", "to": "q-envoy", "label": "rotated SVID · no restart", "kind": "async" }, { "from": "q-server", "to": "q-bao", "label": "renew 7-day CA at half-life", "kind": "call" }, { "from": "q-bao", "to": "q-server", "label": "CA signed by c07 intermediate", "kind": "return" } ], "note": "The pod never names itself. Its identity comes from what the kubelet reports about the process on a node the server has already attested.", "meta": { "v": "1.0", "owner": "Security Architecture", "date": "2026-09" } }, { "id": "17-root-rotation", "title": "Root Rotation — Additive, With a 30-Day Overlap", "layout": "swimlane", "laneHeaderWidth": 160, "stages": [ "T − 30 d · add", "Overlap", "T0 · switch", "T0 → 24 h", "T + 30 d · retire" ], "lanes": [ { "title": "Trust bundle", "cells": [ [ { "label": "Old + new root", "kind": "store" } ], [ { "label": "Reaches every proxy", "kind": "store" } ], [], [], [ { "label": "Old root removed", "kind": "store" } ] ] }, { "title": "Intermediates", "cells": [ [], [ { "label": "Re-signed by new root", "kind": "security" } ], [ { "label": "SPIRE CAs chain to new", "kind": "security" } ], [], [] ] }, { "title": "Workload SVIDs", "cells": [ [], [], [ { "label": "New issuance, new chain", "kind": "app" } ], [ { "label": "Old-chain SVIDs expire", "kind": "app" } ], [] ] }, { "title": "Gate", "cells": [ [ { "label": "Bundle coverage 100%", "kind": "decision" } ], [ { "label": "Skewed handshakes = 0", "kind": "decision" } ], [ { "label": "Hold if any proxy lags", "kind": "risk" } ], [ { "label": "Old-chain count → 0", "kind": "decision" } ], [ { "label": "Removal PR, two keys", "kind": "security" } ] ] } ], "note": "Every step can be reversed until the last, and the last is taken only after the overlap has been measured, not assumed.", "meta": { "v": "1.0", "owner": "Security Architecture", "date": "2026-09" } }, { "id": "18-canary-with-automatic-rollback", "title": "A Canary That Fails — Automatic Rollback in 41 Seconds", "layout": "sequence", "lifelines": [ { "id": "r-eng", "label": "Release engineer", "kind": "actor", "icon": "fa5_user_tie" }, { "id": "r-roll", "label": "Argo Rollouts", "kind": "app", "icon": "argocd" }, { "id": "r-api", "label": "Kubernetes API", "kind": "platform", "icon": "kubernetes" }, { "id": "r-istiod", "label": "istiod", "kind": "app", "icon": "istio" }, { "id": "r-envoy", "label": "Caller proxies", "kind": "integration", "icon": "envoy" }, { "id": "r-thanos", "label": "Thanos", "kind": "store", "icon": "prometheus" } ], "messages": [ { "from": "r-eng", "to": "r-roll", "label": "start v2.14 at 1%", "kind": "call" }, { "from": "r-roll", "to": "r-api", "label": "route weights 99 / 1", "kind": "call" }, { "from": "r-api", "to": "r-istiod", "label": "watch event", "kind": "async" }, { "from": "r-istiod", "to": "r-envoy", "label": "delta xDS: one route", "kind": "async" }, { "from": "r-envoy", "to": "r-istiod", "label": "ACK", "kind": "return" }, { "from": "r-roll", "to": "r-thanos", "label": "applied canary share? error ratio?", "kind": "call" }, { "from": "r-thanos", "to": "r-roll", "label": "0.98% · 5xx 2.3× stable", "kind": "return" }, { "from": "r-roll", "to": "r-roll", "label": "analysis failed: abort", "kind": "self" }, { "from": "r-roll", "to": "r-api", "label": "route weights 100 / 0", "kind": "error" }, { "from": "r-istiod", "to": "r-envoy", "label": "delta xDS: one route", "kind": "async" }, { "from": "r-roll", "to": "r-eng", "label": "aborted · 41 s after breach", "kind": "return", "icon": "fa5_clock" } ], "note": "The rollout checks the share the mesh reports, not the weight it wrote. Only Argo Rollouts may write this route; a human aborts the rollout, not the route.", "meta": { "v": "1.0", "owner": "Platform Networking Architecture", "date": "2026-09" } }, { "id": "19-cross-cluster-failover", "title": "Cross-Cluster Failover — The Caller's Identity Arrives Intact", "layout": "sequence", "lifelines": [ { "id": "x-app", "label": "checkout · c07", "kind": "app", "icon": "fa5_cube" }, { "id": "x-cp", "label": "checkout proxy · c07", "kind": "integration", "icon": "envoy" }, { "id": "x-local", "label": "ledger pods · c07", "kind": "app", "icon": "fa5_cubes" }, { "id": "x-gw", "label": "East-west gateway · c12", "kind": "integration", "icon": "envoy" }, { "id": "x-lp", "label": "ledger proxy · c12", "kind": "integration", "icon": "envoy" }, { "id": "x-ledger", "label": "ledger app · c12", "kind": "app", "icon": "fa5_cube" } ], "messages": [ { "from": "x-app", "to": "x-cp", "label": "GET ledger/balance", "kind": "call" }, { "from": "x-cp", "to": "x-local", "label": "try local zone", "kind": "call" }, { "from": "x-local", "to": "x-cp", "label": "5 consecutive 503s", "kind": "error" }, { "from": "x-cp", "to": "x-cp", "label": "eject · local healthy below 70%", "kind": "self" }, { "from": "x-cp", "to": "x-gw", "label": "TLS · SNI names ledger subset", "kind": "call" }, { "from": "x-gw", "to": "x-lp", "label": "bytes forwarded, TLS untouched", "kind": "call" }, { "from": "x-lp", "to": "x-lp", "label": "peer is c07/checkout · allowed", "kind": "self" }, { "from": "x-lp", "to": "x-ledger", "label": "request", "kind": "call" }, { "from": "x-ledger", "to": "x-lp", "label": "200", "kind": "return" }, { "from": "x-cp", "to": "x-app", "label": "200 · spillover counted", "kind": "return" } ], "note": "The gateway reads SNI and nothing else. It holds no workload identity, so it cannot be the caller.", "meta": { "v": "1.0", "owner": "Platform Networking Architecture", "date": "2026-09" } }, { "id": "20-retry-amplification-contained", "title": "A Slow Dependency, and Why It Does Not Become an Outage", "layout": "swimlane", "laneHeaderWidth": 160, "stages": [ "Dependency slows", "Retries begin", "Budget reached", "Shedding", "Recovery" ], "lanes": [ { "title": "Caller proxies", "cells": [ [ { "label": "p99 280 ms → 2 s", "kind": "risk", "icon": "fa5_clock" } ], [ { "label": "Retry 503 · GET only", "kind": "integration" } ], [ { "label": "Budget 20% spent", "kind": "decision" } ], [ { "label": "Fast 503 to app", "kind": "security" } ], [ { "label": "Budget refills", "kind": "opportunity" } ] ] }, { "title": "Callee proxies", "cells": [ [ { "label": "Pending grows", "kind": "risk" } ], [ { "label": "Outlier ejects 2 pods", "kind": "integration" } ], [ { "label": "Concurrency at limit", "kind": "decision" } ], [ { "label": "Overflow shed", "kind": "security" } ], [ { "label": "Ejections expire", "kind": "opportunity" } ] ] }, { "title": "Deadline", "cells": [ [ { "label": "Caller allows 800 ms", "kind": "journey" } ], [ { "label": "250 ms per try", "kind": "journey" } ], [ { "label": "No retry past deadline", "kind": "security" } ], [], [] ] }, { "title": "Signals", "cells": [ [ { "label": "Latency alert", "kind": "platform" } ], [ { "label": "Retry ratio 0.2", "kind": "platform" } ], [ { "label": "retry_overflow", "kind": "platform" } ], [ { "label": "Origin: mesh limit", "kind": "platform" } ], [ { "label": "Budget refills", "kind": "platform" } ] ] } ], "note": "Without the budget, three attempts per call triples load on the one service already failing. With it, load rises by at most a fifth.", "meta": { "v": "1.0", "owner": "Platform Networking Architecture", "date": "2026-09" } }, { "id": "21-control-plane-outage", "title": "Total Control-Plane Outage — A Freeze, Then a Deadline", "layout": "grid", "laneHeaderWidth": 180, "columns": [ "0 – 12 h", "12 – 24 h", "Beyond 24 h", "When it returns" ], "rows": [ { "title": "Existing traffic", "cells": [ [ { "label": "Flows on last config", "kind": "opportunity" } ], [ { "label": "Flows · expiry paging", "kind": "decision" } ], [ { "label": "Fails closed per pod", "kind": "risk" } ], [ { "label": "Renew · reconnect", "kind": "app", "icon": "fa5_sync_alt" } ] ] }, { "title": "Certificate renewal", "cells": [ [ { "label": "Not yet due", "kind": "opportunity" } ], [ { "label": "Renewals fail, retried", "kind": "decision", "icon": "fa5_sync_alt" } ], [ { "label": "Emergency issuance", "kind": "risk" } ], [ { "label": "Backlog issued ≤ 20 s", "kind": "app", "icon": "fa5_clock" } ] ] }, { "title": "Routes and denies", "cells": [ [ { "label": "Frozen at last push", "kind": "decision", "icon": "fa5_snowflake" } ], [ { "label": "Frozen", "kind": "decision", "icon": "fa5_snowflake" } ], [ { "label": "Frozen", "kind": "decision", "icon": "fa5_snowflake" } ], [ { "label": "Push · drift clears", "kind": "app" } ] ] }, { "title": "New pods", "cells": [ [ { "label": "Refused in strict ns", "kind": "risk" } ], [ { "label": "Refused in strict ns", "kind": "risk" } ], [ { "label": "Refused in strict ns", "kind": "risk" } ], [ { "label": "Config · SVID · ready", "kind": "app" } ] ] }, { "title": "Crashed proxy", "cells": [ [ { "label": "Pod unready · drained", "kind": "security" } ], [ { "label": "Pod unready · drained", "kind": "security" } ], [ { "label": "Pod unready · drained", "kind": "security" } ], [ { "label": "Restart fetches config", "kind": "app", "icon": "fa5_sync_alt" } ] ] }, { "title": "Emergency deny", "cells": [ [ { "label": "Cilium L3 policy only", "kind": "security" } ], [ { "label": "Cilium L3 policy only", "kind": "security" } ], [ { "label": "Cilium L3 policy only", "kind": "security" } ], [ { "label": "Mesh deny lands", "kind": "app" } ] ] } ], "note": "istiod, SPIRE server and OpenBao all down together. 12 hours is the promise; 24 hours is the hard edge set by certificate lifetime.", "meta": { "v": "1.0", "owner": "Platform Networking Architecture", "date": "2026-09" } }, { "id": "22-deployment-architecture", "title": "Deployment — Three Sites, Twenty Clusters, No Cross-Site Dependency In-Site", "layout": "nested", "boxes": [ { "title": "Site A · three rooms", "kind": "onprem", "dir": "col", "children": [ { "title": "Seven workload clusters, each spread across rooms", "kind": "boundary", "dir": "row", "children": [ { "title": "Room 1", "kind": "plain", "dir": "col", "nodes": [ { "id": "y-i1", "label": "istiod", "sub": "replica 1", "kind": "app", "icon": "istio" }, { "id": "y-s1", "label": "SPIRE server", "sub": "replica 1", "kind": "security", "icon": "fa5_id_badge" }, { "id": "y-w1", "label": "Workers", "sub": "sidecars · agents", "kind": "app", "icon": "kubernetes" } ] }, { "title": "Room 2", "kind": "plain", "dir": "col", "nodes": [ { "id": "y-i2", "label": "istiod", "sub": "replica 2", "kind": "app", "icon": "istio" }, { "id": "y-s2", "label": "SPIRE server", "sub": "replica 2", "kind": "security", "icon": "fa5_id_badge" }, { "id": "y-w2", "label": "Workers", "sub": "sidecars · agents", "kind": "app", "icon": "kubernetes" } ] }, { "title": "Room 3", "kind": "plain", "dir": "col", "nodes": [ { "id": "y-i3", "label": "istiod", "sub": "replica 3", "kind": "app", "icon": "istio" }, { "id": "y-s3", "label": "SPIRE server", "sub": "replica 3", "kind": "security", "icon": "fa5_id_badge" }, { "id": "y-gw", "label": "East-west gateways", "sub": "BGP VIP · ECMP", "kind": "integration", "icon": "envoy" } ] } ] }, { "title": "Site services", "kind": "boundary", "dir": "row", "nodes": [ { "id": "y-argo", "label": "Argo CD", "sub": "site A clusters only", "kind": "app", "icon": "argocd" }, { "id": "y-bao", "label": "OpenBao PKI", "sub": "5 voters · 3 rooms", "kind": "security", "icon": "fa5_key" }, { "id": "y-git", "label": "Forgejo", "sub": "primary", "kind": "store", "icon": "git" }, { "id": "y-harbor", "label": "Harbor", "sub": "images · bundles", "kind": "store", "icon": "fa5_anchor" }, { "id": "y-obs", "label": "Thanos · Tempo · ClickHouse", "sub": "site stores", "kind": "store", "icon": "prometheus" } ] } ] }, { "title": "Sites B and C · same shape", "kind": "onprem", "dir": "col", "nodes": [ { "id": "y-bc", "label": "Thirteen clusters", "sub": "own istiod · SPIRE", "kind": "app", "icon": "kubernetes" }, { "id": "y-bcsvc", "label": "Site services", "sub": "Argo CD · OpenBao", "kind": "app", "icon": "fa5_building" }, { "id": "y-mirror", "label": "Forgejo mirror", "sub": "read-only", "kind": "store", "icon": "git" } ] } ], "outside": [ { "id": "y-root", "label": "Root CA vault room", "sub": "offline HSM · two keyholders", "kind": "security", "icon": "fa5_microchip" }, { "id": "y-global", "label": "Global views", "sub": "Thanos query · Grafana", "kind": "platform", "icon": "grafana" } ], "edges": [ { "from": "y-gw", "to": "y-bc", "label": "mTLS · SNI" } ], "note": "A site cut off from the other two still changes, issues and serves for itself. Mirrors, global views and the yearly root ceremony pause.", "meta": { "v": "1.0", "owner": "Platform Networking Architecture", "date": "2026-09" } }, { "id": "23-config-rollout-in-waves", "title": "A Mesh Configuration Change Rolls Out in Waves", "layout": "flow", "chain": true, "stages": [ { "title": "Merge", "nodes": [ { "id": "w-pr", "label": "Intent change", "sub": "owner repo · 2 approvals", "kind": "store", "icon": "git" } ] }, { "title": "Wave 0", "nodes": [ { "id": "w-0", "label": "Canary cluster", "sub": "synthetic + real", "kind": "app", "icon": "kubernetes" }, { "id": "w-g0", "label": "Health gate", "sub": "10 min", "kind": "decision", "icon": "fa5_traffic_light" } ] }, { "title": "Wave 1", "nodes": [ { "id": "w-1", "label": "One cluster per site", "sub": "≈ 15% of proxies", "kind": "app", "icon": "kubernetes" }, { "id": "w-g1", "label": "Health gate", "sub": "15 min", "kind": "decision", "icon": "fa5_traffic_light" } ] }, { "title": "Wave 2", "nodes": [ { "id": "w-2", "label": "Remaining clusters", "sub": "site by site", "kind": "app", "icon": "kubernetes" }, { "id": "w-g2", "label": "Health gate", "sub": "per site", "kind": "decision", "icon": "fa5_traffic_light" } ] }, { "title": "On breach", "nodes": [ { "id": "w-pin", "label": "Pin previous bundle", "sub": "one operation · ≤ 60 s", "kind": "risk", "icon": "fa5_undo" } ] } ], "edges": [ { "from": "w-g0", "to": "w-pin", "label": "breach", "kind": "error", "route": "gutter" } ], "note": "Gates read mesh-attributed error ratio, NACK count and drift. Wave 1 and 2 gates halt and revert the same way; one edge is drawn.", "meta": { "v": "1.0", "owner": "Platform Networking Architecture", "date": "2026-09" } }, { "id": "24-proxy-fleet-upgrade", "title": "Proxy Fleet Upgrade — Two Revisions Side by Side", "layout": "swimlane", "laneHeaderWidth": 160, "stages": [ "Install", "Wave 1 · 5%", "Wave 2 · 30%", "Wave 3 · 100%", "Retire" ], "lanes": [ { "title": "Control plane", "cells": [ [ { "label": "1.N+1 beside 1.N", "kind": "app" } ], [ { "label": "Both revisions serve", "kind": "app" } ], [ { "label": "Both revisions serve", "kind": "app" } ], [ { "label": "1.N has no proxies", "kind": "app" } ], [ { "label": "1.N removed", "kind": "app" } ] ] }, { "title": "Namespaces", "cells": [ [ { "label": "Canary tag moved", "kind": "journey" } ], [ { "label": "Low-risk namespaces", "kind": "journey" } ], [ { "label": "Tier-2 namespaces", "kind": "journey" } ], [ { "label": "Tier-1 namespaces", "kind": "journey" } ], [] ] }, { "title": "Proxies", "cells": [ [], [ { "label": "Rolling restart · PDB", "kind": "integration" } ], [ { "label": "Rolling restart · PDB", "kind": "integration" } ], [ { "label": "Rolling restart · PDB", "kind": "integration" } ], [ { "label": "Skew window closed", "kind": "integration" } ] ] }, { "title": "Gate", "cells": [ [ { "label": "Conformance suite", "kind": "decision" } ], [ { "label": "Errors · p99 · NACKs", "kind": "decision" } ], [ { "label": "Errors · p99 · NACKs", "kind": "decision" } ], [ { "label": "Errors · p99 · NACKs", "kind": "decision" } ], [ { "label": "Zero proxies on 1.N", "kind": "decision" } ] ] }, { "title": "Abort", "cells": [ [], [ { "label": "Retag to 1.N · restart", "kind": "risk" } ], [ { "label": "Retag to 1.N · restart", "kind": "risk" } ], [ { "label": "Stop · mixed fleet OK", "kind": "risk" } ], [] ] } ], "note": "A newer proxy never talks to an older control plane: each proxy connects to its own revision, so skew is held in both directions by construction.", "meta": { "v": "1.0", "owner": "Platform Networking Architecture", "date": "2026-09" } }, { "id": "25-observability", "title": "Observability — What Is Collected, Kept, Answered and Alerted", "layout": "grid", "laneHeaderWidth": 170, "columns": [ "Collected", "Kept", "Answers", "Pages on" ], "rows": [ { "title": "Request metrics", "cells": [ [ { "label": "Envoy stats · pruned", "kind": "integration", "icon": "envoy" } ], [ { "label": "Thanos 15 d · 13 mo", "kind": "store", "icon": "fa5_database" } ], [ { "label": "Rate, errors, p99 by peer", "kind": "journey" } ], [ { "label": "Mesh errors over 0.01%", "kind": "risk" } ] ] }, { "title": "Traces", "cells": [ [ { "label": "Span per hop · 1%", "kind": "integration" } ], [ { "label": "Tempo · 7 d", "kind": "store", "icon": "fa5_database" } ], [ { "label": "Which hop was slow", "kind": "journey" } ], [ { "label": "Context dropped", "kind": "risk" } ] ] }, { "title": "Access logs", "cells": [ [ { "label": "ALS · all errors", "kind": "integration" } ], [ { "label": "ClickHouse · 30 d", "kind": "store", "icon": "fa5_database" } ], [ { "label": "Peer, route, retries", "kind": "journey" } ], [ { "label": "Undeclared destination", "kind": "risk" } ] ] }, { "title": "Config state", "cells": [ [ { "label": "Sha and nonce per proxy", "kind": "integration" } ], [ { "label": "Thanos · current", "kind": "store", "icon": "fa5_database" } ], [ { "label": "Is intent effective?", "kind": "journey" } ], [ { "label": "Stale over 60 s · NACK", "kind": "risk", "icon": "fa5_clock" } ] ] }, { "title": "Identity", "cells": [ [ { "label": "Expiry · issuance", "kind": "integration" } ], [ { "label": "ClickHouse · 13 mo", "kind": "store", "icon": "fa5_database" } ], [ { "label": "Who got which cert", "kind": "journey" } ], [ { "label": "Expiry within 6 h", "kind": "risk", "icon": "fa5_clock" } ] ] }, { "title": "Mesh cost", "cells": [ [ { "label": "Proxy CPU, memory, bytes", "kind": "integration" } ], [ { "label": "OpenCost · monthly", "kind": "store" } ], [ { "label": "What each team pays", "kind": "journey" } ], [ { "label": "Over 8% CPU budget", "kind": "risk" } ] ] } ], "meta": { "v": "1.0", "owner": "Platform Networking Architecture", "date": "2026-09" } }, { "id": "26-mesh-cost-budget", "title": "Mesh Cost — Where the Budget Goes at 40,000 Proxies", "layout": "grid", "laneHeaderWidth": 170, "columns": [ "Driver", "Planning figure", "Lever", "Reported as" ], "rows": [ { "title": "Idle proxy floor", "cells": [ [ { "label": "40k proxies × idle", "kind": "journey" } ], [ { "label": "≈ 400 vCPU at 10 m", "kind": "risk", "icon": "fa5_tachometer_alt" } ], [ { "label": "Dependency scoping", "kind": "opportunity" } ], [ { "label": "Per team · monthly", "kind": "platform" } ] ] }, { "title": "Request processing", "cells": [ [ { "label": "800k proxy hops/s", "kind": "journey", "icon": "fa5_tachometer_alt" } ], [ { "label": "≈ 80 vCPU", "kind": "decision", "icon": "fa5_tachometer_alt" } ], [ { "label": "Connection reuse", "kind": "opportunity" } ], [ { "label": "vCPU per 1k rps", "kind": "platform", "icon": "fa5_tachometer_alt" } ] ] }, { "title": "Proxy memory", "cells": [ [ { "label": "Config size × proxies", "kind": "journey" } ], [ { "label": "≤ 4.8 TB at p95", "kind": "risk", "icon": "fa5_tachometer_alt" } ], [ { "label": "Scoping · L4 per node", "kind": "opportunity" } ], [ { "label": "p95 · p99 per proxy", "kind": "platform" } ] ] }, { "title": "Telemetry", "cells": [ [ { "label": "Series × label values", "kind": "journey" } ], [ { "label": "Largest line item", "kind": "risk" } ], [ { "label": "Sampling per namespace", "kind": "opportunity" } ], [ { "label": "Bytes per team", "kind": "platform" } ] ] }, { "title": "Cross-zone traffic", "cells": [ [ { "label": "Spillover · failover", "kind": "journey" } ], [ { "label": "Measured, not guessed", "kind": "decision" } ], [ { "label": "Locality routing", "kind": "opportunity" } ], [ { "label": "Bytes by locality pair", "kind": "platform" } ] ] } ], "note": "At this fleet size the idle floor costs about five times the traffic itself. That is why scoping ships before any latency tuning.", "meta": { "v": "1.0", "owner": "Platform Networking Architecture", "date": "2026-09" } }, { "id": "27-roadmap", "title": "Roadmap — What Each Phase Makes True", "layout": "flow", "chain": true, "align": "top", "stages": [ { "title": "MVP · one site", "nodes": [ { "id": "m-id", "label": "SPIRE identity · 24 h", "kind": "security", "icon": "fa5_clock" }, { "id": "m-mtls", "label": "Permissive → strict", "kind": "security" }, { "id": "m-authz", "label": "In-proxy authz · dry-run", "kind": "security" }, { "id": "m-w", "label": "1% weights · revert", "kind": "app" }, { "id": "m-res", "label": "Timeouts · retries · ejection", "kind": "app" }, { "id": "m-scope", "label": "Namespace scoping", "kind": "app" }, { "id": "m-mc", "label": "Clusters on one network", "kind": "platform" } ] }, { "title": "Phase 2 · three sites", "nodes": [ { "id": "p2-scope", "label": "Dependency scoping · delta", "kind": "app" }, { "id": "p2-waves", "label": "Config waves · auto halt", "kind": "app" }, { "id": "p2-ew", "label": "East-west gateways", "kind": "integration", "icon": "envoy" }, { "id": "p2-egress", "label": "Controlled egress", "kind": "integration" }, { "id": "p2-budget", "label": "Retry budgets · shedding", "kind": "app" }, { "id": "p2-upg", "label": "Revision upgrades", "kind": "platform" } ] }, { "title": "Phase 3 · cost and depth", "nodes": [ { "id": "p3-amb", "label": "Per-node L4 for no-L7", "kind": "opportunity" }, { "id": "p3-ext", "label": "External authz opt-in", "kind": "security" }, { "id": "p3-fed", "label": "Cross-site spillover", "kind": "integration" }, { "id": "p3-slo", "label": "SLO-burn rollback", "kind": "app" }, { "id": "p3-root", "label": "Root rotation rehearsal", "kind": "security", "icon": "fa5_sync_alt" }, { "id": "p3-replay", "label": "Policy replay at scale", "kind": "security" } ] } ], "note": "Coarse scoping ships with the MVP. Unscoped, every proxy carries the whole mesh and its memory grows with the fleet instead of with the workload.", "meta": { "v": "1.0", "owner": "Platform Networking Architecture", "date": "2026-09" } }, { "id": "28-progressive-delivery-cycle", "title": "Progressive Delivery — The Loop Every Release Runs", "layout": "cycle", "centre": { "label": "Release", "icon": "fa5_shipping_fast" }, "nodes": [ { "id": "v1", "label": "Declare subset", "sub": "version label", "kind": "app", "icon": "fa5_tags" }, { "id": "v2", "label": "Mirror", "sub": "idempotent only", "kind": "integration", "icon": "fa5_clone" }, { "id": "v3", "label": "Cohort", "sub": "header match", "kind": "integration", "icon": "fa5_user_friends" }, { "id": "v4", "label": "Weight step", "sub": "1 → 5 → 25 → 50%", "kind": "app", "icon": "fa5_random" }, { "id": "v5", "label": "Read effective", "sub": "mesh-reported share", "kind": "store", "icon": "prometheus" }, { "id": "v6", "label": "Decide", "sub": "promote or revert", "kind": "decision", "icon": "fa5_balance_scale" } ], "ringLabels": [ "pods ready", "no diffs", "staff pass", "applied", "analysis", "next release" ], "rx": 430, "ry": 215, "meta": { "v": "1.0", "owner": "Platform Networking Architecture", "date": "2026-09" } }, { "id": "29-security-trust-zones", "title": "Security — Trust Zones and What Crosses Them", "layout": "zones", "zones": [ { "title": "Outside the mesh", "kind": "trust", "nodes": [ { "id": "z-ext", "label": "External APIs", "sub": "declared hosts", "kind": "external", "icon": "fa5_globe" }, { "id": "z-legacy", "label": "Legacy VM job", "sub": "no identity", "kind": "risk", "icon": "fa5_server" } ] }, { "title": "Boundary", "kind": "trust", "nodes": [ { "id": "z-eg", "label": "Egress gateway", "sub": "TLS origination", "kind": "integration", "icon": "fa5_sign_out_alt" } ] }, { "title": "Strict namespaces", "kind": "trust", "nodes": [ { "id": "z-checkout", "label": "checkout", "sub": "default deny", "kind": "app", "icon": "fa5_cube" }, { "id": "z-ledger", "label": "ledger", "sub": "allow by identity", "kind": "app", "icon": "fa5_cube" } ] }, { "title": "Mesh control", "kind": "trust", "nodes": [ { "id": "z-istiod", "label": "istiod", "sub": "config · no keys", "kind": "app", "icon": "istio" }, { "id": "z-spire", "label": "SPIRE server", "sub": "cluster CA", "kind": "security", "icon": "fa5_id_badge" } ] }, { "title": "Key custody", "kind": "trust", "nodes": [ { "id": "z-bao", "label": "OpenBao PKI", "sub": "intermediates", "kind": "security", "icon": "fa5_key" }, { "id": "z-root", "label": "Offline root", "sub": "HSM · ceremony", "kind": "security", "icon": "fa5_microchip" } ] } ], "edges": [ { "from": "z-eg", "to": "z-ext", "label": "TLS · allowlist" }, { "from": "z-checkout", "to": "z-eg", "label": "declared host" }, { "from": "z-legacy", "to": "z-ledger", "label": "plaintext refused", "kind": "error" }, { "from": "z-istiod", "to": "z-ledger", "label": "xDS over mTLS", "kind": "async" }, { "from": "z-spire", "to": "z-bao", "label": "CA renewal" } ], "note": "No proxy holds a key that proves any identity but its own. istiod holds no signing key at all; the only in-cluster CA lives 7 days.", "meta": { "v": "1.0", "owner": "Security Architecture", "date": "2026-09" } }, { "id": "30-authorisation-decision", "title": "Authorisation at the Destination — Enforced and Dry-Run Rules Together", "layout": "sequence", "lifelines": [ { "id": "u-app", "label": "checkout app", "kind": "app", "icon": "fa5_cube" }, { "id": "u-cp", "label": "checkout proxy", "kind": "integration", "icon": "envoy" }, { "id": "u-lp", "label": "ledger proxy", "kind": "integration", "icon": "envoy" }, { "id": "u-ledger", "label": "ledger app", "kind": "app", "icon": "fa5_cube" }, { "id": "u-otel", "label": "OTel collector", "kind": "platform", "icon": "opentelemetry" } ], "messages": [ { "from": "u-app", "to": "u-cp", "label": "POST /refunds", "kind": "call" }, { "from": "u-cp", "to": "u-lp", "label": "mTLS · SVID c07/ns/shop/sa/checkout", "kind": "call" }, { "from": "u-lp", "to": "u-lp", "label": "chain valid · SAN in expected set", "kind": "self" }, { "from": "u-lp", "to": "u-lp", "label": "deny rules first: none match", "kind": "self" }, { "from": "u-lp", "to": "u-lp", "label": "allow rule matches peer, POST, path", "kind": "self" }, { "from": "u-lp", "to": "u-lp", "label": "dry-run rule v2: would deny", "kind": "self" }, { "from": "u-lp", "to": "u-otel", "label": "shadow denial, no header values", "kind": "async" }, { "from": "u-lp", "to": "u-ledger", "label": "forward · peer identity header", "kind": "call" }, { "from": "u-ledger", "to": "u-lp", "label": "201", "kind": "return" }, { "from": "u-lp", "to": "u-cp", "label": "201", "kind": "return" }, { "from": "u-cp", "to": "u-app", "label": "201", "kind": "return" } ], "note": "No step leaves the ledger proxy. The dry-run rule is compiled alongside the enforced one and changes nothing but a log line.", "meta": { "v": "1.0", "owner": "Security Architecture", "date": "2026-09" } }, { "id": "31-failure-modes", "title": "Failure Modes — Detection, Containment, What Requests See", "layout": "grid", "laneHeaderWidth": 190, "columns": [ "Detected by", "Contained by", "Requests see", "Back to normal" ], "rows": [ { "title": "istiod down", "cells": [ [ { "label": "xDS age per proxy", "kind": "platform" } ], [ { "label": "Last-good config held", "kind": "security" } ], [ { "label": "Nothing", "kind": "opportunity", "icon": "fa5_check_circle" } ], [ { "label": "Push resumes", "kind": "app" } ] ] }, { "title": "SPIRE or CA down", "cells": [ [ { "label": "Renewal errors · expiry", "kind": "platform", "icon": "fa5_sync_alt" } ], [ { "label": "24 h SVIDs · 7 d CA", "kind": "security", "icon": "fa5_clock" } ], [ { "label": "Nothing for 12 h", "kind": "opportunity", "icon": "fa5_check_circle" } ], [ { "label": "Emergency issuance", "kind": "app" } ] ] }, { "title": "Bad config push", "cells": [ [ { "label": "Wave gate · NACKs", "kind": "platform" } ], [ { "label": "Wave 0 only", "kind": "security" } ], [ { "label": "Errors in one cluster", "kind": "risk" } ], [ { "label": "Bundle pinned ≤ 60 s", "kind": "app", "icon": "fa5_clock" } ] ] }, { "title": "Trust-bundle skew", "cells": [ [ { "label": "Handshake cause code", "kind": "platform" } ], [ { "label": "Additive bundle · 30 d", "kind": "security", "icon": "fa5_clock" } ], [ { "label": "TLS errors, attributed", "kind": "decision" } ], [ { "label": "Bundle converges", "kind": "app" } ] ] }, { "title": "Proxy OOM", "cells": [ [ { "label": "Container restarts", "kind": "platform" } ], [ { "label": "Pod unready · drained", "kind": "security" } ], [ { "label": "Retried on a peer", "kind": "decision" } ], [ { "label": "Restart refetches", "kind": "app", "icon": "fa5_sync_alt" } ] ] }, { "title": "Injection webhook down", "cells": [ [ { "label": "Admission errors", "kind": "platform" } ], [ { "label": "Strict namespaces refuse", "kind": "security" } ], [ { "label": "Nothing · no new pods", "kind": "opportunity", "icon": "fa5_check_circle" } ], [ { "label": "Webhook back", "kind": "app" } ] ] }, { "title": "Retry storm", "cells": [ [ { "label": "retry_overflow", "kind": "platform" } ], [ { "label": "Budget 20% · limits", "kind": "security" } ], [ { "label": "Fast 503s", "kind": "decision" } ], [ { "label": "Budget refills", "kind": "app" } ] ] }, { "title": "East-west gateway lost", "cells": [ [ { "label": "Remote ejections", "kind": "platform" } ], [ { "label": "Local-only serving", "kind": "security" } ], [ { "label": "Less remote capacity", "kind": "decision" } ], [ { "label": "Gateway returns", "kind": "app" } ] ] }, { "title": "Clock skew", "cells": [ [ { "label": "chrony offset over 60 s", "kind": "platform", "icon": "fa5_clock" } ], [ { "label": "Node tainted", "kind": "security" } ], [ { "label": "Nothing", "kind": "opportunity", "icon": "fa5_check_circle" } ], [ { "label": "Resync · untaint", "kind": "app" } ] ] }, { "title": "Telemetry sink slow", "cells": [ [ { "label": "Collector drop count", "kind": "platform" } ], [ { "label": "Bounded buffers", "kind": "security" } ], [ { "label": "Nothing", "kind": "opportunity", "icon": "fa5_check_circle" } ], [ { "label": "Gap in telemetry", "kind": "app" } ] ] } ], "meta": { "v": "1.0", "owner": "Platform Networking Architecture", "date": "2026-09" } } ]