Ops Proxmox

Proxmox Infrastructure Skill

Proxmox VE infrastructure management with Terraform: provisioning of virtual machines, LXC containers, network configuration, storage and backup.

When to use this skill

This skill is automatically activated when the conversation mentions:

• "Proxmox", "PVE", "Proxmox VE"
• "Proxmox VM", "Proxmox LXC", "Proxmox container"
• "Proxmox cluster", "Proxmox node"
• "PBS", "Proxmox Backup Server"
• "Proxmox cloud-init"
• "QEMU/KVM" in a Proxmox context

Core principles

1. Infrastructure as Code

All Proxmox infrastructure must be managed via Terraform:

• Reproducibility: same config = same result
• Versioning: history in Git
• Review: PR to validate infra changes
• Documentation: the code IS the documentation

2. Environment separation

environments/
├── dev/           # Can be destroyed
├── staging/       # Mirrors prod
└── prod/          # Critical

Each environment has its own variables (terraform.tfvars), its own Terraform state and its own credentials.

3. Reusable modules

modules/
├── vm/            # QEMU/KVM virtual machine
├── lxc/           # LXC container
├── network/       # Network configuration
├── storage/       # Storage configuration
└── backup/        # PBS configuration

Proxmox architecture

Resource hierarchy

Datacenter
├── Cluster (optional)
│   ├── Node 1 (pve1) → VMs, LXC, Storage, Network
│   ├── Node 2 (pve2)
│   └── Node 3 (pve3)
├── Storage (datacenter level)
│   ├── local, local-lvm (per node)
│   ├── nfs-shared (shared)
│   └── ceph (distributed)
└── SDN (Zones, VNets, Subnets)

Resource types

| Type | Description | Use case | |------|-------------|----------| | VM (QEMU) | Full virtual machine | Heavy workloads, strong isolation | | LXC | System container | Lightweight services, high density | | Template | Base image | Fast cloning of VMs/LXC | | Snippet | cloud-init files | Automated configuration |

Terraform provider

bpg/proxmox (recommended)

Modern, well-maintained provider, full coverage of the Proxmox API.

terraform {
  required_version = ">= 1.5.0"
  required_providers {
    proxmox = {
      source  = "bpg/proxmox"
      version = "~> 0.50"
    }
  }
}

provider "proxmox" {
  endpoint  = var.proxmox_endpoint
  api_token = var.proxmox_api_token  # Recommended token
  insecure  = var.proxmox_insecure   # Dev only

  ssh {
    agent    = true
    username = "root"
  }
}

API token authentication

# On the Proxmox node
pveum user token add terraform@pve terraform-token --privsep=0

# Minimal permissions
pveum aclmod / -user terraform@pve -role PVEVMAdmin
pveum aclmod /storage -user terraform@pve -role PVEDatastoreUser

Format: terraform@pve!terraform-token=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Naming conventions

VMs and containers

| Environment | Pattern | Example | |---------------|---------|---------| | Production | prod-{role}-{index} | prod-web-01 | | Staging | stg-{role}-{index} | stg-api-01 | | Development | dev-{role}-{index} | dev-db-01 | | Test | test-{purpose} | test-migration |

VMID ranges

| Range | Usage | |-------|-------| | 100-199 | Infrastructure (DNS, DHCP, etc.) | | 200-299 | Production | | 300-399 | Staging | | 400-499 | Development | | 500-599 | Test/Temporary | | 9000-9099 | Templates |

Recommended tags

environment:prod
role:webserver
team:platform
backup:daily
managed-by:terraform
criticality:high

Security

Best practices

1. API Token: minimal permissions (dedicated role, not root)
2. Firewall: enable the Proxmox firewall by default
3. Isolation: separate VLANs per environment
4. Unprivileged LXC: always use unprivileged containers
5. Audit: log API and SSH access
6. Secrets: NEVER hardcode in HCL (use Vault, TFVAR*, or gitignored tfvars)

Minimal Terraform permissions

# Dedicated role
pveum role add TerraformRole -privs "VM.Allocate VM.Clone VM.Config.CDROM VM.Config.CPU VM.Config.Cloudinit VM.Config.Disk VM.Config.HWType VM.Config.Memory VM.Config.Network VM.Config.Options VM.Monitor VM.Audit VM.PowerMgmt Datastore.AllocateSpace Datastore.AllocateTemplate Datastore.Audit SDN.Use"

# User + assignment
pveum user add terraform@pve
pveum aclmod / -user terraform@pve -role TerraformRole

References

This SKILL.md section contains the core principles. For technical details with full HCL examples, see the reference files:

| File | Content | |---------|---------| | [references/terraform-modules.md](references/terraform-modules.md) | VM modules, LXC, usage, network, storage | | [references/cloud-init.md](references/cloud-init.md) | cloud-config templates, snippet uploads | | [references/backup-ha.md](references/backup-ha.md) | PBS schedule, commands, HA configuration | | [references/troubleshooting.md](references/troubleshooting.md) | Common issues, diagnostic commands, recovery |

Rules

IMPORTANT: NEVER manage Proxmox manually via the UI. Always via Terraform.

IMPORTANT: Use unprivileged LXC by default (limited privilege escalation).

IMPORTANT: One Terraform state per environment (dev/staging/prod isolated).

YOU MUST use the bpg/proxmox provider (modern, maintained) rather than telmate/proxmox (deprecated).

YOU MUST use API tokens with minimal permissions, never root.

NEVER hardcode secrets in committed HCL. Use gitignored tfvars or Vault.

NEVER skip PBS backups on critical VMs.

Attribution

This skill is based on:

• Official Proxmox VE documentation
• bpg/proxmox Terraform provider

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: christopherlouet
• Source: christopherlouet/claude-base
• License: MIT
• Homepage: https://christopherlouet.github.io/claude-base/

Install and usage instructions live in the source repository linked above.