othman.suseno/hephaestus-hpc-api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
Files
main
hephaestus-hpc-api/srs-sds/HCP_SRS_v1.md
Othman H. Suseno eefa9d7035 add srs and sds documents
2025-12-30 13:00:47 +07:00

7.0 KiB
Raw Permalink Blame History

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.