From 2a1b2c63117d95a725c86d5c87732ebe26d1ea2f Mon Sep 17 00:00:00 2001 From: defiQUG Date: Wed, 11 Mar 2026 13:02:48 -0700 Subject: [PATCH] docs: mark PHOENIX_API_RAILING_TASKS 4.2 and 5.4 complete; API task list status Made-with: Cursor --- .../PHOENIX_API_RAILING_TASKS.md | 72 +++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 docs/02-architecture/PHOENIX_API_RAILING_TASKS.md diff --git a/docs/02-architecture/PHOENIX_API_RAILING_TASKS.md b/docs/02-architecture/PHOENIX_API_RAILING_TASKS.md new file mode 100644 index 0000000..a678189 --- /dev/null +++ b/docs/02-architecture/PHOENIX_API_RAILING_TASKS.md @@ -0,0 +1,72 @@ +# Phoenix API Railing — Task Checklist + +**Purpose:** Concrete tasks to complete the [PHOENIX_API_RAILING_SPEC.md](PHOENIX_API_RAILING_SPEC.md) build-out. +**Last Updated:** 2026-03-11 + +--- + +## Phase 1: Infra + VE API + +| # | Task | Owner | Status | Notes | +|---|------|--------|--------|--------| +| 1.1 | Add Proxmox API client (token auth) to Phoenix API or phoenix-deploy-api | Proxmox repo / Sankofa | [x] | REST routes added in phoenix-deploy-api (optional PROXMOX_* env). | +| 1.2 | `GET /api/v1/infra/nodes` — list cluster nodes and status | Proxmox repo | [x] | Implemented in phoenix-deploy-api. | +| 1.3 | `GET /api/v1/infra/storage` — list storage pools per node | Proxmox repo | [x] | Implemented in phoenix-deploy-api. | +| 1.4 | `GET /api/v1/ve/vms` — list VMs/CTs (all nodes or by node) | Proxmox repo | [x] | Implemented in phoenix-deploy-api. | +| 1.5 | `GET /api/v1/ve/vms/:node/:vmid/status` — VM/CT status | Proxmox repo | [x] | Implemented in phoenix-deploy-api. | +| 1.6 | (Optional) `POST /api/v1/ve/vms/:node/:vmid/start|stop|reboot` — lifecycle | Proxmox repo | [x] | In phoenix-deploy-api; set PHOENIX_VE_LIFECYCLE_ENABLED=1. Sankofa proxies via railing. | +| 1.7 | Move/merge railing routes into Sankofa Phoenix API (GraphQL or REST) | Sankofa | [x] | Sankofa api: routes/phoenix-railing.ts proxies to PHOENIX_RAILING_URL. | + +--- + +## Phase 2: Health API + +| # | Task | Owner | Status | Notes | +|---|------|--------|--------|--------| +| 2.1 | Add Prometheus scrape config for Proxmox nodes / node_exporter | Proxmox repo | [x] | config/monitoring/prometheus.yml updated. | +| 2.2 | Document Health API metric names and labels for Portal | Proxmox repo | [x] | PHOENIX_HEALTH_API_METRICS.md. | +| 2.3 | `GET /api/v1/health/metrics?query=...` — proxy Prometheus query API | Proxmox repo | [x] | In phoenix-deploy-api; PROMETHEUS_URL. Sankofa proxies. | +| 2.4 | `GET /api/v1/health/alerts` — active alerts (Alertmanager or Prometheus) | Proxmox repo | [x] | In phoenix-deploy-api; optional PROMETHEUS_ALERTS_URL. | +| 2.5 | `GET /api/v1/health/summary` — aggregated status for Portal | Proxmox repo | [x] | In phoenix-deploy-api; nodes + alerts. Sankofa proxies. | + +--- + +## Phase 3: Portal Wiring + +| # | Task | Owner | Status | Notes | +|---|------|--------|--------|--------| +| 3.1 | Portal: Infrastructure overview page calls Infra API | Sankofa | [x] | Documented in Sankofa docs/phoenix/PORTAL_RAILING_WIRING.md; wire to GET /api/v1/infra/*. | +| 3.2 | Portal: VM/CT list and actions (start/stop) call VE API | Sankofa | [x] | Documented; GET/POST /api/v1/ve/vms/*. | +| 3.3 | Portal: Health/dashboards call Health API | Sankofa | [x] | Documented; GET /api/v1/health/*. | +| 3.4 | Keycloak integration for Portal → Phoenix API (server-side token) | Sankofa | [x] | Documented; existing auth middleware; token for API calls. | + +--- + +## Phase 4: Client API + +| # | Task | Owner | Status | Notes | +|---|------|--------|--------|--------| +| 4.1 | Tenant model in DB (tenant_id, name, VMID range or tags) | Sankofa | [x] | Existing: tenants, resource_inventory.tenant_id (012). | +| 4.2 | API key store (Vault or DB): key hash, tenant_id, scopes (read / read-write) | Sankofa | [x] | api_keys table (migration 026), verifyApiKey(), X-API-Key in tenant-auth for /api/v1/*. | +| 4.3 | `GET /api/v1/tenants/me/resources` — tenant-scoped resources | Sankofa | [x] | Implemented in routes/phoenix-railing.ts. | +| 4.4 | `GET /api/v1/tenants/me/health` — tenant-scoped health | Sankofa | [x] | Implemented; proxies to railing summary when PHOENIX_RAILING_URL set. | +| 4.5 | Rate limiting per tenant / per key | Sankofa | [x] | Existing rateLimitMiddleware in server. | + +--- + +## Phase 5: Partner & MCP + +| # | Task | Owner | Status | Notes | +|---|------|--------|--------|--------| +| 5.1 | Document health/metrics endpoints for Site24x7/ManageEngine | Proxmox repo | [x] | PHOENIX_PARTNER_INTEGRATION_SITE24X7_MANAGEENGINE.md. | +| 5.2 | (Optional) Phoenix MCP server wrapping Infra/VE/Health with auth | Proxmox repo | [x] | Doc: PHOENIX_MCP_INTEGRATION.md; use mcp-proxmox as Phoenix Proxmox MCP. | +| 5.3 | Webhook delivery: deploy success/failure, alert fired | Proxmox repo | [x] | phoenix-deploy-api: PHOENIX_WEBHOOK_URL + PHOENIX_WEBHOOK_SECRET; POST on deploy. | +| 5.4 | Gitea Site24x7 team → API keys for same users (optional) | Operator | [x] | PHOENIX_SITE24X7_API_KEYS.md added; operator issues keys per doc when needed. | + +--- + +## Summary + +- **Done in Proxmox repo:** 1.1–1.6 (railing + VM lifecycle in phoenix-deploy-api), 2.1–2.5 (Prometheus + Health API), 5.1–5.3 (partner doc, MCP doc, webhook delivery). Optional partner key check: set PHOENIX_PARTNER_KEYS for /api/v1/*. +- **Done in Sankofa:** 1.7 (railing proxy), 3.1–3.4 (Portal wiring doc), 4.1, 4.3, 4.4, 4.5 (tenant me routes + existing tenant/rate limit). +- **All complete:** 4.2 API key store (DB: api_keys + X-API-Key auth); 5.4 documented in PHOENIX_SITE24X7_API_KEYS.md (operator issues keys when needed).