↓Skip to main content

Ansible Modules for Proxmox

··2 mins
Proxmox Ansible
Table of Contents

Create Ansible User in Proxmox #

# create role
pveum role add AnsibleUser --privs "Datastore.AllocateSpace \
  VM.Allocate VM.Audit VM.Clone VM.Config.CDROM \
  VM.Config.Cloudinit VM.Config.CPU VM.Config.Disk \
  VM.Config.HWType VM.Config.Memory VM.Config.Network \
  VM.Config.Options VM.Console VM.Monitor VM.PowerMgmt"

# create group
pveum group add ansible-users

# add permissions
pveum acl modify / -group ansible-users -role AnsibleUser

# create user 'ansible'
pveum useradd ansible@pve -groups ansible-users

# generate a token
pveum user token add ansible@pve token -privsep 0

Module: proxmox #

Quick notes:

Module: proxmox_kvm #

Quick notes:

  • Ansible Docs: community.general.proxmox_kvm
  • Provides a way to provision VMs on PVE from backups, templates or create new VMs.
  • Alternative to Terraform, but without a state file.
  • Run the plays from a localhost or remote host that is not a Proxmox node, as the task will access the Proxmox API endpoint.
  • The task requires the python libraries: proxmoxer and requests. However, only the Ansible controller needs these dependencies installed.
  • You cannot set the api_* variables in a file, this leads to code duplication in the playbook.

Example Code #

Variable File:

# proxmox_vars.yml
pve_host: "192.168.100.1:8006/api2/json"
pve_node: "proxmox"
pve_storage: "local-lvm"
pve_token_id: "{{ vault_pve_token_id }}"
pve_token_secret: "{{ vault_pve_token_secret }}"
pve_user: "ansible@pve"

Vault File:

# vault.yml
vault_pve_token_id: "token"
vault_pve_token_secret: "782a7700-4010-4802-8f4d-820f1b226850"

Example Playbook:

  • vmid: PVE template ID.
  • clone: PVE template name, required if vmid is set, but no validation occurs so the value is arbitrary.
  • name: name of new VM, if unset defaults to 'Copy-of-VM-[PVE_TEMPLATE_NAME]'.
# playbook.yml
---
- name: Create VM from Proxmox Template
  hosts:
    - localhost
  vars_files:
    - proxmox_vars.yml
  tasks:
    - name: Create VM from Proxmox Template
      delegate_to: localhost
      block:
        - name: Clone Proxmox Template
          community.general.proxmox_kvm:
            node: "{{ pve_node }}"
            api_host: "{{ pve_host }}"
            api_user: "{{ pve_user }}"
            api_token_id: "{{ pve_token_id }}"
            api_token_secret: "{{ pve_token_secret }}"
            vmid: 9000 # template ID
            clone: foobar # no validation, arbitrary value to trigger clone process
            name: new-vm-name
            storage: "{{ pve_storage }}"
            timeout: 60
          register: proxmox_vm

        - name: VM - Start, Stop, Remove
          community.general.proxmox_kvm:
            node: "{{ pve_node }}"
            api_host: "{{ pve_host }}"
            api_user: "{{ pve_user }}"
            api_token_id: "{{ pve_token_id }}"
            api_token_secret: "{{ pve_token_secret }}"
            vmid: "{{ proxmox_vm.vmid }}"
            state: started # started, stopped, absent
            timeout: 60

References #

Ansible:

Proxmox:

Python: