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

Note

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

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

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
requests

Parameters

Parameter	Choices/Defaults	Comments
api_host string / required		Specify the target host of the Proxmox VE cluster.
api_password string		Specify 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		Specify 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		This option was previously described as "hard disk size in GB for instance" however several formats describing a lxc mount are permitted. Older versions of Proxmox will accept a numeric value for size using the storage parameter to automatically choose which storage to allocate from, however new versions enforce the `<STORAGE>:<SIZE>` syntax. Additional options are available by using some combination of the following key-value pairs as a comma-delimited list `[volume=]<volume> [,acl=<1\|0>] [,mountoptions=<opt[;opt...]>] [,quota=<1\|0>] [,replicate=<1\|0>] [,ro=<1\|0>] [,shared=<1\|0>] [,size=<DiskSize>]`. See https://pve.proxmox.com/wiki/Linux_Container for a full description. 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.
features list / elements=string added in 2.0.0 of community.general		Specifies a list of features to be enabled. For valid options, see https://pve.proxmox.com/wiki/Linux_Container#pct_options. Some features require the use of a privileged container.
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
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 on which to operate. Only required for state=present. For every other states it will be autodiscovered.
onboot boolean	Choices: 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
pool string		Add the new VM to the specified pool.
proxmox_default_behavior string added in 1.3.0 of community.general	Choices: 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
purge boolean added in 2.3.0 of community.general	Choices: no ← yes	Remove container from all related configurations. For example backup jobs, replication jobs, or HA. Related ACLs and Firewall entries will always be removed. Used with state `absent`.
searchdomain string		sets DNS search domain for a container
state string	Choices: 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	Choices: no ← yes	Indicate if the container should be unprivileged
validate_certs boolean	Choices: no ← yes	If `no`, SSL certificates will not be validated. This should only be used on personally controlled sites using self-signed certificates.
vmid integer		Specifies the instance ID. If not set the next available ID will be fetched from ProxmoxAPI.

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: Create a new container with nesting enabled and allows the use of CIFS/NFS inside the 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'
    features:
     - nesting=1
     - mount=cifs,nfs


- 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–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/general/proxmox_module.html

Docs

Docs4dev

Title here