Skip to main content

Proxmox · Debian-VM-Strategie (Cloud-Init)

Proxmox · Debian-VM-Strategie

abstract: Zweck Debian-13-VMs auf Proxmox reproduzierbar aus einem Cloud-Init-Template bereitstellen. Dieses Dokument beschreibt den aktuellen CORESTREAM-Standard und verweist für den ausführbaren Stand auf das zentrale OneDev-Repo.

Gültig für: Debian 13 (trixie), Proxmox VE, UEFI/OVMF, qcow2-Images

Inhaltsverzeichnis

  1. 1 · Standard und Entscheidung
  2. 2 · Skripte installieren
  3. 3 · Voraussetzungen vorbereiten
  4. 4 · Template bauen
  5. 5 · VM klonen
  6. 6 · Verifikation
  7. 7 · User und SSH-Zugriff
  8. 8 · Goldene Regeln
  9. 9 · Troubleshooting
  10. 10 · Source of Truth

1 · Standard und Entscheidung

Modus Image Einsatz
cloudinit debian-13-generic-amd64.qcow2 CORESTREAM-Standard; User, Key, Hostname und IP pro VM
bake debian-13-nocloud-amd64.qcow2 Sonderfall für bewusst fest gebackene Images

tip: Empfehlung Für neue Kunden-, Staging- und Infrastruktur-VMs immer cloudinit mit --img genericcloud verwenden.

warning: Image-Falle nocloud enthält kein Cloud-Init. Der Skriptparameter --img genericcloud verwendet im aktuellen CORESTREAM-Workflow die Datei debian-13-generic-amd64.qcow2.

2 · Skripte installieren

Auf jedem neuen Proxmox-Host als root:

curl -fsSL https://git.corestream.ch/corestream/proxmox-debian-cloudinit-scripts/~raw/master/install-on-proxmox.sh | bash

Fester Installationspfad:

  • /opt/corestream/proxmox-debian-cloudinit/build-debian-template.sh
  • /opt/corestream/proxmox-debian-cloudinit/clone-vm.sh

Kommandos über Symlinks:

  • /usr/local/sbin/build-debian-template
  • /usr/local/sbin/clone-vm

note: > Der OneDev-Raw-Zugriff ist anonym als Code Reader freigegeben. Der Installer kann deshalb ohne Token ausgeführt werden.

3 · Voraussetzungen vorbereiten

3.1 Pakete auf Proxmox

apt update
apt install -y libguestfs-tools wget curl

qemu-guest-agent wird nicht für den Proxmox-Host benötigt. Das Build-Skript installiert und verifiziert das Paket innerhalb des Debian-Images.

3.2 Storage und Debian-Image

pvesm status --enabled
mkdir -p /mnt/pve/<STORE>/import
cd /mnt/pve/<STORE>/import
wget -O debian-13-generic-amd64.qcow2 https://cloud.debian.org/images/cloud/trixie/latest/debian-13-generic-amd64.qcow2
wget -O SHA512SUMS https://cloud.debian.org/images/cloud/trixie/latest/SHA512SUMS
sha512sum -c --ignore-missing SHA512SUMS

Das Build-Skript trennt zwei Rollen:

  • Quellstorage: NFS mit dem unveränderten qcow2 unter /mnt/pve/<SOURCE_STORE>/import/; bei mehreren NFS-Storages erscheint ein Auswahlmenü, alternativ --source-store <STORE>.
  • Zielstorage: lokaler, aktivierter Proxmox-Storage mit Content-Typ images; bei mehreren lokalen Zielen erscheint ein Auswahlmenü, alternativ --target-store <STORE>.

Die VM-Disk, EFI-Disk und Cloud-Init-Disk liegen immer auf dem gewählten Zielstorage. NFS wird automatisch nicht als VM-Ziel angeboten.

3.3 Admin-Public-Key

Standardpfad:

test -s /root/.ssh/id_csgadmin.pub

Fehlt die Datei, einen vorhandenen Public-Key beim Build explizit übergeben:

