feat(iac): scaffold orca-platform layout (M1.1) #3

Merged

sharang merged 3 commits from feat/m1.1-iac-layout into main 2026-05-18 20:28:41 +00:00

Conversation 0 Commits 3 Files Changed 53

+1023 -35

sharang commented 2026-05-18 20:02:12 +00:00

Owner

Copy Link

Copy Source

What

• Lands the directory tree for platform/orca-platform per INFRASTRUCTURE.md §2 and IMPLEMENTATION_PLAN.md M1.1.
• 35 stub manifests (one per VM × service), 4 VM specs, 3 env overlays, DNS zone placeholder, cluster.toml.tmpl, plan/apply/validate scripts, Makefile.
• Swaps the M0.2 placeholder orca validate (which doesn't exist as a subcommand) for make validate — a Python TOML parser plus structural sanity check.

Why

M1.1 acceptance: make plan ENV=stage produces a no-op diff once applied; orca validate runs in CI; PRs that break a manifest fail. Without this, no later milestone (M2.1 Keycloak, M4.1 tenant-registry, M5.1 portal, …) has anywhere to land its real config.

Linked milestone: M1.1

How

• Manifests are stubs. Each carries a header pointing at the milestone that finalises its image, env, and ports. Today's images are mostly registry.yourplatform.com/<service>:placeholder — make validate accepts them, but make apply will refuse a placeholder once that gate lands in M1.2.
• TOML structural check catches a real bug: top-level service keys (depends_on, extra_ports, cmd, mounts) MUST come before any [service.xxx] header, or TOML scopes them under the wrong sub-table. The validator rejects mis-nesting explicitly.
• Overlays are placeholder-shaped: dev is a no-op, stage selects only manifests/stage/, prod selects vm-edge + vm-control + vm-data. The merge today is a passthrough — real per-env deltas (image tags resolved from registry, replica bumps) will land alongside the first milestone that needs them.
• VM specs (vms/*.toml) name flavor, public IP, private CIDR, and firewall ingress per VM. Consumed by M1.2 provisioner (Terraform against SysEleven OpenStack); Orca itself ignores this dir.
• Resource caps baked into every stub per INFRASTRUCTURE.md §6 co-tenant notes — Keycloak gets 2Gi (1.5G JVM heap), ERPNext 6Gi, MariaDB 3Gi, portal 1Gi, pg-app 3Gi, etc.
• orca validate doesn't exist. Inspected the Orca CLI (orca --help); only deploy, no validate / plan / dry-run. make validate does the equivalent locally via TOML parse + schema check.

Test plan

• Unit tests added/updated — n/a (no executable code; the validator IS the test)
• Integration tests added/updated — n/a
• Playwright e2e added/updated — n/a
• Manual smoke locally:
  • make validate ✅ — checks 42 files (35 manifests + 3 overlays + 4 VMs)
  • make plan ENV=stage ✅ — writes 11 resolved manifests to .orca-out/stage/
  • make plan ENV=prod ✅ — writes 24 resolved manifests
  • make apply ENV=stage ✅ — correctly no-ops with ORCA_API_URL not set
  • make plan ENV=bogus ✅ — rejects unknown env
• Regression test added — the validator catches mis-nested depends_on (a real bug I hit in a first-pass bash heredoc generator)

Risk

Blast radius: repo-local. No services touched. No cluster contact.

What could break:

• Schema drift between these stubs and the real Orca ServiceConfig struct as Orca evolves. Mitigation: make validate only enforces fields Orca currently requires; if Orca adds a mandatory field later, validator gets a new rule.
• Someone fills in a stub with the wrong placement.node and make validate doesn't catch it because dir-vs-placement is now an explicit rule — but they could put the file in the wrong directory. Mitigation: low risk; reviewer + CODEOWNERS catches it.

Rollback plan: revert the PR. Until M1.2 ships, this repo is descriptive only — nothing reads from it in production.

Checklist

• Docs updated (README rewritten; CHANGELOG entry)
• Audit events — n/a
• Secrets via Infisical — referenced as ${secrets.NAME}, never inlined (Keycloak DB URI excepted per §8 rule 3)
• Migration — n/a
• Tenant scoping — n/a
• OpenAPI spec — n/a
• featureFlags.evaluate() — n/a
• CHANGELOG entry under "Unreleased"

## What - Lands the directory tree for `platform/orca-platform` per INFRASTRUCTURE.md §2 and IMPLEMENTATION_PLAN.md M1.1. - 35 stub manifests (one per VM × service), 4 VM specs, 3 env overlays, DNS zone placeholder, cluster.toml.tmpl, plan/apply/validate scripts, Makefile. - Swaps the M0.2 placeholder `orca validate` (which doesn't exist as a subcommand) for `make validate` — a Python TOML parser plus structural sanity check. ## Why M1.1 acceptance: `make plan ENV=stage` produces a no-op diff once applied; `orca validate` runs in CI; PRs that break a manifest fail. Without this, no later milestone (M2.1 Keycloak, M4.1 tenant-registry, M5.1 portal, …) has anywhere to land its real config. Linked milestone: **M1.1** ## How - **Manifests are stubs.** Each carries a header pointing at the milestone that finalises its image, env, and ports. Today's images are mostly `registry.yourplatform.com/<service>:placeholder` — `make validate` accepts them, but `make apply` will refuse a placeholder once that gate lands in M1.2. - **TOML structural check** catches a real bug: top-level service keys (`depends_on`, `extra_ports`, `cmd`, `mounts`) MUST come before any `[service.xxx]` header, or TOML scopes them under the wrong sub-table. The validator rejects mis-nesting explicitly. - **Overlays** are placeholder-shaped: `dev` is a no-op, `stage` selects only `manifests/stage/`, `prod` selects `vm-edge` + `vm-control` + `vm-data`. The merge today is a passthrough — real per-env deltas (image tags resolved from registry, replica bumps) will land alongside the first milestone that needs them. - **VM specs** (`vms/*.toml`) name flavor, public IP, private CIDR, and firewall ingress per VM. Consumed by M1.2 provisioner (Terraform against SysEleven OpenStack); Orca itself ignores this dir. - **Resource caps** baked into every stub per INFRASTRUCTURE.md §6 co-tenant notes — Keycloak gets 2Gi (1.5G JVM heap), ERPNext 6Gi, MariaDB 3Gi, portal 1Gi, pg-app 3Gi, etc. - **`orca validate` doesn't exist.** Inspected the Orca CLI (`orca --help`); only `deploy`, no validate / plan / dry-run. `make validate` does the equivalent locally via TOML parse + schema check. ## Test plan - [x] Unit tests added/updated — n/a (no executable code; the validator IS the test) - [x] Integration tests added/updated — n/a - [x] Playwright e2e added/updated — n/a - [x] Manual smoke locally: - `make validate` ✅ — checks 42 files (35 manifests + 3 overlays + 4 VMs) - `make plan ENV=stage` ✅ — writes 11 resolved manifests to `.orca-out/stage/` - `make plan ENV=prod` ✅ — writes 24 resolved manifests - `make apply ENV=stage` ✅ — correctly no-ops with `ORCA_API_URL not set` - `make plan ENV=bogus` ✅ — rejects unknown env - [x] Regression test added — the validator catches mis-nested `depends_on` (a real bug I hit in a first-pass bash heredoc generator) ## Risk **Blast radius:** repo-local. No services touched. No cluster contact. **What could break:** - Schema drift between these stubs and the real Orca `ServiceConfig` struct as Orca evolves. Mitigation: `make validate` only enforces fields Orca currently requires; if Orca adds a mandatory field later, validator gets a new rule. - Someone fills in a stub with the wrong placement.node and `make validate` doesn't catch it because dir-vs-placement is now an explicit rule — but they could put the file in the wrong directory. Mitigation: low risk; reviewer + CODEOWNERS catches it. **Rollback plan:** revert the PR. Until M1.2 ships, this repo is descriptive only — nothing reads from it in production. ## Checklist - [x] Docs updated (README rewritten; CHANGELOG entry) - [ ] Audit events — n/a - [x] Secrets via Infisical — referenced as `${secrets.NAME}`, never inlined (Keycloak DB URI excepted per §8 rule 3) - [ ] Migration — n/a - [ ] Tenant scoping — n/a - [ ] OpenAPI spec — n/a - [ ] featureFlags.evaluate() — n/a - [x] CHANGELOG entry under "Unreleased"

sharang added 1 commit 2026-05-18 20:02:13 +00:00

feat(iac): scaffold orca-platform layout (M1.1) ... 6cd1a1546c

Lands the per-VM × per-service manifest tree, per-env overlays, VM specs
for SysEleven provisioning, DNS zone placeholder, plan/apply/validate
scripts, and a Makefile.

Structure (per INFRASTRUCTURE.md §2 + IMPLEMENTATION_PLAN.md M1.1):
- manifests/{vm-edge,vm-control,vm-data,stage}/<service>.toml — 35 stubs
- overlays/{dev,stage,prod}/overlay.toml — env-selection rules
- vms/{vm-edge,vm-control,vm-data,stage}.toml — OpenStack flavor/IP/firewall
- dns/yourplatform.com.zone.template — PowerDNS zone (body lands in M0.3)
- cluster.toml.tmpl — cluster-level config rendered per env
- scripts/validate.sh — TOML parse + structural sanity
- scripts/plan.sh — merge manifests + overlay → .orca-out/<env>/
- scripts/apply.sh — push to Orca controller (no-op until M1.2)
- Makefile — validate / plan / apply / diff / clean

Each manifest header names the milestone that finalises its real values;
images today are 'placeholder' for services that need their own repo to
exist first. make validate stays green; apply gates on ORCA_API_URL.

CI workflow swapped from the broken 'orca validate' to 'make validate',
which calls a Python TOML parser plus structural checks (placement.node
matches vm dir, resources.memory present, no mis-nested keys).

Refs: M1.1

CODEOWNERS rules requested review from Benjamin_Boenisch 2026-05-18 20:02:13 +00:00

sharang added 1 commit 2026-05-18 20:07:44 +00:00

chore(domain): yourplatform.com → breakpilot.com ... 1a728428cf

Apply the platform-domain decision (2026-05-18) to every manifest,
overlay, DNS template, README, and script in this repo.

Refs: M1.1

sharang added 1 commit 2026-05-18 20:13:35 +00:00

fix(iac): drop vms/ — Orca does not provision VMs ... 3d7b67060e

Re-read the Orca spec: 'orca nodes' lists already-joined hosts and
'orca join' attaches an existing node to a cluster, but Orca does not
provision the VMs themselves. VM provisioning (SysEleven OpenStack
via Terraform) is a separate concern and will land in a dedicated repo
under the M1.2 milestone, not in orca-platform.

Removes vms/{vm-edge,vm-control,vm-data,stage}.toml + vms/README.md.
Updates README directory tree and milestone fill-in table to reflect
that M1.2's VM specs live elsewhere. validate.sh stops checking vms/.

Refs: M1.1

sharang merged commit 8e37f65b8e into main 2026-05-18 20:28:41 +00:00

sharang deleted branch feat/m1.1-iac-layout 2026-05-18 20:28:41 +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

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: platform/orca-platform#3