proxmox - management of instances in Proxmox VE cluster¶

New in version 2.0.

Synopsis
- Requirements
Parameters
Notes
Examples
Status
Maintenance
- Author

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 bool	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 bool	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 bool (added in 2.3)	Choices: no ← yes	Indicate if the container should be unprivileged
validate_certs bool	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: [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 with 8GB
- 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/"}'

# Create new container with minimal options defining a cpu core limit
- 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'
    cores: 2

# Start container
- proxmox:
    vmid: 100
    api_user: [email protected]
    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: [email protected]
    api_password: 1q2w3e
    api_host: node1
    state: started
    timeout: 90

# 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

Status ¶

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

Maintenance ¶

This module is flagged as community which means that it is maintained by the Ansible Community. See Module Maintenance & Support for more info.

For a list of other modules that are also maintained by the Ansible Community, see here.

Author ¶

Sergei Antipov (@UnderGreen)

Hint

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