proxmox – management of instances in Proxmox VE cluster

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 -		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 -		Proxmox VE resource pool
pubkey -		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	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: restarted

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

Status

• This module is not guaranteed to have a backwards compatible interface. [preview]
• This module is maintained by the Ansible Community. [community]

Authors

• Sergei Antipov (@UnderGreen)

Hint

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