# proxmox_kvm – Management of Qemu(KVM) Virtual Machines in Proxmox VE cluster

- Synopsis

- Requirements

- Parameters

- Examples

- Return Values

- Status

## 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
boolean

Choices:
- no
- yes ←

Specify if ACPI should be enabled/disabled.

agent
boolean

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
boolean

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 initiating 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
boolean

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
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
-

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
boolean

Choices:
- no
- yes ←

Enable/disable KVM hardware virtualization.

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
-

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",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 - |  | 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
boolean

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
boolean

Choices:
- no
- yes

Enable/disable the protection flag of the VM. This will enable/disable the remove VM and remove disk operations.

reboot
boolean

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 fetched. You can access it with `results.status`

storage - |  | Target storage for full clone.

tablet
boolean

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
boolean

Choices:
- no
- yes

Enables/disables time drift fix.

template
boolean

Choices:
- no ←
- yes

Enables/disables the template.

timeout - | Default: 30 | Timeout for operations.

update
boolean

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
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 - |  | 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    : root@pam
        api_password: secret
        api_host    : helldorado
        name        : spynal
        node        : sabrewulf

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

    # Create new VM with two network interface options.
    - 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,"}'

    # Create new VM with one network interface, three virto hard disk, 4 cores, and 2 vcpus.
    - 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

    # Clone VM with only source VM name
    - proxmox_kvm:
        api_user    : root@pam
        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    : root@pam
        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    : root@pam
        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    : root@pam
        api_password: secret
        api_host    : helldorado
        name        : spynal
        node        : sabrewulf
        protection  : yes

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

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

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

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

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

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

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

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

    # Revert a pending change
    - 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
--- | --- | ---
devices dictionary | 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 dictionary | 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 dictionary | 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 integer | success | The VM vmid. Sample: 115

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]

- This module is maintained by the Ansible Community. [community]

### Authors

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

Hint

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