local-ci-cd-system/docs/postmortem-2026-06-06-linux-template-no-ip.md

Postmortem — Template Linux: deploy/prepare "no IP" (2026-06-06)

Sintesi

Durante l'aggiunta di dipendenze GUI al toolchain del template Linux (python3-gi gir1.2-gtk-4.0 xvfb), una serie di fallimenti ha aperto una lunga sessione di debug. Sono emersi due problemi distinti, più una causa ambientale che ha confuso la diagnosi:

1. Origine reale della sessione — prepare-linux falliva allo Step 4a con Unable to locate package gir1.2-gtk-4.0. Causa: --skip-update saltava anche apt-get update, lasciando l'indice apt vecchio. Non c'entrava la rete. Fix banale, applicato.

2. Bug deploy-linux --force — il resize allo Step 4 falliva con "disk is part of a snapshot chain" perché --force riusava la directory senza rimuovere la snapshot chain precedente. Bug deterministico, colpito due volte. Fix applicato.

3. Saga "no IP" (ambientale) — il rilevamento IP via open-vm-tools andava in timeout in modo intermittente. Causa finale: il servizio DHCP/NAT di vmnet8 sull'host si era inceppato a causa della churn di debug (decine di vmrun start/stop, tcpdump promiscuo, DISCOVER ripetuti del guest). Risolto con un restart di vmware-networks. Non è un bug del codice né del CI normale.

Stato finale: template BaseClean-Linux ricostruito da powered-off, con gtk/xvfb e cloud-init sigillato. Tutti i test passano (coverage 94.4%).

---

Cronologia

Ora (host)	Evento
~10:50	prepare-linux --skip-update → fallisce allo Step 4a (gir1.2-gtk-4.0 non trovato) per indice apt stale
~11:00	Dopo fix apt + revert snapshot: prepare-linux riesce, guest ottiene IP .153, snapshot ripreso
~11:03+	I boot successivi dello snapshot non ottengono IP utile → inizio debug rete
11:20	Cattura sul filo: DHCP OFFER/ACK presenti, ma il guest non applica l'IPv4
12:06	Deploy fresco: il guest ottiene .143 (cloud-init), ma deploy Step 7 va in timeout sui tools
12:26	Reboot: stesso guest non ottiene IP (intermittenza)
~12:30	vmware-networks --stop/--start → l'IP torna stabile. Sblocco confermato
dopo	Implementati e testati i fix; template rigenerato

---

Analisi cause

2.1 Step 4a apt (origine della sessione)

Install-CIToolchain-Linux2404.sh faceva apt-get update solo se non era passato --skip-update. Ma --skip-update dovrebbe saltare il solo upgrade (lento), non il refresh dell'indice. Con indice vecchio, i pacchetti nuovi (gir1.2-gtk-4.0, xvfb) non venivano trovati.

A riprova che a quel punto la rete funzionava: quel prepare-linux era entrato in SSH nel guest senza problemi.

2.2 deploy-linux --force e la snapshot chain

deploy-linux --force riusa la directory della VM ma non rimuoveva gli artefatti di un'eventuale snapshot precedente (-NNNNNN.vmdk, .vmsn, .vmsd). Con la chain presente, vmware-vdiskmanager rifiuta il resize dello Step 4:

This disk is part of a snapshot chain in '.../LinuxBuild2404.vmx'.
The selected operation can only be executed on a disk with no snapshots.

2.3 La saga "no IP" — vmnet8 DHCP inceppato

Sintomo: vmrun getGuestIPAddress → "VMware Tools are not running" / "Unable to get the IP address", in modo intermittente. Il guest in realtà:

• bootava correttamente (login prompt),
• aveva open-vm-tools installato e attivo,
• ma systemd-networkd a volte non applicava un lease DHCPv4 (link up, solo IPv6LL, networkd-wait-online in timeout).

Sul filo il DHCP a volte completava (.143 applicato e raggiungibile), a volte no. Il server rispondeva (altre VM ottenevano lease). La causa finale: il demone vmnet-dhcpd/vmnet-natd di vmnet8 era andato in uno stato degradato dopo la churn di debug. Il restart vmware-networks --stop/--start lo ha sbloccato e l'IP è tornato stabile e immediato.

Ipotesi scartate (vicoli ciechi)

