495 lines
17 KiB
Markdown
495 lines
17 KiB
Markdown
# Fase B — Checklist finale per l'utente
|
||
|
||
La Fase B è la migrazione del runner CI dall'host Windows attuale a un
|
||
nuovo host **Linux Mint LTS** con VMware Workstation Pro Linux.
|
||
|
||
> **Stato repo**: solo lo step **B5** (unit `systemd` per i task
|
||
> periodici) è già committato in `deploy/systemd/` sul branch
|
||
> `feature/python-rewrite-and-linux-migration` (commit `50d37b5`).
|
||
> Tutti gli altri step (B1–B4, B6–B8) sono **operazioni hardware**
|
||
> sull'host Linux nuovo e devono essere eseguiti dall'utente.
|
||
|
||
> **Pre-requisito**: la Fase A deve essere `done` (vedi
|
||
> `plans/PhaseA-user-checklist.md` Passo 9, merge + tag).
|
||
> B1, B2, B3 possono partire in parallelo a A3/A4/A5; B4–B8 sono
|
||
> sequenziali e iniziano solo dopo "A done".
|
||
|
||
> **Tempo stimato totale**: 1–2 giorni di lavoro distribuiti su una
|
||
> finestra di 1–2 settimane (per consentire il burn-in tra B6 e B8).
|
||
|
||
---
|
||
|
||
## Passo 1 — Setup host Linux Mint (B1)
|
||
|
||
**Obiettivo**: hardware target con Linux Mint LTS, VMware Workstation
|
||
Pro Linux, layout storage e venv Python pronti.
|
||
|
||
- [x] Installare Linux Mint LTS sull'hardware target.
|
||
- [x] `sudo apt update && sudo apt full-upgrade -y && sudo reboot`
|
||
- [x] Scaricare e installare VMware Workstation Pro Linux (bundle
|
||
`.bundle` da Broadcow):
|
||
|
||
```bash
|
||
sudo bash VMware-Workstation-Full-*.bundle
|
||
vmrun -T ws --version # deve ritornare versione coerente
|
||
```
|
||
|
||
- [x] Smoke test Workstation (UI): creare VM trivia, clone, start,
|
||
stop, delete.
|
||
- [x] Configurare `vmnet8` NAT range `192.168.79.0/24` (allineato a
|
||
Windows) editando `/etc/vmware/vmnet8/dhcpd/dhcpd.conf` o via
|
||
`vmware-netcfg`.
|
||
- [x] Creare utente di servizio `ci-runner`:
|
||
|
||
```bash
|
||
sudo useradd -r -m -s /bin/bash ci-runner
|
||
```
|
||
|
||
- [x] Eseguire `setup-host-linux.sh` (copre mount disco, layout, Python venv,
|
||
clone repo, PowerShell Core):
|
||
|
||
```bash
|
||
# Clonare il repo prima di eseguire lo script
|
||
git clone https://gitea.emulab.it/Simone/local-ci-cd-system.git /tmp/local-ci-cd-system
|
||
|
||
sudo bash /tmp/local-ci-cd-system/setup-host-linux.sh -d /dev/sdf1
|
||
```
|
||
|
||
Lo script:
|
||
- Monta `/dev/sdf1` su `/var/lib/ci` via fstab (boot automatico).
|
||
Se la partizione ha una sottocartella `ci/`, ne sposta i contenuti
|
||
alla root della partizione prima del mount definitivo.
|
||
- Crea il layout `build-vms/`, `artifacts/`, `templates/`, `keys/`,
|
||
`logs/`, `runner/` con permessi e ACL corretti.
|
||
- Installa Python 3.11, crea `/opt/ci/venv`, clona il repo in
|
||
`/opt/ci/local-ci-cd-system` e installa il package.
|
||
- Installa PowerShell Core.
|
||
|
||
Flag utili se alcune dipendenze sono già presenti:
|
||
```bash
|
||
sudo bash setup-host-linux.sh -d /dev/sdf1 --skip-pwsh --skip-clone
|
||
```
|
||
|
||
Atteso a fine script: `ci_orchestrator --help` lista gli 11 sub-comandi.
|
||
|
||
---
|
||
|
||
## Passo 2 — Trasferimento template VM (B2)
|
||
|
||
**Obiettivo**: copiare i template VMware da `F:\CI\Templates\` su
|
||
`/var/lib/ci/templates/` mantenendo gli snapshot.
|
||
|
||
> ⚠️ AGENTS.md errore #9: i template devono essere **fully
|
||
> powered-off** prima della copia. Verificare assenza di `*.vmem` /
|
||
> `*.vmsn` di runtime.
|
||
|
||
- [x] Sull'host Windows:
|
||
|
||
```powershell
|
||
Get-ChildItem 'F:\CI\Templates' -Recurse -Include *.vmem,*.vmsn
|
||
# atteso: nessun risultato
|
||
```
|
||
|
||
- [x] Sull'host Linux, eseguire rsync via SSH dall'host Windows
|
||
(richiede OpenSSH Server attivo su Windows o, in alternativa,
|
||
`scp -r` lanciato da Windows verso Linux):
|
||
|
||
```bash
|
||
sudo -u ci-runner rsync -av --progress \
|
||
user@windows-host:/cygdrive/f/CI/Templates/ \
|
||
/var/lib/ci/templates/
|
||
```
|
||
|
||
- [x] Validare integrità snapshot:
|
||
|
||
```bash
|
||
find /var/lib/ci/templates -name '*.vmx' -exec vmrun -T ws listSnapshots {} \;
|
||
```
|
||
|
||
Atteso: `BaseClean` su `WinBuild2025.vmx` e `WinBuild2022.vmx`,
|
||
`BaseClean-Linux` su `LinuxBuild2404.vmx`.
|
||
|
||
- [x] Aprire ciascun `.vmx` su Workstation Linux per registrarli;
|
||
al prompt rispondere "**I copied it**".
|
||
- [ ] **Prerequisito smoke test Windows**: il keyring file-based deve essere
|
||
configurato e la credenziale `BuildVMGuest` deve essere presente
|
||
**prima** di eseguire `wait-ready` (che prova WinRM). Questo è
|
||
formalmente il Passo 3 (B3), ma il minimo indispensabile per lo
|
||
smoke test è:
|
||
|
||
```bash
|
||
# Configurare il backend file keyring per ci-runner (una sola volta)
|
||
sudo -u ci-runner mkdir -p ~/.local/share/python_keyring
|
||
sudo -u ci-runner bash -c "cat > ~/.local/share/python_keyring/keyringrc.cfg << 'EOF'
|
||
[backend]
|
||
default-keyring=keyrings.alt.file.PlaintextKeyring
|
||
EOF"
|
||
sudo -u ci-runner /opt/ci/venv/bin/pip install keyrings.alt -q
|
||
|
||
# Salvare la credenziale guest Windows
|
||
sudo -u ci-runner /opt/ci/venv/bin/python /opt/ci/local-ci-cd-system/tools/ci-cred-set.py BuildVMGuest "WINBUILD-2025\\ci_build"
|
||
|
||
# Verificare
|
||
sudo -u ci-runner /opt/ci/venv/bin/python /opt/ci/local-ci-cd-system/tools/ci-cred-check.py BuildVMGuest
|
||
# atteso: OK (file) username='WINBUILD-2025\ci_build' password=****
|
||
```
|
||
|
||
> Il setup completo delle credenziali (chiavi SSH, GiteaPAT,
|
||
> PoC headless systemd) è nel Passo 3.
|
||
|
||
- [ ] Smoke test pipeline VM:
|
||
|
||
```bash
|
||
# Windows smoke
|
||
CLONE_VMX=$(sudo -u ci-runner /opt/ci/venv/bin/python -m ci_orchestrator vm new \
|
||
--template /var/lib/ci/templates/WinBuild2025/WinBuild2025.vmx \
|
||
--snapshot BaseClean \
|
||
--clone-base-dir /var/lib/ci/build-vms \
|
||
--job-id smoke-b2-win \
|
||
--start)
|
||
echo "Clone VMX: $CLONE_VMX"
|
||
|
||
sudo -u ci-runner /opt/ci/venv/bin/python -m ci_orchestrator wait-ready \
|
||
--vmx "$CLONE_VMX" --guest-os windows --timeout 300
|
||
|
||
sudo -u ci-runner /opt/ci/venv/bin/python -m ci_orchestrator vm remove \
|
||
--vmx "$CLONE_VMX" --force
|
||
```
|
||
|
||
Ripetere per `LinuxBuild2404` (snapshot `BaseClean-Linux`,
|
||
`--guest-os linux`, `--job-id smoke-b2-linux`).
|
||
|
||
---
|
||
|
||
## Passo 3 — Trasferimento credenziali e chiavi (B3)
|
||
|
||
**Obiettivo**: chiavi SSH e credenziali guest disponibili al user
|
||
`ci-runner` headless.
|
||
|
||
- [x] Chiavi SSH guest Linux già presenti in `/var/lib/ci/keys/` (copiate
|
||
insieme ai template). Correggere solo i permessi:
|
||
|
||
```bash
|
||
sudo chown ci-runner:ci-runner /var/lib/ci/keys/ci_linux /var/lib/ci/keys/ci_linux.pub
|
||
sudo chmod 600 /var/lib/ci/keys/ci_linux
|
||
sudo chmod 644 /var/lib/ci/keys/ci_linux.pub
|
||
# verifica
|
||
ls -la /var/lib/ci/keys/
|
||
```
|
||
|
||
- [x] Credenziale guest Windows `BuildVMGuest` già salvata nel
|
||
prerequisito del Passo 2 con `keyrings.alt.file.PlaintextKeyring`
|
||
(schema a due entry — `secret-tool` scartato perché non funziona
|
||
headless senza D-Bus session).
|
||
|
||
Per riscrivere la credenziale se necessario:
|
||
|
||
```bash
|
||
sudo -u ci-runner /opt/ci/venv/bin/python /opt/ci/local-ci-cd-system/tools/ci-cred-set.py BuildVMGuest "WINBUILD-2025\\ci_build"
|
||
sudo -u ci-runner /opt/ci/venv/bin/python /opt/ci/local-ci-cd-system/tools/ci-cred-check.py BuildVMGuest
|
||
```
|
||
|
||
- [x] Re-store Gitea PAT con lo stesso schema:
|
||
|
||
```bash
|
||
sudo -u ci-runner /opt/ci/venv/bin/python /opt/ci/local-ci-cd-system/tools/ci-cred-set.py GiteaPAT ci-runner-linux
|
||
sudo -u ci-runner /opt/ci/venv/bin/python /opt/ci/local-ci-cd-system/tools/ci-cred-check.py GiteaPAT
|
||
```
|
||
|
||
- [x] **PoC headless**: il backend `PlaintextKeyring` non usa D-Bus —
|
||
funziona già da `sudo -u ci-runner` e funzionerà da
|
||
`act-runner.service`. Verificato durante smoke test Passo 2.
|
||
|
||
---
|
||
|
||
## Passo 4 — Setup act_runner come systemd service (B4)
|
||
|
||
**Obiettivo**: act_runner Linux registrato verso Gitea, gestito da
|
||
systemd.
|
||
|
||
- [x] Scaricare il binario act_runner Linux ≥ v1.0.4:
|
||
|
||
```bash
|
||
sudo mkdir -p /opt/ci/act_runner
|
||
sudo wget -O /opt/ci/act_runner/act_runner \
|
||
https://gitea.com/gitea/runner/releases/download/v1.0.4/gitea-runner-1.0.4-linux-amd64
|
||
sudo chmod +x /opt/ci/act_runner/act_runner
|
||
sudo chown -R ci-runner:ci-runner /opt/ci/act_runner
|
||
```
|
||
|
||
- [x] Generare token registrazione su Gitea (Admin → Runners → Create new runner).
|
||
- [x] Registrare il runner (sostituire `<TOKEN>`):
|
||
|
||
```bash
|
||
sudo -u ci-runner mkdir -p /var/lib/ci/runner
|
||
cd /var/lib/ci/runner
|
||
sudo -u ci-runner /opt/ci/act_runner/act_runner register \
|
||
--no-interactive \
|
||
--instance https://gitea.emulab.it \
|
||
--token <TOKEN> \
|
||
--name ci-linux \
|
||
--labels windows-build:host,linux-build:host
|
||
```
|
||
|
||
> ⚠️ Lasciare il runner in stato **paused** lato Gitea UI fino al
|
||
> cutover (Passo 6), per non intercettare job di produzione.
|
||
|
||
- [x] Creare `/etc/systemd/system/act-runner.service`:
|
||
|
||
```ini
|
||
[Unit]
|
||
Description=Gitea Act Runner
|
||
After=network-online.target
|
||
Wants=network-online.target
|
||
|
||
[Service]
|
||
Type=simple
|
||
User=ci-runner
|
||
WorkingDirectory=/var/lib/ci/runner
|
||
Environment="PYTHONIOENCODING=utf-8"
|
||
Environment="CI_ROOT=/var/lib/ci"
|
||
Environment="CI_TEMPLATES=/var/lib/ci/templates"
|
||
Environment="CI_BUILD_VMS=/var/lib/ci/build-vms"
|
||
Environment="CI_ARTIFACTS=/var/lib/ci/artifacts"
|
||
Environment="CI_KEYS=/etc/ci/keys"
|
||
ExecStart=/opt/ci/act_runner/act_runner daemon
|
||
Restart=on-failure
|
||
RestartSec=10
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
```
|
||
|
||
- [x] Creare `/etc/ci/environment` (letto dalle unit dei task periodici
|
||
di B5; vedi `deploy/systemd/README.md`):
|
||
|
||
```bash
|
||
sudo tee /etc/ci/environment <<'EOF'
|
||
PYTHONIOENCODING=utf-8
|
||
CI_ROOT=/var/lib/ci
|
||
CI_TEMPLATES=/var/lib/ci/templates
|
||
CI_BUILD_VMS=/var/lib/ci/build-vms
|
||
CI_ARTIFACTS=/var/lib/ci/artifacts
|
||
CI_KEYS=/etc/ci/keys
|
||
EOF
|
||
sudo chmod 644 /etc/ci/environment
|
||
```
|
||
|
||
- [x] Abilitare e avviare:
|
||
|
||
```bash
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable --now act-runner.service
|
||
sudo systemctl status act-runner
|
||
sudo journalctl -u act-runner -f # Ctrl+C dopo conferma OK
|
||
```
|
||
|
||
- [ ] Smoke job: triggerare manualmente `self-test.yml` selezionando
|
||
il runner Linux (mettere temporaneamente in pausa quello Windows
|
||
o usare label distinte). Atteso: PASS.
|
||
|
||
---
|
||
|
||
## Passo 5 — Installare i timer systemd (B5)
|
||
|
||
**Obiettivo**: attivare le coppie `.service`+`.timer` già committate
|
||
in `deploy/systemd/` per replicare i task periodici di
|
||
`Register-CIScheduledTasks.ps1`.
|
||
|
||
- [ ] Copiare le unit:
|
||
|
||
```bash
|
||
cd /opt/ci/local-ci-cd-system
|
||
sudo cp deploy/systemd/ci-*.service deploy/systemd/ci-*.timer /etc/systemd/system/
|
||
sudo systemctl daemon-reload
|
||
```
|
||
|
||
- [ ] Abilitare e avviare tutti i timer:
|
||
|
||
```bash
|
||
for t in ci-cleanup-orphans ci-retention-policy \
|
||
ci-watch-disk-space ci-watch-runner-health \
|
||
ci-backup-template; do
|
||
sudo systemctl enable --now "${t}.timer"
|
||
done
|
||
```
|
||
|
||
- [ ] Verificare lo schedule:
|
||
|
||
```bash
|
||
systemctl list-timers --all 'ci-*'
|
||
```
|
||
|
||
Atteso: 5 timer in stato `active`.
|
||
|
||
- [ ] Trigger manuale di ciascun service per validare l'esecuzione
|
||
one-shot:
|
||
|
||
```bash
|
||
for s in ci-cleanup-orphans ci-watch-disk-space ci-watch-runner-health; do
|
||
sudo systemctl start "${s}.service"
|
||
sudo systemctl status "${s}.service" --no-pager
|
||
done
|
||
```
|
||
|
||
> `ci-retention-policy` e `ci-backup-template` chiamano `pwsh`:
|
||
> eseguirli solo dopo aver verificato che `pwsh --version` funzioni
|
||
> sotto user `ci-runner`.
|
||
|
||
- [ ] Per maggiori dettagli (mapping Windows→Linux, troubleshooting,
|
||
rollback) vedi `deploy/systemd/README.md`.
|
||
|
||
---
|
||
|
||
## Passo 6 — Cutover (B6)
|
||
|
||
**Obiettivo**: spostare la produzione dall'host Windows a Linux in una
|
||
finestra di manutenzione concordata.
|
||
|
||
> ⚠️ Eseguire solo dopo che i Passi 1–5 sono tutti `[x]` PASS.
|
||
|
||
- [ ] Annunciare la finestra di manutenzione (durata stimata: 30–60 min).
|
||
- [ ] Verificare nessun job in coda lato Gitea (Admin → Actions → Tasks).
|
||
- [ ] **Stop** act_runner sull'host Windows:
|
||
|
||
```powershell
|
||
Stop-Service actions-runner
|
||
Get-Service actions-runner # atteso: Stopped
|
||
```
|
||
|
||
- [ ] **Disabilitare** scheduled task Windows:
|
||
|
||
```powershell
|
||
Get-ScheduledTask -TaskName 'CI-*' | Unregister-ScheduledTask -Confirm:$false
|
||
```
|
||
|
||
- [ ] Rsync incrementale finale degli artifact:
|
||
|
||
```bash
|
||
sudo -u ci-runner rsync -av --delete \
|
||
user@windows-host:/cygdrive/f/CI/Artifacts/ \
|
||
/var/lib/ci/artifacts/
|
||
```
|
||
|
||
- [ ] Sbloccare il runner Linux su Gitea UI (rimuovere `paused` o
|
||
ripristinare le label di produzione `windows-build:host,linux-build:host`).
|
||
- [ ] Verificare runner Linux online su Gitea UI.
|
||
- [ ] Smoke trigger:
|
||
- [ ] `self-test.yml` → PASS dal runner Linux
|
||
- [ ] `build-ns7zip.yml` matrix Win+Linux → PASS dal runner Linux
|
||
- [ ] Monitorare per ≥30 min:
|
||
|
||
```bash
|
||
sudo journalctl -u act-runner -f --since "30min ago"
|
||
```
|
||
|
||
Nessun errore di severità critica atteso.
|
||
|
||
> **Rollback (entro 30 min se PASS critico fallisce)**:
|
||
> 1. `sudo systemctl stop act-runner` su Linux
|
||
> 2. `Start-Service actions-runner` su Windows
|
||
> 3. Re-registrare scheduled task con `scripts\Register-CIScheduledTasks.ps1`
|
||
> 4. Documentare incidente in `TODO.md` e tornare a B1–B5 per fix
|
||
|
||
---
|
||
|
||
## Passo 7 — Capacity burn-in (B7)
|
||
|
||
**Obiettivo**: validare il carico target con tempi paragonabili al
|
||
baseline Windows (entro ±20%).
|
||
|
||
- [ ] Burn-in 4 job concorrenti × 10 round su `WinBuild2025`
|
||
(lo script `Test-CapacityBurnIn.ps1` ora delega via shim alla CLI
|
||
Python `job` e gira anche da `pwsh` su Linux):
|
||
|
||
```bash
|
||
pwsh /opt/ci/local-ci-cd-system/scripts/Test-CapacityBurnIn.ps1 \
|
||
-Concurrency 4 -Rounds 10 -Template /var/lib/ci/templates/WinBuild2025/WinBuild2025.vmx
|
||
```
|
||
|
||
- [ ] Burn-in 4 × 10 su `LinuxBuild2404` (analogo, `--Template`
|
||
sul VMX Linux).
|
||
- [ ] Misurare:
|
||
- [ ] Tempo medio per job, confronto con baseline A5
|
||
- [ ] Tutti i 80 job (2 × 4 × 10) PASS
|
||
- [ ] Zero VM orfane in `/var/lib/ci/build-vms/`:
|
||
|
||
```bash
|
||
sudo -u ci-runner /opt/ci/venv/bin/python -m ci_orchestrator vm cleanup --what-if
|
||
```
|
||
|
||
- [ ] Spazio disco `/var/lib/ci/build-vms/` torna al baseline post-cleanup
|
||
- [ ] Documentare i risultati in `docs/RUNBOOK.md` (sezione "Linux
|
||
host baseline").
|
||
- [ ] Se delta > 20% vs baseline Windows: aprire issue in `TODO.md`
|
||
con dettagli per profiling (probabile candidato: filesystem ext4
|
||
vs NTFS — valutare XFS/BTRFS).
|
||
|
||
---
|
||
|
||
## Passo 8 — Stabilità ≥1 settimana
|
||
|
||
**Obiettivo**: verificare ≥1 settimana di esercizio Linux senza
|
||
incidenti critici. (NB: non è più gate per una dismissione Windows —
|
||
vedi Passo 9: host Windows mantenuto in permanenza.)
|
||
|
||
- [ ] Esercizio normale per ≥7 giorni con runner Linux primario.
|
||
- [ ] Verifica giornaliera (bastano 2 minuti):
|
||
|
||
```bash
|
||
sudo systemctl --failed # nessun service in failed
|
||
systemctl list-timers --all 'ci-*' # tutti gli ultimi run OK
|
||
sudo journalctl -u act-runner --since "24h ago" -p err
|
||
```
|
||
|
||
- [ ] Nessun rollback effettuato durante la settimana.
|
||
|
||
---
|
||
|
||
## Passo 9 — ~~Decommissioning host Windows~~ — ANNULLATO
|
||
|
||
> 🚫 **VINCOLO CATEGORICO: l'host Windows NON va dismesso.** Resta un
|
||
> target supportato di prima classe in permanenza (run dual-host
|
||
> Win+Linux), non solo rollback. Niente `shutdown` definitivo, niente
|
||
> riallocazione hardware che tolga la capacità Windows. Questo step è
|
||
> mantenuto solo come record storico.
|
||
|
||
- [ ] (Facoltativo, igiene) Backup periodico di `F:\CI\` su archivio
|
||
esterno:
|
||
|
||
```powershell
|
||
$stamp = Get-Date -Format 'yyyyMMdd'
|
||
$archive = "E:\Backup\CI-$stamp.tar"
|
||
& 'C:\Program Files\Git\usr\bin\tar.exe' -cf $archive 'F:\CI\'
|
||
Get-FileHash $archive -Algorithm SHA256 | Tee-Object "$archive.sha256"
|
||
```
|
||
|
||
- [ ] Host Windows **resta installato e operativo** (uso dual-host).
|
||
- [ ] Aggiornare `docs/RUNBOOK.md` documentando l'uso di **entrambi**
|
||
gli host (Windows + Linux), non una procedura di dismissione.
|
||
- [ ] ~~Spegnere/riallocare host Windows~~ — NON applicabile.
|
||
|
||
---
|
||
|
||
## Tracciamento globale
|
||
|
||
| Passo | Step | Descrizione | Stato |
|
||
| ----- | ---- | -------------------------------------------------- | ----- |
|
||
| 1 | B1 | Setup host Linux Mint (OS, Workstation, venv, ACL) | [x] |
|
||
| 2 | B2 | Trasferimento template VM + smoke `vm new` | [~] transfer fatto; smoke test pendente |
|
||
| 3 | B3 | Chiavi SSH + keyring (PoC headless) | [ ] |
|
||
| 4 | B4 | act_runner systemd service registrato | [ ] |
|
||
| 5 | B5 | Timer systemd installati e attivi | [ ] |
|
||
| 6 | B6 | Cutover (Linux primario, Windows resta operativo) | [ ] |
|
||
| 7 | B7 | Capacity burn-in 4 × 10 (Win + Linux) | [ ] |
|
||
| 8 | — | ≥1 settimana di stabilità | [ ] |
|
||
| 9 | B8 | ~~Decommissioning Windows~~ ANNULLATO (dual-host) | [x] |
|
||
|
||
> **Vincolo categorico**: host Windows supportato in permanenza
|
||
> (dual-host), mai dismesso. Fase B = Linux **in aggiunta**, non al
|
||
> posto di Windows.
|
||
|
||
Quando i passi 1-8 sono `[x]`, la **Fase B è chiusa** (B8 annullato per
|
||
vincolo) e si può valutare l'apertura della Fase C (backend ESXi, vedi
|
||
`plans/idea-3-esxi-support.md`).
|