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

Note

This module is part of the community.proxmox collection (version 2.0.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.proxmox. You need further requirements to be able to use this module, see Requirements for details.

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

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 >= 2.3

• requests

Parameters

Parameter	Comments
acpi boolean	Specify if ACPI should be enabled/disabled. Choices: false true
agent string	Specify if the QEMU Guest Agent should be enabled/disabled.
api_host string / required	Specify the target host of the Proxmox VE cluster. Uses the PROXMOX_HOST environment variable if not specified.
api_otp string	Specify the OTP. Uses the PROXMOX_OTP environment variable if not specified.
api_password string	Specify the password to authenticate with. Uses the PROXMOX_PASSWORD environment variable if not specified.
api_port integer	Specify the target port of the Proxmox VE cluster. Uses the PROXMOX_PORT environment variable if not specified.
api_timeout integer	Time limit for requests towards the Proxmox VE API. Default: 5
api_token_id string	Specify the token ID. Uses the PROXMOX_TOKEN_ID environment variable if not specified.
api_token_secret string	Specify the token secret. Uses the PROXMOX_TOKEN_SECRET environment variable if not specified.
api_user string / required	Specify the user to authenticate with. Uses the PROXMOX_USER environment variable if not specified.
archive string	Specify a path to an archive to restore (instead of creating or cloning a VM).
args string	Pass arbitrary arguments to kvm. This option is for experts only!
audio dictionary	A hash/dictionary of audio devices for the VM. audio={"key":"value", "key":"value"}. Keys allowed are - audio[n] where 0 ≤ n ≤ N. Values allowed are - device="ich9-intel-hda|intel-hda|AC97",driver="none|spice". device is either ich9-intel-hda or intel-hda or AC97. Option driver is none or spice.
autostart boolean	Specify if the VM should be automatically restarted after crash (currently ignored in PVE API). Choices: false true
balloon integer	Specify the amount of RAM for the VM in MB. Using zero disables the balloon driver.
bios string	Specify the BIOS implementation. Choices: "seabios" "ovmf"
boot string	Specify the boot order -> boot on floppy a, hard disk c, CD-ROM d, or network n. For newer versions of Proxmox VE, use a boot order like order=scsi0;net0;hostpci0. You can combine to set order. Network boot requires setting rng0 since PVE 8.3.5.
bootdisk string	Enable booting from specified disk. Format (ide|sata|scsi|virtio)\d+.
ca_path path	Path to a local certificate, which will be used to verify TLS connections. Ignored if validate_certs=false.
cicustom string	Cloud-init: Specify custom files to replace the automatically generated ones at start.
cipassword string	Cloud-init: password of default user to create.
citype string	Cloud-init: Specifies the cloud-init configuration format. The default depends on the configured operating system type (ostype). We use the nocloud format for Linux, and configdrive2 for Windows. Choices: "nocloud" "configdrive2"
ciupgrade boolean	Cloud-init: do an automatic package upgrade after the first boot. Choices: false true
ciuser string	Cloud-init: username of default user to create.
clone string	Name of VM to be cloned. If vmid is set, clone can take an arbitrary value but is required for initiating the clone.
cores integer	Specify number of cores per socket.
cpu string	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	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.
destroy_unreferenced_disks boolean	Remove unreferenced disks that belong to the virtual machine. Volumes referenced in the config will always be removed. Used with state=absent. Choices: false ← (default) true
digest string	Specify if to prevent changes if current configuration file has different SHA1 digest. This can be used to prevent concurrent modifications.
efidisk0 dictionary	Specify a hash/dictionary of EFI disk options. Requires bios=ovmf to be set to be able to use it.
efitype string	efitype indicates the size of the EFI disk. 2m will allow for a 2MB EFI disk, which will be enough to persist boot order and new boot entries. 4m will allow for a 4MB EFI disk, which will additionally allow to store EFI keys in order to enable Secure Boot. Choices: "2m" "4m"
format string	format is the drive’s backing file’s data format. Refer to the Proxmox VE documentation at https://pve.proxmox.com/pve-docs/chapter-pvesm.html, tables 3 to 14, to find out format supported by the provided storage backend.
pre_enrolled_keys boolean	pre_enrolled_keys indicates whether EFI keys for Secure Boot should be enrolled 1 in the VM firmware upon creation or not (0). If set to 1, Secure Boot will also be enabled by default when the VM is created. Choices: false true
storage string	storage is the storage identifier where to create the disk.
force boolean	If true, allows forceful power operations (stop, reset). When used with state=stopped, attempts a graceful shutdown and if the VM is still running after timeout, it will be forcefully powered off. When used with state=restarted, performs reset (power off and on) and not a graceful reboot. Choices: false true
format string	Target drive’s backing file’s data format. Used only with clone. Use format=unspecified and full=false for a linked clone. Refer to the Proxmox VE documentation at https://pve.proxmox.com/pve-docs/chapter-pvesm.html, tables 3 to 14, to find out format supported by the provided storage backend. Not specifying this option is equivalent to setting it to unspecified. Choices: "cloop" "cow" "qcow" "qcow2" "qed" "raw" "vmdk" "unspecified"
freeze boolean	Specify if PVE should freeze CPU at startup (use ‘c’ monitor command to start execution). Choices: false true
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. Choices: false true ← (default)
hookscript string	Script that will be executed during various steps in the containers lifetime.
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	Enable/disable hugepages memory. Choices: "any" "2" "1024"
ide dictionary	A hash/dictionary of volume used as IDE hard disk or CD-ROM. Keys must be ide[n] where 0 ≤ n ≤ 3. Values are strings containing comma-separated options in formats accepted by Proxmox VE. Examples: "<storage>:10,format=qcow2" for a disk, "<storage>:cloudinit,format=qcow2" for cloud-init, "<storage>:iso/debian.iso,media=cdrom" for an ISO-backed CD-ROM, or "none,media=cdrom" for an empty CD-ROM. Refer to the Proxmox VE documentation at https://pve.proxmox.com/pve-docs/chapter-qm.html#qm_options:#:~:text=ide,-[n]%3A.
ipconfig dictionary	Cloud-init: IP configuration for network interfaces. Maps to net[n] interfaces (e.g. ipconfig0 for net0). Keys must be ipconfig[n] where 0 ≤ n ≤ 31. Values are comma-separated options in the format ip=<addr>[,gw=<gateway>][,ip6=<addr>][,gw6=<gateway>]. Options: - ip: IPv4 address in CIDR notation (e.g. 192.168.1.10/24) or dhcp for DHCP. - gw: IPv4 gateway (requires ip); omit when using ip=dhcp. - ip6: IPv6 address in CIDR notation, dhcp, or auto for SLAAC. - gw6: IPv6 gateway (requires ip6); omit when using ip6=dhcp or ip6=auto. Examples: ip=dhcp for DHCP; ip=192.168.1.10/24,gw=192.168.1.1 for static IPv4. If cloud-init is enabled and no address is specified, IPv4 defaults to DHCP.
keyboard string	Sets the keyboard layout for VNC server.
kvm boolean	Enable/disable KVM hardware virtualization. Choices: false true
localtime boolean	Sets the real time clock to local time. This is enabled by default if ostype indicates a Microsoft OS. Choices: false true
lock string	Lock/unlock the VM. Choices: "migrate" "backup" "snapshot" "rollback"
machine string	Specifies the Qemu machine type. Type => (pc|pc(-i440fx)?-\d+\.\d+(\.pxe)?|q35|pc-q35-\d+\.\d+(\.pxe)?). Allows to set, [[type=]<machine type>] [,enable-s3=<1|0>] [,enable-s4=<1|0>] [,viommu=<intel|virtio>].
memory integer	Memory size in MB for instance.
migrate boolean	Migrate the VM to node if it is on another node. Choices: false ← (default) true
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. Name could be non-unique across the cluster. Required only for state=present. With state=present if vmid not provided and VM with name exists in the cluster then no changes will be made.
nameservers list / elements=string	Cloud-init: DNS server IP address(es). If unset, PVE host settings are used.
net dictionary	A hash/dictionary of network interfaces for the VM. Keys must be net[n] where 0 ≤ n ≤ N. Values are strings containing comma-separated options in the format [model=]<enum>[,option=value]... Examples: "virtio,bridge=vmbr0" for a basic interface, or "virtio,bridge=vmbr0,firewall=1,rate=200,tag=10" for a rate-limited VLAN interface with firewall enabled. macaddr=XX:XX:XX:XX:XX:XX must be a unique MAC address. If not specified, a unique MAC address is automatically generated. Refer to the Proxmox VE documentation at https://pve.proxmox.com/pve-docs/chapter-qm.html#qm_options:#:~:text=net,-[n]%3A.
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 on which to operate. Only required for state=present. For every 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.
numa_enabled boolean	Enables NUMA. Choices: false true
onboot boolean	Specifies whether a VM will be started during system bootup. Choices: false true
ostype string	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. Choices: "other" "wxp" "w2k" "w2k3" "w2k8" "wvista" "win7" "win8" "win10" "win11" "l24" "l26" "solaris"
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	Enable/disable the protection flag of the VM. This will enable/disable the remove VM and remove disk operations. Choices: false true
purge boolean	Remove VMID from configurations, like backup & replication jobs and HA. Used with state absent. Choices: false ← (default) true
reboot boolean	Allow reboot. If set to true, the VM exit on reboot. Choices: false true
revert string	Revert a pending change.
rng0 string added in community.proxmox 1.0.0	Randomness source for RNG device, for example /dev/urandom.
sata dictionary	A hash/dictionary of volume used as SATA hard disk or CD-ROM. Keys must be sata[n] where 0 ≤ n ≤ 5. Values are strings containing comma-separated options in formats accepted by Proxmox VE. Examples: "<storage>:10,format=qcow2" for a disk, "<storage>:cloudinit,format=qcow2" for cloud-init, "<storage>:iso/debian.iso,media=cdrom" for an ISO-backed CD-ROM, or "none,media=cdrom" for an empty CD-ROM. Refer to the Proxmox VE documentation at https://pve.proxmox.com/pve-docs/chapter-qm.html#qm_options:#:~:text=sata,-[n]%3A.
scsi dictionary	A hash/dictionary of volume used as SCSI hard disk or CD-ROM. Keys must be scsi[n] where 0 ≤ n ≤ 30. Values are strings containing comma-separated options in formats accepted by Proxmox VE. Examples: "<storage>:10,format=qcow2" for a disk, "<storage>:cloudinit,format=qcow2" for cloud-init, "<storage>:iso/debian.iso,media=cdrom" for an ISO-backed CD-ROM, or "none,media=cdrom" for an empty CD-ROM. Refer to the Proxmox VE documentation at https://pve.proxmox.com/pve-docs/chapter-qm.html#qm_options:#:~:text=scsi,-[n]%3A.
scsihw string	Specifies the SCSI controller model. Choices: "lsi" "lsi53c810" "virtio-scsi-pci" "virtio-scsi-single" "megasas" "pvscsi"
searchdomains list / elements=string	Cloud-init: Sets DNS search domain(s). If unset, PVE host settings are used.
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	Ignore locks. Only root is allowed to use this option. Choices: false true
smbios string	Specifies SMBIOS type 1 fields. Comma separated, Base64 encoded (optional) SMBIOS properties:. [base64=<1|0>] [,family=<Base64 encoded string>]. [,manufacturer=<Base64 encoded string>]. [,product=<Base64 encoded string>]. [,serial=<Base64 encoded string>]. [,sku=<Base64 encoded string>]. [,uuid=<UUID>]. [,version=<Base64 encoded string>].
snapname string	The name of the snapshot. Used only with clone.
sockets integer	Sets the number of CPU sockets. (1 - N).
spice_enhancements string	Configure additional SPICE enhancements. Value is a comma-separated list of options in the format foldersharing=<0|1>[,videostreaming=<off|all|filter>]. Refer to the Proxmox VE documentation at https://pve.proxmox.com/pve-docs/chapter-qm.html#qm_spice_enhancements.
sshkeys string	Cloud-init: SSH public key(s) to assign to the default user. Supports multiple SSH keys by providing a multi-line value. Each key should be on a separate line in the format ssh-key-type key-data [comment]. Use YAML literal block scalar (|) to provide multiple keys, one per line.
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	Indicates desired state of the instance. If current, the current state of the VM will be fetched. You can access it with results.status. stopped ensures that the VM is powered off using a graceful shutdown. Choices: "present" ← (default) "started" "absent" "stopped" "restarted" "current" "template" "paused" "hibernated"
storage string	Target storage for full clone. If restoring from archive, target storage for all disks. If omitted, storage location embedded inside archive will be used.
tablet boolean	Enables/disables the USB tablet device. Choices: false true
tags list / elements=string	List of tags to apply to the VM instance. Tags must start with [a-z0-9_] followed by zero or more of the following characters [a-z0-9_-+.]. Tags are only available in Proxmox 6+.
target string	Target node. Only allowed if the original VM is on shared storage. Used only with clone.
tdf boolean	Enables/disables time drift fix. Choices: false true
template boolean	Enables/disables the template. Choices: false true
timeout integer	Timeout in seconds for operations. If the timeout is reached with state=stopped and force=True, the VM will be forcefully powered off. If the timeout is reached with state=stopped and force=False, the task will fail. Default: 30
tpmstate0 dictionary	A hash/dictionary of options for the Trusted Platform Module disk. A TPM state disk is required for Windows 11 installations.
storage string / required	tpmstate0.storage is the storage identifier where to create the disk.
version string	The TPM version to use. Choices: "1.2" "2.0" ← (default)
update boolean	If true, the VM will be updated with new value. Because of the operations of the API and security reasons, I have disabled the update of the following parameters net, virtio, virtiofs, ide, sata, scsi. Per example updating net update the MAC address and virtio create always new disk… This security feature can be disabled by setting the update_unsafe to true. Update of pool is disabled. It needs an additional API endpoint not covered by this module. Choices: false ← (default) true
update_unsafe boolean	If true, do not enforce limitations on parameters net, virtio, virtiofs, ide, sata, scsi, efidisk0, and tpmstate0. Use this option with caution because an improper configuration might result in a permanent loss of data (for example disk recreated). Choices: false ← (default) true
usb dictionary	A hash/dictionary of USB devices for the VM. usb='{"key":"value", "key":"value"}'. Keys allowed are - usb[n] where 0 ≤ n ≤ N. Values allowed are - host="value|spice",mapping="value",usb3="1|0". Host is either spice or the USB id/port. Option mapping is the mapped USB device name. Option usb3 enables USB 3 support.
validate_certs boolean	Validate the TLS certificates used for the connection to the Proxmox VE API. May be set through the environment variable PROXMOX_VALIDATE_CERTS. Choices: false true ← (default)
vcpus integer	Sets number of hotplugged vcpus.
vga string	Select VGA type. If you want to use high resolution modes (>= 1280x1024x16) then you should use option std or vmware. Refer to the Proxmox VE documentation at https://pve.proxmox.com/pve-docs/chapter-qm.html#qm_options:#:~:text=vga%3A.
virtio dictionary	A hash/dictionary of volume used as VIRTIO hard disk or CD-ROM. Keys must be virtio[n] where 0 ≤ n ≤ 15. Values are strings containing comma-separated options in the format <storage>:<size>[,option=value]... Examples: "<storage>:10,format=qcow2" for a disk, or "<storage>:iso/debian.iso,media=cdrom" for a CD-ROM. Refer to the Proxmox VE documentation at https://pve.proxmox.com/pve-docs/chapter-qm.html#qm_options:#:~:text=virtio,-[n]%3A.
virtiofs dictionary	A hash/dictionary of Virtio-fs devices for sharing directories between host and guest. Keys must be virtiofs[n] where 0 ≤ n ≤ 9. Values are strings containing comma-separated options. Requires a directory mapping to be created first. Options: - dirid: Identifier of the directory mapping. - cache: Caching policy always, auto, metadata, or never. - direct-io: Whether to allow direct I/O. 0 or 1. - expose-acl: Whether to expose POSIX ACLs. 0 or 1. Implies xattr when enabled. - expose-xattr: Enable support for extended attributes. 0 or 1. Example: "dirid=my-share,cache=always,direct-io=1,expose-acl=1,expose-xattr=1" Available in Proxmox VE 8.4 and later. For more information, see https://pve.proxmox.com/pve-docs/qm.conf.5.html#:~:text=virtiofs,-[n]%3A.
vmid integer	Specifies the instance ID. If not set the next available ID will be fetched from ProxmoxAPI.
watchdog string	Creates a virtual hardware watchdog device.
with_local_disks boolean	Enables migration of local disks to the next node. Choices: false ← (default) true

Attributes

Attribute	Support	Description
action_group	Action group: community.proxmox.proxmox	Use group/community.proxmox.proxmox in module_defaults to set defaults for this module.
check_mode	Support: none	Can run in check_mode and return changed status prediction without modifying target.
diff_mode	Support: none	Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

See Also

See also

community.proxmox.proxmox_disk

Manage VM disks and disk options.

community.proxmox.proxmox_vm_info

Retrieve information about one or more Proxmox VE virtual machines.

Proxmox VE QEMU/KVM Virtual Machines documentation

Proxmox VE QEMU/KVM Virtual Machines documentation.

Authentication

Complete guide for the Proxmox API authentication

Examples

- name: Create new VM with minimal options
  community.proxmox.proxmox_kvm:
    name: spynal
    node: sabrewulf

- name: Create a VM from archive (backup)
  community.proxmox.proxmox_kvm:
    archive: backup-storage:backup/vm/140/2023-03-08T06:41:23Z
    name: spynal

- name: Create new VM with minimal options and given vmid
  community.proxmox.proxmox_kvm:
    name: spynal
    node: sabrewulf
    vmid: 100

- name: Create new VM with two network interface options
  community.proxmox.proxmox_kvm:
    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.proxmox.proxmox_kvm:
    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: Create VM with 1 10GiB SATA disk and an EFI disk, with Secure Boot disabled by default
  community.proxmox.proxmox_kvm:
    name: spynal
    node: sabrewulf
    sata:
      sata0: 'VMs_LVM:10,format=raw'
    bios: ovmf
    efidisk0:
      storage: VMs_LVM_thin
      format: raw
      efitype: 4m
      pre_enrolled_keys: false

- name: Create VM with 1 10GiB SATA disk and an EFI disk, with Secure Boot enabled by default
  community.proxmox.proxmox_kvm:
    name: spynal
    node: sabrewulf
    sata:
      sata0: 'VMs_LVM:10,format=raw'
    bios: ovmf
    efidisk0:
      storage: VMs_LVM
      format: raw
      efitype: 4m
      pre_enrolled_keys: 1

- name: >
    Clone VM with only source VM name.
    The VM source is spynal.
    The target VM name is zavala
  community.proxmox.proxmox_kvm:
    clone: spynal
    name: zavala
    node: sabrewulf
    storage: VMs
    format: qcow2
    timeout: 500

- name: >
    Create linked clone VM with only source VM name.
    The VM source is spynal.
    The target VM name is zavala
  community.proxmox.proxmox_kvm:
    clone: spynal
    name: zavala
    node: sabrewulf
    storage: VMs
    full: false
    format: unspecified
    timeout: 500

- name: Clone VM with source vmid and target newid and raw format
  community.proxmox.proxmox_kvm:
    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 snapshot
  community.proxmox.proxmox_kvm:
    name: spynal
    node: sabrewulf
    lock: snapshot

- name: Create new VM and set protection to disable the remove VM and remove disk operations
  community.proxmox.proxmox_kvm:
    name: spynal
    node: sabrewulf
    protection: true

- name: Create new VM using cloud-init with a username and password
  community.proxmox.proxmox_kvm:
    node: sabrewulf
    name: spynal
    ide:
      ide2: 'local:cloudinit,format=qcow2'
    ciuser: mylinuxuser
    cipassword: supersecret
    searchdomains: 'mydomain.internal'
    nameservers: 1.1.1.1
    net:
      net0: 'virtio,bridge=vmbr1,tag=77'
    ipconfig:
      ipconfig0: 'ip=192.168.1.1/24,gw=192.168.1.1'

- name: Create new VM using Cloud-Init with an ssh key
  community.proxmox.proxmox_kvm:
    node: sabrewulf
    name: spynal
    ide:
      ide2: 'local:cloudinit,format=qcow2'
    sshkeys: |
      ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPUF/cMCRObddaMmvUDio//yge6gRGXNv3uqMq7ve0x3 ssh-key-1@example.com
      ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIP+v9HERWdWKh1lxceobl98LBX3+alfVK0zJnAxLbMRq ssh-key-2@example.com
    searchdomains: 'mydomain.internal'
    nameservers:
      - '1.1.1.1'
      - '8.8.8.8'
    net:
      net0: 'virtio,bridge=vmbr1,tag=77'
    ipconfig:
      ipconfig0: 'ip=192.168.1.1/24'

- name: Start VM
  community.proxmox.proxmox_kvm:
    name: spynal
    node: sabrewulf
    state: started

- name: Stop VM
  community.proxmox.proxmox_kvm:
    name: spynal
    node: sabrewulf
    state: stopped

- name: Stop VM with force
  community.proxmox.proxmox_kvm:
    name: spynal
    node: sabrewulf
    state: stopped
    force: true

- name: Restart VM
  community.proxmox.proxmox_kvm:
    name: spynal
    node: sabrewulf
    state: restarted

- name: Convert VM to template
  community.proxmox.proxmox_kvm:
    name: spynal
    node: sabrewulf
    state: template

- name: Convert VM to template (stop VM if running)
  community.proxmox.proxmox_kvm:
    name: spynal
    node: sabrewulf
    state: template
    force: true

- name: Remove VM
  community.proxmox.proxmox_kvm:
    name: spynal
    node: sabrewulf
    state: absent

- name: >-
    Remove VM, deleting all volumes that use the VM's ID, regardless
    of whether they are mentioned in the config or not
  community.proxmox.proxmox_kvm:
    name: spynal
    node: sabrewulf
    state: absent
    destroy_unreferenced_disks: true

- name: Get VM current state
  community.proxmox.proxmox_kvm:
    name: spynal
    node: sabrewulf
    state: current

- name: Update VM configuration
  community.proxmox.proxmox_kvm:
    name: spynal
    node: sabrewulf
    cores: 8
    memory: 16384
    update: true

- name: Update VM configuration (incl. unsafe options)
  community.proxmox.proxmox_kvm:
    name: spynal
    node: sabrewulf
    cores: 8
    memory: 16384
    net:
      net0: virtio,bridge=vmbr1
    update: true
    update_unsafe: true

- name: Delete QEMU parameters
  community.proxmox.proxmox_kvm:
    name: spynal
    node: sabrewulf
    delete: 'args,template,cpulimit'

- name: Revert a pending change
  community.proxmox.proxmox_kvm:
    name: spynal
    node: sabrewulf
    revert: 'template,cpulimit'

- name: Migrate VM on second node
  community.proxmox.proxmox_kvm:
    name: spynal
    node: sabrewulf-2
    migrate: true

- name: Add hookscript to existing VM
  community.proxmox.proxmox_kvm:
    vmid: 999
    node: sabrewulf
    hookscript: local:snippets/hookscript.pl
    update: true

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Description
msg string	A short message. Returned: always Sample: "VM kropta with vmid = 110 is running"
status string	The current virtual machine status. Returned: success, not clone, not absent, not update Sample: "running"
vmid integer	The VM vmid. Returned: success Sample: 115

Authors

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

Collection links

• Issue Tracker
• Repository (Sources)
• Report an issue
• Communication