# Hypervisor Control Plane (HCP)
## Software Requirements Specification (SRS)
**Version: 1.0 (V1 – Enterprise Foundation)**

---

## 1. Ringkasan

Dokumen ini mendefinisikan kebutuhan perangkat lunak (Software Requirements Specification) untuk **Hypervisor Control Plane (HCP)**, yaitu layanan control-plane yang menyediakan API *provider-agnostic* untuk manajemen lifecycle Virtual Machine (VM) dan resource compute terkait.

HCP dirancang untuk mendukung banyak backend hypervisor/provider, termasuk namun tidak terbatas pada:
- Proxmox VE
- VMware vSphere/ESXi
- KVM/QEMU (via libvirt atau API lain)
- Hyper-V

HCP menjadi komponen inti yang diakses oleh **Central API Gateway** dan/atau layanan lain dalam platform, dengan pola **desired state + asynchronous jobs** untuk operasi yang berdampak pada infrastruktur.

---

## 2. Tujuan & Prinsip Desain

### 2.1 Tujuan
- Menyediakan API compute yang konsisten untuk berbagai hypervisor.
- Mendukung multi-tenant dan multi-project dengan isolasi akses yang ketat.
- Menyediakan mekanisme provisioning yang robust: idempotent, dapat di-retry, dapat di-reconcile.
- Menjadi fondasi enterprise untuk ekspansi fitur (snapshot, migration, GPU, dsb) melalui *capability negotiation*.

### 2.2 Prinsip
- **Provider-agnostic Northbound API**: API tidak mengekspos detail spesifik provider (mis. `vmid`, `moid`, `datastore`, `node`).
- **Plugin/Driver model**: integrasi provider melalui adapter dengan kontrak yang jelas.
- **Async by default** untuk operasi yang memerlukan waktu (create, delete, start/stop, attach).
- **Strict authorization boundary**: walaupun ada central gateway, HCP tetap melakukan verifikasi scope/claims.
- **Auditability**: semua aksi control-plane dapat diaudit.

---

## 3. Stakeholders & Peran

### 3.1 Tenant-side (melalui Central Gateway)
- Project Owner / Admin
- Operator
- Viewer

### 3.2 Provider/Ops-side
- Cloud Operator
- Infrastructure Admin
- Security/Audit Admin
- Break-glass Admin

---

## 4. Ruang Lingkup (V1)

### 4.1 In Scope (MUST)
- VM lifecycle: create, start, stop, reboot, delete
- VM query: list/detail, status, addresses, metadata/tags
- Catalog: images & flavors (read-only untuk tenant, writable untuk ops sesuai kebijakan platform)
- Console access: request sesi console short-lived (VNC/SPICE/WebConsole/RDP via abstraction)
- Job system integration: setiap operasi berdampak infra menghasilkan `job_id`
- Capability model: expose dukungan fitur per provider dan/atau per cluster/location
- Placement abstraction: zone/location/cluster (tanpa expose host/node spesifik)
- Audit event emission (minimal: request/started/succeeded/failed)
- Error taxonomy yang konsisten lintas provider

### 4.2 Out of Scope (V1)
- Auto-scaling dan elasticity
- Full billing engine (HCP hanya emit metering events; perhitungan final di service lain)
- Advanced SDN dan orchestration network di luar attach NIC dasar
- Backup orchestration end-to-end (bisa disiapkan hook/extension)
- Live migration/DRS otomatis (opsional post-V1)
- Multi-region replication control-plane

---

## 5. Kebutuhan Fungsional

### 5.1 API & Operasi Compute
- HCP SHALL menyediakan endpoint untuk membuat VM dari image/template yang disetujui.
- HCP SHALL menyediakan operasi: start, stop, reboot, delete VM.
- HCP SHALL menyediakan endpoint list/detail VM dalam scope project.
- HCP SHALL menjaga state VM dan job state di datastore yang persisten.

### 5.2 Asynchronous Jobs
- Semua operasi yang memodifikasi infra (create/start/stop/reboot/delete) SHALL berjalan asynchronous.
- HCP SHALL mengembalikan `202 Accepted` dengan `resource_id` dan `job_id`.
- HCP SHALL menyediakan endpoint untuk query status job dan error detail.

