community.general.proxmox – management of instances in Proxmox VE cluster¶
Note
This plugin is part of the community.general collection (version 2.5.1).
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
|
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. |
|
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
|
|
forcing operations
can be used only with states
present , stopped , restarted with
state=present force option allow to overwrite existing containerwith 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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
Indicate if the container should be unprivileged
|
validate_certs
boolean
|
|
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)