community.general.proxmox_kvm – Management of Qemu(KVM) Virtual Machines 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_kvm.

Synopsis

  • Allows you to create/delete/stop Qemu(KVM) Virtual Machines in Proxmox VE cluster.

  • 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
acpi
boolean
    Choices:
  • no
  • yes
Specify if ACPI should be enabled/disabled.
If proxmox_default_behavior is set to compatiblity (the default value), this option has a default of yes. Note that the default value of proxmox_default_behavior changes in community.general 4.0.0.
agent
boolean
    Choices:
  • no
  • yes
Specify if the QEMU Guest Agent should be enabled/disabled.
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.
args
string
Pass arbitrary arguments to kvm.
This option is for experts only!
If proxmox_default_behavior is set to compatiblity (the default value), this option has a default of -serial unix:/var/run/qemu-server/<vmid>.serial,server,nowait. Note that the default value of proxmox_default_behavior changes in community.general 4.0.0.
autostart
boolean
    Choices:
  • no
  • yes
Specify if the VM should be automatically restarted after crash (currently ignored in PVE API).
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.
balloon
integer
Specify the amount of RAM for the VM in MB.
Using zero disables the balloon driver.
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.
bios
string
    Choices:
  • seabios
  • ovmf
Specify the BIOS implementation.
boot
string
Specify the boot order -> boot on floppy a, hard disk c, CD-ROM d, or network n.
You can combine to set order.
If proxmox_default_behavior is set to compatiblity (the default value), this option has a default of cnd. Note that the default value of proxmox_default_behavior changes in community.general 4.0.0.
bootdisk
string
Enable booting from specified disk. (ide|sata|scsi|virtio\d+)
cicustom
string
added in 1.3.0 of community.general
cloud-init: Specify custom files to replace the automatically generated ones at start.
cipassword
string
added in 1.3.0 of community.general
cloud-init: password of default user to create.
citype
string
added in 1.3.0 of community.general
    Choices:
  • nocloud
  • configdrive2
cloud-init: Specifies the cloud-init configuration format.
The default depends on the configured operating system type (ostype).
We use the nocloud format for Linux, and configdrive2 for Windows.
ciuser
string
added in 1.3.0 of community.general
cloud-init: username of default user to create.
clone
string
Name of VM to be cloned. If vmid is setted, clone can take arbitrary value but required for initiating the clone.
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.
cpu
string
Specify emulated CPU type.
If proxmox_default_behavior is set to compatiblity (the default value), this option has a default of kvm64. Note that the default value of proxmox_default_behavior changes in community.general 4.0.0.
cpulimit
integer
Specify if CPU usage will be limited. Value 0 indicates no CPU limit.
If the computer has 2 CPUs, it has total of '2' CPU time
cpuunits
integer
Specify CPU weight for a VM.
You can disable fair-scheduler configuration by setting this to 0
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.
delete
string
Specify a list of settings you want to delete.
description
string
Specify the description for the VM. Only used on the configuration web interface.
This is saved as comment inside the configuration file.
digest
string
Specify if to prevent changes if current configuration file has different SHA1 digest.
This can be used to prevent concurrent modifications.
force
boolean
    Choices:
  • no
  • yes
Allow to force stop VM.
Can be used with states stopped, restarted and absent.
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.
format
string
    Choices:
  • cloop
  • cow
  • qcow
  • qcow2
  • qed
  • raw
  • vmdk
  • unspecified
Target drive's backing file's data format.
Used only with clone
Use format=unspecified and full=false for a linked clone.
If proxmox_default_behavior is set to compatiblity (the default value), this option has a default of qcow2. If proxmox_default_behavior is set to no_defaults, not specifying this option is equivalent to setting it to unspecified. Note that the default value of proxmox_default_behavior changes in community.general 4.0.0.
freeze
boolean
    Choices:
  • no
  • yes
Specify if PVE should freeze CPU at startup (use 'c' monitor command to start execution).
full
boolean
    Choices:
  • no
  • yes ←
