d-bis/proxmox
4
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: mark PHOENIX_API_RAILING_TASKS 4.2 and 5.4 complete; API task list status

Browse Source 
Made-with: Cursor
This commit is contained in:
defiQUG
2026-03-11 13:02:48 -07:00
parent 1580e19029
commit 2a1b2c6311
1 changed files with 72 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
docs/02-architecture/PHOENIX_API_RAILING_TASKS.md Normal file
View File

@@ -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).