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 RolleTofuProv, nie alsroot@pam. - Cloud-init-Snippets lädt der Provider
bpg/proxmoxper SSH hoch. Dafür gibt es den Systembenutzertofumit 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
gpu0entkoppelt 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/interfacesErwartet (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 -3Warum? 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) und10.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.shErwartet (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
*.tfoderterraform.tfvarsschreiben. 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.versionErwartet (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.shErwartet (gekürzt):
/etc/sudoers.d/tofu: parsed OK
Sicherheit: Niemals
NOPASSWD: /usr/sbin/qmoder/var/lib/vz/*freigeben.qm set --hookscriptund*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/cmdlineErwartet (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-grubOder systemd-boot (ZFS-Root mit UEFI):
sed -i 's/$/ iommu=pt/' /etc/kernel/cmdline
proxmox-boot-tool refreshNach dem Reboot (Drill 6 macht den Reboot gleich mit):
dmesg | grep -e DMAR -e IOMMU -e AMD-Vi | head -5Erwartet (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 nvidiaErwartet (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
rebootHat 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 mitpvesh 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.secretErwartet (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
tofumuss 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.