From 43d842311f058ca3d7279e5cab379f2631fc7871 Mon Sep 17 00:00:00 2001
From: "Othman H. Suseno" <othman.suseno@gmail.com>
Date: Tue, 30 Dec 2025 13:11:26 +0700
Subject: [PATCH] add readme file

---
 README.md | 274 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 274 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..37d386a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,274 @@
+# 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.