platform/docs
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(arch): align INFRASTRUCTURE + PLATFORM_ARCHITECTURE to cluster split #7

Merged
sharang merged 1 commits from refactor/cluster-split-arch-docs into main 2026-06-30 21:30:49 +00:00
Conversation 0 Commits 1 Files Changed 2
+119 -84
sharang commented 2026-06-30 21:29:58 +00:00
Owner
Copy Link
Copy Source

Summary

Closes the loop on the 2026-06-30 cluster-split decision across the two remaining architecture docs. Companions: platform/docs PR #6 (IMPLEMENTATION_PLAN.md, merged at a8593091) and platform/orca-platform PR #6 (cluster manifest layout, merged at 6be727d4).

Same 4 VMs in the same flavors. Same SLA targets. Same plane vocabulary. What changes:

  • 3 Orca clusters (was 1), 1 cluster per plane
  • vm-data → vm-app-prod; standalone stage VM → vm-app-stage (both inside breakpilot-app cluster)
  • "Data plane" → "App plane" (carries product workloads, not just storage)
  • Identity + Infra co-tenant in breakpilot-edge (single-VM core)
  • Multi-VM rollout gated on legal entity

What changes per doc

INFRASTRUCTURE.md

  • Prelude block summarising the cluster split + legal-entity gate + SLA-unchanged note.
  • §1 VM Inventory: rewritten table adds Cluster column; bullet list updated for vm-app-prod / vm-app-stage + JVM-pin phrasing.
  • §2 Service-to-VM Mapping: cluster name per VM block; KC repurpose noted on keycloak-26; vm-app-stage block explains shared-cluster model + names which cluster each "calls OUT" target lives in.
  • §5 Backup table: "Data Plane" → "App Plane" owner column.
  • §6 Plane ownership boxes: each box now lists its cluster + VMs. Identity box gets JVM-pin escape hatch + CERTifAI-KC repurpose. Control box notes vm-app-stage callers via tenant.kind = "stage". App Plane box (was Data Plane) explains prod+stage cluster-sharing. Infra box notes per-cluster backup buckets.
  • §10 Scenario E header: "Stage VM compromised or buggy" → "vm-app-stage compromised or buggy".
  • Mechanical vm-data → vm-app-prod rename across the rest of the doc.

PLATFORM_ARCHITECTURE.md

  • Prelude block preserving the four-plane vocabulary as the SLA + ownership abstraction.
  • §3 The Four Planes: diagram annotated with cluster + VM per plane; Plane 3 relabeled "APP (was DATA)"; closing paragraph explains the stage/prod cluster-sharing.
  • §6 renamed "Plane 3 — Data" → "Plane 3 — App (was 'Data')" with rationale (carries product workloads, not just storage).
  • §7 Plane 4 — Infra: leading paragraph spells out Identity+Infra co-tenancy, JVM-pin invariant, escape hatch; orchestration bullet updated for per-node ingress + 3 clusters + per-cluster IaC repo.

What does NOT change

  • Plane vocabulary (still 4 planes: Identity, Control, App, Infra)
  • JWT shape, role definitions, IdP brokering, audit log schema
  • RPO / RTO numbers in §7 SLA table
  • Dependency graph / failure scenarios (just renames in headings/text)
  • VM count, flavors, total compute, monthly bill

Stats

INFRASTRUCTURE.md        | 149 ++++++++++++++++++++++++++--------------------
PLATFORM_ARCHITECTURE.md |  54 ++++++++++-------
2 files changed, 119 insertions(+), 84 deletions(-)

🤖 Generated with Claude Code

