Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 6: Proxmox vorbereiten

Ziel: Proxmox hat einen API-Token für OpenTofu, ein Ubuntu-Template 9000 und eine GPU, die per vfio für eine VM reserviert ist. · Dauer: ca. 90 min · Voraussetzung: Tag 0

Briefing

  • OpenTofu spricht mit Proxmox über einen API-Token (tofu@pve!provider) mit eigener Rolle TofuProv, nie als root@pam.
  • Cloud-init-Snippets lädt der Provider bpg/proxmox per SSH hoch. Dafür gibt es den Systembenutzer tofu mit genau zwei sudo-Regeln.
  • Alle sechs VMs entstehen als Klon von Template 9000 (ubuntu-2404-tpl).
  • GPU-Passthrough braucht IOMMU, vfio-Module und einen Host-Kernel, der die Finger von der Karte lässt. Das Resource Mapping gpu0 entkoppelt die VM von der PCI-Adresse.
Laptop (tofu, ssh-agent)
   |  HTTPS :8006  API-Token tofu@pve!provider
   |  SSH   :22    Benutzer tofu (nur tee -> snippets/)
   v
pve1  vmbr0 ── 10.10.20.0/24 ── VMs 211-231
      local:snippets   local-lvm: Template 9000
      GPU 0000:01:00.0 -> vfio-pci -> Mapping gpu0 -> rke2-gpu-1

Achtung: Proxmox- und GPU-Befehle in diesem Kapitel sind gegen die offizielle Doku geprüft (pve.proxmox.com für PVE 9, registry.terraform.io/providers/bpg/proxmox v0.116), aber nicht live getestet. Ausgaben sind gekürzt und können je nach Version abweichen. Die Skripte liegen unter code/infra-proxmox/host/.

Drill 1: Netz prüfen – Bridge und VLAN

Alle VMs hängen an vmbr0. Liegt das Kubernetes-Netz in einem eigenen VLAN, muss die Bridge VLAN-aware sein.

ip -br addr show vmbr0
grep -A8 '^iface vmbr0' /etc/network/interfaces

Erwartet (gekürzt, kann je nach Version abweichen):

vmbr0            UP             10.10.20.5/24
iface vmbr0 inet static
        address 10.10.20.5/24
        gateway 10.10.20.1
        bridge-ports eno1
        bridge-stp off
        bridge-fd 0

Für ein separates VLAN (z. B. 20) ergänzt du die Bridge so und setzt später in OpenTofu vlan_id = 20:

        bridge-vlan-aware yes
        bridge-vids 2-4094
ifreload -a
bridge vlan show dev eno1 | head -3

Warum? Ohne bridge-vlan-aware verwirft die Bridge getaggte Frames der VMs stillschweigend. Für das Lab reicht untagged auf vmbr0, wenn 10.10.20.0/24 das Management-Netz ist.

Tipp: Reserviere 10.10.20.10 (API-VIP) und 10.10.20.100–120 (LoadBalancer-Pool) im DHCP-Server deines Routers, sonst vergibt er sie doppelt.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Rolle, Benutzer und API-Token

Die Rolle enthält nur, was Klonen, Konfigurieren, Starten und Mapping-Nutzung brauchen. SDN.Audit/SDN.Use sind nötig, sonst sieht der Token die Bridges nicht.

cat > /root/01-tofu-user.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail

PRIVS="Datastore.Allocate Datastore.AllocateSpace Datastore.Audit"
PRIVS+=" VM.Allocate VM.Audit VM.Clone VM.Config.CDROM VM.Config.CPU"
PRIVS+=" VM.Config.Cloudinit VM.Config.Disk VM.Config.HWType"
PRIVS+=" VM.Config.Memory VM.Config.Network VM.Config.Options"
PRIVS+=" VM.PowerMgmt VM.Migrate VM.Console VM.GuestAgent.Audit"
PRIVS+=" Sys.Audit Sys.Console SDN.Audit SDN.Use"
PRIVS+=" Mapping.Audit Mapping.Use"

