Added initial lab setup scripts

2026-02-19 08:28:14 +01:00 · 2026-02-19 08:28:14 +01:00 · 331f61d92c
parent e2909c9149
commit 331f61d92c
6 changed files with 2357 additions and 2 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -17,7 +17,8 @@ incu-contrib/
 │   ├── README.md          # Detailed usage docs
 │   ├── incusos-iso        # ISO/IMG builder (wraps flasher-tool)
 │   ├── incusos-seed       # Seed archive generator
-│   └── examples/          # Example seed YAML files
+│   ├── incusos-proxmox    # Declarative Proxmox VM deployment
+│   └── examples/          # Example seed + Proxmox YAML files
 └── notes/                 # Research notes and reference material
 ```

@ -63,6 +64,34 @@ incu-contrib/
 - Operations Center **requires** at least one trusted certificate -- without it,
  you are locked out after installation.

+### Proxmox VE deployment
+
+- **`incusos-proxmox`** reads a YAML config, generates per-VM SEED_DATA images
+  via `incusos-seed --format fat`, uploads the ISO + seeds to Proxmox, creates
+  VMs with IncusOS-correct settings, and boots them through installation.
+- **Connection methods**: SSH (default, `ssh root@host qm ...`) or API
+  (`curl -k https://host:8006/api2/json/...` with `PVEAPIToken` header).
+- **Minimum API privileges** for token-based access:
+  ```
+  VM.Allocate VM.Config.Disk VM.Config.CPU VM.Config.Memory
+  VM.Config.Network VM.Config.CDROM VM.Config.Options VM.Config.HWType
+  VM.PowerMgmt VM.Audit Datastore.AllocateSpace Datastore.AllocateTemplate
+  Datastore.Audit SDN.Use
+  ```
+- **Required VM settings** (getting any wrong causes IncusOS install failure):
+  - `bios=ovmf`, `machine=q35` -- UEFI boot required
+  - `efidisk0`: `pre-enrolled-keys=0` -- IncusOS enrolls its own Secure Boot keys
+  - `tpmstate0`: `version=v2.0` -- required for disk encryption
+  - `cpu=host` -- needed for x86_64_v3 instruction set requirement
+  - `scsihw=virtio-scsi-pci` + `scsi0` -- VirtIO-blk is broken with IncusOS
+  - `balloon=0` -- IncusOS manages memory internally
+  - `ide3` -- SEED_DATA FAT image attached as second CD-ROM
+  - Minimum 50 GiB disk, minimum 4096 MiB RAM
+- **Install flow**: boot from ISO (ide2) -> read SEED_DATA (ide3) -> install
+  to disk (scsi0) -> force_reboot -> boot from disk. Boot order is swapped
+  to `order=scsi0;ide2` immediately after first start so the reboot lands
+  on disk.
+
 ## Coding conventions for scripts

 - **Shell**: bash with `set -euo pipefail`
--- a/README.md
+++ b/README.md
@ -19,6 +19,10 @@ Scripts for building IncusOS installation media and seed configurations:
  customization. Covers all seed file types: install, applications, Incus preseed,
  Operations Center, network, and update configuration.

+- **`incusos-proxmox`** -- Declarative IncusOS deployment on Proxmox VE. Define VMs in
+  YAML, and the script handles seed generation, ISO upload, VM creation with correct
+  settings (UEFI, TPM 2.0, VirtIO-SCSI), and automated installation.
+
 See [`incusos/README.md`](incusos/README.md) for full documentation.

 ### [`notes/`](notes/)
