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

The below requirements are needed on the host that executes this module.

  • proxmoxer
  • python >= 2.7
  • requests

Parameters

Parameter Choices/Defaults Comments
api_host
- / required
the host of the Proxmox VE cluster
api_password
-
the password to authenticate with
you can use PROXMOX_PASSWORD environment variable
api_user
- / required
the user to authenticate with
cores
-
added in 2.4
 Default:
1
Specify number of cores per socket.
cpus
-
Default:
1
numbers of allocated cpus for instance
cpuunits
-
Default:
1000
CPU weight for a VM
disk
-
Default:
3
hard disk size in GB for instance
force
boolean
    Choices:
  • no ←
  • yes
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
-
the instance hostname
required only for state=present
must be unique if vmid is not passed
ip_address
-
specifies the address the container will be assigned
memory
-
Default:
512
memory size in MB for instance
mounts
-
added in 2.2
specifies additional mounts (separate disks) for the container. As a hash/dictionary defining mount points
nameserver
-
sets DNS server IP address for a container
netif
-
specifies network interfaces for the container. As a hash/dictionary defining interfaces.
node
-
Proxmox VE node, when new VM will be created
required only for state=present
for another states will be autodiscovered
onboot
boolean
    Choices:
  • no ←
  • yes
specifies whether a VM will be started during system bootup
ostemplate
-
the template for VM creating
required only for state=present
password
-
the instance root password
required only for state=present
pool
-
added in 2.3
Proxmox VE resource pool
pubkey
-
added in 2.3
Public key to add to /root/.ssh/authorized_keys. This was added on Proxmox 4.2, it is ignored for earlier versions
searchdomain
-
sets DNS search domain for a container
state
-
    Choices:
  • present ←
  • started
  • absent
  • stopped
  • restarted
Indicate desired state of the instance
storage
-
Default:
"local"
target storage
swap
-
Default:
0
swap memory size in MB for instance
timeout
-
Default:
30
timeout for operations
unprivileged
boolean
added in 2.3
    Choices:
  • no ←
  • yes
Indicate if the container should be unprivileged
validate_certs
boolean
    Choices:
  • no ←
  • yes
enable / disable https certificate verification
vmid
-
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

Notes

Note

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

Examples

# Create new container with minimal options
- proxmox:
    vmid: 100
    node: uk-mc02
    api_user: root@pam
    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: 'root@pam'
    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: root@pam
    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: root@pam
    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: root@pam
    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: root@pam
    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 with 8GB
- proxmox:
    vmid: 100
    node: uk-mc02
    api_user: root@pam
    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/"}'

# Create new container with minimal options defining a cpu core limit
- proxmox:
    vmid: 100
    node: uk-mc02
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    password: 123456
    hostname: example.org
    ostemplate: local:vztmpl/ubuntu-14.04-x86_64.tar.gz'
    cores: 2

# Start container
- proxmox:
    vmid: 100
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    state: started

# Start container with mount. You should enter a 90-second timeout because servers with additional disks take longer to boot.
- proxmox:
    vmid: 100
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    state: started
    timeout: 90

# Stop container
- proxmox:
    vmid: 100
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    state: stopped

# Stop container with force
- proxmox:
    vmid: 100
    api_user: root@pam
    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: root@pam
    api_password: 1q2w3e
    api_host: node1
    state: stopped

# Remove container
- proxmox:
    vmid: 100
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    state: absent

Status

Authors

  • Sergei Antipov (@UnderGreen)

Hint

If you notice any issues in this documentation you can edit this document to improve it.