community.general.proxmox – management of instances in Proxmox VE cluster

From Get docs
Ansible/docs/2.10/collections/community/general/proxmox module


community.general.proxmox – management of instances in Proxmox VE cluster

Note

This plugin is part of the community.general collection (version 1.3.2).

To install it use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.proxmox.


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)
  • From community.general 4.0.0 on, there will be no default values, see proxmox_default_behavior.

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

string / required

the host of the Proxmox VE cluster

api_password

string

the password to authenticate with

you can use PROXMOX_PASSWORD environment variable

api_token_id

string

added in 1.3.0 of community.general

Specify the token ID.

api_token_secret

string

added in 1.3.0 of community.general

Specify the token secret.

api_user

string / required

the user to authenticate with

cores

integer

Specify number of cores per socket.

If proxmox_default_behavior is set to compatiblity (the default value), this option has a default of 1. Note that the default value of proxmox_default_behavior changes in community.general 4.0.0.

cpus

integer

numbers of allocated cpus for instance

If proxmox_default_behavior is set to compatiblity (the default value), this option has a default of 1. Note that the default value of proxmox_default_behavior changes in community.general 4.0.0.

cpuunits

integer

CPU weight for a VM

If proxmox_default_behavior is set to compatiblity (the default value), this option has a default of 1000. Note that the default value of proxmox_default_behavior changes in community.general 4.0.0.

description

string

added in 0.2.0 of community.general

Specify the description for the container. Only used on the configuration web interface.

This is saved as a comment inside the configuration file.

disk

string

hard disk size in GB for instance

If proxmox_default_behavior is set to compatiblity (the default value), this option has a default of 3. Note that the default value of proxmox_default_behavior changes in community.general 4.0.0.

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

hookscript

string

added in 0.2.0 of community.general

Script that will be executed during various steps in the containers lifetime.

hostname

string

the instance hostname

required only for state=present

must be unique if vmid is not passed

ip_address

string

specifies the address the container will be assigned

memory

integer

memory size in MB for instance

If proxmox_default_behavior is set to compatiblity (the default value), this option has a default of 512. Note that the default value of proxmox_default_behavior changes in community.general 4.0.0.

mounts

dictionary

specifies additional mounts (separate disks) for the container. As a hash/dictionary defining mount points

nameserver

string

sets DNS server IP address for a container

netif

dictionary

specifies network interfaces for the container. As a hash/dictionary defining interfaces.

node

string

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

If proxmox_default_behavior is set to compatiblity (the default value), this option has a default of no. Note that the default value of proxmox_default_behavior changes in community.general 4.0.0.

ostemplate

string

the template for VM creating

required only for state=present

password

string

the instance root password

required only for state=present

pool

string

Proxmox VE resource pool

proxmox_default_behavior

string

added in 1.3.0 of community.general

  • compatibility
  • no_defaults

Various module options used to have default values. This cause problems when user expects different behavior from proxmox by default or fill options which cause problems when they have been set.

The default value is compatibility, which will ensure that the default values are used when the values are not explicitly specified by the user.

From community.general 4.0.0 on, the default value will switch to no_defaults. To avoid deprecation warnings, please set proxmox_default_behavior to an explicit value.

This affects the disk, cores, cpus, memory, onboot, swap, cpuunits options.

pubkey

string

Public key to add to /root/.ssh/authorized_keys. This was added on Proxmox 4.2, it is ignored for earlier versions

searchdomain

string

sets DNS search domain for a container

state

string

  • present

  • started
  • absent
  • stopped
  • restarted

Indicate desired state of the instance

storage

string

Default:

"local"

target storage

swap

integer

swap memory size in MB for instance

If proxmox_default_behavior is set to compatiblity (the default value), this option has a default of 0. Note that the default value of proxmox_default_behavior changes in community.general 4.0.0.

timeout

integer

Default:

30

timeout for operations

unprivileged

boolean

  • no

  • yes

Indicate if the container should be unprivileged

validate_certs

boolean

  • no

  • yes

enable / disable https certificate verification

vmid

string

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

- name: Create new container with minimal options
  community.general.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'

- name: Create new container with hookscript and description
  community.general.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'
    hookscript: 'local:snippets/vm_hook.sh'
    description: created with ansible

- name: Create new container automatically selecting the next available vmid.
  community.general.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'

- name: Create new container with minimal options with force(it will rewrite existing container)
  community.general.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

- name: Create new container with minimal options use environment PROXMOX_PASSWORD variable(you should export it before)
  community.general.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'

- name: Create new container with minimal options defining network interface with dhcp
  community.general.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"}'

- name: Create new container with minimal options defining network interface with static ip
  community.general.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"}'

- name: Create new container with minimal options defining a mount with 8GB
  community.general.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/"}'

- name: Create new container with minimal options defining a cpu core limit
  community.general.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

- name: Start container
  community.general.proxmox:
    vmid: 100
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    state: started

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

- name: Stop container
  community.general.proxmox:
    vmid: 100
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    state: stopped

- name: Stop container with force
  community.general.proxmox:
    vmid: 100
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    force: yes
    state: stopped

- name: Restart container(stopped or mounted container you can't restart)
  community.general.proxmox:
    vmid: 100
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    state: restarted

- name: Remove container
  community.general.proxmox:
    vmid: 100
    api_user: root@pam
    api_password: 1q2w3e
    api_host: node1
    state: absent

Authors

  • Sergei Antipov (@UnderGreen)

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