pveum role add TofuProv -privs "${PRIVS// /,}"
pveum user add tofu@pve --comment "OpenTofu bpg/proxmox"
pveum aclmod / -user tofu@pve -role TofuProv
pveum user token add tofu@pve provider --privsep 0
EOF
bash /root/01-tofu-user.sh

Erwartet (gekürzt, kann je nach Version abweichen):

┌──────────────┬──────────────────────────────────────┐
│ key          │ value                                │
╞══════════════╪══════════════════════════════════════╡
│ full-tokenid │ tofu@pve!provider                    │
│ info         │ {"privsep":"0"}                      │
│ value        │ 3f1c...-....-....-....-............  │
└──────────────┴──────────────────────────────────────┘

Der value erscheint nur einmal. --privsep 0 heißt: der Token erbt exakt die Rechte von tofu@pve, du pflegst ACLs nur an einer Stelle.

Sicherheit: Den Token nie in *.tf oder terraform.tfvars schreiben. Er gehört in eine Datei mit Modus 600 außerhalb von Git.

Auf dem Laptop:

cat > ~/ki-lab/pve.env <<'EOF'
export PROXMOX_VE_ENDPOINT='https://10.10.20.5:8006/'
export PROXMOX_VE_API_TOKEN='tofu@pve!provider=HIER-DEN-VALUE-EINFUEGEN'
EOF
chmod 600 ~/ki-lab/pve.env
source ~/ki-lab/pve.env
curl -sk -H "Authorization: PVEAPIToken=${PROXMOX_VE_API_TOKEN}" \
  "${PROXMOX_VE_ENDPOINT}api2/json/version" | jq -r .data.version

Erwartet (kann je nach Version abweichen):

9.1.4

Fortschritt speichern? Kostenlos registrieren

Drill 3: SSH-Benutzer und Snippets-Storage

bpg/proxmox lädt snippets (cloud-init user-data) per SSH hoch, weil die Proxmox-API dafür keinen Upload kennt. Der Benutzer tofu darf per sudo nur zwei exakt beschriebene Befehle ausführen.

cat > /root/02-tofu-ssh.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
apt-get install -y sudo
id tofu >/dev/null 2>&1 || useradd -m -s /bin/bash tofu
install -d -m 700 -o tofu -g tofu /home/tofu/.ssh
cat > /etc/sudoers.d/tofu <<'SUDO'
tofu ALL=(root) NOPASSWD: /usr/sbin/pvesm apiinfo
tofu ALL=(root) NOPASSWD: /usr/bin/tee /var/lib/vz/snippets/[a-zA-Z0-9_][a-zA-Z0-9_.-]*
SUDO
chmod 440 /etc/sudoers.d/tofu
visudo -cf /etc/sudoers.d/tofu
pvesm set local --content iso,vztmpl,backup,snippets
EOF
bash /root/02-tofu-ssh.sh

Erwartet (gekürzt):

/etc/sudoers.d/tofu: parsed OK