Create a full copy of all disk. This is always done when you clone a normal VM.
For VM templates, we try to create a linked clone by default.
Used only with clone
hostpci
dictionary
Specify a hash/dictionary of map host pci devices into guest. hostpci='{"key":"value", "key":"value"}'.
Keys allowed are - hostpci[n] where 0 ≤ n ≤ N.
Values allowed are - "host="HOSTPCIID[;HOSTPCIID2...]",pcie="1|0",rombar="1|0",x-vga="1|0"".
The host parameter is Host PCI device pass through. HOSTPCIID syntax is bus:dev.func (hexadecimal numbers).
pcie=boolean default=0 Choose the PCI-express bus (needs the q35 machine model).
rombar=boolean default=1 Specify whether or not the device's ROM will be visible in the guest's memory map.
x-vga=boolean default=0 Enable vfio-vga device support.
/!\ This option allows direct access to host hardware. So it is no longer possible to migrate such machines - use with special care.
hotplug
string
Selectively enable hotplug features.
This is a comma separated list of hotplug features 'network', 'disk', 'cpu', 'memory' and 'usb'.
Value 0 disables hotplug completely and value 1 is an alias for the default 'network,disk,usb'.
hugepages
string
    Choices:
  • any
  • 2
  • 1024
Enable/disable hugepages memory.
ide
dictionary
A hash/dictionary of volume used as IDE hard disk or CD-ROM. ide='{"key":"value", "key":"value"}'.
Keys allowed are - ide[n] where 0 ≤ n ≤ 3.
Values allowed are - "storage:size,format=value".
storage is the storage identifier where to create the disk.
size is the size of the disk in GB.
format is the drive's backing file's data format. qcow2|raw|subvol.
ipconfig
dictionary
added in 1.3.0 of community.general
cloud-init: Set the IP configuration.
A hash/dictionary of network ip configurations. ipconfig='{"key":"value", "key":"value"}'.
Keys allowed are - ipconfig[n] where 0 ≤ n ≤ network interfaces.
Values allowed are - "[gw=<GatewayIPv4>] [,gw6=<GatewayIPv6>] [,ip=<IPv4Format/CIDR>] [,ip6=<IPv6Format/CIDR>]".
cloud-init: Specify IP addresses and gateways for the corresponding interface.
IP addresses use CIDR notation, gateways are optional but they should be in the same subnet of specified IP address.
The special string 'dhcp' can be used for IP addresses to use DHCP, in which case no explicit gateway should be provided.
For IPv6 the special string 'auto' can be used to use stateless autoconfiguration.
If cloud-init is enabled and neither an IPv4 nor an IPv6 address is specified, it defaults to using dhcp on IPv4.
keyboard
string
Sets the keyboard layout for VNC server.
kvm
boolean
    Choices:
  • no
  • yes
Enable/disable KVM hardware virtualization.
If proxmox_default_behavior is set to compatiblity (the default value), this option has a default of yes. Note that the default value of proxmox_default_behavior changes in community.general 4.0.0.
localtime
boolean
    Choices:
  • no
  • yes
Sets the real time clock to local time.
This is enabled by default if ostype indicates a Microsoft OS.
lock
string
    Choices:
  • migrate
  • backup
  • snapshot
  • rollback
Lock/unlock the VM.
machine
string
Specifies the Qemu machine type.
type => (pc|pc(-i440fx?-\d+\.\d+(\.pxe)?|q35|pc-q35-\d+\.\d+(\.pxe)?))
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.
migrate_downtime
integer
Sets maximum tolerated downtime (in seconds) for migrations.
migrate_speed
integer
Sets maximum speed (in MB/s) for migrations.
A value of 0 is no limit.
name
string
Specifies the VM name. Only used on the configuration web interface.
Required only for state=present.
nameservers
list / elements=string
added in 1.3.0 of community.general
cloud-init: DNS server IP address(es).
If unset, PVE host settings are used.
net
dictionary
A hash/dictionary of network interfaces for the VM. net='{"key":"value", "key":"value"}'.
Keys allowed are - net[n] where 0 ≤ n ≤ N.
Values allowed are - "model="XX:XX:XX:XX:XX:XX",bridge="value",rate="value",tag="value",firewall="1|0",trunks="vlanid"".
Model is one of e1000 e1000-82540em e1000-82544gc e1000-82545em i82551 i82557b i82559er ne2k_isa ne2k_pci pcnet rtl8139 virtio vmxnet3.
XX:XX:XX:XX:XX:XX should be an unique MAC address. This is automatically generated if not specified.
The bridge parameter can be used to automatically add the interface to a bridge device. The Proxmox VE standard bridge is called 'vmbr0'.
Option rate is used to limit traffic bandwidth from and to this interface. It is specified as floating point number, unit is 'Megabytes per second'.
If you specify no bridge, we create a kvm 'user' (NATed) network device, which provides DHCP and DNS services.
newid
integer
VMID for the clone. Used only with clone.
If newid is not set, the next available VM ID will be fetched from ProxmoxAPI.
node
string
Proxmox VE node on which to operate.
Only required for state=present.
For every other states it will be autodiscovered.
numa
dictionary
A hash/dictionaries of NUMA topology. numa='{"key":"value", "key":"value"}'.
Keys allowed are - numa[n] where 0 ≤ n ≤ N.
Values allowed are - "cpu="<id[-id];...>",hostnodes="<id[-id];...>",memory="number",policy="(bind|interleave|preferred"").
cpus CPUs accessing this NUMA node.
hostnodes Host NUMA nodes to use.
memory Amount of memory this NUMA node provides.
policy NUMA allocation policy.
numa_enabled
boolean
    Choices:
  • no
  • yes
