gh-poindexter12-waypoint-technologies/skills/proxmox/references/automation-tools.md

Proxmox Automation Tools

Integration patterns for managing Proxmox with Terraform and Ansible.

Tool Selection Guide

Task	Recommended Tool	Rationale
VM/LXC provisioning	Terraform	Declarative state, idempotent, handles dependencies
Template creation	Packer	Repeatable builds, version-controlled
Post-boot configuration	Ansible	Agent-based, procedural, good for drift
One-off VM operations	Ansible	Quick tasks, no state file needed
Dynamic inventory	Ansible	Query running VMs for configuration
Bulk VM creation	Terraform	count/for_each, parallel creation
Snapshot management	Either	Terraform for lifecycle, Ansible for ad-hoc
Cluster administration	CLI/API	Direct access for maintenance tasks

Terraform Integration

Provider

terraform {
  required_providers {
    proxmox = {
      source  = "telmate/proxmox"
      version = "~> 3.0"
    }
  }
}

provider "proxmox" {
  pm_api_url          = "https://proxmox.example.com:8006/api2/json"
  pm_api_token_id     = "terraform@pve!mytoken"
  pm_api_token_secret = var.pm_api_token_secret
}

Common Patterns

# Clone from template
resource "proxmox_vm_qemu" "vm" {
  name        = "myvm"
  target_node = "joseph"
  clone       = "tmpl-ubuntu-2404-standard"
  full_clone  = true

  cores   = 2
  memory  = 4096

  disks {
    scsi {
      scsi0 {
        disk {
          storage = "local-lvm"
          size    = "50G"
        }
      }
    }
  }
}

Skill Reference

Load terraform skill for detailed patterns:

• terraform/references/proxmox/gotchas.md - Critical issues
• terraform/references/proxmox/vm-qemu.md - VM resource patterns
• terraform/references/proxmox/authentication.md - API setup

Ansible Integration

Collection

ansible-galaxy collection install community.general

Common Patterns

# Clone VM
- name: Clone from template
  community.general.proxmox_kvm:
    api_host: proxmox.example.com
    api_user: ansible@pve
    api_token_id: mytoken
    api_token_secret: "{{ proxmox_token_secret }}"
    node: joseph
    vmid: 300
    name: myvm
    clone: tmpl-ubuntu-2404-standard
    full: true
    timeout: 500

# Start VM
- name: Start VM
  community.general.proxmox_kvm:
    # ... auth ...
    vmid: 300
    state: started

Skill Reference

Load ansible skill for detailed patterns:

• ansible/references/proxmox/modules.md - All Proxmox modules
• ansible/references/proxmox/gotchas.md - Common issues
• ansible/references/proxmox/dynamic-inventory.md - Auto-discovery

Terraform vs Ansible Decision

Use Terraform When

• Creating infrastructure from scratch
• Managing VM lifecycle (create, update, destroy)
• Need state tracking and drift detection
• Deploying multiple similar VMs (for_each)
• Complex dependencies between resources
• Team collaboration with state locking

Use Ansible When

• Configuring VMs after creation
• Ad-hoc operations (start/stop specific VMs)
• Dynamic inventory needed for other playbooks
• Quick one-off tasks
• No state file management desired
• Integration with existing Ansible workflows

Use Both When

• Terraform provisions VMs
• Ansible configures them post-boot
• Ansible uses Proxmox dynamic inventory to find Terraform-created VMs

Hybrid Workflow Example

1. Packer builds VM template
   └── packer build ubuntu-2404.pkr.hcl

2. Terraform provisions VMs from template
   └── terraform apply
   └── Outputs: VM IPs, hostnames

3. Ansible configures VMs
   └── Uses Proxmox dynamic inventory OR
   └── Uses Terraform output as inventory

4. Ongoing management
   └── Terraform for infrastructure changes
   └── Ansible for configuration drift

API Token Sharing

Both tools can share the same API token:

# Create shared token
pveum user add automation@pve
pveum aclmod / -user automation@pve -role PVEAdmin
pveum user token add automation@pve shared --privsep 0

Store in shared secrets management (1Password, Vault, etc.).

Common Gotchas

Issue	Terraform	Ansible
VMID	Auto-assigns if not specified	Must specify manually
Cloud-init changes	Use replace_triggered_by	Limited support, use API
State tracking	Yes (tfstate)	No state file
Parallel operations	Yes (configurable)	Yes (forks)
Template name vs ID	Supports both	Supports both
Timeout handling	Provider config	Module parameter