Initial commit

skills/proxmox-infrastructure/reference/cloud-init-patterns.md

@@ -0,0 +1,163 @@
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# Clone template to new VM
+qm clone 9000 123 --name ubuntu2
+```
+
+### Configure VM
+
+```bash
+# 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:
+
+```bash
+qm set 9000 --cicustom "user=<volume>,network=<volume>,meta=<volume>"
+```
+
+Example using local snippets storage:
+
+```bash
+qm set 9000 --cicustom "user=local:snippets/userconfig.yaml"
+```
+
+### Dump Generated Config
+
+Use as a base for custom configurations:
+
+```bash
+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`