Enables NUMA.
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 yes. Note that the default value of proxmox_default_behavior changes in community.general 4.0.0.
ostype
string
    Choices:
  • other
  • wxp
  • w2k
  • w2k3
  • w2k8
  • wvista
  • win7
  • win8
  • win10
  • l24
  • l26
  • solaris
Specifies guest operating system. This is used to enable special optimization/features for specific operating systems.
The l26 is Linux 2.6/3.X Kernel.
If proxmox_default_behavior is set to compatiblity (the default value), this option has a default of l26. Note that the default value of proxmox_default_behavior changes in community.general 4.0.0.
parallel
dictionary
A hash/dictionary of map host parallel devices. parallel='{"key":"value", "key":"value"}'.
Keys allowed are - (parallel[n]) where 0 ≤ n ≤ 2.
Values allowed are - "/dev/parport\d+|/dev/usb/lp\d+".
pool
string
Add the new VM to the specified pool.
protection
boolean
    Choices:
  • no
  • yes
Enable/disable the protection flag of the VM. This will enable/disable the remove VM and remove disk operations.
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 acpi, autostart, balloon, boot, cores, cpu, cpuunits, force, format, kvm, memory, onboot, ostype, sockets, tablet, template, vga, options.
reboot
boolean
    Choices:
  • no
  • yes
Allow reboot. If set to yes, the VM exit on reboot.
revert
string
Revert a pending change.
sata
dictionary
A hash/dictionary of volume used as sata hard disk or CD-ROM. sata='{"key":"value", "key":"value"}'.
Keys allowed are - sata[n] where 0 ≤ n ≤ 5.
Values allowed are - "storage:size,format=value".
storage is the storage identifier where to create the disk.
size is the size of the disk in GB.
format is the drive's backing file's data format. qcow2|raw|subvol.
scsi
dictionary
A hash/dictionary of volume used as SCSI hard disk or CD-ROM. scsi='{"key":"value", "key":"value"}'.
Keys allowed are - sata[n] where 0 ≤ n ≤ 13.
Values allowed are - "storage:size,format=value".
storage is the storage identifier where to create the disk.
size is the size of the disk in GB.
format is the drive's backing file's data format. qcow2|raw|subvol.
scsihw
string
    Choices:
  • lsi
  • lsi53c810
  • virtio-scsi-pci
  • virtio-scsi-single
  • megasas
  • pvscsi
Specifies the SCSI controller model.
searchdomains
list / elements=string
added in 1.3.0 of community.general
cloud-init: Sets DNS search domain(s).
If unset, PVE host settings are used.
serial
dictionary
A hash/dictionary of serial device to create inside the VM. '{"key":"value", "key":"value"}'.
Keys allowed are - serial[n](str; required) where 0 ≤ n ≤ 3.
Values allowed are - (/dev/.+|socket).
/!\ If you pass through a host serial device, it is no longer possible to migrate such machines - use with special care.
shares
integer
Rets amount of memory shares for auto-ballooning. (0 - 50000).
The larger the number is, the more memory this VM gets.
The number is relative to weights of all other running VMs.
Using 0 disables auto-ballooning, this means no limit.
skiplock
boolean
    Choices:
  • no
  • yes
Ignore locks
Only root is allowed to use this option.
smbios
string
Specifies SMBIOS type 1 fields.
snapname
string
The name of the snapshot. Used only with clone.
sockets
integer
Sets the number of CPU sockets. (1 - N).
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.
sshkeys
string
added in 1.3.0 of community.general
cloud-init: SSH key to assign to the default user. NOT TESTED with multiple keys but a multi-line value should work.
startdate
string
Sets the initial date of the real time clock.
Valid format for date are 'now' or '2016-09-25T16:01:21' or '2016-09-25'.
startup
string
Startup and shutdown behavior. [[order=]\d+] [,up=\d+] [,down=\d+].
Order is a non-negative number defining the general startup order.
Shutdown in done with reverse ordering.
state
string
    Choices:
  • present ←
  • started
  • absent
  • stopped
  • restarted
  • current
