ansible/roles/proxmox_vm

Role: proxmox_vm

Provision Proxmox guests via API. This role supports both:

• LXC containers (proxmox_guest_type: lxc) via community.proxmox.proxmox
• KVM VMs (proxmox_guest_type: kvm) via community.general.proxmox_kvm

The entry point is roles/proxmox_vm/tasks/main.yml, which dispatches to tasks/lxc.yml or tasks/kvm.yml.

Requirements

• Ansible (project tested with modern Ansible; older 2.9-era setups may need adjustments)
• Proxmox VE API access
• Collections:
  • community.proxmox
  • community.general (for proxmox_kvm)
• Python lib on the control machine:
  • proxmoxer (installed by make bootstrap / requirements.txt)

Authentication (vault-backed)

Store secrets in inventories/production/group_vars/all/vault.yml:

• vault_proxmox_host
• vault_proxmox_user
• vault_proxmox_password (or token auth)
• vault_proxmox_token_id (optional)
• vault_proxmox_token (optional)
• vault_ssh_public_key (used for bootstrap access where applicable)

Key variables

Common:

• proxmox_guest_type: lxc or kvm
• proxmox_host, proxmox_user, proxmox_node
• proxmox_api_port (default 8006)
• proxmox_validate_certs (default false)

LXC (tasks/lxc.yml):

• lxc_vmid, lxc_hostname
• lxc_ostemplate (e.g. local:vztmpl/debian-12-standard_*.tar.zst)
• lxc_storage (default local-lvm)
• lxc_network_bridge (default vmbr0)
• lxc_ip (CIDR), lxc_gateway
• lxc_cores, lxc_memory_mb, lxc_swap_mb, lxc_rootfs_size_gb

KVM (tasks/kvm.yml):

• vm_id, vm_name
• vm_cores, vm_memory, vm_disk_size
• vm_storage, vm_network_bridge
• cloud-init parameters used by the existing KVM provisioning flow

Safety guardrails

LXC provisioning includes a VMID collision guardrail:

• If the target VMID already exists but the guest name does not match the expected name, provisioning fails.
• Override only if you really mean it: -e allow_vmid_collision=true

Example usage

Provisioning is typically orchestrated by playbooks/app/provision_vms.yml, but you can call the role directly:

- name: Provision one LXC
  hosts: localhost
  connection: local
  gather_facts: false
  tasks:
    - name: Create/update container
      ansible.builtin.include_role:
        name: proxmox_vm
      vars:
        proxmox_guest_type: lxc
        lxc_vmid: 9301
        lxc_hostname: projectA-dev
        lxc_ip: "10.0.10.101/24"
        lxc_gateway: "10.0.10.1"