Skip to main content

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

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

abstract: Zweck Debian-13-VMs auf Proxmox reproduzierbar aus einem Cloud-Init-Template bereitstellen. DiesesAusführbarer Source of Truth ist das zentrale interne Git-Repo; dieses Dokument beschreibt den aktuellen CORESTREAM-Standard und verweistdie für den ausführbaren Stand auf das zentrale OneDev-Repo.Betriebsregeln.

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

Inhaltsverzeichnis

    1 · Standard und Entscheidung 2 · Skripte installieren 3 · Voraussetzungen vorbereiten 4 · Template bauen 5 · VM klonen 6 · Verifikation 7 · User und SSH-Zugriff 8 · Goldene Regeln 9 · Troubleshooting 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 per Cloud-Init
    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:

    • 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.freigegeben; Derder Installer kannbraucht deshalbkein ohneToken. 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.benötigt Das— das Build-Skript installiert und verifiziert dases Paket innerhalb desim Debian-Images.Image.

      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

      DasRollen im Build-Skript trennt zwei Rollen:Skript:

      • Quellstorage: NFS mit dem unverändertenunverändertem 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; beiAuswahlmenü mehreren lokalen Zielen erscheint ein Auswahlmenü, alternativbzw. --target-store <STORE>.

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

      3.3 Admin-Public-Key

      Standardpfad:Standardpfad prüfen:

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

      Fehlt die Datei, explizit 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-Zugriffwarning: nur> auf--user-key ausdrücklichen/root/.ssh/authorized_keys Wunsch:übernimmt alle dort enthaltenen Keys. Für genau einen Admin-Key eine dedizierte Public-Key-Datei verwenden.

      4 · Template bauen

      build-debian-template -t 9000 -n debian13-init -m cloudinit --img genericcloud
## optional: --user-key /pfad/admin.pub
## optional (opt-in): --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 in der Arbeitskopie 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-/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:Prüfen:

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

      Erwartet:

        agent: 1 beziehungsweise(bzw. enabled=1), scsi1 enthält cloudinit, ciuser: csgadmin, Boot-Reihenfolge enthält scsi0;scsi1 .

        important: > Template niemals booten.booten Immer— immer einen Clone zum Testen verwenden. Ein gebootetes Template hat Cloud-Init bereits ausgeführt.

        5 · VM klonen

        Test-VM mit DHCP und gewünschter Endgrösse:

        ## DHCP, gewünschte Endgrösse
clone-vm 9000 901 test-debian dhcp --disk-size 32G
        ##

        VMstatische mit statischer IPv4-Adresse undIPv4, 64-GB-Disk:

        Disk 
        (Werte im Zielnetz geltend setzen)
clone-vm 9000 121 app-staging 10.10.10.121/24<IPv4>/<CIDR> 10.10.10.1<Gateway-IPv4> --disk-size 64G
        ##

        --disk-size ist optional. Der Clone-Helper vergrössert scsi0 vor dem ersten Start auf die angegebene absolute Grösse. Debian Cloud-Init/growpart erweitert beim ersten Boot Partition und Dateisystem automatisch. Verkleinern ist nicht möglich; die Zielgrösse muss mindestens so gross wie die Template-Disk sein.

        Der Clone-Helper:

          erstellt einen Full Clone setzt Proxmox-seitig agent enabled=1 setzt DHCP oder statische IPv4-Konfiguration vergrössert optional scsi0 mit --disk-size <SIZE> vor dem ersten Boot ergänzt wiederholbar weitere NICs mit --add-nic <BRIDGE> <dhcp|IPv4/CIDR> regeneriert den Cloud-Init-Seed nach allen Änderungen startet die VM

          Zusätzlichezusätzliche NIC beim(wiederholbar) Erstellen:

          clone-vm 9000 130 dualnic 10.10.10.130/24 10.10.10.1dhcp --add-nic vmbr1 dhcp

            --disk-size ist optional; vergrössert scsi0 vor dem ersten Boot auf die absolute Grösse. Verkleinern nicht möglich; mindestens Template-Grösse. Debian Cloud-Init/growpart erweitert Partition und Dateisystem automatisch. --add-nic ist wiederholbar und erzeugt net1/ipconfig1, danachdann net2/ipconfig2 usw. Sekundäre NICs erhalten bewusst kein zweites Default-Gateway. Der Clone-Helper erstellt Full Clones, setzt agent enabled=1, die IP-Konfiguration, regeneriert den Cloud-Init-Seed nach allen Änderungen und startet die VM. Linked Clones nur für Throwaway-Tests; Staging-/Prod-/Infra-VMs bleiben Full Clones.

            Netzwerkdienst im Debian-Gast

            Das Debian-13-generic-amd64-Image verwendet(laut offiziellem Paketmanifest, Stand 2026-10) enthält Netplan als(netplan.io) Konfigurationsschicht. Der Renderer/Daemon ist normalerweise systemd-networkd, DNS läuft überund systemd-resolved; NetworkManager und klassisches ifupdown sind im offiziellen Paketmanifest nicht enthalten. Netplan rendert per Standard-Renderer systemd-networkd (Teil von systemd).

            systemctl is-active systemd-networkd
