docs: update documentation for Linux VM support (Sprint 9)
AGENTS.md (new): - Environment reference for AI agents: host specs, PS 5.1 constraints, dir structure, VM templates, transport layer, style rules - Lessons #9 (snapshot cold state) and #10 (vmrun list vs getGuestIPAddress) ARCHITECTURE.md: - Add SSH/SCP transport section (Linux VMs) - Update system diagram to include _Transport.psm1, SSH transport path - Network layout: add SSH port 22 for Linux VMs - Timeline: Linux readiness check phases documented CI-FLOW.md: - Prerequisites table: add Template VM (Linux), SSH key row - Step 6 (readiness): document Windows vs Linux phases - Step 7 (build) and Step 8 (artifacts): document Linux/SSH paths - ci-report-ip guestinfo mechanism referenced HOST-SETUP.md: - Directory tree: add LinuxBuild2404 template dir and keys/ - Post-setup checklist: add step 5 (SSH key generation + Linux template) - Fix duplicate step numbering (56, 67) - Reference Paths table: add Linux template VMX, snapshot, SSH key LINUX-TEMPLATE-SETUP.md: - Rewritten as implementation record (no longer a plan) - Fase A user-data: minimal (user+SSH key only, no packages/runcmd) - All phases marked complete with actual paths and snapshot names WINDOWS-TEMPLATE-SETUP.md: minor updates for consistency TODO.md: - Summary: update last-updated to 2026-05-11, Sprint 9 description - Linux Build VM row: all 5 items complete - Prossimi passi: Test Plan + §6.6 Tier-2 as next priorities
This commit is contained in:
Simone
@@ -0,0 +1,154 @@
|
||||
# AGENTS.md — Environment Reference
|
||||
|
||||
Questo file descrive l'ambiente su cui e' costruito il progetto.
|
||||
Leggerlo prima di generare o modificare qualsiasi script.
|
||||
|
||||
> **Istruzione per gli agenti**: questo file va tenuto aggiornato.
|
||||
> Se durante il lavoro si scopre un errore nuovo, un vincolo non documentato,
|
||||
> un pattern che ha causato problemi o una best-practice utile, aggiungerla
|
||||
> nella sezione "Errori frequenti da evitare" o in una sezione apposita.
|
||||
> Non aggiungere dettagli ovvi o gia' coperti; solo informazioni che
|
||||
> impedirebbero errori concreti in sessioni future.
|
||||
|
||||
---
|
||||
|
||||
## Host
|
||||
|
||||
| Parametro | Valore |
|
||||
| ------------------ | ----------------------------------------------------------------------- |
|
||||
| OS | Windows 11 |
|
||||
| Hardware | i9-10900X, 64 GB RAM, NVMe SSD |
|
||||
| PowerShell | **5.1** (Windows PowerShell — NON Core/7) |
|
||||
| VMware Workstation | Pro, `vmrun.exe` in `C:\Program Files (x86)\VMware\VMware Workstation\` |
|
||||
| SSH client | `ssh.exe` / `scp.exe` built-in Windows 11 (PATH) |
|
||||
| act_runner | v1.0.2 — `F:\CI\act_runner\act_runner.exe` |
|
||||
| Gitea | `http://10.10.20.11:3100` / `https://gitea.emulab.it` |
|
||||
|
||||
---
|
||||
|
||||
## PowerShell 5.1 — Vincoli critici
|
||||
|
||||
Tutti gli script devono girare su **Windows PowerShell 5.1**. Le seguenti
|
||||
sintassi sono disponibili solo in PS 7+ e NON vanno usate:
|
||||
|
||||
| Costrutto PS 7+ | Alternativa PS 5.1 corretta |
|
||||
| ------------------------- | ----------------------------------------- |
|
||||
| `$x ??= 'default'` | `if ($null -eq $x) { $x = 'default' }` |
|
||||
| `$a ?? $b` | `if ($null -ne $a) { $a } else { $b }` |
|
||||
| `cmd1 && cmd2` | `cmd1; if ($LASTEXITCODE -eq 0) { cmd2 }` |
|
||||
| `cmd1 \|\| cmd2` | `cmd1; if ($LASTEXITCODE -ne 0) { cmd2 }` |
|
||||
| `$x is [int]` | `$x -is [int]` |
|
||||
| Ternary `$a ? $b : $c` | `if ($a) { $b } else { $c }` |
|
||||
| `foreach-object` con `&&` | pipeline classico con `-ErrorAction Stop` |
|
||||
|
||||
Ogni script deve avere in testa:
|
||||
|
||||
```powershell
|
||||
#Requires -Version 5.1
|
||||
Set-StrictMode -Version Latest
|
||||
$ErrorActionPreference = 'Stop'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Struttura directory host (fissa)
|
||||
|
||||
```
|
||||
F:\CI\
|
||||
act_runner\ — binario e stato act_runner
|
||||
Templates\
|
||||
WinBuild2025\ — template Windows Server 2025
|
||||
WinBuild2022\ — template Windows Server 2022
|
||||
LinuxBuild2404\ — template Ubuntu 24.04
|
||||
BuildVMs\ — clone efimeri (creati/distrutti per ogni job)
|
||||
Artifacts\ — artifact raccolti (per job-id)
|
||||
ISO\ — ISO/VMDK di bootstrap (cache download)
|
||||
keys\
|
||||
ci_linux — chiave SSH privata per guest Linux (no passphrase)
|
||||
ci_linux.pub — chiave pubblica corrispondente
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## VM Template
|
||||
|
||||
### Windows (WinBuild2025 — primario)
|
||||
|
||||
| Parametro | Valore |
|
||||
| -------------- | ------------------------------------------------------------------------------- |
|
||||
| OS | Windows Server 2025 |
|
||||
| VMX | `F:\CI\Templates\WinBuild2025\WinBuild2025.vmx` |
|
||||
| Snapshot clone | `BaseClean` |
|
||||
| Transport | WinRM HTTPS porta 5986, cert self-signed (lab-only) |
|
||||
| Credenziali | Windows Credential Manager target `BuildVMGuest` |
|
||||
| Rete | VMnet8 NAT — `192.168.79.0/24` |
|
||||
| Toolchain | VS Build Tools 2026 (MSBuild 18.5 / v145), .NET SDK 10, Python 3.13, Git, 7-Zip |
|
||||
|
||||
Variante **WinBuild2022**: path `F:\CI\Templates\WinBuild2022\WinBuild2022.vmx`, stesso snapshot `BaseClean`.
|
||||
|
||||
### Linux (LinuxBuild2404)
|
||||
|
||||
| Parametro | Valore |
|
||||
| -------------- | ------------------------------------------------------------- |
|
||||
| OS | Ubuntu 24.04 LTS (cloud image) |
|
||||
| VMX | `F:\CI\Templates\LinuxBuild2404\LinuxBuild2404.vmx` |
|
||||
| Snapshot clone | `BaseClean-Linux` |
|
||||
| Transport | SSH porta 22, utente `ci_build`, chiave `F:\CI\keys\ci_linux` |
|
||||
| Rete | VMnet8 NAT — `192.168.79.0/24` |
|
||||
| Toolchain | GCC, G++, Clang, CMake, Ninja, Python 3, Git, 7-Zip |
|
||||
| CI dirs | `/opt/ci/{build,output,scripts,cache}` — owner `ci_build` |
|
||||
|
||||
---
|
||||
|
||||
## Transport layer
|
||||
|
||||
- **Windows guest**: WinRM (`New-PSSession` con `New-CISessionOption` da `_Common.psm1`).
|
||||
Usare `Invoke-Command -Session`, `Copy-Item -ToSession / -FromSession`.
|
||||
- **Linux guest**: SSH/SCP via `ssh.exe` / `scp.exe`.
|
||||
Usare le funzioni di `scripts/_Transport.psm1`:
|
||||
`Invoke-SshCommand`, `Copy-SshItem`, `Test-SshReady`.
|
||||
- **vmrun.exe**: sempre invocato tramite `Invoke-Vmrun` da `_Common.psm1`
|
||||
(wrapper uniforme che gestisce `$LASTEXITCODE` e output).
|
||||
|
||||
NON modificare il branch WinRM esistente quando si lavora sul branch Linux e viceversa.
|
||||
|
||||
---
|
||||
|
||||
## act_runner / Gitea Actions
|
||||
|
||||
- Labels runner: `windows-build:host`, `linux-build:host`
|
||||
- Env vars iniettate in ogni job (da `runner/config.yaml`):
|
||||
- `GITEA_CI_TEMPLATE_PATH` — VMX Windows template
|
||||
- `GITEA_CI_LINUX_TEMPLATE_PATH` — VMX Linux template
|
||||
- `GITEA_CI_CLONE_BASE_DIR` — `F:\CI\BuildVMs`
|
||||
- `GITEA_CI_ARTIFACT_DIR` — `F:\CI\Artifacts`
|
||||
- `GITEA_CI_GUEST_CRED_TARGET` — `BuildVMGuest`
|
||||
- `GITEA_CI_SSH_KEY_PATH` — `F:\CI\keys\ci_linux`
|
||||
|
||||
---
|
||||
|
||||
## Regole di stile (PSScriptAnalyzer)
|
||||
|
||||
Configurazione in `PSScriptAnalyzerSettings.psd1`. Regole principali:
|
||||
|
||||
- Indentazione: **4 spazi** (no tab)
|
||||
- `Write-Host` e' permesso (output catturato da act_runner; `Write-Output` interferisce con i return value)
|
||||
- `Invoke-Expression` vietato
|
||||
- Funzioni state-changing devono supportare `-WhatIf` / `ShouldProcess`
|
||||
- Credenziali solo come `[PSCredential]`, mai plain-text string
|
||||
- Nessuna variabile globale (`$global:`)
|
||||
|
||||
---
|
||||
|
||||
## Errori frequenti da evitare
|
||||
|
||||
1. **Sintassi PS 7+** in script PS 5.1 — vedi tabella sopra.
|
||||
2. **`$LASTEXITCODE` non controllato** dopo `vmrun`, `ssh`, `scp` — controllare sempre e fare `throw` se non zero.
|
||||
3. **Percorsi hardcoded senza parametro** — ogni path critico deve avere un parametro con default documentato.
|
||||
4. **Modificare entrambi i branch (WinRM e SSH) nello stesso script** — mantenerli separati con `if ($GuestOS -eq 'Linux')`.
|
||||
5. **Usare `New-PSSession` / WinRM verso host Linux** — Linux usa solo SSH tramite `_Transport.psm1`.
|
||||
6. **Non rimuovere il seed ISO dal VMX** dopo il primo boot Linux — `ide1:0.present = "FALSE"` deve essere settato dopo cloud-init.
|
||||
7. **`[ordered]@{}` non disponibile in PS 2** — non e' un problema qui (PS 5.1), ma ricordare che `[ordered]` e' PS 3+.
|
||||
8. **`ForEach-Object -Parallel`** — disponibile solo in PS 7+; usare `foreach` classico o `Start-Job`.
|
||||
9. **Snapshot template catturato con VM accesa** — produce file `*.vmem` / `*.vmsn` con memoria; `vmrun clone ... linked -snapshot=<name>` rifiuta con `Error: The virtual machine should not be powered on. It is already running.` anche se `vmrun list` mostra 0 VM. Catturare snapshot SOLO da stato fully powered-off (verificare assenza di `.vmem` nella dir template).
|
||||
10. **`vmrun getGuestIPAddress` per check "VM running"** — richiede VMware Tools attivi nel guest; in headless Tools puo' impiegare 30-60s a rispondere e il check appare bloccato. Usare `vmrun list` e cercare il path del VMX nell'output.
|
||||
Reference in New Issue
Block a user