docs(plans): rename idea-3-esxi-support → idea-4 (fix name collision)
idea-3- prefix was shared with idea-3-powershell-removal.md; rename the ESXi idea to idea-4-esxi-support.md and update the ideas-overview link. Pure rename, content unchanged. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Simone
@@ -0,0 +1,180 @@
|
||||
# Fase D — Supporto ESXi per le Build VM (futuro)
|
||||
|
||||
> **Stato**: **piano differito**, da rivalutare dopo che Fase A
|
||||
> ([rewrite Python](idea-1-python-rewrite.md)), Fase B
|
||||
> ([host Linux](idea-2-linux-host.md)) e Fase C
|
||||
> ([eliminazione PowerShell](idea-3-powershell-removal.md)) sono stabili
|
||||
> in produzione. Vedi [overview](ideas-overview.md).
|
||||
>
|
||||
> Questo documento esiste per:
|
||||
> 1. Garantire che il design di Fase A abbia gli hook corretti
|
||||
> (astrazione `VmBackend`).
|
||||
> 2. Avere un piano pronto se/quando si decide di scalare oltre i limiti
|
||||
> dell'host singolo Workstation Pro.
|
||||
|
||||
---
|
||||
|
||||
## 1. Quando attivare Fase C
|
||||
|
||||
Fase C ha senso **solo se** si verifica almeno uno di:
|
||||
|
||||
- Saturazione della concorrenza locale (>4 job paralleli regolarmente)
|
||||
- Necessità di disaccoppiare hardware CI control plane (ufficio) dal hardware
|
||||
build (rack/datacenter)
|
||||
- Disponibilità di hardware ESXi + licenza vSphere Essentials o superiore
|
||||
- Richiesta di QoS / resource pool per i job CI vs altri carichi
|
||||
|
||||
Se nessuno è vero a 6-12 mesi dal completamento Fase B, **non aprire Fase C**:
|
||||
Workstation Pro su Linux copre il caso d'uso e l'overhead operativo di un
|
||||
secondo backend non è giustificato.
|
||||
|
||||
---
|
||||
|
||||
## 2. Architettura prevista
|
||||
|
||||
```
|
||||
┌──────────────┐ ┌─────────────────────────────┐
|
||||
│ Gitea │ │ ESXi host(s) │
|
||||
│ act_runner │ │ ├─ Template Windows (snap BaseClean) │
|
||||
│ (Linux Mint) │ │ ├─ Template Linux (snap BaseClean-Linux) │
|
||||
│ │ │ └─ Datastore: ci-builds │
|
||||
└──────┬───────┘ └──────────▲──────────────────┘
|
||||
│ │ vSphere API (443)
|
||||
▼ │
|
||||
┌──────────────────┐ │
|
||||
│ ci_orchestrator │───────────┘
|
||||
│ (Python, Linux) │
|
||||
│ ↳ EsxiBackend │
|
||||
└─────┬────────────┘
|
||||
│ WinRM/SSH
|
||||
▼
|
||||
Build VM efimera su ESXi
|
||||
```
|
||||
|
||||
L'host CI Linux (Fase B) continua a esistere come control plane.
|
||||
Le build VM girano su ESXi remoto. Il transport WinRM/SSH al guest non
|
||||
cambia.
|
||||
|
||||
---
|
||||
|
||||
## 3. Implementazione: nuovo backend pyVmomi
|
||||
|
||||
Sfruttando l'astrazione `VmBackend` introdotta in Fase A:
|
||||
|
||||
```python
|
||||
# src/ci_orchestrator/backends/esxi.py
|
||||
class EsxiBackend(VmBackend):
|
||||
def __init__(self, host: str, user: str, password: str, datastore: str, folder: str): ...
|
||||
def clone_linked(self, template: str, snapshot: str, name: str) -> VmHandle: ...
|
||||
def start(self, vm: VmHandle) -> None: ...
|
||||
def stop(self, vm: VmHandle, hard: bool = True) -> None: ...
|
||||
def delete(self, vm: VmHandle) -> None: ...
|
||||
def get_ip(self, vm: VmHandle, timeout: float) -> str: ...
|
||||
```
|
||||
|
||||
Selezione backend via env / config:
|
||||
|
||||
```toml
|
||||
[backend]
|
||||
type = "esxi" # oppure "workstation"
|
||||
|
||||
[backend.esxi]
|
||||
host = "esxi.lab.local"
|
||||
user = "ci-runner@vsphere.local"
|
||||
datastore = "ci-builds"
|
||||
folder = "ci"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Mappa operazioni Workstation → ESXi
|
||||
|
||||
| Operazione | Workstation (oggi) | ESXi (Fase C, pyVmomi) |
|
||||
| ----------------------------- | --------------------------------------------- | ----------------------------------------------------------------------- |
|
||||
| Linked clone | `vmrun clone ... linked -snapshot=BaseClean` | `vim.VirtualMachineCloneSpec(linkedClone=True, snapshot=ref)` |
|
||||
| Start VM | `vmrun start <vmx>` | `VirtualMachine.PowerOn()` (Task) |
|
||||
| Stop VM | `vmrun stop <vmx> hard` | `VirtualMachine.PowerOff()` (Task) |
|
||||
| Delete VM | `vmrun deleteVM <vmx>` | `VirtualMachine.Destroy_Task()` |
|
||||
| List snapshots | `vmrun listSnapshots` | `VirtualMachine.snapshot.rootSnapshotList` |
|
||||
| Get guest IP | `vmrun getGuestIPAddress` | `VirtualMachine.guest.ipAddress` (richiede VMware Tools nei guest) |
|
||||
| Test running | `vmrun list` | `VirtualMachine.runtime.powerState == 'poweredOn'` |
|
||||
|
||||
---
|
||||
|
||||
## 5. Setup ESXi richiesto (Step C0)
|
||||
|
||||
Prerequisiti hardware/licenza da verificare PRIMA di pianificare:
|
||||
|
||||
- **Licenza**: ESXi free **non basta** (le API write sono bloccate dal 2020).
|
||||
Serve almeno **vSphere Essentials** o licenza valutativa rinnovabile.
|
||||
- **Hardware**: server con CPU che supporti la versione ESXi target,
|
||||
RAM ≥64 GB, NVMe locale per datastore.
|
||||
- **Network**: portgroup dedicato per le build VM, DHCP raggiungibile.
|
||||
- **Account**: user dedicato con ruolo custom (datastore, folder, snapshot,
|
||||
power, network — minimo set richiesto da `clone_linked`/`destroy`).
|
||||
|
||||
---
|
||||
|
||||
## 6. Sequenza implementativa
|
||||
|
||||
### C1 — Validazione ambiente
|
||||
- Setup hardware ESXi + licenza
|
||||
- Account vSphere dedicato
|
||||
- Test manuale clone+start+stop via UI vSphere
|
||||
- Misurazione tempi di clone (baseline)
|
||||
|
||||
### C2 — Implementazione `EsxiBackend`
|
||||
- `pip install pyvmomi` aggiunto al `pyproject.toml`
|
||||
- `src/ci_orchestrator/backends/esxi.py` implementato
|
||||
- Test pytest con `pyvmomi` mock + un test di integrazione
|
||||
opzionale che gira solo se env `CI_TEST_ESXI_HOST` è settata
|
||||
|
||||
### C3 — Migrazione template
|
||||
- Export OVF dei template Workstation: `ovftool ... template.vmx template.ovf`
|
||||
- Import su datastore ESXi: `ovftool template.ovf vi://...`
|
||||
- Verifica WinRM/SSH raggiungibili dal control plane verso le VM ESXi
|
||||
- Snapshot `BaseClean` / `BaseClean-Linux` ricreati lato ESXi
|
||||
|
||||
### C4 — Canary deploy
|
||||
- Workflow di test dedicato con label `windows-build:esxi` o
|
||||
config override `backend=esxi`
|
||||
- Eseguito quotidianamente per ≥1 settimana
|
||||
- Confronto metriche (tempo totale, success rate) vs Workstation backend
|
||||
|
||||
### C5 — Rollout selettivo
|
||||
- Workflow di produzione spostati uno a uno su backend ESXi
|
||||
- Monitoring tempi via `Measure-CIBenchmark` equivalente Python
|
||||
- Workstation backend resta disponibile come fallback (basta cambiare config)
|
||||
|
||||
### C6 — Adattamenti tooling secondari
|
||||
- `Cleanup-OrphanedBuildVMs` esteso per query ESXi folder-scoped
|
||||
- `Watch-DiskSpace` esteso a query datastore via API
|
||||
- `Backup-CITemplate` sostituito da snapshot ESXi nativi o `ovftool` schedulato
|
||||
|
||||
---
|
||||
|
||||
## 7. Rischi specifici Fase C
|
||||
|
||||
| Rischio | Severità | Mitigazione |
|
||||
| -------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------- |
|
||||
| Licenza ESXi free blocca API write (`CloneVM_Task` non autorizzata) | **Critica** | Verificare licenza in C1 prima di qualsiasi sviluppo. Procurare vSphere Essentials. |
|
||||
| Linked clone su ESXi standalone (no vCenter) ha gap funzionali | Alta | PoC manuale in C1; se gap rilevante, valutare full clone vs linked. |
|
||||
| Tempo clone+poweron+IP > Workstation locale per latenza rete + overhead vSphere | Media | Misurare in C1; possibile mitigazione: pool di VM "warm" pre-clonate. |
|
||||
| VMware Tools nel guest non sempre rapide a riportare IP via API | Bassa | Stesso problema oggi (`AGENTS.md` errore #10). Fallback: parse DHCP lease su ESXi via API. |
|
||||
| Concorrenza: race condition su naming VM o folder | Media | Lock per JobId lato orchestrator; suffisso UUID nel nome VM. |
|
||||
| Cleanup VM orfane più costoso (API call per ogni VM in folder) | Bassa | Riscrivere cleanup come query folder-scoped, non scan globale. |
|
||||
| Single point of failure: ESXi giù = tutta la CI giù | Media | Documentare procedura fallback su backend Workstation locale (basta cambio config). |
|
||||
| Errore #11 `AGENTS.md` (machine-id identico clone Linux) si ripropone | Bassa | Stessa fix lato template, già documentata. |
|
||||
|
||||
---
|
||||
|
||||
## 8. Definizione di "fatto" (Fase C)
|
||||
|
||||
- [ ] Hardware ESXi + licenza Essentials operativi
|
||||
- [ ] `EsxiBackend` implementato, testato (unit + integration test)
|
||||
- [ ] Template Windows e Linux importati e funzionanti su ESXi con snapshot
|
||||
- [ ] Almeno 1 workflow di produzione in canary su backend ESXi per ≥1 settimana
|
||||
senza regressioni
|
||||
- [ ] Documentazione (`docs/HOST-SETUP.md`, `docs/ARCHITECTURE.md`,
|
||||
`AGENTS.md`) aggiornata con istruzioni multi-backend
|
||||
- [ ] Procedura di rollback su backend Workstation testata e documentata
|
||||
Reference in New Issue
Block a user