gh-basher83-lunar-claude-plugins-infrastructure-proxmox-infrastructure/skills/proxmox-infrastructure/reference/cloud-init-patterns.md

Cloud-Init Patterns for Proxmox VE

*Source: https://pve.proxmox.com/wiki/Cloud-Init_Support*

Overview

Cloud-Init is the de facto multi-distribution package that handles early initialization of virtual machines. When a VM starts for the first time, Cloud-Init applies network and SSH key settings configured on the hypervisor.

Template Creation Workflow

Download and Import Cloud Image

# Download Ubuntu cloud image
wget https://cloud-images.ubuntu.com/bionic/current/bionic-server-cloudimg-amd64.img

# Create VM with VirtIO SCSI controller
qm create 9000 --memory 2048 --net0 virtio,bridge=vmbr0 --scsihw virtio-scsi-pci

# Import disk to storage
qm set 9000 --scsi0 local-lvm:0,import-from=/path/to/bionic-server-cloudimg-amd64.img

Important: Ubuntu Cloud-Init images require virtio-scsi-pci controller type for SCSI drives.

Configure Cloud-Init Components

# Add Cloud-Init CD-ROM drive
qm set 9000 --ide2 local-lvm:cloudinit

# Set boot order (speeds up boot)
qm set 9000 --boot order=scsi0

# Configure serial console (required for many cloud images)
qm set 9000 --serial0 socket --vga serial0

# Convert to template
qm template 9000

Deploying from Templates

Clone Template

# Clone template to new VM
qm clone 9000 123 --name ubuntu2

Configure VM

# Set SSH public key
qm set 123 --sshkey ~/.ssh/id_rsa.pub

# Configure network
qm set 123 --ipconfig0 ip=10.0.10.123/24,gw=10.0.10.1

Custom Cloud-Init Configuration

Using Custom Config Files

Proxmox allows custom cloud-init configurations via the cicustom option:

qm set 9000 --cicustom "user=<volume>,network=<volume>,meta=<volume>"

Example using local snippets storage:

qm set 9000 --cicustom "user=local:snippets/userconfig.yaml"

Dump Generated Config

Use as a base for custom configurations:

qm cloudinit dump 9000 user
qm cloudinit dump 9000 network
qm cloudinit dump 9000 meta

Cloud-Init Options Reference

cicustom

Specify custom files to replace automatically generated ones:

• meta=<volume> - Meta data (provider specific)
• network=<volume> - Network data
• user=<volume> - User data
• vendor=<volume> - Vendor data

cipassword

Password for the user. Not recommended - use SSH keys instead.

citype

Configuration format: configdrive2 | nocloud | opennebula

• Default: nocloud for Linux, configdrive2 for Windows

ciupgrade

Automatic package upgrade after first boot (default: true)

ciuser

Username to configure (instead of image's default user)

ipconfig[n]

IP addresses and gateways for network interfaces.

Format: [gw=<GatewayIPv4>] [,gw6=<GatewayIPv6>] [,ip=<IPv4Format/CIDR>] [,ip6=<IPv6Format/CIDR>]

Special values:

• ip=dhcp - Use DHCP for IPv4
• ip6=auto - Use stateless autoconfiguration (requires cloud-init 19.4+)

sshkeys

Public SSH keys (one per line, OpenSSH format)

nameserver

DNS server IP address

searchdomain

DNS search domains

Best Practices

1. Use SSH keys instead of passwords for authentication
2. Configure serial console for cloud images (many require it)
3. Set boot order to speed up boot process
4. Convert to template for fast linked clone deployment
5. Store custom configs in snippets storage (must be on all nodes for migration)
6. Test with a clone before modifying template

Troubleshooting

Template Won't Boot

• Check if serial console is configured: qm set <vmid> --serial0 socket --vga serial0
• Verify boot order: qm set <vmid> --boot order=scsi0

Network Not Configured

• Ensure cloud-init CD-ROM is attached: qm set <vmid> --ide2 local-lvm:cloudinit
• Check IP configuration: qm config <vmid> | grep ipconfig

SSH Keys Not Working

• Verify sshkeys format (OpenSSH format, one per line)
• Check cloud-init logs in VM: cat /var/log/cloud-init.log