W3cubDocs

/Ansible 2.10

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

Note

This plugin is part of the community.general collection.

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)

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_user
string / required
the user to authenticate with
cores
integer
Default:
1
Specify number of cores per socket.
cpus
integer
Default:
1
numbers of allocated cpus for instance
cpuunits
integer
Default:
1000
CPU weight for a VM
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
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
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
Default:
512
memory size in MB for instance
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
    Choices:
  • no ←
  • yes
specifies whether a VM will be started during system bootup
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
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
    Choices:
  • present ←
  • started
  • absent
  • stopped
  • restarted
Indicate desired state of the instance
storage
string
Default:
"local"
target storage
swap
integer
Default:
0
swap memory size in MB for instance
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
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