hephaestus-hpc-api/README.md

Hypervisor Control Plane (HCP)

Provider-Agnostic Compute API Gateway

Hypervisor Control Plane (HCP) adalah compute control-plane service yang menyediakan API provider-agnostic untuk manajemen lifecycle Virtual Machine (VM) di berbagai hypervisor, termasuk:

• Proxmox VE
• VMware vSphere / ESXi
• KVM / QEMU (libvirt)
• Microsoft Hyper-V

HCP berfungsi sebagai jembatan antara Central API Gateway / Management Console dan infrastructure hypervisor, dengan pendekatan desired state + asynchronous job orchestration.

---

🎯 Tujuan Utama

• Menyediakan API compute yang konsisten lintas hypervisor
• Mendukung multi-tenant & multi-project isolation
• Menyediakan enterprise-grade control plane
  • async job
  • idempotency
  • retry & reconciliation
  • auditability
• Menjadi fondasi jangka panjang untuk ekspansi fitur compute tanpa rewrite

---

🧠 Konsep Arsitektur

HCP bukan sekadar reverse-proxy ke API hypervisor.

HCP adalah stateful control plane yang:

• Menyimpan desired state VM
• Mengelola lifecycle via job system
• Mengabstraksi perbedaan hypervisor melalui provider adapter
• Menghasilkan audit & metering events

Control Plane vs Data Plane

• Control Plane: HCP API + Job orchestration + State
• Data Plane: Hypervisor & provider-specific execution (via adapter/agent)

---

🧩 Komponen Utama

1. HCP API Service

• Northbound REST API (tenant & ops)
• AuthN/AuthZ enforcement (JWT + RBAC)
• Validasi request & idempotency
• Persist state VM & job
• Publish job ke queue

2. HCP Worker

• Consume job dari queue
• Jalankan workflow state machine
• Panggil provider adapter
• Update state VM & job
• Emit audit & metering events

3. Provider Adapter Layer

• Implementasi driver per hypervisor
• Mapping:
  • generic VM spec → API provider
  • error provider → error taxonomy HCP
• Tidak mengekspos detail provider ke API northbound

4. Datastore & Queue

• PostgreSQL: VM state, job state, catalog, placement
• Queue/Stream: NATS JetStream / RabbitMQ
• Audit/Event Store: append-only

---

🔌 Provider-Agnostic Design

Northbound API (Stable)

API HCP tidak pernah mengekspos:

• node / host hypervisor
• vmid / moid / UUID provider
• datastore / resource pool

Tenant hanya berinteraksi dengan:

• image
• flavor
• network attachment
• placement (zone/location)
• metadata/tags

Southbound Providers (Pluggable)

Setiap hypervisor diintegrasikan melalui provider adapter dengan kontrak yang konsisten.

---

🔁 Job & Workflow Model

Semua operasi yang berdampak ke infra dijalankan sebagai async job.

Contoh:

• create VM
• start / stop / reboot
• delete VM
• request console

Pola Standar

1. API request diterima
2. Desired state disimpan (PENDING)
3. Job dibuat & dipublish
4. Worker mengeksekusi via provider
5. State diperbarui (ACTIVE / ERROR)
6. Audit & event di-emit

API akan mengembalikan:

202 Accepted
{
  "resource_id": "...",
  "job_id": "..."
}

---

🌐 API Namespace

Disarankan dipanggil via Central API Gateway, namun HCP tetap melakukan guardrail sendiri.

Tenant

/api/hcp/tenant/v1/...

Operations / Provider

/api/hcp/ops/v1/...

Common (read-only)

/api/hcp/common/v1/...

---

🧪 Contoh Operasi Utama

Create VM

POST /api/hcp/tenant/v1/projects/{projectId}/vms

Response:

202 Accepted
{
  "vm_id": "...",
  "job_id": "..."
}

Get Job Status

GET /api/hcp/tenant/v1/jobs/{jobId}

Request Console

POST /api/hcp/tenant/v1/projects/{projectId}/vms/{vmId}:console

Response:

{
  "type": "vnc | spice | web | rdp",
  "url": "...",
  "expires_at": "..."
}

---

🧠 Capability Negotiation

Setiap provider/cluster memiliki capability flags, contoh:

• supports_cloud_init
• supports_snapshot
• supports_live_migration
• supports_console_vnc
• supports_gpu_passthrough

Jika fitur tidak tersedia, API mengembalikan:

409 FEATURE_NOT_SUPPORTED

---

🔐 Security Model

• JWT-based authentication
• RBAC enforcement di level API
• Strict tenant vs ops boundary
• Provider credential terenkripsi
• Console session short-lived
• Semua aksi tercatat di audit log

---

📊 Observability

HCP menyediakan:

• Metrics: request rate, latency, job success/failure
• Structured logs: trace_id, job_id, vm_id
• Distributed tracing (OpenTelemetry-ready)

---

🗂️ Repository Structure (Suggested)

hcp/
├── cmd/
│   ├── api/
│   └── worker/
├── internal/
│   ├── api/
│   ├── auth/
│   ├── jobs/
│   ├── providers/
│   │   ├── proxmox/
│   │   ├── vsphere/
│   │   ├── libvirt/
│   │   └── hyperv/
│   ├── reconcile/
│   └── audit/
├── pkg/
│   └── models/
├── docs/
│   ├── HCP_SRS_v1.md
│   └── HCP_SDS_v1.md
└── README.md

---

📄 Documentation

• SRS: docs/HCP_SRS_v1.md
• SDS: docs/HCP_SDS_v1.md

Dokumen tersebut adalah authoritative reference untuk desain dan implementasi HCP.

---

🚀 Roadmap Singkat

V1

• Proxmox provider
• VM lifecycle
• Async job & audit
• Console abstraction

Post-V1

• vSphere provider
• Libvirt/KVM provider
• Hyper-V provider
• Snapshot & migration
• Policy-based placement

---

🧭 Philosophy

HCP is not built to support one hypervisor.
HCP is built so that hypervisors can come and go.