Documentation

proxmox_kvm - Management of Qemu(KVM) Virtual Machines in Proxmox VE cluster.

New in version 2.3.

Synopsis

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

Requirements

The below requirements are needed on the host that executes this module.

  • proxmoxer
  • requests

Parameters

Parameter Choices/Defaults Comments
acpi
bool
    Choices:
  • no
  • yes ←
Specify if ACPI should be enabled/disabled.
agent
bool
    Choices:
  • no
  • yes
Specify if the QEMU Guest Agent should be enabled/disabled.
api_host
required
Specify the target host of the Proxmox VE cluster.
api_password
Specify the password to authenticate with.
You can use PROXMOX_PASSWORD environment variable.
api_user
required
Specify the user to authenticate with.
args Default:
-serial unix:/var/run/qemu-server/VMID.serial,server,nowait
Pass arbitrary arguments to kvm.
This option is for experts only!
autostart
bool
    Choices:
  • no ←
  • yes
Specify if the VM should be automatically restarted after crash (currently ignored in PVE API).
balloon Default:
0
Specify the amount of RAM for the VM in MB.
Using zero disables the balloon driver.
bios
    Choices:
  • seabios
  • ovmf
Specify the BIOS implementation.
boot Default:
cnd
Specify the boot order -> boot on floppy a, hard disk c, CD-ROM d, or network n.
You can combine to set order.
bootdisk
Enable booting from specified disk. (ide|sata|scsi|virtio\d+)
clone
Name of VM to be cloned. If vmid is setted, clone can take arbitrary value but required for intiating the clone.
cores Default:
1
Specify number of cores per socket.
cpu Default:
kvm64
Specify emulated CPU type.
cpulimit
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 Default:
1000
Specify CPU weight for a VM.
You can disable fair-scheduler configuration by setting this to 0
delete
Specify a list of settings you want to delete.
description
Specify the description for the VM. Only used on the configuration web interface.
This is saved as comment inside the configuration file.
digest
Specify if to prevent changes if current configuration file has different SHA1 digest.
This can be used to prevent concurrent modifications.
force
bool
    Choices:
  • no
  • yes
Allow to force stop VM.
Can be used only with states stopped, restarted.
format
    Choices:
  • cloop
  • cow
  • qcow
  • qcow2 ←
  • qed
  • raw
  • vmdk
Target drive's backing file's data format.
Used only with clone
freeze
bool
    Choices:
  • no
  • yes
Specify if PVE should freeze CPU at startup (use 'c' monitor command to start execution).
full
bool
    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
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
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
    Choices:
  • any
  • 2
  • 1024
Enable/disable hugepages memory.
ide
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.
keyboard
Sets the keyboard layout for VNC server.
kvm
bool
    Choices:
  • no
  • yes ←
Enable/disable KVM hardware virtualization.
localtime
bool
    Choices:
  • no
  • yes
Sets the real time clock to local time.
This is enabled by default if ostype indicates a Microsoft OS.
lock
    Choices:
  • migrate
  • backup
  • snapshot
  • rollback
Lock/unlock the VM.
machine
Specifies the Qemu machine type.
type => (pc|pc(-i440fx?-\d+\.\d+(\.pxe)?|q35|pc-q35-\d+\.\d+(\.pxe)?))
memory Default:
512
Memory size in MB for instance.
migrate_downtime
Sets maximum tolerated downtime (in seconds) for migrations.
migrate_speed
Sets maximum speed (in MB/s) for migrations.
A value of 0 is no limit.
name
Specifies the VM name. Only used on the configuration web interface.
Required only for state=present.
net
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",brigde="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
VMID for the clone. Used only with clone.
If newid is not set, the next available VM ID will be fetched from ProxmoxAPI.
node
Proxmox VE node, where the new VM will be created.
Only required for state=present.
For other states, it will be autodiscovered.
numa
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.
onboot
bool
    Choices:
  • no
  • yes ←
Specifies whether a VM will be started during system bootup.
ostype
    Choices:
  • other
  • wxp
  • w2k
  • w2k3
  • w2k8
  • wvista
  • win7
  • win8
  • 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.
parallel
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
Add the new VM to the specified pool.
protection
bool
    Choices:
  • no
  • yes
Enable/disable the protection flag of the VM. This will enable/disable the remove VM and remove disk operations.
reboot
bool
    Choices:
  • no
  • yes
Allow reboot. If set to yes, the VM exit on reboot.
revert
Revert a pending change.
sata
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
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
    Choices:
  • lsi
  • lsi53c810
  • virtio-scsi-pci
  • virtio-scsi-single
  • megasas
  • pvscsi
Specifies the SCSI controller model.
serial
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
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
Ignore locks
Only root is allowed to use this option.
smbios
Specifies SMBIOS type 1 fields.
snapname
The name of the snapshot. Used only with clone.
sockets Default:
1
Sets the number of CPU sockets. (1 - N).
startdate
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
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
    Choices:
  • present ←
  • started
  • absent
  • stopped
  • restarted
  • current
Indicates desired state of the instance.
If current, the current state of the VM will be fecthed. You can access it with results.status
storage
Target storage for full clone.
tablet
bool
    Choices:
  • no ←
  • yes
Enables/disables the USB tablet device.
target
Target node. Only allowed if the original VM is on shared storage.
Used only with clone
tdf
bool
    Choices:
  • no
  • yes