## Summary Closes the loop on the 2026-06-30 cluster-split decision across the two remaining architecture docs. Companions: [`platform/docs` PR #6](https://gitea.meghsakha.com/platform/docs/pulls/6) (IMPLEMENTATION_PLAN.md, merged at `a8593091`) and [`platform/orca-platform` PR #6](https://gitea.meghsakha.com/platform/orca-platform/pulls/6) (cluster manifest layout, merged at `6be727d4`). **Same 4 VMs in the same flavors. Same SLA targets. Same plane vocabulary.** What changes: - 3 Orca clusters (was 1), 1 cluster per plane - `vm-data` → `vm-app-prod`; standalone `stage` VM → `vm-app-stage` (both inside `breakpilot-app` cluster) - "Data plane" → "App plane" (carries product workloads, not just storage) - Identity + Infra co-tenant in `breakpilot-edge` (single-VM core) - Multi-VM rollout gated on legal entity ## What changes per doc **`INFRASTRUCTURE.md`** - Prelude block summarising the cluster split + legal-entity gate + SLA-unchanged note. - §1 VM Inventory: rewritten table adds Cluster column; bullet list updated for `vm-app-prod` / `vm-app-stage` + JVM-pin phrasing. - §2 Service-to-VM Mapping: cluster name per VM block; KC repurpose noted on `keycloak-26`; `vm-app-stage` block explains shared-cluster model + names which cluster each "calls OUT" target lives in. - §5 Backup table: "Data Plane" → "App Plane" owner column. - §6 Plane ownership boxes: each box now lists its cluster + VMs. Identity box gets JVM-pin escape hatch + CERTifAI-KC repurpose. Control box notes `vm-app-stage` callers via `tenant.kind = "stage"`. App Plane box (was Data Plane) explains prod+stage cluster-sharing. Infra box notes per-cluster backup buckets. - §10 Scenario E header: "Stage VM compromised or buggy" → "`vm-app-stage` compromised or buggy". - Mechanical `vm-data` → `vm-app-prod` rename across the rest of the doc. **`PLATFORM_ARCHITECTURE.md`** - Prelude block preserving the four-plane vocabulary as the SLA + ownership abstraction. - §3 The Four Planes: diagram annotated with cluster + VM per plane; Plane 3 relabeled "APP (was DATA)"; closing paragraph explains the stage/prod cluster-sharing. - §6 renamed "Plane 3 — Data" → "Plane 3 — App (was 'Data')" with rationale (carries product workloads, not just storage). - §7 Plane 4 — Infra: leading paragraph spells out Identity+Infra co-tenancy, JVM-pin invariant, escape hatch; orchestration bullet updated for per-node ingress + 3 clusters + per-cluster IaC repo. ## What does NOT change - Plane vocabulary (still 4 planes: Identity, Control, App, Infra) - JWT shape, role definitions, IdP brokering, audit log schema - RPO / RTO numbers in §7 SLA table - Dependency graph / failure scenarios (just renames in headings/text) - VM count, flavors, total compute, monthly bill ## Stats ``` INFRASTRUCTURE.md | 149 ++++++++++++++++++++++++++-------------------- PLATFORM_ARCHITECTURE.md | 54 ++++++++++------- 2 files changed, 119 insertions(+), 84 deletions(-) ``` 🤖 Generated with [Claude Code](https://claude.com/claude-code)
sharang added 1 commit 2026-06-30 21:29:58 +00:00
docs(arch): align INFRASTRUCTURE + PLATFORM_ARCHITECTURE to cluster split
ci / shared (pull_request) Successful in 12s
Details
8b27ca688b 
Aligns the two remaining architecture docs with the 2026-06-30 cluster-split decision now reflected in IMPLEMENTATION_PLAN.md (PR #6, sha a8593091) and platform/orca-platform PR #6 (sha 6be727d4). Same 4 VMs in the same flavors; what changes is the operational organization (3 clusters, 1 per plane, Identity + Infra co-tenant) and the naming (vm-data → vm-app-prod, stage → vm-app-stage, Data plane → App plane).

INFRASTRUCTURE.md
- Prelude block under title summarises the cluster split + legal-entity gate, and notes SLA targets in §6/§7 are unaffected (they apply at plane level).
- §1 VM Inventory: rewritten box adds a Cluster column; 4 VMs across 3 clusters (vm-edge, vm-control, vm-app-prod, vm-app-stage). Bullet list of "critical isolations preserved" updated for vm-app-prod / vm-app-stage and JVM-pin phrasing.
- §2 Service-to-VM Mapping: each VM block now carries its cluster name in the header; KC repurpose called out on the keycloak-26 line; vm-app-stage block updated to explain it shares a cluster with vm-app-prod, and the "calls OUT" list now names which cluster each prod dependency lives in.
- §5 Backup table: "Data Plane" → "App Plane" in the owner column.
- §6 Plane ownership boxes: each box now names its cluster + VMs. Identity box gets the JVM-pin escape hatch + the CERTifAI-KC repurpose note. Control box notes vm-app-stage callers go through the same tenant-registry under tenant.kind = "stage". App Plane box (was Data Plane) covers both vm-app-prod and vm-app-stage and the cluster-sharing model. Infra box notes per-cluster backup buckets.
- §10 Scenario E header: "Stage VM compromised or buggy" → "vm-app-stage compromised or buggy".
- All mechanical vm-data → vm-app-prod renames across the rest of the doc.

PLATFORM_ARCHITECTURE.md
- Prelude block summarises the cluster split and explicitly preserves the plane vocabulary as the SLA + ownership abstraction.
- §3 The Four Planes: diagram annotated with cluster + VM per plane; Plane 3 relabeled "APP (was DATA)"; closing paragraph explains the stage/prod sharing within the App cluster.
- §6 renamed "Plane 3 — Data" → "Plane 3 — App (was 'Data')" with the rationale (carries product workloads, not just storage).
- §7 Plane 4 — Infra: leading paragraph spells out Identity+Infra co-tenancy on vm-edge, the JVM-pin invariant, and the escape hatch. Orchestration bullet rewritten for per-node ingress + 3 clusters + per-cluster IaC repo.

No changes to product semantics, JWT shape, role definitions, RPO/RTO numbers, or the dependency graph. Only the operational organization + naming.
CODEOWNERS rules requested review from Benjamin_Boenisch 2026-06-30 21:29:58 +00:00
sharang merged commit 1fd03592c0 into main 2026-06-30 21:30:49 +00:00
sharang deleted branch refactor/cluster-split-arch-docs 2026-06-30 21:30:49 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Benjamin_Boenisch
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
Benjamin_Boenisch sharang (Sharang Parnerkar)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: platform/docs#7