proxmox – management of instances in Proxmox VE cluster

From Get docs
Ansible/docs/2.7/modules/proxmox module


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

  • 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

  • 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

-

  • 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

  • no

  • yes

Indicate if the container should be unprivileged

validate_certs

boolean

  • 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.


© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.7/modules/proxmox_module.html