community.general.proxmox module – Management of instances in Proxmox VE cluster
Note
This module is part of the community.general collection (version 9.5.0).
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
.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: community.general.proxmox
.
Synopsis
Allows you to create/delete/stop instances in Proxmox VE cluster.
The module automatically detects containerization type (lxc for PVE 4, openvz for older).
Since community.general 4.0.0 on, there are no more default values.
Requirements
The below requirements are needed on the host that executes this module.
proxmoxer
requests
Parameters
Parameter |
Comments |
---|---|
Specify the target host of the Proxmox VE cluster. |
|
Specify the password to authenticate with. You can use |
|
Specify the target port of the Proxmox VE cluster. Uses the |
|
Specify the token ID. Requires |
|
Specify the token secret. Requires |
|
Specify the user to authenticate with. |
|
ID of the container to be cloned.
The type of clone created is defined by the This operator is only supported for Proxmox clusters that use LXC containerization (PVE version >= 4). |
|
Type of the clone created.
Choices:
|
|
Specify number of cores per socket. |
|
numbers of allocated cpus for instance |
|
CPU weight for a VM |
|
Specify the description for the container. Only used on the configuration web interface. This is saved as a comment inside the configuration file. |
|
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 Additional options are available by using some combination of the following key-value pairs as a comma-delimited list See https://pve.proxmox.com/wiki/Linux_Container for a full description. This option is mutually exclusive with |
|
Specify a hash/dictionary of the See https://pve.proxmox.com/wiki/Linux_Container#pct_mount_points for a full description. |
|
Mutually exclusive with |
|
The value of any given option must be a string, for example |
|
The size is given in GB. Required only if |
|
Mutually exclusive with |
|
If not defined, the module will check if one exists. If not, a new volume will be created. If defined, the volume must exist under that name. Required only if |
|
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. |
|
Forcing operations. Can be used only with states with with states Choices:
|
|
Script that will be executed during various steps in the containers lifetime. |
|
specifies the address the container will be assigned |
|
memory size in MB for instance |
|
Specify additional mounts (separate disks) for the container. As a hash/dictionary defining mount points. See https://pve.proxmox.com/wiki/Linux_Container#pct_mount_points for a full description. This Option is mutually exclusive with |
|
Mutually exclusive with |
|
|
|
|
|
The value of any given option must be a string, for example |
|
The size is given in GB. Required only if |
|
Mutually exclusive with |
|
If not defined, the module will check if one exists. If not, a new volume will be created. If defined, the volume must exist under that name. Required only if |
|
Specifies additional mounts (separate disks) for the container. As a hash/dictionary defining mount points as strings. This Option is mutually exclusive with |
|
sets DNS server IP address for a container |
|
specifies network interfaces for the container. As a hash/dictionary defining interfaces. |
|
Proxmox VE node on which to operate. Only required for For every other states it will be autodiscovered. |
|
specifies whether a VM will be started during system bootup Choices:
|
|
the template for VM creating required only for |
|
Specifies the If set to Choices:
|
|
the instance root password |
|
Add the new VM to the specified pool. |
|
Public key to add to /root/.ssh/authorized_keys. This was added on Proxmox 4.2, it is ignored for earlier versions |
|
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 Choices:
|
|
sets DNS search domain for a container |
|
Specifies the startup order of the container. Use Use Use |
|
Indicate desired state of the instance
Choices:
|
|
swap memory size in MB for instance |
|
List of tags to apply to the container. Tags must start with Tags are only available in Proxmox 7+. |
|
timeout for operations Default: |
|
Timezone used by the container, accepts values like The special value |
|
Indicate if the container should be unprivileged. The default change to Choices:
|
|
If Choices:
|
|
If This should only be used on personally controlled sites using self-signed certificates. Choices:
|
|
Specifies the instance ID. If not set the next available ID will be fetched from ProxmoxAPI. |
Attributes
Attribute |
Support |
Description |
---|---|---|
Action group: community.general.proxmox added in community.general 9.0.0 |
Use |
|
Support: none |
Can run in |
|
Support: none |
Will return details on what has changed (or possibly needs changing in |
See Also
See also
- community.general.proxmox_vm_info
Retrieve information about one or more Proxmox VE virtual machines.
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 minimal options specifying disk storage location and size
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'
disk: 'local-lvm:20'
- name: Create new container with minimal options specifying disk storage location and size via disk_volume
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'
disk_volume:
storage: local
size: 20
- 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: true
- 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 more options defining network interface with static ip4 and ip6 with vlan-tag and mtu
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,ip6=fe80::1227/64,gw6=fe80::1,bridge=vmbr0,firewall=1,tag=934,mtu=1500"
- 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 mount with 8GB using mount_volumes
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'
mount_volumes:
- id: mp0
storage: local
size: 8
mountpoint: /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 new container with minimal options and same timezone as proxmox host
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'
timezone: host
- 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: >
Create a linked clone of the template container with id 100. The newly created container with be a
linked clone, because no storage parameter is defined
community.general.proxmox:
vmid: 201
node: uk-mc02
api_user: root@pam
api_password: 1q2w3e
api_host: node1
clone: 100
hostname: clone.example.org
- name: Create a full clone of the container with id 100
community.general.proxmox:
vmid: 201
node: uk-mc02
api_user: root@pam
api_password: 1q2w3e
api_host: node1
clone: 100
hostname: clone.example.org
storage: local
- name: Update container configuration
community.general.proxmox:
vmid: 100
node: uk-mc02
api_user: root@pam
api_password: 1q2w3e
api_host: node1
netif:
net0: "name=eth0,gw=192.168.0.1,ip=192.168.0.3/24,bridge=vmbr0"
update: true
- 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: true
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: Convert container to template
community.general.proxmox:
vmid: 100
api_user: root@pam
api_password: 1q2w3e
api_host: node1
state: template
- name: Convert container to template (stop container if running)
community.general.proxmox:
vmid: 100
api_user: root@pam
api_password: 1q2w3e
api_host: node1
state: template
force: true
- name: Remove container
community.general.proxmox:
vmid: 100
api_user: root@pam
api_password: 1q2w3e
api_host: node1
state: absent