docs: introduce Phase C (pwsh removal), rename ESXi to Phase D
- Add plans/idea-3-powershell-removal.md: Phase C goal is to eliminate the pwsh dependency from the Linux host by porting the remaining PS scripts (bench run, validate host, smoke run) to Python sub-commands. - Update idea-3-esxi-support.md header: Fase C → Fase D. - Update ideas-overview.md: new four-phase table (A/B/C/D) with prerequisiti and criteri for Phase C. - Rename all "Hook futuri Fase C" (ESXi) → "Hook futuri Fase D" in implementation-plan-A-B.md; add Phase C/D entries to summary and references section. - Update PhaseB-user-checklist.md end note and CLAUDE.md to point Phase C → pwsh removal, Phase D → ESXi. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
This commit is contained in:
@@ -23,7 +23,12 @@ Sintesi fasi:
|
||||
- **Stato: pronta** (gating "A done" soddisfatto). Esecuzione via
|
||||
`plans/PhaseB-user-checklist.md`; design/rischi/cronoprogramma in
|
||||
§2/§3/§5/§6 di questo piano.
|
||||
- **Fase C — (Hook only, non implementata) backend ESXi via `pyVmomi`**
|
||||
- **Fase C — Eliminazione dipendenza `pwsh` dall'host Linux**
|
||||
- Output verificabile: `bench run`, `validate host`, `smoke run` portati
|
||||
in Python; `pwsh` disinstallabile senza impatti.
|
||||
- Stato: non in scope (da avviare dopo B stabile). Design in
|
||||
`plans/idea-3-powershell-removal.md`.
|
||||
- **Fase D — (Hook only, non implementata) backend ESXi via `pyVmomi`**
|
||||
- Output verificabile: Protocol `VmBackend` rispettato; `[backend]`
|
||||
selector in `config.toml`.
|
||||
- Stato: non in scope.
|
||||
@@ -177,7 +182,7 @@ WinRM/SSH e credential store funzionanti contro l'ambiente reale via PoC
|
||||
- [x] Test pytest unitari: `test_vmrun.py` (mock subprocess, casi `vmrun list` con e senza VMX target — copre errore #10), `test_winrm.py` (mock `pypsrp`), `test_ssh.py` (mock `paramiko`, copre errore #12), `test_credentials.py` (mock `keyring`)
|
||||
- [x] Aggiungere job `python` a `gitea/workflows/lint.yml`: setup venv → `ruff check src/ tests/` → `mypy --strict src/` → `pytest --cov=ci_orchestrator --cov-fail-under=70`
|
||||
|
||||
**Hook futuri Fase C**: il Protocol `VmBackend` deve usare nomi neutri
|
||||
**Hook futuri Fase D**: il Protocol `VmBackend` deve usare nomi neutri
|
||||
(`clone_linked`, non `vmrun_clone`), accettare `template`/`snapshot`/`name`
|
||||
come stringhe opache (non path Windows), separare `clone_linked` da
|
||||
`start` (ESXi richiede `PowerOn` come task distinto). Niente assunzioni
|
||||
@@ -230,9 +235,9 @@ stato con l'orchestratore, sostituendoli con shim minimi.
|
||||
- [ ] Convertire `tests/Remove-BuildVM.Tests.ps1` in `tests/test_commands_vm_remove.py`
|
||||
- [ ] Verificare che gli scheduled task esistenti (`Register-CIScheduledTasks.ps1`) continuino a funzionare invocando gli shim PS
|
||||
|
||||
**Hook futuri Fase C**: `vm cleanup` non deve assumere scan locale del
|
||||
**Hook futuri Fase D**: `vm cleanup` non deve assumere scan locale del
|
||||
filesystem — la firma deve accettare un `VmBackend` come dipendenza,
|
||||
così che in Fase C la stessa logica interroghi l'API ESXi (folder-scoped
|
||||
così che in Fase D la stessa logica interroghi l'API ESXi (folder-scoped
|
||||
list).
|
||||
|
||||
**Test / validazione**:
|
||||
@@ -275,7 +280,7 @@ Python preservando il comportamento dei `.ps1` esistenti.
|
||||
- [x] Aggiungere test pytest per `artifacts collect` (mock SFTP/WinRM file copy + tmp_path)
|
||||
- [ ] Validare end-to-end: clone WinBuild2025 → build script PowerShell trivial → collect artifact ZIP
|
||||
|
||||
**Hook futuri Fase C**: `build run` deve ricevere un `VmHandle` opaco,
|
||||
**Hook futuri Fase D**: `build run` deve ricevere un `VmHandle` opaco,
|
||||
non un path VMX (ESXi non ha path locale al control plane). Adattare le
|
||||
CLI a accettare entrambe (`--vmx` per workstation, `--vm-id` futuro per
|
||||
ESXi) con dispatcher nel layer `commands/`.
|
||||
@@ -317,7 +322,7 @@ Gitea per chiamare la CLI Python direttamente.
|
||||
- [ ] Eseguire workflow `self-test.yml` PASS
|
||||
- [ ] Eseguire workflow `lint.yml` PASS
|
||||
|
||||
**Hook futuri Fase C**: la selezione del backend deve avvenire in
|
||||
**Hook futuri Fase D**: la selezione del backend deve avvenire in
|
||||
`job.py` leggendo `config.toml` `[backend].type` (default `workstation`).
|
||||
Niente import diretto di `WorkstationVmrunBackend` in `job.py` — usare
|
||||
factory `backends.load_backend(config)`.
|
||||
@@ -359,7 +364,7 @@ aggiornare documentazione, eseguire burn-in finale.
|
||||
- [ ] Eseguire burn-in 4 job concorrenti × 10 round PASS sull'host Windows — richiede VM reali, a carico utente
|
||||
- [ ] Aggiornare `docs/RUNBOOK.md` con sezione "Operare da Python CLI" — deferito a chiusura Fase B (RUNBOOK riscritto end-to-end in B-finale)
|
||||
|
||||
**Hook futuri Fase C**: documentare in `docs/ARCHITECTURE.md` il
|
||||
**Hook futuri Fase D**: documentare in `docs/ARCHITECTURE.md` il
|
||||
contratto `VmBackend` come "extension point" e il selettore `[backend]`
|
||||
in `config.toml` come unica via per aggiungere ESXi.
|
||||
|
||||
@@ -421,7 +426,7 @@ parallelo a A3/A4. Riferimento `idea-2-linux-host.md` §4.
|
||||
- [ ] Validare `sudo -u ci-runner /opt/ci/venv/bin/python -m ci_orchestrator --help`
|
||||
- [ ] Aggiungere `[paths.linux]` a `config.example.toml` con i path POSIX
|
||||
|
||||
**Hook futuri Fase C**: lo stesso host Linux farà da control plane se
|
||||
**Hook futuri Fase D**: lo stesso host Linux farà da control plane se
|
||||
si attiverà ESXi. Non installare nulla che assuma "VM girano in locale"
|
||||
(es. condivisioni `vmware-shared-folders` host-only).
|
||||
|
||||
@@ -466,7 +471,7 @@ mantenendo snapshot integri.
|
||||
- [ ] Validare snapshot `BaseClean-Linux` su `LinuxBuild2404.vmx`
|
||||
- [ ] Smoke test: `python -m ci_orchestrator vm new --template /var/lib/ci/templates/WinBuild2025/WinBuild2025.vmx --snapshot BaseClean --name smoke1` + `wait-ready` + `vm remove`
|
||||
|
||||
**Hook futuri Fase C**: i template restano in formato VMX. Per ESXi
|
||||
**Hook futuri Fase D**: i template restano in formato VMX. Per ESXi
|
||||
serviranno OVF (`ovftool`) — non fare nulla in B2, ma documentare che
|
||||
il dataset attuale è la base per export futuro.
|
||||
|
||||
@@ -507,7 +512,7 @@ guest e i token Gitea, accessibili da `ci-runner` headless.
|
||||
- [ ] PoC headless: testare lettura keyring da contesto systemd (no sessione D-Bus utente). Se fallisce, implementare backend `keyring` file-based con vault `age` o `sops` come fallback documentato
|
||||
- [ ] Documentare la scelta finale in `docs/HOST-SETUP.md`
|
||||
|
||||
**Hook futuri Fase C**: anche ESXi userà credenziali da `keyring` (user
|
||||
**Hook futuri Fase D**: anche ESXi userà credenziali da `keyring` (user
|
||||
vSphere). Lo stesso `KeyringCredentialStore` deve poter caricare `EsxiHost`
|
||||
target — niente hard-coding di nomi credenziali.
|
||||
|
||||
@@ -551,7 +556,7 @@ systemd, equivalente al servizio Windows attuale.
|
||||
- [ ] Validare `journalctl -u act-runner -f` mostra connessione a Gitea OK
|
||||
- [ ] **NON** avviare ancora workflow di produzione — il runner Windows è ancora primario
|
||||
|
||||
**Hook futuri Fase C**: env vars `CI_*` restano valide; per ESXi si
|
||||
**Hook futuri Fase D**: env vars `CI_*` restano valide; per ESXi si
|
||||
aggiungeranno solo `CI_BACKEND=esxi` + sezione `[backend.esxi]` in
|
||||
`config.toml`. `act-runner.service` non cambia.
|
||||
|
||||
@@ -596,7 +601,7 @@ per l'inventario dei task.
|
||||
- [ ] Validare `systemctl list-timers` mostra tutti i timer schedulati
|
||||
- [x] Documentare il mapping in `docs/HOST-SETUP.md`
|
||||
|
||||
**Hook futuri Fase C**: `vm cleanup` con backend ESXi userà la stessa
|
||||
**Hook futuri Fase D**: `vm cleanup` con backend ESXi userà la stessa
|
||||
unit — il selettore backend è in `config.toml`, non nel comando.
|
||||
|
||||
**Rischi specifici**:
|
||||
@@ -637,7 +642,7 @@ una finestra di manutenzione concordata.
|
||||
- [ ] Trigger manuale `build-ns7zip.yml` matrix Win + Linux PASS
|
||||
- [ ] Monitorare `journalctl -u act-runner -f` per ≥30 min sotto carico reale
|
||||
|
||||
**Hook futuri Fase C**: nessuno specifico in B6. Cutover non tocca
|
||||
**Hook futuri Fase D**: nessuno specifico in B6. Cutover non tocca
|
||||
backend.
|
||||
|
||||
**Rischi specifici**:
|
||||
@@ -682,7 +687,7 @@ tempi paragonabili.
|
||||
- [ ] Misurare uso disco `/var/lib/ci/build-vms/` durante e dopo burn-in (cleanup automatico)
|
||||
- [ ] Documentare risultati in `docs/RUNBOOK.md`
|
||||
|
||||
**Hook futuri Fase C**: i risultati di B7 sono il baseline contro cui
|
||||
**Hook futuri Fase D**: i risultati di B7 sono il baseline contro cui
|
||||
confrontare un eventuale backend ESXi (criterio di "C done" in
|
||||
`idea-3-esxi-support.md` §8).
|
||||
|
||||
@@ -725,7 +730,7 @@ host Windows.~~ → Host Windows mantenuto operativo a regime.
|
||||
- [ ] Documentare in `docs/RUNBOOK.md` come usare entrambi gli host
|
||||
- [ ] ~~Riallocare hardware~~ — NON applicabile (Windows host permanente)
|
||||
|
||||
**Hook futuri Fase C**: nessuno.
|
||||
**Hook futuri Fase D**: nessuno.
|
||||
|
||||
**Rischi specifici**:
|
||||
|
||||
@@ -762,7 +767,7 @@ re-registrare runner Windows verso Gitea.
|
||||
- [ ] Configurare `PSScriptAnalyzerSettings.psd1` per coprire `scripts/`, `template/`, `tests/` (già presente in repo)
|
||||
- [ ] Configurare `pyproject.toml` con `[tool.ruff]`, `[tool.mypy]`, `[tool.pytest.ini_options]`
|
||||
|
||||
**Hook futuri Fase C**: nessuno specifico.
|
||||
**Hook futuri Fase D**: nessuno specifico.
|
||||
|
||||
**Test / validazione**:
|
||||
|
||||
@@ -789,7 +794,7 @@ re-registrare runner Windows verso Gitea.
|
||||
- [ ] In B4: configurare service unit per inviare stdout/stderr a journald (default systemd) e validare `journalctl -u act-runner -o json`
|
||||
- [ ] Documentare query journald utili in `docs/RUNBOOK.md`
|
||||
|
||||
**Hook futuri Fase C**: log strutturati facilitano correlazione job ↔ backend.
|
||||
**Hook futuri Fase D**: log strutturati facilitano correlazione job ↔ backend.
|
||||
|
||||
**Test / validazione**:
|
||||
|
||||
@@ -818,7 +823,7 @@ systemd (Linux) senza sessione utente interattiva.
|
||||
- [ ] Implementare backend `keyring` file-based come opzione `KeyringFileBackend(vault_path, age_key_path)` se serve
|
||||
- [ ] Test pytest che simulano contesto headless (mock `keyring.get_credential` ritorna `None` → fallback a file vault)
|
||||
|
||||
**Hook futuri Fase C**: stesso `CredentialStore` userà credenziali
|
||||
**Hook futuri Fase D**: stesso `CredentialStore` userà credenziali
|
||||
vSphere — mantenere API generica.
|
||||
|
||||
**Test / validazione**:
|
||||
@@ -852,7 +857,7 @@ Linux + Python).
|
||||
- [ ] Aggiornare `AGENTS.md`: sezione "Python development" + nota errore #12 N/A in Python
|
||||
- [ ] Aggiornare `README.md`: quick-start Python + Linux
|
||||
|
||||
**Hook futuri Fase C**: lasciare placeholder "Backend ESXi (futuro)" in
|
||||
**Hook futuri Fase D**: lasciare placeholder "Backend ESXi (futuro)" in
|
||||
`docs/ARCHITECTURE.md` e `docs/HOST-SETUP.md`.
|
||||
|
||||
**Test / validazione**:
|
||||
@@ -868,7 +873,7 @@ Linux + Python).
|
||||
- [ ] Link interni validi
|
||||
- [ ] Quick-start testato da operatore esterno
|
||||
|
||||
## 4. Hook architetturali per Fase C
|
||||
## 4. Hook architetturali per Fase D
|
||||
|
||||
Punti di design da rispettare durante A e B per non bloccare un futuro
|
||||
backend ESXi senza implementarlo:
|
||||
@@ -955,7 +960,7 @@ Ogni voce: **Rischio** — Fase / Severità / Mitigazione / Owner action item.
|
||||
- Mitigazione: strategia shim minimizza la finestra; `lint.yml`
|
||||
dual-stack.
|
||||
- Owner: X1 attività complete.
|
||||
- **Astrazione `VmBackend` over-engineered se Fase C non parte mai**
|
||||
- **Astrazione `VmBackend` over-engineered se Fase D non parte mai**
|
||||
- Fase: A1 — Severità: Bassa
|
||||
- Mitigazione: 1 implementazione concreta + Protocol = ~50 LOC extra;
|
||||
costo trascurabile.
|
||||
@@ -1050,7 +1055,7 @@ Ogni voce: **Rischio** — Fase / Severità / Mitigazione / Owner action item.
|
||||
Domande di auto-verifica a cui il documento risponde "sì":
|
||||
|
||||
- **Ogni voce della checklist master compare almeno una volta come `- [ ]` dentro lo step corrispondente?** Sì: voci `[A1]…[A5]` mappate alle attività in §1, `[B1]…[B8]` in §2, `[X1]…[X4]` in §3.
|
||||
- **Ogni step `A<n>`/`B<n>`/`X<n>` ha tutte le sottosezioni richieste?** Sì: Obiettivo, Input/dipendenze, Attività, Hook futuri Fase C, Test/validazione, Rollback, Definizione di fatto presenti per ogni step (B*: in più rischi specifici).
|
||||
- **Ogni step `A<n>`/`B<n>`/`X<n>` ha tutte le sottosezioni richieste?** Sì: Obiettivo, Input/dipendenze, Attività, Hook futuri Fase D, Test/validazione, Rollback, Definizione di fatto presenti per ogni step (B*: in più rischi specifici).
|
||||
- **I 12 errori frequenti di `AGENTS.md` sono stati indirizzati o dichiarati non applicabili?**
|
||||
- #1 (sintassi PS 7+): si applica solo agli shim PS residui in A2/A3 — vincolo PS 5.1 mantenuto
|
||||
- #2 (`$LASTEXITCODE` non controllato): N/A in Python (`subprocess.returncode` esplicito)
|
||||
@@ -1072,7 +1077,8 @@ Domande di auto-verifica a cui il documento risponde "sì":
|
||||
- [plans/ideas-overview.md](ideas-overview.md) — razionale ordine fasi, criteri "fase completata", rollback
|
||||
- [plans/idea-1-python-rewrite.md](idea-1-python-rewrite.md) — Fase A: design, mappa traduzione, step A1–A5, layout repo, rischi
|
||||
- [plans/idea-2-linux-host.md](idea-2-linux-host.md) — Fase B: hypervisor, mappa adattamento, step B1–B8, rischi
|
||||
- [plans/idea-3-esxi-support.md](idea-3-esxi-support.md) — Fase C: §2 architettura, §3 backend pyVmomi (solo per hook)
|
||||
- [plans/idea-3-powershell-removal.md](idea-3-powershell-removal.md) — Fase C: eliminazione `pwsh` dall'host Linux
|
||||
- [plans/idea-3-esxi-support.md](idea-3-esxi-support.md) — Fase D: §2 architettura, §3 backend pyVmomi (solo per hook)
|
||||
- [docs/ARCHITECTURE.md](../docs/ARCHITECTURE.md) — layout attuale del sistema
|
||||
- [docs/CI-FLOW.md](../docs/CI-FLOW.md) — flusso job CI corrente
|
||||
- [docs/HOST-SETUP.md](../docs/HOST-SETUP.md) — setup host Windows attuale
|
||||
|
||||
Reference in New Issue
Block a user