Simone/local-ci-cd-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
536fd688e833aeea99399faa56c1347445698e5e
local-ci-cd-system/plans/PhaseB-user-checklist.md
T

18 KiB
Raw Blame History

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.

  • Installare Linux Mint LTS sull'hardware target.

  • sudo apt update && sudo apt full-upgrade -y && sudo reboot

  • Scaricare e installare VMware Workstation Pro Linux (bundle .bundle da Broadcow):

    sudo bash VMware-Workstation-Full-*.bundle
vmrun -T ws --version    # deve ritornare versione coerente

  • Smoke test Workstation (UI): creare VM trivia, clone, start, stop, delete.

  • Configurare vmnet8 NAT range 192.168.79.0/24 (allineato a Windows) editando /etc/vmware/vmnet8/dhcpd/dhcpd.conf o via vmware-netcfg.

  • Creare utente di servizio ci-runner:

    sudo useradd -r -m -s /bin/bash ci-runner

  • Eseguire setup-host-linux.sh (copre mount disco, layout, Python venv, clone repo, PowerShell Core):

    # 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:

    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.

  • Sull'host Windows:

    Get-ChildItem 'F:\CI\Templates' -Recurse -Include *.vmem,*.vmsn
# atteso: nessun risultato

  • 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):

    sudo -u ci-runner rsync -av --progress \
  user@windows-host:/cygdrive/f/CI/Templates/ \
  /var/lib/ci/templates/

  • Validare integrità snapshot:

    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.

  • 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 è:

    # 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:

    # 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.

  • Chiavi SSH guest Linux già presenti in /var/lib/ci/keys/ (copiate insieme ai template). Correggere solo i permessi:

    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/

  • 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:

    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

  • Re-store Gitea PAT con lo stesso schema:

    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

  • 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.

  • Scaricare il binario act_runner Linux ≥ v1.0.4:

    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

  • Generare token registrazione su Gitea (Admin → Runners → Create new runner).

  • Registrare il runner (sostituire <TOKEN>):

    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.

  • Creare /etc/systemd/system/act-runner.service:

    [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 --config /var/lib/ci/runner/config.yaml
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

  • Creare /etc/ci/environment (letto dalle unit dei task periodici di B5; vedi deploy/systemd/README.md):

    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

  • Generare e configurare config.yaml del runner:

    # 1. Generare il file di default (conserva la registrazione in .runner)
sudo -u ci-runner /opt/ci/act_runner/act_runner generate-config \
  | sudo -u ci-runner tee /var/lib/ci/runner/config.yaml > /dev/null

# 2. Sostituire le righe di esempio nella sezione runner.envs con le variabili CI
#    (generate-config scrive due righe A_TEST_ENV_NAME_* come placeholder)
sudo -u ci-runner sed -i \
  -e 's/    A_TEST_ENV_NAME_1: a_test_env_value_1/    CI_PYTHON_LAUNCHER: \/opt\/ci\/venv\/bin\/python/' \
  -e 's/    A_TEST_ENV_NAME_2: a_test_env_value_2/    GITEA_CI_TEMPLATE_PATH: \/var\/lib\/ci\/templates\/WinBuild2025\/WinBuild2025.vmx\n    GITEA_CI_LINUX_TEMPLATE_PATH: \/var\/lib\/ci\/templates\/LinuxBuild2404\/LinuxBuild2404.vmx/' \
  /var/lib/ci/runner/config.yaml

# 3. Verificare il risultato
grep -A4 'envs:' /var/lib/ci/runner/config.yaml

    Atteso:

      envs:
    CI_PYTHON_LAUNCHER: /opt/ci/venv/bin/python
    GITEA_CI_TEMPLATE_PATH: /var/lib/ci/templates/WinBuild2025/WinBuild2025.vmx
    GITEA_CI_LINUX_TEMPLATE_PATH: /var/lib/ci/templates/LinuxBuild2404/LinuxBuild2404.vmx

    Le variabili di sistema (CI_ROOT, PYTHONIOENCODING, ecc.) restano nel service unit. runner.envs è per la configurazione specifica del runner CI (path template, launcher Python).

    # 4. Ricaricare e riavviare
sudo systemctl daemon-reload
sudo systemctl restart act-runner.service
sudo journalctl -u act-runner -n 20    # confermare avvio OK

  • Smoke job: triggerare manualmente self-test.yml selezionando il runner Linux (mettere temporaneamente in pausa quello Windows o usare label distinte). Atteso: PASS.

    ⚠️ Prerequisito: le variabili GITEA_CI_TEMPLATE_PATH e GITEA_CI_LINUX_TEMPLATE_PATH devono essere presenti nel service unit prima di avviare lo smoke test, altrimenti il job fallisce con "Got unexpected extra argument".

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:

    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:

    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:

    systemctl list-timers --all 'ci-*'

    Atteso: 5 timer in stato active.

  • Trigger manuale di ciascun service per validare l'esecuzione one-shot:

    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:

    Stop-Service actions-runner
Get-Service actions-runner    # atteso: Stopped

  • Disabilitare scheduled task Windows:

    Get-ScheduledTask -TaskName 'CI-*' | Unregister-ScheduledTask -Confirm:$false

  • Rsync incrementale finale degli artifact:

    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:

    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):

    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/:

      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):

    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:

    $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).

Reference in New Issue View Git Blame Copy Permalink