From 4ac6dd85f9cede94314f5639003c0794f96c5820 Mon Sep 17 00:00:00 2001 From: Simone Date: Wed, 13 May 2026 11:08:01 +0200 Subject: [PATCH] refactor: restructure implementation plan for clarity and readability --- plans/implementation-plan-A-B.md | 134 ++++++++++++++++++++++++------- 1 file changed, 107 insertions(+), 27 deletions(-) diff --git a/plans/implementation-plan-A-B.md b/plans/implementation-plan-A-B.md index 3665cfd..eb5f145 100644 --- a/plans/implementation-plan-A-B.md +++ b/plans/implementation-plan-A-B.md @@ -8,11 +8,21 @@ mantenendo VMware Workstation Pro come hypervisor (Fase B). Il risultato è un unico stack Python in produzione su Linux, con i template VM, i workflow Gitea Actions e act_runner invariati nella sostanza. -| Fase | Obiettivo | Output verificabile | Stato | -| ---- | --------- | ------------------- | ----- | -| A | Rewrite Python dell'orchestratore (host Windows attuale) | `python -m ci_orchestrator job ...` sostituisce `Invoke-CIJob.ps1`; `pytest` ≥70% coverage; workflow `build-nsInnoUnp.yml` PASS | da iniziare | -| B | Migrazione host a Linux Mint + Workstation Pro Linux | act_runner come `act-runner.service` systemd; storage `/var/lib/ci/`; burn-in 4 job concorrenti PASS | da iniziare (gating: A done) | -| C | (Hook only, non implementata) backend ESXi via `pyVmomi` | Protocol `VmBackend` rispettato; `[backend]` selector in `config.toml` | non in scope | +Sintesi fasi: + +- **Fase A — Rewrite Python dell'orchestratore (host Windows attuale)** + - Output verificabile: `python -m ci_orchestrator job ...` sostituisce + `Invoke-CIJob.ps1`; `pytest` ≥70% coverage; workflow + `build-nsInnoUnp.yml` PASS. + - Stato: da iniziare. +- **Fase B — Migrazione host a Linux Mint + Workstation Pro Linux** + - Output verificabile: act_runner come `act-runner.service` systemd; + storage `/var/lib/ci/`; burn-in 4 job concorrenti PASS. + - Stato: da iniziare (gating: A done). +- **Fase C — (Hook only, non implementata) backend ESXi via `pyVmomi`** + - Output verificabile: Protocol `VmBackend` rispettato; `[backend]` + selector in `config.toml`. + - Stato: non in scope. Decisioni architetturali già prese e non rinegoziabili: @@ -875,28 +885,98 @@ flowchart TD ## 6. Matrice rischi consolidata -| Rischio | Fase | Severità | Mitigazione | Owner action item | -| ------- | ---- | -------- | ----------- | ----------------- | -| `pypsrp` edge case con WinRM HTTPS self-signed | A1 | Media | PoC `wait-ready` come primo deliverable A1 prima di committare al resto | A1 attività #10 | -| `keyring` sotto SYSTEM (act_runner service) non vede credenziali utente | A1, B3 | Alta | DPAPI machine scope su Win; PoC vault file `age`/`sops` su Linux in B3 | X3 attività complete | -| Perdita di know-how errori `AGENTS.md` #9–#12 durante refactor | A5 | Media | Ognuno convertito in test pytest **prima** di rimuovere il `.ps1` corrispondente | A5 attività #1 | -| Doppio mantenimento PS+Python durante migrazione | A2–A4 | Alta | Strategia shim minimizza la finestra; `lint.yml` dual-stack | X1 attività complete | -| Astrazione `VmBackend` over-engineered se Fase C non parte mai | A1 | Bassa | 1 implementazione concreta + Protocol = ~50 LOC extra; costo trascurabile | accettato | -| act_runner cattura male output Python (encoding cp1252) | A4 | Media | `PYTHONIOENCODING=utf-8` in `runner/config.yaml` | A4 attività #4 | -| `vmrun` su Linux ha differenze parsing output `list` / `getGuestIPAddress` | B1 | Media | Test modulo `vmrun.py` su Linux subito in B1 | B1 attività #3 | -| Performance I/O linked clone su ext4 vs NTFS | B7 | Bassa | Misurare con burn-in B7; eventualmente XFS/BTRFS | B7 attività #5 | -| `vmnet8` NAT range diverso → IP collision LAN | B1 | Media | Allineare `192.168.79.0/24` in B1 | B1 attività #5 | -| WinRM HTTPS da Linux: TLS 1.2 cipher non supportati dal Windows guest | B2 | Media | Smoke test prima del cutover; stesso codice già testato in A1 da Win host | B2 attività #7 | -| Permessi `/var/lib/ci/build-vms/` per `ci-runner` | B1 | Media | ACL POSIX con `setfacl -d -m` | B1 attività #8 | -| `secret-tool` headless senza D-Bus session | B3 | Alta | PoC + fallback file vault `age` | B3 attività #5 | -| Errore `AGENTS.md` #11 (machine-id Linux) si ripropone | B2 | Bassa | Già documentato; fix nel template prima dello snapshot | preservato | -| Errore `AGENTS.md` #12 (stderr nativa + `'Stop'`) | A | N/A | Sparisce in Python | dichiarato in A5 | -| Cutover gap window (job in errore tra stop Win e start Linux) | B6 | Media | Finestra a zero traffic + Gitea "paused" preventivo | B6 attività #2 | -| Decommissioning prematuro elimina rollback | B8 | Media | Gating ≥1 settimana + ≥1 mese spento prima di riallocare | B8 attività #3 | -| **(integrazione A↔B)** Shim PS che assume path Windows si rompe in Fase B | A2, B6 | Media | Shim deve invocare Python via path da env (`%CI_PYTHON_VENV%`), non hardcoded `F:\` | A2 attività #7 | -| **(integrazione A↔B)** `config.toml` con default Win-only blocca B1 | A1, B1 | Bassa | A1 deve già includere `[paths.linux]` con default POSIX | A1 attività #4 | -| **(integrazione A↔B)** Test pytest assumono `Path('F:\\CI')` e falliscono su Linux | A1, B1 | Media | Fixture parametrizzata `tmp_path` in tutti i test, no path hardcoded | A1 attività #11 | -| Licenza Workstation Pro Linux cambia post-Broadcom | B1 | Bassa | Free per uso personale e commerciale dal 2024; monitorare; piano B = KVM (rimandato) | B1 monitoring continuo | +Ogni voce: **Rischio** — Fase / Severità / Mitigazione / Owner action item. + +- **`pypsrp` edge case con WinRM HTTPS self-signed** + - Fase: A1 — Severità: Media + - Mitigazione: PoC `wait-ready` come primo deliverable A1 prima di + committare al resto. + - Owner: A1 attività #10. +- **`keyring` sotto SYSTEM (act_runner service) non vede credenziali utente** + - Fase: A1, B3 — Severità: Alta + - Mitigazione: DPAPI machine scope su Win; PoC vault file `age`/`sops` + su Linux in B3. + - Owner: X3 attività complete. +- **Perdita di know-how errori `AGENTS.md` #9–#12 durante refactor** + - Fase: A5 — Severità: Media + - Mitigazione: ognuno convertito in test pytest **prima** di rimuovere + il `.ps1` corrispondente. + - Owner: A5 attività #1. +- **Doppio mantenimento PS+Python durante migrazione** + - Fase: A2–A4 — Severità: Alta + - Mitigazione: strategia shim minimizza la finestra; `lint.yml` + dual-stack. + - Owner: X1 attività complete. +- **Astrazione `VmBackend` over-engineered se Fase C non parte mai** + - Fase: A1 — Severità: Bassa + - Mitigazione: 1 implementazione concreta + Protocol = ~50 LOC extra; + costo trascurabile. + - Owner: accettato. +- **act_runner cattura male output Python (encoding cp1252)** + - Fase: A4 — Severità: Media + - Mitigazione: `PYTHONIOENCODING=utf-8` in `runner/config.yaml`. + - Owner: A4 attività #4. +- **`vmrun` su Linux ha differenze parsing output `list` / `getGuestIPAddress`** + - Fase: B1 — Severità: Media + - Mitigazione: test modulo `vmrun.py` su Linux subito in B1. + - Owner: B1 attività #3. +- **Performance I/O linked clone su ext4 vs NTFS** + - Fase: B7 — Severità: Bassa + - Mitigazione: misurare con burn-in B7; eventualmente XFS/BTRFS. + - Owner: B7 attività #5. +- **`vmnet8` NAT range diverso → IP collision LAN** + - Fase: B1 — Severità: Media + - Mitigazione: allineare `192.168.79.0/24` in B1. + - Owner: B1 attività #5. +- **WinRM HTTPS da Linux: TLS 1.2 cipher non supportati dal Windows guest** + - Fase: B2 — Severità: Media + - Mitigazione: smoke test prima del cutover; stesso codice già testato + in A1 da Win host. + - Owner: B2 attività #7. +- **Permessi `/var/lib/ci/build-vms/` per `ci-runner`** + - Fase: B1 — Severità: Media + - Mitigazione: ACL POSIX con `setfacl -d -m`. + - Owner: B1 attività #8. +- **`secret-tool` headless senza D-Bus session** + - Fase: B3 — Severità: Alta + - Mitigazione: PoC + fallback file vault `age`. + - Owner: B3 attività #5. +- **Errore `AGENTS.md` #11 (machine-id Linux) si ripropone** + - Fase: B2 — Severità: Bassa + - Mitigazione: già documentato; fix nel template prima dello snapshot. + - Owner: preservato. +- **Errore `AGENTS.md` #12 (stderr nativa + `'Stop'`)** + - Fase: A — Severità: N/A + - Mitigazione: sparisce in Python. + - Owner: dichiarato in A5. +- **Cutover gap window (job in errore tra stop Win e start Linux)** + - Fase: B6 — Severità: Media + - Mitigazione: finestra a zero traffic + Gitea "paused" preventivo. + - Owner: B6 attività #2. +- **Decommissioning prematuro elimina rollback** + - Fase: B8 — Severità: Media + - Mitigazione: gating ≥1 settimana + ≥1 mese spento prima di + riallocare. + - Owner: B8 attività #3. +- **(integrazione A↔B) Shim PS che assume path Windows si rompe in Fase B** + - Fase: A2, B6 — Severità: Media + - Mitigazione: shim deve invocare Python via path da env + (`%CI_PYTHON_VENV%`), non hardcoded `F:\`. + - Owner: A2 attività #7. +- **(integrazione A↔B) `config.toml` con default Win-only blocca B1** + - Fase: A1, B1 — Severità: Bassa + - Mitigazione: A1 deve già includere `[paths.linux]` con default POSIX. + - Owner: A1 attività #4. +- **(integrazione A↔B) Test pytest assumono `Path('F:\\CI')` e falliscono su Linux** + - Fase: A1, B1 — Severità: Media + - Mitigazione: fixture parametrizzata `tmp_path` in tutti i test, no + path hardcoded. + - Owner: A1 attività #11. +- **Licenza Workstation Pro Linux cambia post-Broadcom** + - Fase: B1 — Severità: Bassa + - Mitigazione: free per uso personale e commerciale dal 2024; + monitorare; piano B = KVM (rimandato). + - Owner: B1 monitoring continuo. ## 7. Definizione di "fatto" globale (A+B)