feat(iac): scaffold orca-platform layout (M1.1)
Lands manifests/, overlays/, dns/, scripts/, Makefile per M1.1. Bundles yourplatform.com→breakpilot.com rename. vms/ removed (out-of-scope for Orca). Refs: M1.1
This commit was merged in pull request #3.
This commit is contained in:
@@ -1,58 +1,105 @@
|
||||
# orca-platform
|
||||
|
||||
IaC for VMs, Orca manifests, DNS, TLS, backups.
|
||||
IaC for the Breakpilot Platform: per-VM Orca service manifests, per-env overlays, DNS zones, backup/restore tooling, and the `make plan`/`make apply` wrappers.
|
||||
|
||||
> Part of the **Breakpilot Platform**. For the big picture see [`platform/docs`](https://gitea.meghsakha.com/platform/docs):
|
||||
> [Architecture](https://gitea.meghsakha.com/platform/docs/src/branch/main/PLATFORM_ARCHITECTURE.md) ·
|
||||
> [Infrastructure](https://gitea.meghsakha.com/platform/docs/src/branch/main/INFRASTRUCTURE.md) ·
|
||||
> [Product Integration Spec](https://gitea.meghsakha.com/platform/docs/src/branch/main/PRODUCT_INTEGRATION_SPEC.md) ·
|
||||
> [Implementation Plan](https://gitea.meghsakha.com/platform/docs/src/branch/main/IMPLEMENTATION_PLAN.md)
|
||||
|
||||
## What this is
|
||||
|
||||
IaC for VMs, Orca manifests, DNS, TLS, backups. Scaffolded under milestone M1.1. See [`platform/docs`](https://gitea.meghsakha.com/platform/docs) for the full architecture context.
|
||||
The single source of truth for which container runs on which VM in which environment. Every change to prod infrastructure should flow through this repo — never through `orca deploy` from a laptop.
|
||||
|
||||
**Plane:** Infra
|
||||
**Owner:** @sharang
|
||||
**Status:** pre-alpha
|
||||
**Status:** pre-alpha (M1.1 — layout only; real values land per the per-milestone schedule below)
|
||||
**Linked milestone:** [M1.1](https://gitea.meghsakha.com/platform/docs/src/branch/main/IMPLEMENTATION_PLAN.md)
|
||||
|
||||
## Directory layout
|
||||
|
||||
```
|
||||
.
|
||||
├── manifests/ # Base service.toml per VM × service (35 stubs)
|
||||
│ ├── vm-edge/ Identity + Infra plane services
|
||||
│ ├── vm-control/ Control plane services
|
||||
│ ├── vm-data/ Data plane services
|
||||
│ └── stage/ Stage (app plane only)
|
||||
├── overlays/ # Per-env sparse deltas applied on top of manifests/
|
||||
│ ├── dev/overlay.toml no-op; dev runs docker-compose per-service
|
||||
│ ├── stage/overlay.toml include manifests/stage/, image_tag=env-stage
|
||||
│ └── prod/overlay.toml include vm-{edge,control,data}, image_tag=env-prod
|
||||
├── dns/
|
||||
│ └── breakpilot.com.zone.template PowerDNS zone — body lands in M0.3
|
||||
├── cluster.toml.tmpl # Cluster-level config (acme_email, backup, ai); rendered per env
|
||||
├── scripts/
|
||||
│ ├── validate.sh # `make validate`
|
||||
│ ├── plan.sh # `make plan ENV=<env>` → .orca-out/<env>/
|
||||
│ ├── apply.sh # `make apply ENV=<env>` (no-op until M1.2)
|
||||
│ └── restore-drill.sh.template M1.3 placeholder
|
||||
└── Makefile # validate / plan / apply / diff / clean
|
||||
```
|
||||
|
||||
## Run locally
|
||||
|
||||
```bash
|
||||
# prerequisites: see CONTRIBUTING.md for tooling once code lands
|
||||
make dev # starts dependencies + this service on http://localhost:3000
|
||||
make test # unit + integration
|
||||
make e2e # only if this repo ships user-facing flows
|
||||
make validate # check all manifests parse + have required fields
|
||||
make plan ENV=stage # resolve manifests for stage → .orca-out/stage/
|
||||
make plan ENV=prod # same for prod
|
||||
make apply ENV=stage # no-op until M1.2 stands up the Orca controller
|
||||
```
|
||||
|
||||
Local secrets come from `.env.local` (gitignored). Template at `.env.example`.
|
||||
`make validate` runs in CI on every PR.
|
||||
|
||||
## Per-milestone fill-in schedule
|
||||
|
||||
Each stub manifest in `manifests/` carries a header comment naming the milestone that finalises its real values. Summary:
|
||||
|
||||
| Milestone | What it fills in |
|
||||
|---|---|
|
||||
| **M0.3** | `vm-edge/powerdns-auth.toml`, DNS zone body, orca-proxy routes |
|
||||
| **M1.2** | VM provisioning (Terraform/OpenStack in a separate repo); brings `make apply` online |
|
||||
| **M1.3** | Backup cron services + `scripts/restore-drill.sh` |
|
||||
| **M2.1** | `vm-edge/keycloak.toml` + `pg-keycloak.toml` |
|
||||
| **M3.1** | `vm-edge/infisical.toml` + `pg-infisical.toml` + `redis-infisical.toml` |
|
||||
| **M3.2** | `vm-control/stalwart.toml` |
|
||||
| **M4.1** | `vm-control/tenant-registry.toml` + `vm-data/pg-app.toml` |
|
||||
| **M5.1** | `vm-control/customer-portal.toml` + stage equivalents |
|
||||
| **M6.x** | `vm-data/certifai-dashboard.toml`, `mongodb.toml`, `litellm.toml` |
|
||||
| **M7.x** | compliance services on vm-data + stage |
|
||||
| **M8.1** | `vm-control/erpnext.toml`, `mariadb.toml`, `redis-erpnext.toml` |
|
||||
| **M9.1** | `vm-control/frappe-hd.toml` |
|
||||
|
||||
Until the milestone PR lands, the stub still parses and `make validate` stays green — but `apply` will refuse a stub that hasn't replaced its `placeholder` image tag (gate to be added with the first real image).
|
||||
|
||||
## Endpoints / surface
|
||||
|
||||
{{For services: list the top-level routes or commands.
|
||||
For libraries: list the public API entry points.
|
||||
For IaC: list the make targets.}}
|
||||
| Target | What it does |
|
||||
|---|---|
|
||||
| `make validate` | Parse + structural check (no cluster contact) |
|
||||
| `make plan ENV=<env>` | Resolve manifests + overlay → `.orca-out/<env>/` |
|
||||
| `make apply ENV=<env>` | Push to Orca controller at `$ORCA_API_URL` (M1.2 brings this online) |
|
||||
| `make diff ENV=<env>` | Alias for `plan` |
|
||||
| `make clean` | Remove `.orca-out/` |
|
||||
|
||||
## Deployment
|
||||
|
||||
| Env | URL | How |
|
||||
| Env | Apply path | Trigger |
|
||||
|---|---|---|
|
||||
| dev | `http://localhost:3000` | `make dev` |
|
||||
| stage | `https://orca-platform.stage.yourplatform.com` | auto on merge to `main` |
|
||||
| prod | `https://orca-platform.yourplatform.com` | manual: tag `vX.Y.Z` + sign-off |
|
||||
| dev | `docker-compose` in each product repo | dev's machine |
|
||||
| stage | `make apply ENV=stage` against the stage Orca controller | CI on merge to main + image build |
|
||||
| prod | `make apply ENV=prod` against the prod Orca controller | release tag `vX.Y.Z` + sign-off |
|
||||
|
||||
Rollback: `orca rollout undo orca-platform --env={{env}}`.
|
||||
`apply` for prod will be gated by the production-promotion gate (24h stage soak + manual sign-off) per `IMPLEMENTATION_PLAN.md §1.6`. Wiring lands in M1.2.
|
||||
|
||||
## Observability
|
||||
|
||||
- Traces, logs, metrics: [SigNoz](https://signoz.meghsakha.com) — service name `orca-platform`
|
||||
- Audit events: Tenant Registry `/audit` (Retraced-shape schema)
|
||||
- On-call: `oncall@yourplatform.com` · runbook at `platform/docs/runbooks/orca-platform.md`
|
||||
- Traces, logs, metrics: [SigNoz](https://signoz.meghsakha.com) — service name per individual container
|
||||
- On-call: `oncall@breakpilot.com` · runbooks at `platform/docs/runbooks/`
|
||||
|
||||
## Contributing
|
||||
|
||||
See [`CONTRIBUTING.md`](./CONTRIBUTING.md). TL;DR: branch from main, open a PR, 1 review + green CI, squash-merge.
|
||||
See [`CONTRIBUTING.md`](./CONTRIBUTING.md). Every PR touching `manifests/` MUST keep `make validate` green; CI enforces it.
|
||||
|
||||
## License
|
||||
|
||||
|
||||
Reference in New Issue
Block a user