diff --git a/plans/idea-1-python-rewrite.md b/plans/idea-1-python-rewrite.md new file mode 100644 index 0000000..da75469 --- /dev/null +++ b/plans/idea-1-python-rewrite.md @@ -0,0 +1,177 @@ +# Idea 1 — Conversione del sistema in Python + +> Stato: **proposta / valutazione**. Documento esplorativo, non piano esecutivo. +> Baseline: ~13.000 righe PowerShell 5.1 (41 file `.ps1` + 2 `.psm1`), 2 script bash, +> 5 workflow Gitea Actions, orchestratore `Invoke-CIJob.ps1` + moduli +> `_Common.psm1` / `_Transport.psm1`. + +--- + +## 1. Obiettivo + +Riscrivere l'intero sistema CI/CD locale (host orchestrator + script di +provisioning template) in **Python 3.11+**, mantenendo invariati: + +- runtime act_runner + Gitea (consuma comandi via shell, agnostico al linguaggio) +- template VM (Windows con WinRM, Linux con SSH) +- formato artifact e layout `F:\CI\` +- compatibilità con i workflow YAML esistenti (`gitea/workflows/*.yml`) + +Il punto di ingresso `Invoke-CIJob.ps1` viene sostituito da `invoke_ci_job.py` +(o `python -m ci_job ...`), invocato da `gitea/actions/local-ci-build/action.yml`. + +--- + +## 2. Fattibilità + +### 2.1 Mappa di traduzione dei componenti + +| Componente PowerShell | Equivalente Python | Note | +| ----------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------- | +| `Invoke-Vmrun` (wrapper vmrun.exe) | `subprocess.run([vmrun, '-T', 'ws', ...])` | Identico, gestione `returncode` esplicita. | +| `New-PSSession` + `Invoke-Command` (WinRM) | `pypsrp` (`pypsrp.client.Client`) o `pywinrm` | **Rischio basso**. `pypsrp` supporta HTTPS self-signed e PSRP nativo. | +| `Copy-Item -ToSession / -FromSession` | `pypsrp.client.Client.copy()` / `fetch()` | Throughput simile a WinRM nativo. | +| `_Transport.psm1` (ssh.exe / scp.exe) | `paramiko` o `fabric`, oppure subprocess di `ssh`/`scp` | `paramiko` elimina dipendenza da OpenSSH client. | +| Credential Manager (`BuildVMGuest`) | `keyring` (backend `Windows Credential Manager`) | API cross-platform; stesso store sotto Windows. | +| `Get-StoredCredential` | `keyring.get_credential(target, None)` | Modulo PyPI `keyring`. | +| `Pester` test | `pytest` + `pytest-mock` | Riscrittura test 1:1 fattibile. | +| `PSScriptAnalyzer` | `ruff` + `mypy` + `pylint` | Profilo lint più rigoroso (tipi statici). | +| Logging `Write-Host` | `logging` (stdout handler) | act_runner cattura stdout normalmente. | +| `ConvertTo-Json` per stato | `json` stdlib | | +| Workflow YAML | **Invariati** | Cambia solo lo `shell:` / il comando invocato. | +| Script `.sh` in `gitea/burnin-dummy/` | Invariati | Girano nel guest Linux. | + +### 2.2 Aree senza equivalenti dirette / da progettare + +1. **`Set-StrictMode -Version Latest`** → in Python si ottiene con `mypy --strict` + + `from __future__ import annotations`. Cambia il modello mentale (non è + runtime ma static check). +2. **`ShouldProcess` / `-WhatIf`** → richiede un flag `--dry-run` esplicito + implementato manualmente in ogni comando state-changing. +3. **PSSessionOption con `-SkipCACheck`** → `pypsrp` accetta + `cert_validation=False` direttamente. +4. **Pipeline objects** (es. `Get-ChildItem | Where-Object …`) → diventano + list comprehension / generator. Refactor logico, non meccanico. +5. **PowerShell auto-loading di moduli** → in Python serve `pyproject.toml` + + package layout (`src/ci_orchestrator/...`) e installazione (`pip install -e .`). + +### 2.3 Dipendenze runtime aggiuntive sull'host + +- Python 3.11+ (Microsoft Store o python.org installer) +- pacchetti: `pypsrp[credssp]`, `paramiko`, `keyring`, `pyyaml`, `click` + (CLI), `rich` (output colorato), `pytest`, `ruff`, `mypy` +- Tutti installabili in un `venv` isolato (`F:\CI\python\venv\`) → + zero impatto sul Python di sistema. + +### 2.4 Compatibilità con act_runner + +act_runner invoca uno step `run:` con `shell: powershell` oggi. Cambia in: + +```yaml +- shell: cmd + run: F:\CI\python\venv\Scripts\python.exe -m ci_orchestrator job ... +``` + +oppure si lascia un wrapper `.ps1` minimale che chiama Python (più graduale). + +### 2.5 Rischi specifici + +| Rischio | Severità | Mitigazione | +| -------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------- | +| `pypsrp` ha edge case con prompt UAC / loopback HTTPS | Media | PoC isolato su `Wait-VMReady` equivalente prima di committare alla rewrite. | +| `keyring` sotto SYSTEM account (act_runner service) può non vedere credenziali utente | Alta | Già un problema oggi con Credential Manager; stessa mitigazione (DPAPI machine scope o vault file). | +| Perdita di know-how dei `#11`, `#12` di `AGENTS.md` durante refactor | Media | Riportare ogni "errore frequente" come **test pytest** prima di portare il codice. | +| Doppio mantenimento durante la migrazione | Alta | Migrazione "big bang" per branch sconsigliata; usare strategia 2.6. | + +### 2.6 Strategia di migrazione consigliata + +**Strangler fig**, in 4 fasi: + +1. Estrarre `_Common.psm1` + `_Transport.psm1` in `ci_orchestrator/transport.py` + e `ci_orchestrator/vmrun.py`; mantenere gli script `.ps1` esistenti che + chiamano Python via `python -c` per le primitive critiche. Validazione: + workflow `lint.yml` e `self-test.yml` continuano a passare. +2. Portare gli script "foglia" senza state condiviso: `Wait-VMReady`, + `Remove-BuildVM`, `Cleanup-OrphanedBuildVMs`, `Watch-DiskSpace`, + `Watch-RunnerHealth`. Ognuno con i suoi test pytest. +3. Portare `New-BuildVM` + `Get-BuildArtifacts` + `Invoke-RemoteBuild`. +4. Portare `Invoke-CIJob` (orchestratore) per ultimo, switchando il workflow + YAML solo a quel punto. + +Gli script di **template setup** (`template/Prepare-*.ps1`, +`Deploy-*.ps1`, `Install-CIToolchain-*.ps1`) restano in PowerShell perché +girano una tantum e sono fortemente legati a Windows +(autounattend.xml, registry, sysprep). Convertirli ha ROI basso. + +--- + +## 3. Stima volumi / sforzo (relativa) + +| Fase | Indicatori dimensione | Complessità | +| ----------------------------------------------------- | ------------------------------------ | ----------- | +| F1 — Moduli `_Common` + `_Transport` | ~540 righe PS → ~600 righe Py + test | Media | +| F2 — Script foglia (6 file) | ~1.500 righe PS | Bassa | +| F3 — Build pipeline (3 file core) | ~2.000 righe PS | Media | +| F4 — Orchestrator + switch workflow | ~800 righe PS | Alta | +| F5 — Riscrittura test Pester → pytest | 4 file test esistenti + nuovi | Media | +| F6 — Documentazione (AGENTS.md, README, docs/) | 24 file md | Bassa | + +Le fasi F1→F4 devono essere sequenziali; F5 si fa in parallelo a ciascuna fase +(test della fase prima del merge). F6 si fa a fine F4. + +--- + +## 4. Pro / Contro + +### Pro + +- **Cross-platform di base**: rimuove il vincolo PS 5.1 (vedi Idea 2). +- Ecosistema test/typing/lint più ricco (`pytest`, `mypy`, `ruff`). +- Type hints + dataclass riducono la classe di bug `Set-StrictMode` non cattura. +- Libreria `pypsrp` è attivamente manutenuta; `paramiko` standard de facto. +- Più sviluppatori conoscono Python che PS 5.1. + +### Contro + +- **Costo migrazione alto** rispetto al beneficio se il sistema resta + Windows-only e funziona già (oggi è in production-ready). +- Doppio mantenimento per ~tutta la durata della migrazione. +- `pypsrp` su Windows Server target richiede tuning (CredSSP, message + encryption) — possibili sorprese non visibili oggi con WinRM nativo PS. +- Gli `Install-CIToolchain-WinBuild2025.ps1` restano comunque in PS + (girano nel guest Windows) → la codebase non sarà mai 100% Python. +- Documentazione (`AGENTS.md`, `docs/BEST-PRACTICES.md`) tutta da riscrivere. + +--- + +## 5. Decision checklist + +Procedere **solo se** almeno 2 dei seguenti sono veri: + +- [ ] È prevista l'Idea 2 (host Linux) o l'Idea 3 (ESXi) entro 6 mesi. +- [ ] Si vogliono assumere/coinvolgere sviluppatori non-Windows. +- [ ] Si pianifica integrazione con tool Python (es. Ansible per + provisioning, librerie pyVmomi per ESXi). +- [ ] Il debito tecnico di PS 5.1 (no async, no ternari, dipendenza da + Credential Manager) sta bloccando feature concrete. + +Se nessuna è vera, **non vale la pena**: investire piuttosto in test e +osservabilità sul codice PS attuale. + +--- + +## 6. Sinergia con Idee 2 e 3 + +- **Idea 2 (host Linux)**: la riscrittura Python è **prerequisito naturale**. + PS 7 su Linux funziona ma `vmrun` non gira nativamente lì (Workstation è + Windows-only; serve VMware Player Linux o `ovftool`). Python rende il + porting più semplice se anche il transport cambia (es. `libvirt` come + alternativa). +- **Idea 3 (ESXi)**: `pyVmomi` (SDK ufficiale VMware per ESXi/vCenter) è + **solo Python**. Equivalenti PowerShell sono PowerCLI (richiede + PS 7+ moduli VMware.PowerCLI installabili anche su PS 5.1, ma con limiti). + Andare su Python apre la strada al supporto ESXi in modo idiomatico. + +**Raccomandazione**: se si vuole davvero perseguire Idee 2 o 3, la riscrittura +Python diventa quasi obbligata. Se invece il sistema resta su Windows + VMware +Workstation, la conversione è **opzionale** e non urgente. diff --git a/plans/idea-2-linux-host.md b/plans/idea-2-linux-host.md new file mode 100644 index 0000000..3262ffe --- /dev/null +++ b/plans/idea-2-linux-host.md @@ -0,0 +1,211 @@ +# Idea 2 — Adattare il sistema a girare su host Linux (Mint) + +> Stato: **proposta / valutazione**. +> Target host: Linux Mint (kernel ≥ 6.x, su hardware compatibile con +> virtualizzazione hardware; KVM/Intel VT-x presenti su i9-10900X). + +--- + +## 1. Obiettivo + +Spostare l'host CI/CD da Windows 11 + VMware Workstation Pro a Linux Mint, +mantenendo: + +- act_runner / Gitea (identici, già cross-platform — `act_runner` ha build Linux) +- workflow YAML invariati +- template VM Windows e Linux operative come build target +- artifact layout su filesystem locale + +Cambia: hypervisor, transport layer di management, percorsi, eseguibili +amministrativi, gestione credenziali. + +--- + +## 2. Fattibilità + +### 2.1 Bivio strategico: quale hypervisor su Linux? + +| Opzione | Pro | Contro | Verdetto | +| ----------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------- | +| **A. VMware Workstation Linux** | Comando `vmrun` identico; portabilità VMX dei template. | Licenza commerciale (anche per Linux); supporto guest tools invariato. EOL annunciato da Broadcom — futuro incerto. | Possibile ma rischioso a medio termine. | +| **B. KVM + libvirt + QEMU** | Open source, supportato nativamente da Linux Mint; tooling solido (`virsh`, `virt-install`, `virt-clone`); cloud-init friendly. | Conversione VMDK→qcow2 obbligatoria (`qemu-img convert`); riconfigurare guest Windows (driver virtio); riscrivere completamente lo strato vmrun. | **Raccomandata** per il lungo periodo. | +| C. VirtualBox | Cross-platform, simile a Workstation. | Performance inferiore a KVM; snapshot meno robusti; meno usato in CI. | Sconsigliata. | +| D. Proxmox VE | UI di management, API REST. | È un OS dedicato, non gira "sopra" Linux Mint. | Vedi Idea 3 (è simile a ESXi). | + +**Le sezioni seguenti assumono Opzione B (KVM)** salvo dove indicato. + +### 2.2 Mappa di adattamento (assumendo Idea 1 già completata o in corso) + +| Componente attuale | Equivalente Linux + KVM | +| ------------------------------------------------------ | ------------------------------------------------------------------ | +| `vmrun clone -snapshot=BaseClean ... linked` | `virsh snapshot-create` + `virt-clone --reflink` (qcow2 CoW) | +| `vmrun start ` | `virsh start ` | +| `vmrun stop hard` | `virsh destroy ` | +| `vmrun deleteVM` | `virsh undefine --remove-all-storage` | +| File `.vmx` | Domain XML libvirt (definizione VM) | +| `WinBuild2025.vmdk` | `winbuild2025.qcow2` (base) + overlay qcow2 per ogni clone | +| `F:\CI\BuildVMs\` | `/var/lib/ci/build-vms/` (o pool storage libvirt dedicato) | +| `F:\CI\Artifacts\` | `/var/lib/ci/artifacts/` | +| `F:\CI\Templates\` | `/var/lib/ci/templates/` | +| `F:\CI\keys\ci_linux` | `/etc/ci/keys/ci_linux` (perms `600`, owner `ci-runner`) | +| Credential Manager `BuildVMGuest` | `secret-tool` (libsecret/GNOME Keyring) o file `.env` cifrato (`age`/`sops`) | +| WinRM HTTPS verso guest Windows | Identico (lato guest non cambia nulla) | +| SSH verso guest Linux | Identico | +| act_runner come Windows Service | `systemd unit` `act-runner.service` | +| Task Scheduler (`Register-CIScheduledTasks.ps1`) | `systemd timers` (`*.timer` + `*.service`) | +| PowerShell 5.1 | PowerShell 7 (`pwsh`) o **Python** (vedi Idea 1) | +| `vmnet8` (NAT 192.168.79.0/24) | `default` libvirt network (NAT 192.168.122.0/24) o bridge dedicato | + +### 2.3 Conversione dei template VM (lavoro una-tantum) + +#### Template Windows (WinBuild2025/2022) +1. Spegnere VM su Workstation, esportare `.vmx` + `.vmdk`. +2. Convertire: `qemu-img convert -O qcow2 WinBuild2025.vmdk winbuild2025.qcow2`. +3. Iniettare driver **virtio** (network, storage) nel guest Windows **prima** + della conversione (offline injection via `virt-v2v` oppure boot manuale + con ISO `virtio-win.iso` e installazione driver). +4. Importare con `virt-install --import --disk path=winbuild2025.qcow2,bus=virtio --os-variant=win2k25`. +5. Validare WinRM accessibile da host Linux (`Test-WSMan` equivalente con + `pwsh` o `pypsrp`). +6. Spegnere, creare snapshot di base: `virsh snapshot-create-as winbuild2025-template BaseClean`. + +#### Template Linux (LinuxBuild2404) +1. Esportare e convertire VMDK → qcow2 (più semplice, driver virtio già presenti). +2. Importare con `virt-install --import ...`. +3. Già usa SSH + chiave: nessun cambio lato transport. +4. Snapshot `BaseClean-Linux`. + +#### Linked clone su KVM +- `qemu-img create -f qcow2 -b /var/lib/ci/templates/winbuild2025.qcow2 -F qcow2 /var/lib/ci/build-vms/.qcow2` +- Crea overlay CoW (equivalente di linked clone Workstation). +- Performance migliore se il filesystem è XFS con `reflink=1` o BTRFS. + +### 2.4 Permessi e utenti + +- Utente di servizio `ci-runner` (uid dedicato), membro di `libvirt` e `kvm`. +- act_runner gira come `ci-runner` via systemd (`User=ci-runner`). +- Sudoers limitati per operazioni privilegiate (es. `virsh net-start`). +- Storage pool libvirt con ownership corretta (`/var/lib/ci`). + +### 2.5 Networking + +- Bridge `br0` se serve raggiungibilità diretta dei guest dal host Gitea + remoto, oppure NAT (default libvirt) + DHCP statico via libvirt + dnsmasq se Gitea sta sulla stessa LAN. +- Replicare la convenzione "1 IP per job concorrente" già in uso. + +### 2.6 Rischi specifici + +| Rischio | Severità | Mitigazione | +| --------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------- | +| Guest Windows non parte dopo conversione (driver virtio mancanti) | Alta | Iniezione driver prima della conversione, oppure boot in safe mode + install. | +| Performance I/O dei clone qcow2 inferiore a VMware linked clone in alcuni scenari | Media | Filesystem CoW (BTRFS / XFS reflink) + cache=none + aio=native su disco. | +| `vmrun` workflow / convenzioni codificate in `AGENTS.md` errori #9 #10 non più applicabili | Bassa | Documentare nuovo set di "errori frequenti KVM" (es. virtio drivers, SELinux). | +| Linux Mint kernel non sempre allineato al supporto VMware Workstation se si sceglie A | Media | Solo se si va opzione A: vincolarsi a kernel LTS testato. | +| Burn-in concorrente saturazione I/O diversa su qcow2 vs VMDK | Media | Ripetere `Test-CapacityBurnIn` su nuovo host prima del go-live. | +| WinRM HTTPS da host Linux verso guest Windows ha cipher mismatch occasionali | Bassa | Usare `pypsrp` con `auth='credssp'` o `auth='negotiate'`; testato in lab. | +| Conversione VMDK + sysprep del Windows template può rompere attivazione / licenza | Media | Validare licenza Windows e tooling unattended con la nuova HW signature. | + +### 2.7 Vincoli che spariscono / che restano + +**Spariscono**: +- Limitazioni PS 5.1 (`AGENTS.md` tabella PS7+) — su Linux si usa `pwsh` 7 o Python. +- Necessità di Credential Manager con bug noti sotto SYSTEM account. +- `autounattend.xml` solo per refresh del template Windows (operazione rara). +- Errori #9 (snapshot con `.vmem`) e #10 (`getGuestIPAddress` bloccante) + sono specifici di vmrun — non più applicabili. + +**Restano / si trasformano**: +- Necessità di gestire snapshot in stato "powered off". +- IP collision per machine-id identico nei clone Linux (#11): identico + comportamento sotto KVM con dnsmasq DHCP. +- Errore #12 (stderr nativa + `$ErrorActionPreference='Stop'`) sparisce + se si esce da PowerShell, altrimenti resta. + +--- + +## 3. Stima volumi / sforzo (relativa) + +| Area | Indicatori dimensione | Complessità | +| ------------------------------------------------------------------- | ------------------------------- | ----------- | +| Conversione template Windows → qcow2 + virtio | 2 VM (2025, 2022) | Alta | +| Conversione template Linux → qcow2 | 1 VM | Bassa | +| Riscrittura `_Common.psm1` → wrapper `virsh`/`libvirt` | ~300 righe | Media | +| Riscrittura `_Transport.psm1` (WinRM) | ~240 righe | Bassa | +| Adattamento `New-BuildVM` / `Remove-BuildVM` / `Invoke-CIJob` | ~2.000 righe | Media | +| Riscrittura `Setup-Host.ps1` → script bash + systemd | ~400 righe | Media | +| `Register-CIScheduledTasks.ps1` → systemd `.timer` units | 6 task → 6 timer | Bassa | +| Adattamento workflow YAML (path Windows → POSIX) | 5 file | Bassa | +| Documentazione (HOST-SETUP.md, AGENTS.md, BEST-PRACTICES.md) | ~5 file md | Media | +| Validazione e2e: smoke + section 3.3 + capacity burn-in | piano test esistente | Alta | + +Sequenza obbligata: +1. Decidere hypervisor (A vs B). +2. Convertire template Linux (più semplice, fa da PoC). +3. Convertire un template Windows e validare WinRM da Linux. +4. Riscrittura tooling (idealmente in Python — vedi Idea 1). +5. Migrazione storage `F:\CI\` → `/var/lib/ci/`. +6. Switch act_runner. + +--- + +## 4. Pro / Contro + +### Pro + +- Elimina i vincoli PS 5.1 (tabella in `AGENTS.md`). +- Stack open source completo (no licenze VMware Workstation se si va KVM). +- `systemd` + `journalctl` per service management e log centralizzati. +- Filesystem CoW (BTRFS/XFS reflink) → clone disco ~istantanei, equivalente + o migliore di linked clone Workstation. +- Linux Mint ha buon supporto desktop per debug interattivo del runner. +- Disaccoppia dal futuro incerto di VMware Workstation (Broadcom). + +### Contro + +- Migrazione "tutta o niente" del host: non si può avere CI/CD attivo su + Win e su Linux in parallelo se il template/storage layout è condiviso. +- Conversione template Windows è il passaggio più rischioso (virtio, + attivazione, eventuale re-provisioning toolchain). +- Curva di apprendimento libvirt / virsh / domain XML. +- Tutta la documentazione e `AGENTS.md` da riscrivere. +- Test plan completo da rieseguire (smoke, e2e, burn-in). + +--- + +## 5. Sinergia con altre idee + +- **Idea 1 (Python)**: forte prerequisito. PS 7 su Linux è possibile, ma + Python è più idiomatico per `libvirt` (binding `libvirt-python`) e + per riusare `paramiko` / `pypsrp` cross-platform. +- **Idea 3 (ESXi)**: parzialmente alternativa. Se si va su ESXi, l'host CI + resta comunque una macchina di management (può essere Linux Mint con + Python + `pyVmomi`, oppure restare Windows). Il "dove gira l'host" e + "dove girano le VM" si disaccoppiano. + +--- + +## 6. Decision checklist + +Procedere **solo se** almeno 2 dei seguenti sono veri: + +- [ ] Il vincolo Windows host è un problema concreto (licenze, policy aziendale, preferenza team). +- [ ] Si è disposti a investire una settimana piena di test di conversione VMDK→qcow2. +- [ ] Si è già completata (o si è disposti a fare in parallelo) l'Idea 1. +- [ ] Si vuole rimuovere la dipendenza commerciale da VMware Workstation. + +--- + +## 7. Path alternativo "minimo": dual-host + +Se non si vuole migrare ma solo "supportare anche Linux Mint", una via meno +invasiva: +- Mantenere host Windows come primario. +- Aggiungere un **secondo runner** Linux Mint che usa solo `linux-build` jobs + (KVM o Workstation Linux), label `linux-build:host-mint`. +- Workflow esistenti restano invariati; nuovi workflow possono selezionare il + runner secondario per test sperimentali. +- Stima: ~1/3 dello sforzo della migrazione completa, ma codebase divisa + in due (PS Win + qualche script Linux ad hoc) — debito tecnico crescente. + +Questa via ha senso solo come **PoC temporaneo** prima di una migrazione completa. diff --git a/plans/idea-3-esxi-support.md b/plans/idea-3-esxi-support.md new file mode 100644 index 0000000..2d6b818 --- /dev/null +++ b/plans/idea-3-esxi-support.md @@ -0,0 +1,204 @@ +# Idea 3 — Supporto ESXi per le Build VM + +> Stato: **proposta / valutazione**. +> Modello: host CI (Windows o Linux) continua a fare orchestrazione ma le +> build VM girano su un **server ESXi remoto** invece che in VMware +> Workstation locale. + +--- + +## 1. Obiettivo + +Permettere a `Invoke-CIJob` di usare un host **ESXi** (o cluster vCenter) +come backend di virtualizzazione, mantenendo: + +- workflow YAML invariati (eventualmente con nuovo label `windows-build:esxi`) +- transport WinRM/SSH verso i guest invariato +- formato artifact e flusso `clone → start → wait → build → collect → destroy` identico + +Cambia: come si fa clone/start/stop/delete della VM, dove vivono i dischi, +come si determina l'IP del guest, come si autenticano i comandi di management. + +--- + +## 2. Fattibilità + +### 2.1 API di management ESXi + +| Opzione | Pro | Contro | Verdetto | +| ---------------------------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------- | +| **A. pyVmomi** (Python SDK ufficiale) | API completa (cloni, snapshot, power ops, GuestOps); supportata; va anche contro singolo host ESXi senza vCenter. | Solo Python. Curva di apprendimento (managed object reference, task tracking). | **Raccomandata se si va Python (Idea 1).** | +| **B. PowerCLI** (`VMware.PowerCLI` PSGallery) | Idiomatica per PowerShell; comandi `New-VM`, `Get-Snapshot`, ecc. molto leggibili. | Modulo grosso (~2 GB), Windows-friendly ma installazione richiede `Install-Module`. Performance avvio cmdlet non sempre rapida. | Buona se si **resta in PowerShell**. | +| C. `ovftool` + REST API ESXi (vSphere API REST) | Standard moderno; copre la maggior parte delle operazioni in vSphere 7+. | API REST single-host ha gap rispetto a SOAP/pyVmomi; complicata gestione task. | Sconsigliata come strato unico. | +| D. `govc` (VMware/govmomi CLI) | Binario Go portabile, scriptabile da shell qualsiasi. | Meno espressivo per logiche complesse (loop, error handling); diventa un "second-class" tooling. | Buona per script ad-hoc, non per orchestratore. | + +Le due strade realistiche sono **A (pyVmomi)** o **B (PowerCLI)**, in funzione +dell'esito dell'Idea 1. + +### 2.2 Mappa di adattamento + +| Operazione | Workstation oggi | ESXi domani (pyVmomi) | +| ----------------------------------------- | --------------------------------------------- | ---------------------------------------------------------------------- | +| Linked clone | `vmrun clone ... linked -snapshot=BaseClean` | `vim.VirtualMachineCloneSpec` con `linkedClone=True` e snapshot ref | +| Start VM | `vmrun start ` | `VirtualMachine.PowerOn()` (Task) | +| Stop VM | `vmrun stop hard` | `VirtualMachine.PowerOff()` (Task) | +| Delete VM | `vmrun deleteVM ` | `VirtualMachine.Destroy_Task()` | +| List snapshots | `vmrun listSnapshots` | `VirtualMachine.snapshot.rootSnapshotList` (tree) | +| Get guest IP | `vmrun getGuestIPAddress` (errore #10) | `VirtualMachine.guest.ipAddress` (richiede VMware Tools attivi) | +| Test running | `vmrun list` + path search | `VirtualMachine.runtime.powerState == 'poweredOn'` | +| Trasferimento file pre-WinRM/SSH | non usato | GuestOperationsManager (FileManager + ProcessManager) — opzionale, oggi non serve | + +Il transport `_Transport.psm1` (SSH) e le sessioni WinRM **non cambiano**: +una volta che la VM è up con IP raggiungibile, l'host CI parla direttamente +col guest come oggi. + +### 2.3 Architettura proposta + +``` + ┌──────────────┐ ┌─────────────────────────────┐ + │ Gitea │ │ ESXi host(s) │ + │ act_runner │ │ ├─ Template Windows (snap BaseClean) │ + │ │ │ ├─ Template Linux (snap BaseClean-Linux) │ + └──────┬───────┘ │ └─ Datastore: ci-builds │ + │ └──────────▲──────────────────┘ + │ orchestrate │ vSphere API (443) + ▼ │ + ┌──────────────────┐ │ + │ CI orchestrator │──────────────┘ + │ (host Win o Lin)│ + └─────┬────────────┘ + │ WinRM/SSH (network L3 ammessa) + ▼ + Build VM efimera su ESXi +``` + +L'host CI continua a esistere come "control plane". Può essere lo stesso +hardware di oggi (Windows 11) oppure migrato a Linux (Idea 2). Le build VM +non girano più localmente. + +### 2.4 Nuove configurazioni richieste + +- **ESXi host** raggiungibile da host CI sulla 443/TCP. +- Account di servizio ESXi (`ci-runner@vsphere.local` o `local user` con + ruolo custom): permessi minimi su datastore, folder, snapshot, power ops. +- Datastore dedicato (SSD/NVMe) per cloni e template; quota / monitoring. +- Resource pool dedicato `ci-builds` con CPU/memory limits. +- Portgroup di rete con DHCP raggiungibile (o assegnazione IP statica via + cloud-init / Sysprep). +- Snapshot dei template **identico** al setup attuale (`BaseClean` / + `BaseClean-Linux`) — convertire VMX→VMX-su-ESXi via OVF (`ovftool`). + +### 2.5 Rischi specifici + +| Rischio | Severità | Mitigazione | +| --------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------- | +| Linked clone su ESXi standalone (senza vCenter) ha limitazioni rispetto a Workstation | Alta | Validare in PoC: alcune versioni ESXi free non supportano `CloneVM_Task` via API senza license. | +| Licenza ESXi: la versione free **non espone le API write** (solo read-only) — bug noto vSphere | **Critica** | Serve almeno **vSphere Essentials** o licenza valutativa. Verificare PRIMA di pianificare. | +| Throughput linked clone su NFS/iSCSI datastore inferiore a SSD locale Workstation | Media | Datastore VMFS su NVMe locale o vSAN; benchmark con `Test-CapacityBurnIn`. | +| Tempo medio "clone → IP raggiungibile" più alto rispetto a Workstation locale | Media | Misurare con `Measure-CIBenchmark`; ottimizzare warm pool template (`Backup-CITemplate` non più utile, sostituire con template VM in folder dedicata). | +| Gestione concorrente cloni: race su nome VM o snapshot revert | Media | Lock per `JobId` lato orchestrator; oppure naming con suffisso UUID. | +| Determinazione IP: VMware Tools deve essere attivo e DHCP funzionante | Bassa | Già un prerequisito attuale (`Wait-VMReady`). Documentare in `AGENTS.md` nuova versione. | +| Errore #11 (machine-id identico sui clone Linux) si ripropone identico su ESXi | Bassa | Stessa fix: reset machine-id pre-snapshot. Documentato. | +| Sicurezza: credenziali vCenter/ESXi nello stesso store delle credenziali guest | Media | Target Credential Manager separato (`ESXiServiceAccount`) o keyring + ACL. | +| Cleanup VM orfane più costoso (richiede chiamata API per ogni VM in folder) | Bassa | Riscrivere `Cleanup-OrphanedBuildVMs` per usare folder-scoped query. | + +### 2.6 Sequenza di implementazione consigliata + +1. **PoC manuale**: clonare manualmente un template su ESXi via UI/PowerCLI, + avviare, fare WinRM da host CI. Misurare tempi. +2. **PoC scriptato**: una versione minimale di `New-BuildVM-ESXi.ps1` (o + `new_build_vm_esxi.py`) che fa clone+start. Validare race conditions. +3. **Astrazione `IVmBackend`**: introdurre nei moduli `_Common` / + `vmrun.py` un'interfaccia a 2 implementazioni (`Workstation`, `ESXi`), + selezionata via env var (`GITEA_CI_VM_BACKEND=workstation|esxi`). + In questo modo si può fare canary deploy job-per-job. +4. Migrazione template (export OVF da Workstation, import su ESXi datastore). +5. Workflow YAML aggiornati con label `windows-build:esxi` accanto a + `windows-build:host`. +6. Capacity burn-in concorrente sull'host ESXi. + +--- + +## 3. Stima volumi / sforzo (relativa) + +| Area | Indicatori dimensione | Complessità | +| -------------------------------------------------------------------------- | ---------------------------------------- | ----------- | +| Setup hardware/licenze ESXi | 1 host fisico + licenza Essentials | Variabile (acquisto) | +| PoC clone/start/stop via pyVmomi o PowerCLI | ~200 righe | Media | +| Astrazione backend (`IVmBackend` con 2 impl) | refactor di `_Common`, `New-BuildVM`, `Remove-BuildVM`, `Wait-VMReady` | Media | +| Export OVF dei template + import ESXi + ri-validazione snapshot | 3 template | Media | +| Riconfigurazione network/DHCP per build VM su ESXi | 1 portgroup + DHCP scope | Media | +| Adattamento `Cleanup-OrphanedBuildVMs`, `Watch-DiskSpace` (datastore-aware) | ~300 righe | Bassa | +| Documentazione (`HOST-SETUP.md` nuovo capitolo ESXi, `OPTIMIZATION.md`) | 2-3 file md | Bassa | +| Validazione e2e + benchmark vs Workstation | piano test esistente esteso | Alta | + +--- + +## 4. Pro / Contro + +### Pro + +- **Scalabilità**: un ESXi con CPU/RAM adeguate ospita facilmente 8-16 job concorrenti + vs ~4 con Workstation locale (limite testato in `Test-CapacityBurnIn`). +- Disaccoppia host CI (control plane) da hardware di build (data plane). +- Resource pool / shares / reservation: QoS per i job CI. +- Backup template / DR via snapshot ESXi nativi o appliance Veeam. +- Permette di avere host CI Linux (Mint) senza dover usare KVM (Idea 2 + Idea 3 sinergiche). +- Multi-runner futuro più semplice (più host CI puntano allo stesso ESXi). + +### Contro + +- **Costo licenza** vSphere (la free non basta per le API write). +- Hardware aggiuntivo dedicato (o ri-uso di un server esistente). +- Latenza di rete in più rispetto a in-process locale. +- Throughput clone dipende da datastore; può essere peggio se non si ha SSD locale ESXi. +- Backup VMDK template (`Backup-CITemplate.ps1`) va riprogettato (usare + snapshot ESXi nativi o export OVF schedulato). +- Disaster scenario: se ESXi è giù, **tutte** le pipeline si fermano. Con + Workstation locale il guasto era confinato all'host CI. + +--- + +## 5. Sinergia con altre idee + +- **Idea 1 (Python)**: forte sinergia. `pyVmomi` è Python-only; restando in + PowerShell si è costretti a `VMware.PowerCLI`, che ha overhead di + caricamento e dimensioni notevoli. +- **Idea 2 (host Linux)**: complementare. Idea 3 sposta il "dove girano le VM" + ma non vincola il "dove gira l'orchestrator". Si può: + - **Win host + ESXi backend**: minima migrazione lato CI script (resta PS). + - **Linux host + ESXi backend**: massima modernizzazione, ma somma i rischi + delle due migrazioni. Solo dopo Idee 1+2 stabilizzate. +- Con Idea 3 implementata, l'utilità di Idea 2 (host Linux con KVM locale) + cala: la VM locale serve solo per debug, non più per CI in production. + +--- + +## 6. Decision checklist + +Procedere **solo se** almeno 3 dei seguenti sono veri: + +- [ ] È disponibile (o pianificato) hardware ESXi + licenza Essentials. +- [ ] Si prevede di superare i 4 job concorrenti regolarmente. +- [ ] Si vuole disaccoppiare hardware CI da hardware build (es. CI in ufficio, + build in rack). +- [ ] Si è pianificata l'Idea 1 (Python) o si è disposti a usare PowerCLI. +- [ ] Disaster recovery / backup datastore è un requisito esplicito. + +Se la concorrenza richiesta è ≤4 job e l'hardware attuale (i9 + 64GB) regge, +**l'investimento ESXi non si ripaga** rispetto a Workstation locale. + +--- + +## 7. Path incrementale "minimo": ESXi opzionale + +Anziché migrazione totale, supportare **entrambi** i backend in parallelo: + +- Lasciare default `windows-build:host` (Workstation locale, situazione attuale). +- Aggiungere label `windows-build:esxi` per job specifici (es. burn-in + pesanti, regression suite notturna). +- Naming dei job e folder ESXi prefissati con `ci-` per filtering. +- Eventuale rollback semplice (basta disabilitare il label). + +Sforzo ~50% rispetto a migrazione totale, debito tecnico controllato perché +l'astrazione `IVmBackend` è già lì per design. diff --git a/plans/ideas-overview.md b/plans/ideas-overview.md new file mode 100644 index 0000000..c609d14 --- /dev/null +++ b/plans/ideas-overview.md @@ -0,0 +1,50 @@ +# Overview delle tre idee evolutive + +Documento di sintesi che mette in relazione i tre piani esplorativi: + +- [idea-1-python-rewrite.md](idea-1-python-rewrite.md) — Conversione del sistema in Python +- [idea-2-linux-host.md](idea-2-linux-host.md) — Host CI su Linux Mint +- [idea-3-esxi-support.md](idea-3-esxi-support.md) — Build VM su ESXi remoto + +--- + +## Matrice di sinergia + +| Combinazione | Sinergia | Note | +| --------------------------------------- | -------- | -------------------------------------------------------------------------------- | +| Solo Idea 1 (Python) | Neutra | Refactor "interno", nessun beneficio funzionale immediato. Utile se prerequisito a 2/3. | +| Solo Idea 2 (Linux host + KVM) | Alta | Cambio piattaforma; PS 7 possibile ma Python (Idea 1) consigliato. | +| Solo Idea 3 (ESXi backend) | Alta | Compatibile con stato attuale; PowerCLI o pyVmomi. | +| Idea 1 + Idea 2 | **Molto alta** | La rewrite Python rimuove l'attrito cross-platform. | +| Idea 1 + Idea 3 | **Molto alta** | `pyVmomi` è Python-only. | +| Idea 2 + Idea 3 | Media | Host Linux + build ESXi: massimo decoupling, ma rischi sommati. | +| Idee 1 + 2 + 3 | Alta | Massima modernizzazione. Da scaglionare in 3 milestone separate. | + +--- + +## Ordine consigliato (se si vogliono perseguire tutte) + +1. **Idea 1 prima fase** (estrarre `_Common` + `_Transport` in Python con + strangler fig) — riduce rischio futuro senza rompere niente. +2. **Idea 3 con backend astratto** (sui job sperimentali, label dedicata) — + sblocca scalabilità. +3. **Idea 1 fasi 2-4** (completamento rewrite Python). +4. **Idea 2** (migrazione host Linux) — solo dopo 1 e 3 stabili. + +Andare nell'ordine inverso (prima Linux, poi ESXi, infine Python) raddoppia +il debito tecnico nei periodi intermedi. + +--- + +## Quando NON fare nulla + +Il sistema attuale è documentato come `production-ready`. Astenersi se: + +- La concorrenza richiesta è ≤4 job e l'hardware regge. +- Non c'è pressione team su preferenze cross-platform. +- Non si pianifica espansione hardware nei prossimi 6 mesi. +- Il budget tempo è meglio speso in nuovi workflow CI per altri repo. + +In quel caso, l'investimento migliore è **estendere i test** (`tests/` Pester +attuali), aggiungere osservabilità (`Get-CIJobSummary`, metriche) e +documentare meglio l'esistente — non riscrivere.