Try SpotterManagement of Qemu(KVM) Virtual Machines in Proxmox VE cluster.
| "added in version" 2.3 of ansible.builtin"
Authors: Abdoul Bah (@helldorado) <bahabdoul at gmail.com>
preview | supported by community
pipInstall with pip install ansible==2.9.27
Allows you to create/delete/stop Qemu(KVM) Virtual Machines in Proxmox VE cluster.
# 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'
cpu:
default: kvm64
description:
- Specify emulated CPU type.
ide:
description:
- A hash/dictionary of volume used as IDE hard disk or CD-ROM. C(ide='{"key":"value",
"key":"value"}').
- "Keys allowed are - C(ide[n]) where 0 \u2264 n \u2264 3."
- Values allowed are - C("storage:size,format=value").
- C(storage) is the storage identifier where to create the disk.
- C(size) is the size of the disk in GB.
- C(format) is the drive's backing file's data format. C(qcow2|raw|subvol).
kvm:
default: 'yes'
description:
- Enable/disable KVM hardware virtualization.
type: bool
net:
description:
- A hash/dictionary of network interfaces for the VM. C(net='{"key":"value", "key":"value"}').
- "Keys allowed are - C(net[n]) where 0 \u2264 n \u2264 N."
- Values allowed are - C("model="XX:XX:XX:XX:XX:XX",bridge="value",rate="value",tag="value",firewall="1|0",trunks="vlanid"").
- Model is one of C(e1000 e1000-82540em e1000-82544gc e1000-82545em i82551 i82557b
i82559er ne2k_isa ne2k_pci pcnet rtl8139 virtio vmxnet3).
- C(XX:XX:XX:XX:XX:XX) should be an unique MAC address. This is automatically generated
if not specified.
- The C(bridge) parameter can be used to automatically add the interface to a bridge
device. The Proxmox VE standard bridge is called 'vmbr0'.
- Option C(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.
tdf:
description:
- Enables/disables time drift fix.
type: bool
vga:
choices:
- std
- cirrus
- vmware
- qxl
- serial0
- serial1
- serial2
- serial3
- qxl2
- qxl3
- qxl4
default: std
description:
- Select VGA type. If you want to use high resolution modes (>= 1280x1024x16) then
you should use option 'std' or 'vmware'.
acpi:
default: 'yes'
description:
- Specify if ACPI should be enabled/disabled.
type: bool
args:
default: -serial unix:/var/run/qemu-server/VMID.serial,server,nowait
description:
- Pass arbitrary arguments to kvm.
- This option is for experts only!
bios:
choices:
- seabios
- ovmf
description:
- Specify the BIOS implementation.
boot:
default: cnd
description:
- Specify the boot order -> boot on floppy C(a), hard disk C(c), CD-ROM C(d), or network
C(n).
- You can combine to set order.
full:
default: 'yes'
description:
- 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
type: bool
lock:
choices:
- migrate
- backup
- snapshot
- rollback
description:
- Lock/unlock the VM.
name:
description:
- Specifies the VM name. Only used on the configuration web interface.
- Required only for C(state=present).
node:
description:
- Proxmox VE node, where the new VM will be created.
- Only required for C(state=present).
- For other states, it will be autodiscovered.
numa:
description:
- A hash/dictionaries of NUMA topology. C(numa='{"key":"value", "key":"value"}').
- "Keys allowed are - C(numa[n]) where 0 \u2264 n \u2264 N."
- Values allowed are - C("cpu="<id[-id];...>",hostnodes="<id[-id];...>",memory="number",policy="(bind|interleave|preferred)"").
- C(cpus) CPUs accessing this NUMA node.
- C(hostnodes) Host NUMA nodes to use.
- C(memory) Amount of memory this NUMA node provides.
- C(policy) NUMA allocation policy.
pool:
description:
- Add the new VM to the specified pool.
sata:
description:
- A hash/dictionary of volume used as sata hard disk or CD-ROM. C(sata='{"key":"value",
"key":"value"}').
- "Keys allowed are - C(sata[n]) where 0 \u2264 n \u2264 5."
- Values allowed are - C("storage:size,format=value").
- C(storage) is the storage identifier where to create the disk.
- C(size) is the size of the disk in GB.
- C(format) is the drive's backing file's data format. C(qcow2|raw|subvol).
scsi:
description:
- A hash/dictionary of volume used as SCSI hard disk or CD-ROM. C(scsi='{"key":"value",
"key":"value"}').
- "Keys allowed are - C(sata[n]) where 0 \u2264 n \u2264 13."
- Values allowed are - C("storage:size,format=value").
- C(storage) is the storage identifier where to create the disk.
- C(size) is the size of the disk in GB.
- C(format) is the drive's backing file's data format. C(qcow2|raw|subvol).
vmid:
description:
- Specifies the VM ID. Instead use I(name) parameter.
- If vmid is not set, the next available VM ID will be fetched from ProxmoxAPI.
agent:
description:
- Specify if the QEMU Guest Agent should be enabled/disabled.
type: bool
clone:
description:
- Name of VM to be cloned. If C(vmid) is setted, C(clone) can take arbitrary value
but required for initiating the clone.
cores:
default: 1
description:
- Specify number of cores per socket.
force:
description:
- Allow to force stop VM.
- Can be used only with states C(stopped), C(restarted).
type: bool
newid:
description:
- VMID for the clone. Used only with clone.
- If newid is not set, the next available VM ID will be fetched from ProxmoxAPI.
state:
choices:
- present
- started
- absent
- stopped
- restarted
- current
default: present
description:
- Indicates desired state of the instance.
- If C(current), the current state of the VM will be fetched. You can access it with
C(results.status)
vcpus:
description:
- Sets number of hotplugged vcpus.
delete:
description:
- Specify a list of settings you want to delete.
digest:
description:
- Specify if to prevent changes if current configuration file has different SHA1 digest.
- This can be used to prevent concurrent modifications.
format:
choices:
- cloop
- cow
- qcow
- qcow2
- qed
- raw
- vmdk
default: qcow2
description:
- Target drive's backing file's data format.
- Used only with clone
freeze:
description:
- Specify if PVE should freeze CPU at startup (use 'c' monitor command to start execution).
type: bool
memory:
default: 512
description:
- Memory size in MB for instance.
onboot:
default: 'yes'
description:
- Specifies whether a VM will be started during system bootup.
type: bool
ostype:
choices:
- other
- wxp
- w2k
- w2k3
- w2k8
- wvista
- win7
- win8
- l24
- l26
- solaris
default: l26
description:
- 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.
reboot:
description:
- Allow reboot. If set to C(yes), the VM exit on reboot.
type: bool
revert:
description:
- Revert a pending change.
scsihw:
choices:
- lsi
- lsi53c810
- virtio-scsi-pci
- virtio-scsi-single
- megasas
- pvscsi
description:
- Specifies the SCSI controller model.
serial:
description:
- A hash/dictionary of serial device to create inside the VM. C('{"key":"value", "key":"value"}').
- "Keys allowed are - serial[n](str; required) where 0 \u2264 n \u2264 3."
- Values allowed are - C((/dev/.+|socket)).
- /!\ If you pass through a host serial device, it is no longer possible to migrate
such machines - use with special care.
shares:
description:
- 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.
smbios:
description:
- Specifies SMBIOS type 1 fields.
tablet:
default: 'no'
description:
- Enables/disables the USB tablet device.
type: bool
target:
description:
- Target node. Only allowed if the original VM is on shared storage.
- Used only with clone
update:
default: 'no'
description:
- If C(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
- C(net, virtio, ide, sata, scsi). Per example updating C(net) update the MAC address
and C(virtio) create always new disk...
type: bool
virtio:
description:
- A hash/dictionary of volume used as VIRTIO hard disk. C(virtio='{"key":"value",
"key":"value"}').
- "Keys allowed are - C(virto[n]) where 0 \u2264 n \u2264 15."
- Values allowed are - C("storage:size,format=value").
- C(storage) is the storage identifier where to create the disk.
- C(size) is the size of the disk in GB.
- C(format) is the drive's backing file's data format. C(qcow2|raw|subvol).
balloon:
default: 0
description:
- Specify the amount of RAM for the VM in MB.
- Using zero disables the balloon driver.
hostpci:
description:
- Specify a hash/dictionary of map host pci devices into guest. C(hostpci='{"key":"value",
"key":"value"}').
- "Keys allowed are - C(hostpci[n]) where 0 \u2264 n \u2264 N."
- Values allowed are - C("host="HOSTPCIID[;HOSTPCIID2...]",pcie="1|0",rombar="1|0",x-vga="1|0"").
- The C(host) parameter is Host PCI device pass through. HOSTPCIID syntax is C(bus:dev.func)
(hexadecimal numbers).
- C(pcie=boolean) I(default=0) Choose the PCI-express bus (needs the q35 machine model).
- C(rombar=boolean) I(default=1) Specify whether or not the device's ROM will be visible
in the guest's memory map.
- C(x-vga=boolean) I(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:
description:
- Selectively enable hotplug features.
- This is a comma separated list of hotplug features C('network', 'disk', 'cpu', 'memory'
and 'usb').
- Value 0 disables hotplug completely and value 1 is an alias for the default C('network,disk,usb').
machine:
description:
- Specifies the Qemu machine type.
- type => C((pc|pc(-i440fx)?-\d+\.\d+(\.pxe)?|q35|pc-q35-\d+\.\d+(\.pxe)?))
sockets:
default: 1
description:
- Sets the number of CPU sockets. (1 - N).
startup:
description:
- Startup and shutdown behavior. C([[order=]\d+] [,up=\d+] [,down=\d+]).
- Order is a non-negative number defining the general startup order.
- Shutdown in done with reverse ordering.
storage:
description:
- Target storage for full clone.
timeout:
default: 30
description:
- Timeout for operations.
api_host:
description:
- Specify the target host of the Proxmox VE cluster.
required: true
api_user:
description:
- Specify the user to authenticate with.
required: true
bootdisk:
description:
- Enable booting from specified disk. C((ide|sata|scsi|virtio)\d+)
cpulimit:
description:
- 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
description:
- Specify CPU weight for a VM.
- You can disable fair-scheduler configuration by setting this to 0
keyboard:
description:
- Sets the keyboard layout for VNC server.
parallel:
description:
- A hash/dictionary of map host parallel devices. C(parallel='{"key":"value", "key":"value"}').
- "Keys allowed are - (parallel[n]) where 0 \u2264 n \u2264 2."
- Values allowed are - C("/dev/parport\d+|/dev/usb/lp\d+").
skiplock:
description:
- Ignore locks
- Only root is allowed to use this option.
snapname:
description:
- The name of the snapshot. Used only with clone.
template:
default: 'no'
description:
- Enables/disables the template.
type: bool
watchdog:
description:
- Creates a virtual hardware watchdog device.
autostart:
default: 'no'
description:
- Specify if the VM should be automatically restarted after crash (currently ignored
in PVE API).
type: bool
hugepages:
choices:
- any
- '2'
- '1024'
description:
- Enable/disable hugepages memory.
localtime:
description:
- Sets the real time clock to local time.
- This is enabled by default if ostype indicates a Microsoft OS.
type: bool
startdate:
description:
- Sets the initial date of the real time clock.
- Valid format for date are C('now') or C('2016-09-25T16:01:21') or C('2016-09-25').
protection:
description:
- Enable/disable the protection flag of the VM. This will enable/disable the remove
VM and remove disk operations.
type: bool
description:
description:
- Specify the description for the VM. Only used on the configuration web interface.
- This is saved as comment inside the configuration file.
api_password:
description:
- Specify the password to authenticate with.
- You can use C(PROXMOX_PASSWORD) environment variable.
migrate_speed:
description:
- Sets maximum speed (in MB/s) for migrations.
- A value of 0 is no limit.
validate_certs:
default: 'no'
description:
- If C(no), SSL certificates will not be validated. This should only be used on personally
controlled sites using self-signed certificates.
type: bool
migrate_downtime:
description:
- Sets maximum tolerated downtime (in seconds) for migrations.
devices:
description: The list of devices created or used.
returned: success
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" }'
type: dict
mac:
description: List of mac address created and net[n] attached. Useful when you want
to use provision systems like Foreman via PXE.
returned: success
sample: ' { "net0": "3E:6E:97:D2:31:9F", "net1": "B6:A1:FC:EF:78:A4" }'
type: dict
status:
description:
- The current virtual machine status.
- Returned only when C(state=current)
returned: success
sample: '{ "changed": false, "msg": "VM kropta with vmid = 110 is running", "status":
"running" }'
type: dict
vmid:
description: The VM vmid.
returned: success
sample: 115
type: int