feat(plans): add proposals for Python rewrite, Linux host adaptation, and ESXi support
This commit is contained in:
@@ -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.
|
||||
@@ -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 <vmx>` | `virsh start <domain>` |
|
||||
| `vmrun stop <vmx> hard` | `virsh destroy <domain>` |
|
||||
| `vmrun deleteVM` | `virsh undefine <domain> --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/<jobid>.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.
|
||||
@@ -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 <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` (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.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user