proxmox_kvm – Management of Qemu(KVM) Virtual Machines in Proxmox VE cluster
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 boolean |
|
Specify if ACPI should be enabled/disabled. |
agent boolean |
|
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 | |
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 |
|
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 - |
|
Specify the BIOS implementation. |
boot - |
Default: "cnd" |
Specify the boot order -> boot on floppy You can combine to set order. |
bootdisk - |
Enable booting from specified disk. | |
clone - |
Name of VM to be cloned. If | |
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 |
|
Allow to force stop VM. Can be used only with states |
format - |
|
Target drive's backing file's data format. Used only with clone |
freeze boolean |
|
Specify if PVE should freeze CPU at startup (use 'c' monitor command to start execution). |
full boolean |
|
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. Keys allowed are - Values allowed are - The
/!\ 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 Value 0 disables hotplug completely and value 1 is an alias for the default | |
hugepages - |
|
Enable/disable hugepages memory. |
ide - |
A hash/dictionary of volume used as IDE hard disk or CD-ROM. Keys allowed are - Values allowed are -
| |
keyboard - |
Sets the keyboard layout for VNC server. | |
kvm boolean |
|
Enable/disable KVM hardware virtualization. |
localtime boolean |
|
Sets the real time clock to local time. This is enabled by default if ostype indicates a Microsoft OS. |
lock - |
|
Lock/unlock the VM. |
machine - |
Specifies the Qemu machine type. type => | |
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 | |
net - |
A hash/dictionary of network interfaces for the VM. Keys allowed are - Values allowed are - Model is one of
The Option 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 For other states, it will be autodiscovered. | |
numa - |
A hash/dictionaries of NUMA topology. Keys allowed are - Values allowed are -
| |
onboot boolean |
|
Specifies whether a VM will be started during system bootup. |
ostype - |
|
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. Keys allowed are - (parallel[n]) where 0 ≤ n ≤ 2. Values allowed are - | |
pool - |
Add the new VM to the specified pool. | |
protection boolean |
|
Enable/disable the protection flag of the VM. This will enable/disable the remove VM and remove disk operations. |
reboot boolean |
|
Allow reboot. If set to |
revert - |
Revert a pending change. | |
sata - |
A hash/dictionary of volume used as sata hard disk or CD-ROM. Keys allowed are - Values allowed are -
| |
scsi - |
A hash/dictionary of volume used as SCSI hard disk or CD-ROM. Keys allowed are - Values allowed are -
| |
scsihw - |
|
Specifies the SCSI controller model. |
serial - |
A hash/dictionary of serial device to create inside the VM. Keys allowed are - serial[n](str; required) where 0 ≤ n ≤ 3. Values allowed are - /!\ 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 | |
startup - |
Startup and shutdown behavior. Order is a non-negative number defining the general startup order. Shutdown in done with reverse ordering. | |
state - |
|
Indicates desired state of the instance. If |
storage - |
Target storage for full clone. | |
tablet boolean |
|
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 |
|
Enables/disables time drift fix. |
template boolean |
|
Enables/disables the template. |
timeout - |
Default: 30 |
Timeout for operations. |
update boolean |
|
If Cause of the operations of the API and security reasons, I have disabled the update of the following parameters
|
validate_certs boolean |
|
If |
vcpus - |
Sets number of hotplugged vcpus. | |
vga - |
|
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. Keys allowed are - Values allowed are -
| |
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
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)
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.8/modules/proxmox_kvm_module.html