Enables/disables time drift fix.
template
bool
    Choices:
  • no ←
  • yes
Enables/disables the template.
timeout Default:
30
Timeout for operations.
update
bool
    Choices:
  • no ←
  • yes
If yes, the VM will be update 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...
validate_certs
bool
    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
Sets number of hotplugged vcpus.
vga
    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'.
virtio
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
Specifies the VM ID. Instead use name parameter.
If vmid is not set, the next available VM ID will be fetched from ProxmoxAPI.
watchdog
Creates a virtual hardware watchdog device.

Examples

# Create new VM with minimal options
- proxmox_kvm:
    api_user    : [email protected]
    api_password: secret
    api_host    : helldorado
    name        : spynal
    node        : sabrewulf

# Create new VM with minimal options and given vmid
- proxmox_kvm:
    api_user    : [email protected]
    api_password: secret
    api_host    : helldorado
    name        : spynal
    node        : sabrewulf
    vmid        : 100

# Create new VM with two network interface options.
- proxmox_kvm:
    api_user    : [email protected]
    api_password: secret
    api_host    : helldorado
    name        : spynal
    node        : sabrewulf
    net         : '{"net0":"virtio,bridge=vmbr1,rate=200", "net1":"e1000,bridge=vmbr2,"}'

# Create new VM with one network interface, three virto hard disk, 4 cores, and 2 vcpus.
- proxmox_kvm:
    api_user    : [email protected]
    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

# Clone VM with only source VM name
- proxmox_kvm:
    api_user    : [email protected]
    api_password: secret
    api_host    : helldorado
    clone       : spynal   # The VM source
    name        : zavala  # The target VM name
    node        : sabrewulf
    storage     : VMs
    format      : qcow2
    timeout     : 500  # Note: The task can take a while. Adapt

# Clone VM with source vmid and target newid and raw format
- proxmox_kvm:
    api_user    : [email protected]
    api_password: secret
    api_host    : helldorado
    clone       : arbitrary_name
    vmid        : 108
    newid       : 152
    name        : zavala  # The target VM name
    node        : sabrewulf
    storage     : LVM_STO
    format      : raw
    timeout     : 300  # Note: The task can take a while. Adapt

# Create new VM and lock it for snapashot.
- proxmox_kvm:
    api_user    : [email protected]
    api_password: secret
    api_host    : helldorado
    name        : spynal
    node        : sabrewulf
    lock        : snapshot

# Create new VM and set protection to disable the remove VM and remove disk operations
- proxmox_kvm:
    api_user    : [email protected]
    api_password: secret
    api_host    : helldorado
    name        : spynal
    node        : sabrewulf
    protection  : yes

# Start VM
- proxmox_kvm:
    api_user    : [email protected]
    api_password: secret
    api_host    : helldorado
    name        : spynal
    node        : sabrewulf
    state       : started

# Stop VM
- proxmox_kvm:
    api_user    : [email protected]
    api_password: secret
    api_host    : helldorado
    name        : spynal
    node        : sabrewulf
    state       : stopped

# Stop VM with force
- proxmox_kvm:
    api_user    : [email protected]
    api_password: secret
    api_host    : helldorado
    name        : spynal
    node        : sabrewulf
    state       : stopped
    force       : yes

# Restart VM
- proxmox_kvm:
    api_user    : [email protected]
    api_password: secret
    api_host    : helldorado
    name        : spynal
    node        : sabrewulf
    state       : restarted

# Remove VM
- proxmox_kvm:
    api_user    : [email protected]
    api_password: secret
    api_host    : helldorado
    name        : spynal
    node        : sabrewulf
    state       : absent

# Get VM current state
- proxmox_kvm:
    api_user    : [email protected]
    api_password: secret
    api_host    : helldorado
    name        : spynal
    node        : sabrewulf
    state       : current

# Update VM configuration
- proxmox_kvm:
    api_user    : [email protected]
    api_password: secret
    api_host    : helldorado
    name        : spynal
    node        : sabrewulf
    cpu         : 8
    memory      : 16384
    update      : yes

# Delete QEMU parameters
- proxmox_kvm:
    api_user    : [email protected]
    api_password: secret
    api_host    : helldorado
    name        : spynal
    node        : sabrewulf
    delete      : 'args,template,cpulimit'

# Revert a pending change
- proxmox_kvm:
    api_user    : [email protected]
    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
devices
dict
success
The list of devices created or used.

Sample:
{ "ide0": "VMS_LVM:vm-115-disk-1", "ide1": "VMs:115/vm-115-disk-3.raw", "virtio0": "VMS_LVM:vm-115-disk-2", "virtio1": "VMs:115/vm-115-disk-1.qcow2", "virtio2": "VMs:115/vm-115-disk-2.raw" }
mac
dict
success
List of mac address created and net[n] attached. Useful when you want to use provision systems like Foreman via PXE.

Sample:
{ "net0": "3E:6E:97:D2:31:9F", "net1": "B6:A1:FC:EF:78:A4" }
status
dict
success
The current virtual machine status.
Returned only when state=current

Sample:
{ "changed": false, "msg": "VM kropta with vmid = 110 is running", "status": "running" }
vmid
int
success
The VM vmid.

Sample:
115


Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

Author

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

Hint

If you notice any issues in this documentation you can edit this document to improve it.