add srs and sds documents
This commit is contained in:
Othman H. Suseno
169
srs-sds/HCP_SRS_v1.md
Normal file
169
srs-sds/HCP_SRS_v1.md
Normal file
@@ -0,0 +1,169 @@
|
||||
# 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.
|
||||
|
||||
---
|
||||
Reference in New Issue
Block a user