--- a/incusos/README.md
+++ b/incusos/README.md
@ -8,8 +8,9 @@ Scripts for building IncusOS installation media and seed configurations.
 |--------|---------|
 | [`incusos-iso`](#incusos-iso) | Build customized IncusOS ISO/IMG images using the flasher-tool |
 | [`incusos-seed`](#incusos-seed) | Generate seed archives (tar or FAT) for installation customization |
+| [`incusos-proxmox`](#incusos-proxmox) | Declarative IncusOS deployment on Proxmox VE |

-Both scripts support automatic client certificate injection from the local Incus
+All scripts support automatic client certificate injection from the local Incus
 installation, so the freshly installed system is immediately manageable.

 ## Prerequisites
@ -231,6 +232,146 @@ for i in 1 2 3; do
 done
 ```

+## incusos-proxmox
+
+Declarative deployment of IncusOS VMs on Proxmox VE. Define your lab in a YAML
+file and deploy with a single command. Handles seed generation, ISO upload, VM
+creation with IncusOS-correct settings, and automated installation.
+
+IncusOS requires very specific Proxmox VM settings (UEFI without pre-enrolled
+keys, TPM 2.0, VirtIO-SCSI, `host` CPU type, minimum 50 GiB disk, 4 GiB RAM).
+This script ensures all settings are correct, preventing install failures.
+
+### Quick Start
+
+```bash
+# Preview what would be deployed
+./incusos-proxmox --dry-run examples/proxmox-lab.yaml
+
+# Validate config and check Proxmox connectivity
+./incusos-proxmox --phase validate examples/proxmox-lab.yaml
+
+# Deploy everything
+./incusos-proxmox examples/proxmox-lab.yaml
+
+# Deploy a single VM from the config
+./incusos-proxmox --vm ops-center examples/proxmox-lab.yaml
+
+# Tear down all VMs defined in config
+./incusos-proxmox --cleanup examples/proxmox-lab.yaml
+```
+
+### Options Reference
+
+```
+-p, --phase PHASE       validate, prepare, upload, create, install, all (default)
+-m, --method METHOD     Override connection method: ssh (default), api
+-H, --host HOST         Override Proxmox host from config
+-i, --iso FILE          Use local ISO (skip CDN download)
+-c, --cert FILE         Client certificate PEM file (default: auto-detect)
+    --no-cert           Skip certificate injection
+    --vm NAME           Operate on a single VM only
+-y, --yes               Skip confirmation prompts
+    --cleanup           Destroy VMs defined in config
+    --dry-run           Preview without executing
+-q, --quiet             Suppress info output
+-h, --help              Full help text
+-V, --version           Show version
+```
+
+### Deployment Phases
+
+| Phase | What it does |
+|-------|-------------|
+| `validate` | Parse YAML, check fields, verify Proxmox connectivity, allocate VMIDs |
+| `prepare` | Download IncusOS ISO from CDN, generate per-VM SEED_DATA images |
+| `upload` | Upload ISO and seed images to Proxmox ISO storage |
+| `create` | Create VMs with IncusOS-correct settings (UEFI, TPM, VirtIO-SCSI, etc.) |
+| `install` | Start VMs, swap boot order, wait for install, clean up CD-ROMs |
+
+### Config File Format
+
+```yaml
+proxmox:
+  host: 192.168.1.10       # Proxmox host (required)
+  node: pve                 # Node name (default: pve)
+  storage: local-lvm        # VM disk storage (default: local-lvm)
+  iso_storage: local        # ISO storage (default: local)
+  bridge: vmbr0             # Network bridge (default: vmbr0)
+  method: ssh               # ssh (default) or api
+  ssh_user: root            # For ssh method
+
+defaults:
+  cores: 4
+  memory: 8192              # MiB, min 4096
+  disk: 64                  # GiB, min 50
+  channel: stable
+  start_vmid: 200           # Auto-assign VMIDs from here
+
+vms:
+  - name: my-vm
+    app: incus              # incus or operations-center
+    apply_defaults: true
+    cores: 4                # Override defaults per VM
+    memory: 8192
+    disk: 64
+    vmid: 200               # Optional explicit VMID
+    cluster: my-cluster     # Future: cluster formation
+    cluster_role: init      # init or join
+```
+
+### Connection Methods
+
+**SSH (default):** Requires key-based SSH authentication to the Proxmox host.
+Simplest for homelab use.
+
+```bash
+# Test connectivity
+ssh root@192.168.1.10 pvesh get /version
+```
+
+**API:** Requires an API token. Set up minimal privileges:
+
+```bash
+pveum role add IncusOSDeploy --privs "VM.Allocate VM.Config.Disk \
+    VM.Config.CPU VM.Config.Memory VM.Config.Network VM.Config.CDROM \
+    VM.Config.Options VM.Config.HWType VM.PowerMgmt VM.Audit \
+    Datastore.AllocateSpace Datastore.AllocateTemplate Datastore.Audit SDN.Use"
+pveum user add automation@pve
+pveum aclmod / -user automation@pve -role IncusOSDeploy
+pveum user token add automation@pve deploy --privsep 0
+
+export PROXMOX_TOKEN_SECRET="<secret-from-above>"
+```
+
+### Proxmox VM Settings
+
+Every VM is created with these IncusOS-specific settings:
+
+| Setting | Value | Reason |
+|---------|-------|--------|
+| BIOS | OVMF (UEFI) | IncusOS requires UEFI boot |
+| Machine | q35 | Modern chipset for UEFI |
+| EFI disk | pre-enrolled-keys=0 | IncusOS enrolls its own Secure Boot keys |
+| TPM | v2.0 | Required for disk encryption |
+| CPU | host | Needs x86_64_v3 instruction set |
+| SCSI controller | virtio-scsi-pci | VirtIO-blk is broken with IncusOS |
+| Balloon | 0 (disabled) | IncusOS manages memory internally |
+| SEED_DATA | Attached as ide3 CD-ROM | Per-VM seed configuration |
+
+### Prerequisites
+
+- **python3** + **PyYAML** (`python3-yaml`) -- YAML config parsing
+- **ssh** + **scp** (for SSH method) or **curl** (for API method)
+- **incusos-seed** -- sibling script (auto-detected in same directory)
+- **Bash 4+** -- associative arrays
+- **Incus client** (recommended) -- for client certificate auto-detection
+
+### Example Configurations
+
+- [`examples/proxmox-lab.yaml`](examples/proxmox-lab.yaml) -- Full 4-VM lab (ops-center + 3-node cluster)
+- [`examples/proxmox-minimal.yaml`](examples/proxmox-minimal.yaml) -- Single standalone Incus VM
+
 ## Client Certificate Auto-Detection

 Both scripts automatically look for a client certificate in this order:
@ -289,6 +430,8 @@ See the [`examples/`](examples/) directory for sample seed configurations:
 - [`incus-cluster-node.yaml`](examples/incus-cluster-node.yaml) -- Cluster node (no defaults)
 - [`ops-center.yaml`](examples/ops-center.yaml) -- Operations Center
 - [`network-static.yaml`](examples/network-static.yaml) -- Static network configuration
+- [`proxmox-lab.yaml`](examples/proxmox-lab.yaml) -- Proxmox: 4-VM lab (ops-center + 3-node cluster)
+- [`proxmox-minimal.yaml`](examples/proxmox-minimal.yaml) -- Proxmox: single standalone VM

 ## Security Notes

--- a/incusos/examples/proxmox-lab.yaml
+++ b/incusos/examples/proxmox-lab.yaml
@ -0,0 +1,60 @@
+# proxmox-lab.yaml - Full 4-VM IncusOS lab deployment
+#
+# Deploys:
+#   - 1x Operations Center (management UI)
+#   - 3x Incus nodes (cluster: 1 init + 2 join)
+#
+# Usage:
+#   incusos-proxmox --dry-run examples/proxmox-lab.yaml   # Preview
+#   incusos-proxmox examples/proxmox-lab.yaml              # Deploy
+#   incusos-proxmox --cleanup examples/proxmox-lab.yaml    # Tear down
+
+proxmox:
+  host: 192.168.1.10            # Proxmox host IP or hostname
+  node: pve                     # Proxmox node name
+  storage: local-lvm            # VM disk storage
+  iso_storage: local            # ISO/image storage
+  bridge: vmbr0                 # Network bridge
+  method: ssh                   # ssh (default) or api
+  ssh_user: root                # SSH user for ssh method
+  # api_token_id: automation@pve!deploy   # For api method
+
+defaults:
+  cores: 4
+  memory: 8192                  # MiB (minimum: 4096)
+  disk: 64                      # GiB (minimum: 50)
+  channel: stable
+  start_vmid: 200               # Auto-assign VMIDs from here
+
+vms:
+  # Operations Center -- management dashboard for the cluster.
+  # Requires a client certificate for web UI access.
+  - name: ops-center
+    app: operations-center
+    apply_defaults: true
+    cores: 2
+    memory: 4096
+    disk: 50
+
+  # Incus cluster leader -- initializes the cluster, creates the default
+  # ZFS pool and network bridge via apply_defaults.
+  - name: incus-main
+    app: incus
+    apply_defaults: true
+    cluster: my-cluster
+    cluster_role: init
+
+  # Incus cluster joiner #1 -- joins the cluster created by incus-main.
+  # apply_defaults is false because the leader pushes configuration.
+  - name: incus-node-02
+    app: incus
+    apply_defaults: false
+    cluster: my-cluster
+    cluster_role: join
+
+  # Incus cluster joiner #2
+  - name: incus-node-03
+    app: incus
+    apply_defaults: false
+    cluster: my-cluster
+    cluster_role: join
--- a/incusos/examples/proxmox-minimal.yaml
+++ b/incusos/examples/proxmox-minimal.yaml
@ -0,0 +1,24 @@
+# proxmox-minimal.yaml - Single standalone IncusOS VM
+#
+# Simplest possible deployment: one Incus server with defaults.
+#
+# Usage:
+#   incusos-proxmox --dry-run examples/proxmox-minimal.yaml
+#   incusos-proxmox examples/proxmox-minimal.yaml
+
+proxmox:
+  host: 192.168.1.10            # Change to your Proxmox host
+  # All other settings use defaults:
+  #   node: pve, storage: local-lvm, iso_storage: local,
+  #   bridge: vmbr0, method: ssh, ssh_user: root
+
+defaults:
+  start_vmid: 200
+
+vms:
+  - name: incus-standalone
+    app: incus
+    apply_defaults: true
+    cores: 4
+    memory: 8192
+    disk: 64
--- a/incusos/incusos-proxmox
+++ b/incusos/incusos-proxmox