W3cubDocs

/Ansible 2.10

community.general.proxmox_kvm – Management of Qemu(KVM) Virtual Machines in Proxmox VE cluster.

Note

This plugin is part of the community.general collection.

To install it use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.proxmox_kvm.

Synopsis
Requirements
Parameters
Examples
Return Values

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 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_user string / required		Specify the user to authenticate with.
args string	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 integer	Default: 0	Specify the amount of RAM for the VM in MB. Using zero disables the balloon driver.
bios string	Choices: seabios ovmf	Specify the BIOS implementation.
boot string	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 string		Enable booting from specified disk. `(ide\|sata\|scsi\|virtio`\d+)
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	Default: 1	Specify number of cores per socket.
cpu string	Default: "kvm64"	Specify emulated CPU type.
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	Default: 1000	Specify CPU weight for a VM. You can disable fair-scheduler configuration by setting this to 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` and `restarted`.
format string	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 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`.
keyboard string		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 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	Default: 512	Memory size in MB for instance.
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`.
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, where the new VM will be created. Only required for `state=present`. For 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.
onboot boolean	Choices: no yes ←	Specifies whether a VM will be started during system bootup.
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.
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.
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.
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	Default: 1	Sets the number of CPU sockets. (1 - N).
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.
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.
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...
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'.
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 VM ID. Instead use name parameter. If vmid is not set, the next available VM 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: 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 snapashot
  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: 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
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

Authors

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

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.10/collections/community/general/proxmox_kvm_module.html