systemctl is-active systemd-resolved
networkctl
ls -l /etc/netplan/

            Bestehende VM manuell um eine NIC erweitern

            Auf Proxmox die (VM sauber herunterfahren, NIC ergänzen und starten:herunterfahren):

            qm shutdown <VMID>
qm set <VMID> --net1 virtio,bridge=vmbr1
qm start <VMID>

            Im Gast denInterfacename neuenermitteln Interfacenamen ermitteln:

            (ip -br link;

            Typischerweise isttypisch net0 → ens18 und, net1 → ens19; — immer tatsächlich prüfen.

            prüfen).

            DHCP-BeispielNetplan-Datei für ens19:ergänzen:

            ## DHCP
printf '%s\n' 'network:' '  version: 2' '  ethernets:' '    ens19:' '      dhcp4: true' '      dhcp6: false' \
  | sudo tee /etc/netplan/60-secondary-nic.yaml >/dev/null
sudo## netplan generate
sudo netplan apply

            Statische IPv4statisch, ohne zweites Default-Gateway:

            Gateway 
            printf '%s\n' 'network:' '  version: 2' '  ethernets:' '    ens19:' '      dhcp4: false' '      dhcp6: false' '      addresses: [192.168.50.10/24]<IPv4>/<CIDR>]' \
  | sudo tee /etc/netplan/60-secondary-nic.yaml >/dev/null

sudo netplan generate && sudo netplan apply

            DanachPrüfen: prüfen:

            ip -br addr, networkctl status ens19.

            important: > Bei einer bereits initialisierten VM Netplan im Gast ändern;über nichtNetplan ändern. Nicht darauf vertrauen, dass nachträglich gesetztes Proxmox-ipconfig1 Cloud-Init vollständig erneut ausführt.

            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:Init status: done, csgadmin existiertexistiert, HostnameHostname/IPv4 undstimmen, IPv4-Konfiguration stimmen cidata istvorhanden, vorhandenGuest-Agent qemu-guest-agentaktiv, ist installiert Guest-Agent-Dienst ist active disable_ipv6 = 1 Kernel-Commandline enthält, ipv6.disable=1 in der Kernel-Commandline, keine IPv6-Adressen 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ässigStandard /root/.ssh/id_csgadmin.pub Admin-Zugang gemäss Cloud-Image/Cloud-Init
              hermes nur mit --hermes --hermes-key, standardmässigStandard /root/.ssh/id_ed25519.pub NOPASSWD:ALL, Passwort gesperrt
              root kein SSH-Login keiner PermitRootLogin no

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

              important: > Hermes ist opt-in.in Der— 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,sein; bei OVMF auf scsi1.
              4. Nach Änderungen an ci* immer qm cloudinit update <VMID>.
              5. Kunden-/Staging-/Prod-/Infra-VMs als Full CloneClones erstellen.
              6. Admin-Key vor dem Build verifizieren; der Build bricht bei fehlender oder fehlender/leerer Key-Datei ab.
              7. Nach dem ersten Clone Cloud-Init, Guest Agent, IPv4, SSH und deaktiviertes IPv6 prüfen.
              8. Skripte nicht aus Obsidiander KB kopieren; immer den aktuellen OneDev-Stand aus dem Repo 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 oderbzw. --target-store <STORE> setzen
              VM-ID existiert nach fehlgeschlagenem Import alter Build hat die VMTeilbau 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 Debianneu laden; aktueller SkriptstandStand arbeitet mit /var/tmp-Kopie
              Kein SSH-Login Key nicht im Cloud-Init-Seed qm config, (sshkeys), Key-Datei undDatei, 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übersprungen Template wurde gebootet Template sauber neu bauen; künftig nur Clones booten
              qemu-guest-agent fehlt altes/fehlerhaftes Template aktuelles Build-Skript installieren undSkript, 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 aktuellesneues Template bauen;Template; Sysctl, Kernelparameter undKernelparameter, 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,das interne Git-Repo, nicht ein eingebetteter Skriptblock in Obsidian.der KB.

              • Repo: corestream/proxmox-debian-cloudinit-scripts
              • SSH:(internes ssh://git@git.corestream.ch:6611/corestream/proxmox-debian-cloudinit-scripts.gitOneDev)
              • 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 DokumentationDoku und ausführbarer Code nicht erneut auseinanderlaufen.

              Verwandt: Staging- und Produktionskonzept

              Quellen

                Debian Cloud-Images (trixie, latest): https://cloud.debian.org/images/cloud/trix/latest/ Debian Cloud image Paketmanifest (debian-13-generic-amd64.json): https://cloud.debian.org/images/cloud/trix/latest/debian-13-generic-amd64.json Proxmox VE Administration Guide – QEMU/Cloud-Init: https://pve.proxmox.com/pve-docs/chapter-qm.html Proxmox VE Wiki – Cloud-Init Support: https://pve.proxmox.com/wiki/Cloud-Init_Support

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

                Back to top