Simone/local-ci-cd-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(runbook): fix §3 job example — required template flags

Browse Source 
The `job` command enforces --template-path (job.py:447) and defaults
--snapshot-name to BaseClean, which is wrong for Linux. The §3 example
omitted both and failed with "--template-path is required". Add both
flags (BaseClean-Linux) and note them as required.
This commit is contained in:
Simone
2026-06-08 21:37:24 +02:00
parent 027e2ff4b6
commit 9ecb767b18
1 changed files with 49 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/RUNBOOK-PhaseC.md
+11 -4
View File
@@ -48,7 +48,7 @@ sudo); `--uninstall` removes the block. The script defines two helpers:
### 0.3 The live environment ### 0.3 The live environment
| Item | Value | | Item | Value |
| ------------------ | ---------------------------------------------------------------------------------- | | ------------------ | -------------------------------------------------------------------------------------- |
| Service user | `ci-runner` · production venv `/opt/ci/venv/bin/python` | | Service user | `ci-runner` · production venv `/opt/ci/venv/bin/python` |
| Configuration | `/var/lib/ci/config.toml` | | Configuration | `/var/lib/ci/config.toml` |
| Linux template | `/var/lib/ci/templates/LinuxBuild2404/LinuxBuild2404.vmx` (snapshot `BaseClean-Linux`) | | Linux template | `/var/lib/ci/templates/LinuxBuild2404/LinuxBuild2404.vmx` (snapshot `BaseClean-Linux`) |
@@ -61,7 +61,7 @@ sudo); `--uninstall` removes the block. The script defines two helpers:
## 1. Command index ## 1. Command index
| Command | Purpose | Section | | Command | Purpose | Section |
| ----------------------------- | --------------------------------------------- | ------- | | ----------------------------- | ---------------------------------------------------- | --------------------------------------------------- |
| `ci validate host` | Check host prerequisites (no VM) | [§2](#2-health-monitoring--reporting) | | `ci validate host` | Check host prerequisites (no VM) | [§2](#2-health-monitoring--reporting) |
| `ci validate guest --host IP` | Probe a running guest's transport | [§2](#2-health-monitoring--reporting) | | `ci validate guest --host IP` | Probe a running guest's transport | [§2](#2-health-monitoring--reporting) |
| `ci monitor disk` | Free-space alert | [§2](#2-health-monitoring--reporting) | | `ci monitor disk` | Free-space alert | [§2](#2-health-monitoring--reporting) |
@@ -137,6 +137,9 @@ IP=$(sudo -u ci-runner vmrun getGuestIPAddress /var/lib/ci/templates/LinuxBuild2
ci validate guest --host "$IP" --ssh --guest-os linux ci validate guest --host "$IP" --ssh --guest-os linux
# Windows guest over WinRM # Windows guest over WinRM
IP=$(sudo -u ci-runner vmrun getGuestIPAddress /var/lib/ci/templates/WinBuild2022/WinBuild2022.vmx)
ci validate guest --host "$IP" --winrm --guest-os windows
IP=$(sudo -u ci-runner vmrun getGuestIPAddress /var/lib/ci/templates/WinBuild2025/WinBuild2025.vmx) IP=$(sudo -u ci-runner vmrun getGuestIPAddress /var/lib/ci/templates/WinBuild2025/WinBuild2025.vmx)
ci validate guest --host "$IP" --winrm --guest-os windows ci validate guest --host "$IP" --winrm --guest-os windows
``` ```
@@ -179,6 +182,8 @@ by hand too.
```bash ```bash
ci job \ ci job \
--job-id manual-$(date +%s) \ --job-id manual-$(date +%s) \
--template-path /var/lib/ci/templates/LinuxBuild2404/LinuxBuild2404.vmx \
--snapshot-name BaseClean-Linux \
--repo-url https://gitea.emulab.it/Simone/myrepo.git \ --repo-url https://gitea.emulab.it/Simone/myrepo.git \
--branch main \ --branch main \
--guest-os linux \ --guest-os linux \
@@ -186,7 +191,9 @@ ci job \
--use-git-clone --use-git-clone
``` ```
`--job-id`, `--repo-url`, and `--branch` are required. Other useful flags: `--job-id`, `--repo-url`, `--branch`, and `--template-path` are required. The
default `--snapshot-name` is `BaseClean`, so Linux jobs must pass
`--snapshot-name BaseClean-Linux` explicitly. Other useful flags:
- **Source**: `--commit`, `--submodules` / `--no-submodules`, - **Source**: `--commit`, `--submodules` / `--no-submodules`,
`--use-git-clone` / `--host-clone`, `--use-shared-cache` `--use-git-clone` / `--host-clone`, `--use-shared-cache`
@@ -444,7 +451,7 @@ original `.ps1` scripts remain in `scripts/archived/`.
## 9. Troubleshooting ## 9. Troubleshooting
| Symptom | Cause | Fix | | Symptom | Cause | Fix |
| ---------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------- | | -------------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------- |
| `No such command 'bench'` | Production venv not refreshed | [§0.1](#01-refresh-the-production-venv) — `pip install .` | | `No such command 'bench'` | Production venv not refreshed | [§0.1](#01-refresh-the-production-venv) — `pip install .` |
| `validate host` keyring `[FAIL]` | Credential missing or wrong user | [§5](#5-credentials--template-provisioning) — `creds set` | | `validate host` keyring `[FAIL]` | Credential missing or wrong user | [§5](#5-credentials--template-provisioning) — `creds set` |
| `validate guest` connect failure | VM not booted, wrong IP, or firewall | Confirm the VM is running and re-check its IP | | `validate guest` connect failure | VM not booted, wrong IP, or firewall | Confirm the VM is running and re-check its IP |