build-debian-template -t 9000 -n debian13-init -m cloudinit --img genericcloud --user-key /root/.ssh/authorized_keys

warning: > Bei --user-key /root/.ssh/authorized_keys werden alle dort enthaltenen Keys in die VM übernommen. Für genau einen Admin-Key eine dedizierte Public-Key-Datei verwenden.

4 · Template bauen

Standard:

build-debian-template -t 9000 -n debian13-init -m cloudinit --img genericcloud

Mit expliziter Key-Datei:

build-debian-template -t 9000 -n debian13-init -m cloudinit --img genericcloud --user-key /pfad/admin.pub

Hermes-Zugriff nur auf ausdrücklichen Wunsch:

build-debian-template -t 9000 -n debian13-init -m cloudinit --img genericcloud --hermes --hermes-key /pfad/hermes.pub

Das Skript:

  • kopiert das qcow2 pro Build nach /var/tmp und verändert niemals das zentrale NFS-Basisimage
  • aktualisiert nur diese Arbeitskopie vor der Paketinstallation
  • installiert und verifiziert qemu-guest-agent, sudo und openssh-server
  • aktiviert QEMU Guest Agent und serielle Konsole
  • deaktiviert Root-SSH und Passwort-SSH
  • erzwingt die NoCloud-Datasource
  • deaktiviert IPv6 per Sysctl und Kernelparameter ipv6.disable=1
  • fragt bei mehreren lokalen VM-Storages nach dem Ziel
  • importiert VM-, EFI- und Cloud-Init-Disk auf den lokalen Zielstorage
  • ermittelt den tatsächlichen importierten Proxmox-Volume-Namen aus qm config
  • erstellt eine OVMF-/Q35-VM mit SCSI-Disk und Cloud-Init-Drive
  • setzt ciuser=csgadmin, SSH-Key und DHCP als Ausgangswert
  • wandelt die VM in ein Template um

Template-Konfiguration prüfen:

qm config 9000 | grep -E 'agent|scsi1|cloudinit|ciuser|boot'

Erwartet:

  • agent: 1 beziehungsweise enabled=1
  • scsi1 enthält cloudinit
  • ciuser: csgadmin
  • Boot-Reihenfolge enthält scsi0;scsi1

important: > Template niemals booten. Immer einen Clone zum Testen verwenden.

5 · VM klonen

Test-VM mit DHCP:

clone-vm 9000 901 test-debian dhcp

VM mit statischer IPv4-Adresse:

clone-vm 9000 121 app-staging 10.10.10.121/24 10.10.10.1

Der Clone-Helper:

  • erstellt einen Full Clone
  • setzt Proxmox-seitig agent enabled=1
  • setzt DHCP oder statische IPv4-Konfiguration
  • startet die VM

Für Throwaway-Tests kann bei Bedarf manuell ein Linked Clone erstellt werden. Kunden-, Staging-, Produktions- und Infrastruktur-VMs bleiben Full Clones.

6 · Verifikation

6.1 Im Gast

cloud-init status --long
id csgadmin
hostname
ip -4 a
ls -l /dev/disk/by-label/cidata
dpkg-query -W qemu-guest-agent
systemctl is-active qemu-guest-agent
sysctl net.ipv6.conf.all.disable_ipv6
cat /proc/cmdline
ip -6 addr

Erwartet:

  • Cloud-Init: status: done
  • csgadmin existiert
  • Hostname und IPv4-Konfiguration stimmen
  • cidata ist vorhanden
  • qemu-guest-agent ist installiert
  • Guest-Agent-Dienst ist active
  • disable_ipv6 = 1
  • Kernel-Commandline enthält ipv6.disable=1
  • keine IPv6-Adressen

6.2 Auf Proxmox

qm agent <VMID> ping

SSH-Test:

ssh csgadmin@<IPv4>

7 · User und SSH-Zugriff