Indicates desired state of the instance.
If current, the current state of the VM will be fetched. You can access it with results.status
storage
string
Target storage for full clone.
tablet
boolean
    Choices:
  • no
  • yes
Enables/disables the USB tablet device.
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.
tags
list / elements=string
added in 2.3.0 of community.general
List of tags to apply to the VM instance.
Tags must start with [a-z0-9_] followed by zero or more of the following characters [a-z0-9_-+.].
Tags are only available in Proxmox 6+.
target
string
Target node. Only allowed if the original VM is on shared storage.
Used only with clone
tdf
boolean
    Choices:
  • no
  • yes
Enables/disables time drift fix.
template
boolean
    Choices:
  • no
  • yes
Enables/disables the template.
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.
timeout
integer
Default:
30
Timeout for operations.
update
boolean
    Choices:
  • no ←
  • yes
If yes, the VM will be updated with new value.
Cause of the operations of the API and security reasons, I have disabled the update of the following parameters
net, virtio, ide, sata, scsi. Per example updating net update the MAC address and virtio create always new disk...
Update of pool is disabled. It needs an additional API endpoint not covered by this module.
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.
vcpus
integer
Sets number of hotplugged vcpus.
vga
string
    Choices:
  • std
  • cirrus
  • vmware
  • qxl
  • serial0
  • serial1
  • serial2
  • serial3
  • qxl2
  • qxl3
  • qxl4
Select VGA type. If you want to use high resolution modes (>= 1280x1024x16) then you should use option 'std' or 'vmware'.
If proxmox_default_behavior is set to compatiblity (the default value), this option has a default of std. Note that the default value of proxmox_default_behavior changes in community.general 4.0.0.
virtio
dictionary
A hash/dictionary of volume used as VIRTIO hard disk. virtio='{"key":"value", "key":"value"}'.
Keys allowed are - virto[n] where 0 ≤ n ≤ 15.
Values allowed are - "storage:size,format=value".
storage is the storage identifier where to create the disk.
size is the size of the disk in GB.
format is the drive's backing file's data format. qcow2|raw|subvol.
vmid
integer
Specifies the instance ID.
If not set the next available ID will be fetched from ProxmoxAPI.
watchdog
string
Creates a virtual hardware watchdog device.

Examples

- name: Create new VM with minimal options
  community.general.proxmox_kvm:
    api_user: root@pam
    api_password: secret
    api_host: helldorado
    name: spynal
    node: sabrewulf

- name: Create new VM with minimal options and given vmid
  community.general.proxmox_kvm:
    api_user: root@pam
    api_password: secret
    api_host: helldorado
    name: spynal
    node: sabrewulf
    vmid: 100

- name: Create new VM with two network interface options
  community.general.proxmox_kvm:
    api_user: root@pam
    api_password: secret
    api_host: helldorado
    name: spynal
    node: sabrewulf
    net:
      net0: 'virtio,bridge=vmbr1,rate=200'
      net1: 'e1000,bridge=vmbr2'

- name: Create new VM with one network interface, three virto hard disk, 4 cores, and 2 vcpus
  community.general.proxmox_kvm:
    api_user: root@pam
    api_password: secret
    api_host: helldorado
    name: spynal
    node: sabrewulf
    net:
      net0: 'virtio,bridge=vmbr1,rate=200'
    virtio:
      virtio0: 'VMs_LVM:10'
      virtio1: 'VMs:2,format=qcow2'
      virtio2: 'VMs:5,format=raw'
    cores: 4
    vcpus: 2

- name: >
    Clone VM with only source VM name.
    The VM source is spynal.
    The target VM name is zavala
  community.general.proxmox_kvm:
    api_user: root@pam
    api_password: secret
    api_host: helldorado
    clone: spynal
    name: zavala
    node: sabrewulf
    storage: VMs
    format: qcow2
    timeout: 500