### 5.3 Multi-Provider Support
- HCP SHALL mendukung integrasi beberapa provider melalui adapter/driver.
- HCP SHALL mendukung selection provider berdasarkan placement (zone/location/cluster) dan kebijakan ops.
- HCP SHALL menyimpan referensi resource provider secara internal (provider_ref) tanpa diekspos dalam northbound API.

### 5.4 Capability Negotiation
- HCP SHALL mendefinisikan model kemampuan (*capabilities*) untuk fitur compute.
- HCP SHALL mengembalikan error yang konsisten saat fitur tidak didukung oleh provider (mis. `FEATURE_NOT_SUPPORTED`).

### 5.5 Console Access Abstraction
- HCP SHALL menyediakan endpoint untuk meminta sesi console VM.
- Sesi console SHALL bersifat short-lived (memiliki expiry) dan tidak membocorkan credential provider jangka panjang.
- HCP SHOULD mendukung beberapa jenis console (VNC, SPICE, WebConsole, RDP) melalui tipe abstraksi.

### 5.6 Placement & Location Abstraction
- HCP SHALL mendukung konsep `zone/location` dan `compute_cluster/pool` untuk placement.
- Tenant API SHOULD memilih placement secara generik (mis. zone) tanpa melihat host/node.
- Ops API SHALL mengelola mapping zone → provider cluster/pool.

### 5.7 Security & Authorization
- HCP SHALL memverifikasi token/JWT untuk setiap request.
- HCP SHALL menegakkan RBAC pada level endpoint dan resource scope:
  - tenant scope tidak dapat mengakses ops scope
  - user hanya dapat mengakses resource dalam project yang diikat role binding
- HCP SHALL mendukung idempotency key untuk operasi create agar aman terhadap retry.

### 5.8 Audit Logging
- HCP SHALL menghasilkan audit event untuk:
  - request received
  - job started
  - job succeeded
  - job failed
- Audit event minimal memuat: actor, action, target, timestamp, result, trace_id.

### 5.9 Error Taxonomy
- HCP SHALL mengembalikan error yang seragam lintas provider, minimal:
  - INVALID_REQUEST
  - NOT_FOUND
  - UNAUTHORIZED / FORBIDDEN
  - QUOTA_EXCEEDED
  - FEATURE_NOT_SUPPORTED
  - PROVIDER_UNAVAILABLE
  - PROVIDER_TIMEOUT
  - CONFLICT
  - INTERNAL_ERROR

---

## 6. Kebutuhan Non-Fungsional

### 6.1 Reliability
- HCP SHALL tahan terhadap restart komponen tanpa kehilangan state.
- Job processing SHALL bersifat at-least-once dengan idempotency pada handler.

### 6.2 Availability
- API service SHALL stateless dan dapat di-scale horizontal.
- State (VM/job) SHALL tersimpan pada datastore persisten.

### 6.3 Performance
- API read (list/detail) SHOULD responsif dan dapat memakai caching read-model bila diperlukan.
- Operasi write menggunakan async jobs untuk memisahkan latency provider dari latency API.

### 6.4 Security
- Secrets provider credential SHALL disimpan terenkripsi (Vault-ready / envelope encryption).
- Console sessions SHALL menggunakan token sementara (short-lived).
- Input validation SHALL ketat untuk mencegah injection/abuse.

### 6.5 Observability
- HCP SHALL mengekspos metrics (request rate, latency, job success/fail, provider errors).
- HCP SHALL menggunakan trace_id/correlation_id untuk request end-to-end.

---

## 7. Acceptance Criteria (V1)
- Tenant dapat membuat VM dari image yang tersedia dan memonitor status via job.
- Tenant dapat melakukan start/stop/reboot/delete VM dengan job tracking.
- Ops dapat mendaftarkan provider/cluster dan mengatur mapping zone.
- Sistem dapat berjalan dengan minimal 1 provider driver (Proxmox) tanpa mengunci desain untuk provider lain.
- Error dan audit event konsisten, dapat dipakai untuk troubleshooting.

---