Documentation

proxmox - management of instances in Proxmox VE cluster

New in version 2.0.

Synopsis

  • allows you to create/delete/stop instances in Proxmox VE cluster
  • Starting in Ansible 2.1, it automatically detects containerization type (lxc for PVE 4, openvz for older)

Requirements (on host that executes module)

  • proxmoxer
  • python >= 2.7
  • requests

Options

parameter required default choices comments
api_host
yes
the host of the Proxmox VE cluster
api_password
no
the password to authenticate with
you can use PROXMOX_PASSWORD environment variable
api_user
yes
the user to authenticate with
cpus
no 1
numbers of allocated cpus for instance
cpuunits
no 1000
CPU weight for a VM
disk
no 3
hard disk size in GB for instance
force
no
  • yes
  • no
forcing operations
can be used only with states present, stopped, restarted
with state=present force option allow to overwrite existing container
with states stopped , restarted allow to force stop instance
hostname
no
the instance hostname
required only for state=present
must be unique if vmid is not passed
ip_address
no
specifies the address the container will be assigned
memory
no 512
memory size in MB for instance
mounts
(added in 2.2)
no
specifies additional mounts (separate disks) for the container. As a hash/dictionary defining mount points
nameserver
no
sets DNS server IP address for a container
netif
no
specifies network interfaces for the container. As a hash/dictionary defining interfaces.
node
no
Proxmox VE node, when new VM will be created
required only for state=present
for another states will be autodiscovered
onboot
no
specifies whether a VM will be started during system bootup
ostemplate
no
the template for VM creating
required only for state=present
password
no
the instance root password
required only for state=present
pool
(added in 2.3)
no
Proxmox VE resource pool
pubkey
(added in 2.3)
no
Public key to add to /root/.ssh/authorized_keys. This was added on Proxmox 4.2, it is ignored for earlier versions
searchdomain
no
sets DNS search domain for a container
state
no present
  • present
  • started
  • absent
  • stopped
  • restarted
Indicate desired state of the instance
storage
no local
target storage
swap
no
swap memory size in MB for instance
timeout
no 30
timeout for operations
unprivileged
(added in 2.3)
no
Indicate if the container should be unprivileged
validate_certs
no
  • yes
  • no
enable / disable https certificate verification
vmid
no
the instance id
if not set, the next available VM ID will be fetched from ProxmoxAPI.
if not set, will be fetched from PromoxAPI based on the hostname

Examples

# Create new container with minimal options
- proxmox:
    vmid: 100
    node: uk-mc02
    api_user: [email protected]
    api_password: 1q2w3e
    api_host: node1
    password: 123456
    hostname: example.org
    ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz'

# Create new container automatically selecting the next available vmid.
- proxmox:
    node: 'uk-mc02'
    api_user: '[email protected]'
    api_password: '1q2w3e'
    api_host: 'node1'
    password: '123456'
    hostname: 'example.org'
    ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz'

# Create new container with minimal options with force(it will rewrite existing container)
- proxmox:
    vmid: 100
    node: uk-mc02
    api_user: [email protected]
    api_password: 1q2w3e
    api_host: node1
    password: 123456
    hostname: example.org
    ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz'
    force: yes

# Create new container with minimal options use environment PROXMOX_PASSWORD variable(you should export it before)
- proxmox:
    vmid: 100
    node: uk-mc02
    api_user: [email protected]
    api_host: node1
    password: 123456
    hostname: example.org
    ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz'

# Create new container with minimal options defining network interface with dhcp
- proxmox:
    vmid: 100
    node: uk-mc02
    api_user: [email protected]
    api_password: 1q2w3e
    api_host: node1
    password: 123456
    hostname: example.org
    ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz'
    netif: '{"net0":"name=eth0,ip=dhcp,ip6=dhcp,bridge=vmbr0"}'

# Create new container with minimal options defining network interface with static ip
- proxmox:
    vmid: 100
    node: uk-mc02
    api_user: [email protected]
    api_password: 1q2w3e
    api_host: node1
    password: 123456
    hostname: example.org
    ostemplate: 'local:vztmpl/ubuntu-14.04-x86_64.tar.gz'
    netif: '{"net0":"name=eth0,gw=192.168.0.1,ip=192.168.0.2/24,bridge=vmbr0"}'

# Create new container with minimal options defining a mount
- proxmox:
    vmid: 100
    node: uk-mc02
    api_user: [email protected]
    api_password: 1q2w3e
    api_host: node1
    password: 123456
    hostname: example.org
    ostemplate: local:vztmpl/ubuntu-14.04-x86_64.tar.gz'
    mounts: '{"mp0":"local:8,mp=/mnt/test/"}'

# Start container
- proxmox:
    vmid: 100
    api_user: [email protected]
    api_password: 1q2w3e
    api_host: node1
    state: started

# Stop container
- proxmox:
    vmid: 100
    api_user: [email protected]
    api_password: 1q2w3e
    api_host: node1
    state: stopped

# Stop container with force
- proxmox:
    vmid: 100
    api_user: [email protected]
    api_password: 1q2w3e
    api_host: node1
    force: yes
    state: stopped

# Restart container(stopped or mounted container you can't restart)
- proxmox:
    vmid: 100
    api_user: [email protected]
    api_password: 1q2w3e
    api_host: node1
    state: stopped

# Remove container
- proxmox:
    vmid: 100
    api_user: [email protected]
    api_password: 1q2w3e
    api_host: node1
    state: absent

Notes

Note

  • Requires proxmoxer and requests modules on host. This modules can be installed with pip.

Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

Support

This module is community maintained without core committer oversight.

For more information on what this means please read Module Support

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Helping Testing PRs and Developing Modules.