add readme file
This commit is contained in:
Othman H. Suseno
274
README.md
Normal file
274
README.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user