• Controller pvscsi vs lsilogic — il boot funzionava con pvscsi; irrilevante.
• Naming NIC ens192 vs ens160 — cloud-init si adattava; l'IP arrivava lo stesso quando la rete funzionava.
• Saturazione del pool DHCP — il pool era di fatto libero (0 lease attivi); i MAC multipli per IP nel lease DB sono storia normale di ISC dhcpd.
• Seal cloud-init / machine-id — difensivi ma non erano la causa del no-IP.

---

Fix applicati (branch fix/linux-template-toolchain-deploy)

Commit 1 — toolchain

template/Install-CIToolchain-Linux2404.sh

• Step 4a: installa python3-gi gir1.2-gtk-4.0 xvfb con assert su import gi e Xvfb (richiesta originale).
• Step 1: apt-get update ora gira sempre; --skip-update salta solo l'upgrade. Risolve il fallimento Step 4a.

Commit 2 — robustezza deploy/prepare

src/ci_orchestrator/commands/template.py (+ test)

• _clean_force_artifacts: con --force rimuove snapshot delta, .vmsn, .vmsd e .lck prima del resize → niente più errore snapshot-chain. Coperto da 3 unit test.
• prepare-linux Step 7d (seal cloud-init): rimuove la 50-cloud-init.yaml stale, rigenera netplan (resta solo il 99-ci-dhcp-allnics MAC-agnostic), disabilita cloud-init (/etc/cloud/cloud-init.disabled) così non rigira sui cloni.
• deploy user-data: package_update/upgrade: false per non tenere il lock dpkg al primo boot e non ritardare open-vm-tools oltre il poll dello Step 7.
• Step 7 timeout: 300s → 600s come rete di sicurezza per primi boot lenti.

Verifica: ruff ✅, mypy --strict (23 file) ✅, suite completa ✅, coverage 94.4% (gate 90%). Prod venv reinstallato (non-editable).

---

Procedura di recovery: deploy/prepare non ottiene IP

Quando deploy-linux (Step 7) o prepare-linux non riescono a rilevare l'IP ma il guest sembra sano (booting, tools attivi), prima di sospettare immagine o codice, riavvia il networking VMware sull'host:

sudo /usr/bin/vmware-networks --stop
sudo /usr/bin/vmware-networks --start

Flush opzionale dei lease (backup prima), solo se nessuna VM è accesa:

sudo cp /etc/vmware/vmnet8/dhcpd/dhcpd.leases /tmp/dhcpd.leases.bak
sudo sh -c ': > /etc/vmware/vmnet8/dhcpd/dhcpd.leases'

Distinto da:

• Tools-not-running sul template → revert a BaseClean-Linux (vedi template-live-state-recovery).
• vmmon/vmnet non compilati dopo bump kernel → il guard systemd ricostruisce i moduli al boot (vedi vmware-modules-kernel-upgrade).

---

Raccomandazioni (NON applicate di proposito)

Cosa NON fare

• Restart/flush automatico ad ogni clone/deploy/prepare. vmware-networks è globale (bridge + hostonly + NAT insieme): un restart sotto un job in corso rompe la rete di tutte le VM in esecuzione → job concorrenti falliti. Il flush dei lease con VM attive causa conflitti IP al rinnovo. Sproporzionato rispetto a un problema non dimostrato ricorrente.

Cosa fare

• Monitorare. L'inceppamento è nato dalla churn anomala di debug, non dal CI normale. Tenere la recovery manuale e agire solo se ricapita con dati reali.

Se servisse hardening preventivo (a freddo, con cautela)

• Abbassare max-lease-time (i cloni vivono minuti → IP liberati in fretta; i job lunghi rinnovano da soli via networkd).
• Allargare il range DHCP per più margine.
• Caveat: /etc/vmware/vmnet8/dhcpd/dhcpd.conf è auto-generato da VMware ("DO NOT MODIFY", validato con CFG_HASH in /etc/vmware/networking). Edit a mano fragili: rischio rigenerazione al prossimo --configure/update. Da fare solo se il problema si dimostra ricorrente.

---

Lezioni

• L'attività di debug intensa sulla rete host (start/stop ripetuti, sniffing promiscuo) può degradare vmnet-dhcpd: in futuro, minimizzare la churn e preferire osservazione mirata.
• Tre cause distinte si sono sovrapposte; separarle prima ha richiesto tempo. Il guest era fondamentalmente sano per quasi tutta la sessione — l'errore di rilevamento IP non implicava un guest rotto.
• Non sovrastimare: i fix committati coprono i bug veri e provati; il DHCP è stato lasciato invariato per evitare over-engineering.