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 (on host that executes module)
- proxmoxer
- requests
Options
| parameter | required | default | choices | comments |
|---|---|---|---|---|
| acpi |
no | yes |
|
Specify if ACPI should be enables/disabled.
|
| agent |
no |
|
Specify if the QEMU GuestAgent should be enabled/disabled.
|
|
| api_host |
yes |
Specify the target host of the Proxmox VE cluster.
|
||
| api_password |
no |
Specify the password to authenticate with.
You can use
PROXMOX_PASSWORD environment variable.
|
||
| api_user |
yes |
Specify the user to authenticate with.
|
||
| args |
no | -serial unix:/var/run/qemu-server/VMID.serial,server,nowait |
Pass arbitrary arguments to kvm.
This option is for experts only!
|
|
| autostart |
no | no |
|
Specify, if the VM should be automatically restarted after crash (currently ignored in PVE API).
|
| balloon |
no |
Specify the amount of RAM for the VM in MB.
Using zero disables the balloon driver.
|
||
| bios |
no |
|
Specify the BIOS implementation.
|
|
| boot |
no | 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 |
no |
Enable booting from specified disk.
(ide|sata|scsi|virtio\d+)
|
||
| clone |
no |
Name of VM to be cloned. If
vmid is setted,
clone can take arbitrary value but required for intiating the clone.
|
||
| cores |
no | 1 |
Specify number of cores per socket.
|
|
| cpu |
no | kvm64 |
Specify emulated CPU type.
|
|
| cpulimit |
no |
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 |
no | 1000 |
Specify CPU weight for a VM.
You can disable fair-scheduler configuration by setting this to 0
|
|
| delete |
no |
Specify a list of settings you want to delete.
|
||
| description |
no |
Specify the description for the VM. Only used on the configuration web interface.
This is saved as comment inside the configuration file.
|
||
| digest |
no |
Specify if to prevent changes if current configuration file has different SHA1 digest.
This can be used to prevent concurrent modifications.
|
||
| force |
no |
|
Allow to force stop VM.
Can be used only with states
stopped,
restarted.
|
|
| format |
no | qcow2 |
|
Target drive's backing file's data format.
Used only with clone
|
| freeze |
no |
|
Specify if PVE should freeze CPU at startup (use 'c' monitor command to start execution).
|
|
| full |
no | True |
|
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 |
no |
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 |
no |
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 |
no |
|
Enable/disable hugepages memory.
|
|
| ide |
no |
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 |
no |
Sets the keyboard layout for VNC server.
|
||
| kvm |
no | yes |
|
Enable/disable KVM hardware virtualization.
|
| localtime |
no |
|
Sets the real time clock to local time.
This is enabled by default if ostype indicates a Microsoft OS.
|
|
| lock |
no |
|
Lock/unlock the VM.
|
|
| machine |
no |
Specifies the Qemu machine type.
type =>
(pc|pc(-i440fx?-\d+\.\d+(\.pxe)?|q35|pc-q35-\d+\.\d+(\.pxe)?))
|
||
| memory |
no | 512 |
Memory size in MB for instance.
|
|
| migrate_downtime |
no |
Sets maximum tolerated downtime (in seconds) for migrations.
|
||
| migrate_speed |
no |
Sets maximum speed (in MB/s) for migrations.
A value of 0 is no limit.
|
||
| name |
no |
Specifies the VM name. Only used on the configuration web interface.
Required only for
state=present.
|
||
| net |
no |
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 |
no |
VMID for the clone. Used only with clone.
If newid is not set, the next available VM ID will be fetched from ProxmoxAPI.
|
||
| node |
no |
Proxmox VE node, where the new VM will be created.
Only required for
state=present.
For other states, it will be autodiscovered.
|
||
| numa |
no |
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 |
no | yes |
|
Specifies whether a VM will be started during system bootup.
|
| ostype |
no | l26 |
|
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 |
no |
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 |
no |
Add the new VM to the specified pool.
|
||
| protection |
no |
|
Enable/disable the protection flag of the VM. This will enable/disable the remove VM and remove disk operations.
|
|
| reboot |
no |
|
Allow reboot. If set to yes, the VM exit on reboot.
|
|
| revert |
no |
Revert a pending change.
|
||
| sata |
no |
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 |
no |
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 |
no |
|
Specifies the SCSI controller model.
|
|
| serial |
no |
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 |
no |
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 |
no |
Ignore locks
Only root is allowed to use this option.
|
||
| smbios |
no |
Specifies SMBIOS type 1 fields.
|
||
| snapname |
no |
The name of the snapshot. Used only with clone.
|
||
| sockets |
no | 1 |
Sets the number of CPU sockets. (1 - N).
|
|
| startdate |
no |
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 |
no |
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 |
no | present |
|
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 |
no |
Target storage for full clone.
|
||
| tablet |
no | no |
|
Enables/disables the USB tablet device.
|
| target |
no |
Target node. Only allowed if the original VM is on shared storage.
Used only with clone
|
||
| tdf |
no |
|
Enables/disables time drift fix.
|
|
| template |
no | no |
|
Enables/disables the template.
|
| timeout |
no | 30 |
Timeout for operations.
|
|
| update |
no | no |
|
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 |
no | no |
|
If
no, SSL certificates will not be validated. This should only be used on personally controlled sites using self-signed certificates.
|
| vcpus |
no |
Sets number of hotplugged vcpus.
|
||
| vga |
no | std |
|
Select VGA type. If you want to use high resolution modes (>= 1280x1024x16) then you should use option 'std' or 'vmware'.
|
| virtio |
no |
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 |
no |
Specifies the VM ID. Instead use
name parameter.
If vmid is not set, the next available VM ID will be fetched from ProxmoxAPI.
|
||
| watchdog |
no |
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
cpu : 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 Return Values, the following are the fields unique to this module:
| name | description | returned | type | sample |
|---|---|---|---|---|
| devices |
The list of devices created or used.
|
success | dict | { "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 |
List of mac address created and net[n] attached. Useful when you want to use provision systems like Foreman via PXE.
|
success | dict | { "net0": "3E:6E:97:D2:31:9F", "net1": "B6:A1:FC:EF:78:A4" } |
| status |
The current virtual machine status.
Returned only when
state=current
|
success | dict | { "changed": false, "msg": "VM kropta with vmid = 110 is running", "status": "running" } |
| vmid |
The VM vmid.
|
success | int | 115 |
Status
This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.
For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Testing Ansible and Developing Modules.
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.4/proxmox_kvm_module.html