Sicherheit: Niemals NOPASSWD: /usr/sbin/qm oder /var/lib/vz/* freigeben. qm set --hookscript und * mit ../ sind beide root-äquivalent – so steht es auch in der Provider-Doku.

Deinen Laptop-Key hinterlegen und den Weg testen:

# auf dem Laptop
ssh [email protected] 'cat >> /home/tofu/.ssh/authorized_keys' \
  < ~/.ssh/id_ed25519.pub
ssh [email protected] 'chown tofu: /home/tofu/.ssh/authorized_keys'
ssh-add ~/.ssh/id_ed25519
ssh [email protected] 'sudo -n /usr/sbin/pvesm apiinfo; pvesm status \
  --content snippets'

Erwartet (gekürzt, kann je nach Version abweichen):

APIVER 13
APIAGE 4
Name         Type     Status           Total            Used       Available        %
local         dir     active       98497780        12345678        81089632   12.53%

Fortschritt speichern? Kostenlos registrieren

Drill 4: Cloud-Init-Template 9000

Das offizielle Ubuntu-24.04-Cloud-Image wird direkt als Disk importiert. virtio-scsi-single erlaubt später iothread pro Disk.

cat > /root/03-template.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
VMID=9000
STORAGE=local-lvm
IMG=/var/lib/vz/template/iso/noble-server-cloudimg-amd64.img
URL=https://cloud-images.ubuntu.com/noble/current/noble-server-cloudimg-amd64.img

[ -f "$IMG" ] || wget -q -O "$IMG" "$URL"
qm create "$VMID" --name ubuntu-2404-tpl --ostype l26 \
  --memory 2048 --cores 2 --cpu host --agent enabled=1 \
  --net0 virtio,bridge=vmbr0 --scsihw virtio-scsi-single
qm set "$VMID" --scsi0 "$STORAGE:0,import-from=$IMG,discard=on,iothread=1"
qm set "$VMID" --ide2 "$STORAGE:cloudinit"
qm set "$VMID" --boot order=scsi0
qm set "$VMID" --serial0 socket --vga serial0
qm template "$VMID"
EOF
bash /root/03-template.sh
qm config 9000 | grep -E '^(name|scsi0|ide2|boot|scsihw|template|agent):'

Erwartet (gekürzt, kann je nach Version abweichen):

agent: enabled=1
boot: order=scsi0
ide2: local-lvm:vm-9000-cloudinit,media=cdrom
name: ubuntu-2404-tpl
scsi0: local-lvm:base-9000-disk-0,discard=on,iothread=1,size=3584M
scsihw: virtio-scsi-single
template: 1

Warum --serial0 socket --vga serial0? Ubuntu-Cloud-Images schreiben ihre Konsole auf die serielle Schnittstelle. Ohne sie bleibt die Proxmox-Konsole schwarz. Die Disk ist nur 3,5 GB groß – OpenTofu vergrößert sie beim Klonen (Tag 7).

Tipp: Das Image enthält keinen qemu-guest-agent. Den installiert die user-data an Tag 7. Bis dahin meldet Proxmox „guest agent not running“ – das ist normal.

Fortschritt speichern? Kostenlos registrieren

Drill 5: IOMMU einschalten und prüfen

Ab hier nur auf dem GPU-Host. Zuerst im BIOS/UEFI: VT-d (Intel) bzw. AMD-Vi/IOMMU aktivieren, außerdem „Above 4G Decoding“ und – falls vorhanden – „Resizable BAR“ für große GPUs. Bei AMD und bei Intel mit Kernel ≥ 6.8 ist IOMMU im Kernel dann bereits an. Proxmox 9 bringt einen neueren Kernel mit, intel_iommu=on brauchst du also nicht mehr. Optional bringt iommu=pt etwas Performance.

Welcher Bootloader?

uname -r
proxmox-boot-tool status 2>/dev/null | tail -2 || echo "GRUB ohne proxmox-boot-tool"
cat /proc/cmdline

Erwartet (gekürzt, kann je nach Version abweichen):

6.17.2-1-pve
E3A1-56F2 is configured with: uefi (versions: 6.17.2-1-pve)
BOOT_IMAGE=/boot/vmlinuz-6.17.2-1-pve root=/dev/mapper/pve-root ro quiet

iommu=pt setzen – GRUB:

sed -i 's/^\(GRUB_CMDLINE_LINUX_DEFAULT="quiet\)"/\1 iommu=pt"/' \
  /etc/default/grub
update-grub

Oder systemd-boot (ZFS-Root mit UEFI):

sed -i 's/$/ iommu=pt/' /etc/kernel/cmdline
proxmox-boot-tool refresh

Nach dem Reboot (Drill 6 macht den Reboot gleich mit):

dmesg | grep -e DMAR -e IOMMU -e AMD-Vi | head -5

Erwartet (gekürzt, Text hängt von CPU und Kernel ab):

DMAR: IOMMU enabled
DMAR-IR: Enabled IRQ remapping in x2apic mode

Fehlt „remapping“, ist die Plattform für Passthrough ungeeignet oder die BIOS-Option aus.

Fortschritt speichern? Kostenlos registrieren

Drill 6: vfio statt nouveau

Der Host darf die GPU nicht selbst treiben. Du lädst die drei vfio-Module, sperrst nouveau und bindest die Karte über ihre Vendor:Device-ID direkt an vfio-pci.

lspci -nn | grep -i nvidia

Erwartet (Beispiel NVIDIA L4, deine IDs weichen ab):

01:00.0 3D controller [0302]: NVIDIA Corporation AD104GL [L4] [10de:27b8] (rev a1)
cat > /root/04-gpu-host.sh <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
IDS=${1:?Vendor:Device-ID(s), kommasepariert}

cat > /etc/modules-load.d/vfio.conf <<'MOD'
vfio
vfio_iommu_type1
vfio_pci
MOD
cat > /etc/modprobe.d/ki-lab-gpu.conf <<CONF
blacklist nouveau
blacklist nvidiafb
options vfio-pci ids=${IDS}
softdep nouveau pre: vfio-pci
softdep nvidia pre: vfio-pci
CONF
update-initramfs -u -k all
EOF
bash /root/04-gpu-host.sh 10de:27b8
reboot

Hat die Karte eine Audio-Funktion (01:00.1, typisch bei RTX-Karten), gibst du beide IDs an: 10de:2684,10de:22ba.

Nach dem Reboot:

lsmod | grep -E '^vfio'
lspci -nnk -s 01:00.0 | grep 'driver in use'

Erwartet (gekürzt, kann je nach Version abweichen):

vfio_pci               16384  0
vfio_iommu_type1       45056  0
vfio                   61440  2 vfio_iommu_type1,vfio_pci
        Kernel driver in use: vfio-pci

Warum softdep? Falls doch ein NVIDIA-Treiber auf dem Host installiert ist, lädt er sonst vor vfio-pci und schnappt sich die Karte.

Fortschritt speichern? Kostenlos registrieren

Drill 7: IOMMU-Gruppe prüfen und Resource Mapping anlegen

Die GPU muss allein (bzw. nur mit ihren eigenen Funktionen oder ihrem Root-Port) in ihrer IOMMU-Gruppe stecken.

NODE=$(hostname)
pvesh get /nodes/$NODE/hardware/pci --pci-class-blacklist "" \
  --output-format json \
  | jq -r '.[] | select(.vendor=="0x10de")
           | "\(.id) group=\(.iommugroup) \(.device_name)"'

Erwartet (gekürzt, kann je nach Version abweichen):

0000:01:00.0 group=14 AD104GL [L4]
G=14
ls /sys/kernel/iommu_groups/$G/devices/

Erwartet:

0000:01:00.0

Jetzt das clusterweite Mapping gpu0. Die VM referenziert später nur diesen Namen, nicht die PCI-Adresse:

pvesh create /cluster/mapping/pci --id gpu0 \
  --description "KI-Lab GPU fuer rke2-gpu-1" \
  --map node=$NODE,path=0000:01:00.0,id=10de:27b8
pvesh get /cluster/mapping/pci --output-format json | jq -r '.[].id'

Erwartet:

gpu0

Warum Mapping? Der Token tofu@pve darf mit Mapping.Use die GPU zuweisen, ohne root@pam zu sein. Eine direkte hostpci0: 0000:01:00.0-Zuweisung per API erlaubt Proxmox nur root – deshalb verlangt bpg/proxmox für hostpci.id Benutzername und Passwort, für hostpci.mapping reicht der Token.

Tipp: Karten mit Audio-Funktion (01:00.1) legst du am einfachsten im GUI unter Datacenter → Resource Mappings an und wählst dort beide Funktionen aus. Das Ergebnis prüfst du wieder mit pvesh get /cluster/mapping/pci.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

Auf dem Proxmox-Host (GPU-Teil auf dem GPU-Host):

check() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"; else echo "✘ $1"; fi; }
check "Rolle TofuProv" 'pveum role list --output-format json \
  | jq -e ".[] | select(.roleid==\"TofuProv\")"'
check "Token tofu@pve!provider" 'pveum user token list tofu@pve \
  --output-format json | jq -e ".[] | select(.tokenid==\"provider\")"'
check "Snippets auf local" 'pvesm status --content snippets | grep -q "^local "'
check "sudoers gueltig" 'visudo -cf /etc/sudoers.d/tofu'
check "Template 9000" '[ "$(qm config 9000 | sed -n "s/^template: //p")" = 1 ]'
check "IOMMU aktiv" 'dmesg | grep -qE "DMAR: IOMMU enabled|AMD-Vi"'
check "vfio-pci gebunden" 'lspci -nnk | grep -q "driver in use: vfio-pci"'
check "Mapping gpu0" 'pvesh get /cluster/mapping/pci --output-format json \
  | jq -e ".[] | select(.id==\"gpu0\")"'

Erwartet:

✔ Rolle TofuProv
✔ Token tofu@pve!provider
✔ Snippets auf local
✔ sudoers gueltig
✔ Template 9000
✔ IOMMU aktiv
✔ vfio-pci gebunden
✔ Mapping gpu0

Challenge

Beweise, dass die Rolle wirklich eng ist: Lege einen zweiten, privilegiengetrennten Token tofu@pve!readonly an, der nur PVEAuditor hat, und zeige, dass er VMs lesen, aber Template 9000 nicht klonen kann. Lösche ihn danach.

Hinweis: Bei --privsep 1 gelten nur ACLs, die direkt am Token hängen (-token statt -user).

Lösung

pveum user token add tofu@pve readonly --privsep 1 --output-format json \
  | jq -r .value > /root/ro.secret
pveum aclmod / -token 'tofu@pve!readonly' -role PVEAuditor
H="Authorization: PVEAPIToken=tofu@pve!readonly=$(cat /root/ro.secret)"
curl -sk -H "$H" https://localhost:8006/api2/json/nodes/$(hostname)/qemu \
  | jq -r '.data[].name'
curl -sk -o /dev/null -w '%{http_code}\n' -H "$H" -X POST \
  -d newid=9999 https://localhost:8006/api2/json/nodes/$(hostname)/qemu/9000/clone
pveum user token remove tofu@pve readonly && rm /root/ro.secret

Erwartet (gekürzt, kann je nach Version abweichen):

ubuntu-2404-tpl
403

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Pro Umgebung und Pipeline einen eigenen Token mit Ablaufdatum (--expire) und ACLs auf einen Pool (/pool/k8s-prod) statt auf /. Token-Secret aus Vault/OpenBao, nicht aus Dateien.
  • Proxmox-Cluster mit mehreren Nodes: Template auf Shared Storage (Ceph/NFS) oder pro Node ein Template, sonst migriert jeder Klon über das Netz. Die sudo-Regel für tofu muss auf jedem Node liegen.
  • Images nicht direkt aus dem Internet: Cloud-Images versionieren, Prüfsumme (SHA256SUMS) prüfen, im internen Artefakt-Repo spiegeln, Template regelmäßig neu bauen (Packer oder Pipeline).
  • GPU-Hosts: Firmware/BIOS-Profile dokumentieren, ECC und Persistence prüfen. Für mehrere VMs pro GPU braucht es vGPU (NVIDIA-Lizenz) oder MIG statt Passthrough.
  • VLANs und Firewall: Kubernetes-Netz vom Proxmox-Management trennen, Port 8006/22 des Hosts nur aus dem Admin-Netz erreichbar machen.