- name: >
    Create linked clone VM with only source VM name.
    The VM source is spynal.
    The target VM name is zavala
  community.general.proxmox_kvm:
    api_user: root@pam
    api_password: secret
    api_host: helldorado
    clone: spynal
    name: zavala
    node: sabrewulf
    storage: VMs
    full: no
    format: unspecified
    timeout: 500

- name: Clone VM with source vmid and target newid and raw format
  community.general.proxmox_kvm:
    api_user: root@pam
    api_password: secret
    api_host: helldorado
    clone: arbitrary_name
    vmid: 108
    newid: 152
    name: zavala
    node: sabrewulf
    storage: LVM_STO
    format: raw
    timeout: 300

- name: Create new VM and lock it for snapshot
  community.general.proxmox_kvm:
    api_user: root@pam
    api_password: secret
    api_host: helldorado
    name: spynal
    node: sabrewulf
    lock: snapshot

- name: Create new VM and set protection to disable the remove VM and remove disk operations
  community.general.proxmox_kvm:
    api_user: root@pam
    api_password: secret
    api_host: helldorado
    name: spynal
    node: sabrewulf
    protection: yes

- name: Create new VM using cloud-init with a username and password
  community.general.proxmox_kvm:
    node: sabrewulf
    api_user: root@pam
    api_password: secret
    api_host: helldorado
    name: spynal
    ide:
      ide2: 'local:cloudinit,format=qcow2'
    ciuser: mylinuxuser
    cipassword: supersecret
    searchdomains: 'mydomain.internal'
    nameservers: 1.1.1.1
    net:
      net0: 'virtio,bridge=vmbr1,tag=77'
    ipconfig:
      ipconfig0: 'ip=192.168.1.1/24,gw=192.168.1.1'

- name: Create new VM using Cloud-Init with an ssh key
  community.general.proxmox_kvm:
    node: sabrewulf
    api_user: root@pam
    api_password: secret
    api_host: helldorado
    name: spynal
    ide:
      ide2: 'local:cloudinit,format=qcow2'
    sshkeys: 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILJkVm98B71lD5XHfihwcYHE9TVpsJmK1vR1JcaU82L+'
    searchdomains: 'mydomain.internal'
    nameservers:
      - '1.1.1.1'
      - '8.8.8.8'
    net:
      net0: 'virtio,bridge=vmbr1,tag=77'
    ipconfig:
      ipconfig0: 'ip=192.168.1.1/24'

- name: Start VM
  community.general.proxmox_kvm:
    api_user: root@pam
    api_password: secret
    api_host: helldorado
    name: spynal
    node: sabrewulf
    state: started

- name: Stop VM
  community.general.proxmox_kvm:
    api_user: root@pam
    api_password: secret
    api_host: helldorado
    name: spynal
    node: sabrewulf
    state: stopped

- name: Stop VM with force
  community.general.proxmox_kvm:
    api_user: root@pam
    api_password: secret
    api_host: helldorado
    name: spynal
    node: sabrewulf
    state: stopped
    force: yes

- name: Restart VM
  community.general.proxmox_kvm:
    api_user: root@pam
    api_password: secret
    api_host: helldorado
    name: spynal
    node: sabrewulf
    state: restarted

- name: Remove VM
  community.general.proxmox_kvm:
    api_user: root@pam
    api_password: secret
    api_host: helldorado
    name: spynal
    node: sabrewulf
    state: absent

- name: Get VM current state
  community.general.proxmox_kvm:
    api_user: root@pam
    api_password: secret
    api_host: helldorado
    name: spynal
    node: sabrewulf
    state: current

- name: Update VM configuration
  community.general.proxmox_kvm:
    api_user: root@pam
    api_password: secret
    api_host: helldorado
    name: spynal
    node: sabrewulf
    cores: 8
    memory: 16384
    update: yes

- name: Delete QEMU parameters
  community.general.proxmox_kvm:
    api_user: root@pam
    api_password: secret
    api_host: helldorado
    name: spynal
    node: sabrewulf
    delete: 'args,template,cpulimit'

- name: Revert a pending change
  community.general.proxmox_kvm:
    api_user: root@pam
    api_password: secret
    api_host: helldorado
    name: spynal
    node: sabrewulf
    revert: 'template,cpulimit'

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key Returned Description
msg
string
always
A short message

Sample:
VM kropta with vmid = 110 is running
status
string
success, not clone, not absent, not update
The current virtual machine status.

Sample:
running
vmid
integer
success
The VM vmid.

Sample:
115


Authors

  • Abdoul Bah (@helldorado) <bahabdoul at gmail.com>