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

Proxmox · Debian-VM-Strategie

~~Abstract:~~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 · 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.~~

10 · Source of Truth

1 · Standard und Entscheidung

Modus |Image ~~Image~~Einsatz | ~~Einsatz~~ |

~~|---|---|---|~~

cloudinit ~~`cloudinit` | `~~debian-13-generic-amd64.qcow2`qcow2 | CORESTREAM-Standard; User, Key, Hostname und IP pro VM |

~~`bake`~~bake ~~| `~~debian-13-nocloud-amd64.qcow2`qcow2 | Sonderfall für bewusst fest gebackene Images |

~~Tip:~~tip: Empfehlung

Für neue Kunden-, Staging- und Infrastruktur-VMs immer ~~`cloudinit`~~cloudinit mit `--img genericcloud`genericcloud verwenden.

~~Warning:~~warning: Image-Falle

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

2 · Skripte installieren

Auf jedem neuen Proxmox-Host als ~~`root`~~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`sh

~~- `~~

/opt/corestream/proxmox-debian-cloudinit/clone-vm.sh`sh

Kommandos über Symlinks:

`/usr/local/sbin/build-debian-template`template

~~- `~~

/usr/local/sbin/clone-vm`vm

~~Note:~~note:
>
Der OneDev-Raw-Zugriff ist anonym als `Code Reader`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`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`~~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:~~warning:
>
Bei `--user-key /root/.ssh/authorized_keys`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`tmp und verändert niemals das zentrale NFS-Basisimage

aktualisiert nur diese Arbeitskopie vor der Paketinstallation

installiert und verifiziert `qemu-guest-agent`agent, ~~`sudo`~~sudo und `openssh-server`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`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`config

erstellt eine OVMF-/Q35-VM mit SCSI-Disk und Cloud-Init-Drive

setzt `ciuser=csgadmin`csgadmin, SSH-Key und DHCP als Ausgangswert

wandelt die VM in ein Template um

Template-Konfiguration prüfen:

Erwartet:

`agent: 1`1 beziehungsweise `enabled=1`1

~~- `scsi1`~~

scsi1 enthält ~~`cloudinit`~~cloudinit

~~- `~~

ciuser: csgadmin`csgadmin

Boot-Reihenfolge enthält `scsi0;scsi1`scsi1

~~Important:~~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`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`done

~~- `csgadmin`~~

csgadmin existiert

Hostname und IPv4-Konfiguration stimmen

~~- `cidata`~~

cidata ist vorhanden

~~- `~~

qemu-guest-agent`agent ist installiert

Guest-Agent-Dienst ist ~~`active`~~active

~~- `~~

disable_ipv6 = 1`1

Kernel-Commandline enthält `ipv6.disable=1`1

keine IPv6-Adressen

6.2 Auf Proxmox

qm agent <VMID> ping

SSH-Test:

ssh csgadmin@<IPv4>

7 · User und SSH-Zugriff

User |Standard ~~Standard~~Key |Rechte ~~Key~~ | ~~Rechte~~|

~~|---|---|---|---|~~

csgadmin

~~| `csgadmin` |~~

immer im Cloud-Init-Modus ~~| `~~--user-key`key, standardmässig `/root/.ssh/id_csgadmin.pub`pub | Admin-Zugang gemäss Cloud-Image/Cloud-Init |

~~`hermes`~~hermes | nur mit `--hermes`hermes ~~| `~~--hermes-key`key, standardmässig `/root/.ssh/id_ed25519.pub`pub ~~| `~~NOPASSWD:ALL`ALL, Passwort gesperrt |

~~`root`~~root | kein SSH-Login |keiner ~~keiner | `~~PermitRootLogin no`no |

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

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

8 · Goldene Regeln

Für Cloud-Init `debian-13-generic-amd64.qcow2`qcow2 verwenden.

Template nie booten.

Cloud-Init-Drive muss vorhanden sein, bei OVMF auf ~~`scsi1`~~scsi1.

Nach Änderungen an `ci*` immer `qm cloudinit update `<VMID>.

Kunden-/Staging-/Prod-/Infra-VMs als Full Clone erstellen.

Admin-Key vor dem Build verifizieren; der Build bricht bei fehlender oder leerer Key-Datei ab.

Nach dem ersten Clone Cloud-Init, Guest Agent, IPv4, SSH und deaktiviertes IPv6 prüfen.

Skripte nicht aus Obsidian kopieren; immer den aktuellen OneDev-Stand installieren.

9 · Troubleshooting

Symptom |Ursache ~~Ursache~~Fix | ~~Fix~~ |

~~|---|---|---|~~

~~| `~~

user pubkey missing`missing | Default-Key-Datei fehlt | dedizierte Datei bereitstellen oder `--user-key `<datei> verwenden |

`storage ... does not support vm images`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`tmp-Kopie | Kein SSH-Login | Key nicht im Cloud-Init-Seed ~~| `~~qm config`config, ~~`sshkeys`~~sshkeys, Key-Datei und `qm cloudinit update`update prüfen |

`cloud-init: command not found`found ~~| `nocloud`~~nocloud-Image verwendet | Template mit `generic-amd64`amd64 neu bauen |

~~`cidata`~~cidata fehlt | Cloud-Init-Drive fehlt/falscher Bus ~~| `scsi1`~~scsi1 und `qm cloudinit update`update prüfen |

Cloud-Init überspringt | Template wurde gebootet | Template sauber neu bauen; künftig nur Clones booten |

`qemu-guest-agent`agent fehlt | altes/fehlerhaftes Template | aktuelles Build-Skript installieren und Template neu bauen |

`qm agent <VMID> ping`ping scheitert | Paket/Dienst/Agent-Flag fehlt | Gastpaket, Dienst, `/dev/virtio-ports/` und `qm config`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:~~important:
>
Ausführbarer Source of Truth ist OneDev, nicht ein eingebetteter Skriptblock in Obsidian.

**Repo:** `corestream/proxmox-debian-cloudinit-scripts`scripts

SSH: **SSH:** `ssh://git@git.corestream.ch:6611/corestream/proxmox-debian-cloudinit-scripts.git`git

Installer: **Installer:** `https://git.corestream.ch/corestream/proxmox-debian-cloudinit-scripts/~raw/master/install-on-proxmox.sh`sh

Installationspfad: **Installationspfad:** `/opt/corestream/proxmox-debian-cloudinit`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.