Proxmox Infrastructure Management

Expert guidance for managing Proxmox VE clusters, creating templates, provisioning VMs, and configuring network infrastructure.

Quick Start

Common Tasks

Create VM Template:

# See tools/build-template.yml for automated playbook
cd ansible && uv run ansible-playbook playbooks/proxmox-build-template.yml

Clone Template to VM:

qm clone <template-id> <new-vmid> --name <vm-name>
qm set <new-vmid> --sshkey ~/.ssh/id_rsa.pub
qm set <new-vmid> --ipconfig0 ip=192.168.1.100/24,gw=192.168.1.1
qm start <new-vmid>

Check Cluster Status:

# Use tools/cluster_status.py
./tools/cluster_status.py

When to Use This Skill

Activate this skill when:

• Creating or managing Proxmox VM templates
• Provisioning VMs via cloning or Terraform
• Configuring Proxmox networking (bridges, VLANs, bonds)
• Troubleshooting VM deployment or network issues
• Managing CEPH storage pools
• Working with QEMU guest agent
• Interacting with Proxmox API via Python or Ansible

Core Workflows

1. Template Creation

Method 1: Using Ansible (Recommended)

See tools/build-template.yml for complete automation.

Method 2: Manual CLI

See reference/cloud-init-patterns.md for detailed steps.

Key points:

• Use virtio-scsi-pci controller for Ubuntu images
• Add cloud-init CD-ROM drive (ide2)
• Configure serial console for cloud images
• Convert to template with qm template <vmid>

2. VM Provisioning

From Ansible: Analyze existing playbook: ../../ansible/playbooks/proxmox-build-template.yml

From Terraform: See examples in ../../terraform/netbox-vm/

Key Configuration:

# Ansible example
proxmox_kvm:
  node: foxtrot
  api_host: 192.168.3.5
  vmid: 101
  name: docker-01
  clone: ubuntu-template
  storage: local-lvm
  # Network with VLAN
  net:
    net0: 'virtio,bridge=vmbr0,tag=30'
  ipconfig:
    ipconfig0: 'ip=192.168.3.100/24,gw=192.168.3.1'

3. Network Configuration

This Virgo-Core cluster uses:

• vmbr0: Management (192.168.3.0/24, VLAN 9 for Corosync)
• vmbr1: CEPH Public (192.168.5.0/24, MTU 9000)
• vmbr2: CEPH Private (192.168.7.0/24, MTU 9000)

See reference/networking.md for:

• VLAN-aware bridge configuration
• Bond setup (802.3ad LACP)
• Routed vs bridged vs NAT setups

Architecture Reference

This Cluster ("Matrix")

Nodes: Foxtrot, Golf, Hotel (3× MINISFORUM MS-A2)

Hardware per Node:

• AMD Ryzen 9 9955HX (16C/32T)
• 64GB DDR5 @ 5600 MT/s
• 3× NVMe: 1× 1TB (boot), 2× 4TB (CEPH)
• 4× NICs: 2× 10GbE SFP+, 2× 2.5GbE

Network Architecture:

enp4s0 → vmbr0 (mgmt + vlan9 for corosync)
enp5s0f0np0 → vmbr1 (ceph public, MTU 9000)
enp5s0f1np1 → vmbr2 (ceph private, MTU 9000)

See ../../docs/goals.md for complete specs.

Tools Available

Python Scripts (uv)

validate_template.py - Validate template health via API

./tools/validate_template.py --template-id 9000

vm_diagnostics.py - VM health checks

./tools/vm_diagnostics.py --vmid 101

cluster_status.py - Cluster health metrics

./tools/cluster_status.py

Ansible Playbooks

build-template.yml - Automated template creation

• Downloads cloud image
• Creates VM with proper configuration
• Converts to template

configure-networking.yml - VLAN bridge setup

• Creates VLAN-aware bridges
• Configures bonds
• Sets MTU for storage networks

OpenTofu Modules

vm-module-example/ - Reusable VM provisioning

• Clone-based deployment
• Cloud-init integration
• Network configuration

See examples/ directory.

Real Examples from Repository:

• Multi-VM Cluster: ../../terraform/examples/microk8s-cluster - Comprehensive 3-node MicroK8s deployment using for_each pattern, cross-node cloning, dual NIC with VLAN (VLAN 30 primary, VLAN 2 secondary), Ansible integration
• Template with Cloud-Init: ../../terraform/examples/template-with-custom-cloudinit - Custom cloud-init snippet configuration
• VLAN Bridge Configuration: ../../ansible/playbooks/proxmox-enable-vlan-bridging.yml - Enable VLAN-aware bridging on Proxmox nodes (supports VLANs 2-4094)

Troubleshooting

Common issues and solutions:

Template Creation Issues

Serial console required: Many cloud images need serial console configured.

qm set <vmid> --serial0 socket --vga serial0

Boot order:

qm set <vmid> --boot order=scsi0

Network Issues

VLAN not working:

1. Check bridge is VLAN-aware:

   grep "bridge-vlan-aware" /etc/network/interfaces
   

2. Verify VLAN in bridge-vids:

   bridge vlan show
   

MTU problems (CEPH): Ensure MTU 9000 on storage networks:

ip link show vmbr1 | grep mtu

VM Won't Start

1. Check QEMU guest agent:

   qm agent <vmid> ping
   

2. Review cloud-init logs (in VM):

   cloud-init status --wait
   cat /var/log/cloud-init.log
   

3. Validate template exists:

   qm list | grep template
   

For more issues, see troubleshooting/ directory.

Best Practices

1. Always use templates - Clone for consistency
2. SSH keys only - Never use password auth
3. VLAN-aware bridges - Enable for flexibility
4. MTU 9000 for storage - Essential for CEPH performance
5. Serial console - Required for most cloud images
6. Guest agent - Enable for IP detection and graceful shutdown
7. Tag VMs - Use meaningful tags for organization

Progressive Disclosure

For deeper knowledge:

Advanced Automation Workflows (from ProxSpray Analysis)

• Cluster Formation - Complete cluster automation with idempotency
• CEPH Deployment - Automated CEPH storage deployment

Core Reference

• Cloud-Init patterns - Complete template creation guide
• Network configuration - VLANs, bonds, routing, NAT
• API reference - Proxmox API interactions
• Storage management - CEPH, LVM, datastores
• QEMU guest agent - Integration and troubleshooting

Anti-Patterns & Common Mistakes

• Common Mistakes - Real-world pitfalls from OpenTofu/Ansible deployments, template creation, and remote backend configuration

Related Skills

• NetBox + PowerDNS Integration - Automatic DNS for Proxmox VMs
• Ansible Best Practices - Playbook patterns used in this cluster