- AnsibleFest
- Products
- Community
- Webinars & Training
- Blog

Documentation

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