User Standard Key Rechte
csgadmin immer im Cloud-Init-Modus --user-key, standardmässig /root/.ssh/id_csgadmin.pub Admin-Zugang gemäss Cloud-Image/Cloud-Init
hermes nur mit --hermes --hermes-key, standardmässig /root/.ssh/id_ed25519.pub NOPASSWD:ALL, Passwort gesperrt
root kein SSH-Login keiner PermitRootLogin no

Zusätzlich gilt PasswordAuthentication no; SSH-Zugriff erfolgt per Key.

important: > Hermes ist opt-in. Der User wird nie automatisch angelegt.

8 · Goldene Regeln

  1. Für Cloud-Init debian-13-generic-amd64.qcow2 verwenden.
  2. Template nie booten.
  3. Cloud-Init-Drive muss vorhanden sein, bei OVMF auf scsi1.
  4. Nach Änderungen an ci* immer qm cloudinit update <VMID>.
  5. Kunden-/Staging-/Prod-/Infra-VMs als Full Clone erstellen.
  6. Admin-Key vor dem Build verifizieren; der Build bricht bei fehlender oder leerer Key-Datei ab.
  7. Nach dem ersten Clone Cloud-Init, Guest Agent, IPv4, SSH und deaktiviertes IPv6 prüfen.
  8. Skripte nicht aus Obsidian kopieren; immer den aktuellen OneDev-Stand installieren.

9 · Troubleshooting

Symptom Ursache Fix
user pubkey missing Default-Key-Datei fehlt dedizierte Datei bereitstellen oder --user-key <datei> verwenden
storage ... does not support vm images Quell-NFS fälschlich als VM-Ziel verwendet oder alter Skriptstand Installer erneut ausführen; lokalen Zielstorage wählen oder --target-store <STORE> setzen
VM-ID existiert nach fehlgeschlagenem Import alter Build hat die VM vor dem Storage-Fehler angelegt qm config <VMID> prüfen, unbrauchbaren Teilbau gezielt löschen oder neue ID wählen
Basis-qcow2 stimmt nicht mehr mit SHA512 überein alter Skriptstand hat das NFS-Image direkt verändert Original erneut von Debian laden; aktueller Skriptstand arbeitet mit /var/tmp-Kopie
Kein SSH-Login Key nicht im Cloud-Init-Seed qm config, sshkeys, Key-Datei und qm cloudinit update prüfen
cloud-init: command not found nocloud-Image verwendet Template mit generic-amd64 neu bauen
cidata fehlt Cloud-Init-Drive fehlt/falscher Bus scsi1 und qm cloudinit update prüfen
Cloud-Init überspringt Template wurde gebootet Template sauber neu bauen; künftig nur Clones booten
qemu-guest-agent fehlt altes/fehlerhaftes Template aktuelles Build-Skript installieren und Template neu bauen
qm agent <VMID> ping scheitert Paket/Dienst/Agent-Flag fehlt Gastpaket, Dienst, /dev/virtio-ports/ und qm config prüfen
IPv6 noch aktiv alter Template-Stand oder kein Neustart aktuelles Template bauen; Sysctl, Kernelparameter und Cold Boot prüfen
DHCP wartet kein DHCP im Zielnetz statische IPv4 beim Clone übergeben

10 · Source of Truth

important: > Ausführbarer Source of Truth ist OneDev, nicht ein eingebetteter Skriptblock in Obsidian.

  • Repo: corestream/proxmox-debian-cloudinit-scripts
  • SSH: ssh://git@git.corestream.ch:6611/corestream/proxmox-debian-cloudinit-scripts.git
  • Installer: https://git.corestream.ch/corestream/proxmox-debian-cloudinit-scripts/~raw/master/install-on-proxmox.sh
  • Installationspfad: /opt/corestream/proxmox-debian-cloudinit

Die früher eingebetteten Vollkopien der Skripte wurden bewusst entfernt, damit Dokumentation und ausführbarer Code nicht erneut auseinanderlaufen.

Verwandt: Staging- und Produktionskonzept

Quelle: Obsidian Knowledge Base/Proxmox/Proxmox Debian Cloud-Init Strategie.md · Stand: 2026-09-13 · Automatisiert publiziert durch Hermes.

Back to top