gh-poindexter12-waypoint-technologies/skills/ansible/references/proxmox/modules.md

Ansible Proxmox Modules

Proxmox VE management via community.general collection.

Collection Setup

ansible-galaxy collection install community.general

Core Modules

proxmox (LXC Containers)

- name: Create LXC container
  community.general.proxmox:
    api_host: proxmox.example.com
    api_user: ansible@pve
    api_token_id: mytoken
    api_token_secret: "{{ proxmox_token_secret }}"
    node: joseph
    vmid: 200
    hostname: mycontainer
    ostemplate: local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.zst
    storage: local-lvm
    cores: 2
    memory: 2048
    disk: 10
    netif: '{"net0":"name=eth0,bridge=vmbr0,ip=dhcp"}'
    state: present

- name: Start container
  community.general.proxmox:
    api_host: proxmox.example.com
    api_user: ansible@pve
    api_token_id: mytoken
    api_token_secret: "{{ proxmox_token_secret }}"
    node: joseph
    vmid: 200
    state: started

- name: Stop container
  community.general.proxmox:
    # ... auth params ...
    vmid: 200
    state: stopped
    force: true  # Force stop if graceful fails

- name: Remove container
  community.general.proxmox:
    # ... auth params ...
    vmid: 200
    state: absent

proxmox_kvm (VMs)

- name: Create VM 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  # Full clone (not linked)
    storage: local-lvm
    format: raw
    timeout: 500

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

- name: Stop VM (ACPI shutdown)
  community.general.proxmox_kvm:
    # ... auth params ...
    vmid: 300
    state: stopped
    force: false  # Graceful ACPI

- name: Force stop VM
  community.general.proxmox_kvm:
    # ... auth params ...
    vmid: 300
    state: stopped
    force: true

- name: Current state (running/stopped/present/absent)
  community.general.proxmox_kvm:
    # ... auth params ...
    vmid: 300
    state: current
  register: vm_state

proxmox_template

- name: Convert VM to template
  community.general.proxmox_template:
    api_host: proxmox.example.com
    api_user: ansible@pve
    api_token_id: mytoken
    api_token_secret: "{{ proxmox_token_secret }}"
    node: joseph
    vmid: 100
    state: present  # Convert to template

- name: Delete template
  community.general.proxmox_template:
    # ... auth params ...
    vmid: 100
    state: absent

proxmox_snap

- name: Create snapshot
  community.general.proxmox_snap:
    api_host: proxmox.example.com
    api_user: ansible@pve
    api_token_id: mytoken
    api_token_secret: "{{ proxmox_token_secret }}"
    vmid: 300
    snapname: before-upgrade
    description: "Snapshot before major upgrade"
    vmstate: false  # Don't include RAM
    state: present

- name: Rollback to snapshot
  community.general.proxmox_snap:
    # ... auth params ...
    vmid: 300
    snapname: before-upgrade
    state: rollback

- name: Remove snapshot
  community.general.proxmox_snap:
    # ... auth params ...
    vmid: 300
    snapname: before-upgrade
    state: absent

proxmox_nic

- name: Add NIC to VM
  community.general.proxmox_nic:
    api_host: proxmox.example.com
    api_user: ansible@pve
    api_token_id: mytoken
    api_token_secret: "{{ proxmox_token_secret }}"
    vmid: 300
    interface: net1
    bridge: vmbr12
    model: virtio
    tag: 12  # VLAN tag
    state: present

- name: Remove NIC
  community.general.proxmox_nic:
    # ... auth params ...
    vmid: 300
    interface: net1
    state: absent

proxmox_disk

- name: Add disk to VM
  community.general.proxmox_disk:
    api_host: proxmox.example.com
    api_user: ansible@pve
    api_token_id: mytoken
    api_token_secret: "{{ proxmox_token_secret }}"
    vmid: 300
    disk: scsi1
    storage: local-lvm
    size: 50G
    format: raw
    state: present

- name: Resize disk
  community.general.proxmox_disk:
    # ... auth params ...
    vmid: 300
    disk: scsi0
    size: +20G  # Increase by 20G
    state: resized

- name: Detach disk
  community.general.proxmox_disk:
    # ... auth params ...
    vmid: 300
    disk: scsi1
    state: absent

State Reference

Module	States
proxmox (LXC)	present, started, stopped, restarted, absent
proxmox_kvm	present, started, stopped, restarted, absent, current
proxmox_template	present, absent
proxmox_snap	present, absent, rollback
proxmox_nic	present, absent
proxmox_disk	present, absent, resized

Common Parameters

All modules share these authentication parameters:

Parameter	Description
api_host	Proxmox hostname/IP
api_user	User (format: user@realm)
api_token_id	API token name
api_token_secret	API token value
validate_certs	Verify TLS (default: true)
timeout	API timeout seconds