community.general.proxmox_kvm module – Management of Qemu(KVM) Virtual Machines in Proxmox VE cluster
Note
This module is part of the community.general collection (version 8.6.4).
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.general
.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: community.general.proxmox_kvm
.
Synopsis
Allows you to create/delete/stop Qemu(KVM) Virtual Machines in Proxmox VE cluster.
Since community.general 4.0.0 on, there are no more default values, see
proxmox_default_behavior
.
Aliases: cloud.misc.proxmox_kvm
Requirements
The below requirements are needed on the host that executes this module.
proxmoxer
requests
Parameters
Parameter |
Comments |
---|---|
Specify if ACPI should be enabled/disabled. This option has no default unless Choices:
|
|
Specify if the QEMU Guest Agent should be enabled/disabled. Since community.general 5.5.0, this can also be a string instead of a boolean. This allows to specify values such as |
|
Specify the target host of the Proxmox VE cluster. |
|
Specify the password to authenticate with. You can use |
|
Specify the token ID. Requires |
|
Specify the token secret. Requires |
|
Specify the user to authenticate with. |
|
Specify a path to an archive to restore (instead of creating or cloning a VM). |
|
Pass arbitrary arguments to kvm. This option is for experts only! If |
|
Specify if the VM should be automatically restarted after crash (currently ignored in PVE API). This option has no default unless Choices:
|
|
Specify the amount of RAM for the VM in MB. Using zero disables the balloon driver. This option has no default unless |
|
Specify the BIOS implementation. Choices:
|
|
Specify the boot order -> boot on floppy For newer versions of Proxmox VE, use a boot order like You can combine to set order. This option has no default unless |
|
Enable booting from specified disk. Format |
|
cloud-init: Specify custom files to replace the automatically generated ones at start. |
|
cloud-init: password of default user to create. |
|
cloud-init: Specifies the cloud-init configuration format. The default depends on the configured operating system type ( We use the Choices:
|
|
cloud-init: username of default user to create. |
|
Specify number of cores per socket. This option has no default unless |
|
Specify emulated CPU type. This option has no default unless |
|
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 |
|
Specify CPU weight for a VM. You can disable fair-scheduler configuration by setting this to 0 This option has no default unless |
|
Specify a list of settings you want to delete. |
|
Specify the description for the VM. Only used on the configuration web interface. This is saved as comment inside the configuration file. |
|
Specify if to prevent changes if current configuration file has different SHA1 digest. This can be used to prevent concurrent modifications. |
|
Specify a hash/dictionary of EFI disk options. Requires |
|
Choices:
|
|
|
|
If set to Choices:
|
|
|
|
Allow to force stop VM. Can be used with states This option has no default unless Requires parameter Choices:
|
|
Target drive’s backing file’s data format. Used only with clone Use Please refer to the Proxmox VE Administrator Guide, section Proxmox VE Storage (see https://pve.proxmox.com/pve-docs/chapter-pvesm.html for the latest version, tables 3 to 14) to find out format supported by the provided storage backend. This option has no default unless Choices:
|
|
Specify if PVE should freeze CPU at startup (use ‘c’ monitor command to start execution). Choices:
|
|
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:
|
|
Script that will be executed during various steps in the containers lifetime. |
|
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. |
|
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 |
|
Enable/disable hugepages memory. Choices:
|
|
A hash/dictionary of volume used as IDE hard disk or CD-ROM. Keys allowed are - Values allowed are -
|
|
cloud-init: Set the IP configuration. A hash/dictionary of network ip configurations. Keys allowed are - Values allowed are - cloud-init: Specify IP addresses and gateways for the corresponding interface. IP addresses use CIDR notation, gateways are optional but they should be in the same subnet of specified IP address. The special string ‘dhcp’ can be used for IP addresses to use DHCP, in which case no explicit gateway should be provided. For IPv6 the special string ‘auto’ can be used to use stateless autoconfiguration. If cloud-init is enabled and neither an IPv4 nor an IPv6 address is specified, it defaults to using dhcp on IPv4. |
|
Sets the keyboard layout for VNC server. |
|
Enable/disable KVM hardware virtualization. This option has no default unless Choices:
|
|
Sets the real time clock to local time. This is enabled by default if ostype indicates a Microsoft OS. Choices:
|
|
Lock/unlock the VM. Choices:
|
|
Specifies the Qemu machine type. Type => |
|
Memory size in MB for instance. This option has no default unless |
|
Sets maximum tolerated downtime (in seconds) for migrations. |
|
Sets maximum speed (in MB/s) for migrations. A value of 0 is no limit. |
|
Specifies the VM name. Name could be non-unique across the cluster. Required only for With |
|
cloud-init: DNS server IP address(es). If unset, PVE host settings are used. |
|
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. |
|
VMID for the clone. Used only with clone. If newid is not set, the next available VM ID will be fetched from ProxmoxAPI. |
|
Proxmox VE node on which to operate. Only required for For every other states it will be autodiscovered. |
|
A hash/dictionaries of NUMA topology. Keys allowed are - Values allowed are -
|
|
Enables NUMA. Choices:
|
|
Specifies whether a VM will be started during system bootup. This option has no default unless Choices:
|
|
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. This option has no default unless Choices:
|
|
A hash/dictionary of map host parallel devices. Keys allowed are - (parallel[n]) where 0 ≤ n ≤ 2. Values allowed are - |
|
Add the new VM to the specified pool. |
|
Enable/disable the protection flag of the VM. This will enable/disable the remove VM and remove disk operations. Choices:
|
|
As of community.general 4.0.0, various options no longer have default values. These default values caused problems when users expected different behavior from Proxmox by default or filled options which caused problems when set. - The value Choices:
|
|
Allow reboot. If set to Choices:
|
|
Revert a pending change. |
|
A hash/dictionary of volume used as sata hard disk or CD-ROM. Keys allowed are - Values allowed are -
|
|
A hash/dictionary of volume used as SCSI hard disk or CD-ROM. Keys allowed are - Values allowed are -
|
|
Specifies the SCSI controller model. Choices:
|
|
cloud-init: Sets DNS search domain(s). If unset, PVE host settings are used. |
|
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. |
|
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. |
|
Ignore locks Only root is allowed to use this option. Choices:
|
|
Specifies SMBIOS type 1 fields. Comma separated, Base64 encoded (optional) SMBIOS properties:
|
|
The name of the snapshot. Used only with clone. |
|
Sets the number of CPU sockets. (1 - N). This option has no default unless |
|
cloud-init: SSH key to assign to the default user. NOT TESTED with multiple keys but a multi-line value should work. |
|
Sets the initial date of the real time clock. Valid format for date are |
|
Startup and shutdown behavior. Order is a non-negative number defining the general startup order. Shutdown in done with reverse ordering. |
|
Indicates desired state of the instance. If
Choices:
|
|
Target storage for full clone. |
|
Enables/disables the USB tablet device. This option has no default unless Choices:
|
|
List of tags to apply to the VM instance. Tags must start with Tags are only available in Proxmox 6+. |
|
Target node. Only allowed if the original VM is on shared storage. Used only with clone |
|
Enables/disables time drift fix. Choices:
|
|
Enables/disables the template. This option has no default unless Choices:
|
|
Timeout for operations. When used with Default: |
|
A hash/dictionary of options for the Trusted Platform Module disk. A TPM state disk is required for Windows 11 installations. |
|
|
|
The TPM version to use. Choices:
|
|
If Because of the operations of the API and security reasons, I have disabled the update of the following parameters Update of Choices:
|
|
If This should only be used on personally controlled sites using self-signed certificates. Choices:
|
|
Sets number of hotplugged vcpus. |
|
Select VGA type. If you want to use high resolution modes (>= 1280x1024x16) then you should use option ‘std’ or ‘vmware’. This option has no default unless Choices:
|
|
A hash/dictionary of volume used as VIRTIO hard disk. Keys allowed are - Values allowed are -
|
|
Specifies the instance ID. If not set the next available ID will be fetched from ProxmoxAPI. |
|
Creates a virtual hardware watchdog device. |
Attributes
Attribute |
Support |
Description |
---|---|---|
Support: none |
Can run in |
|
Support: none |
Will return details on what has changed (or possibly needs changing in |
See Also
See also
- community.general.proxmox_vm_info
Retrieve information about one or more Proxmox VE virtual machines.
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 a VM from archive (backup)
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
archive: backup-storage:backup/vm/140/2023-03-08T06:41:23Z
name: spynal
- 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: Create VM with 1 10GB SATA disk and an EFI disk, with Secure Boot disabled by default
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
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 10GB SATA disk and an EFI disk, with Secure Boot enabled by default
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
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.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: >
Create linked 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
full: false
format: unspecified
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 snapshot
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: true
- name: Create new VM using cloud-init with a username and password
community.general.proxmox_kvm:
node: sabrewulf
api_user: root@pam
api_password: secret
api_host: helldorado
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.general.proxmox_kvm:
node: sabrewulf
api_user: root@pam
api_password: secret
api_host: helldorado
name: spynal
ide:
ide2: 'local:cloudinit,format=qcow2'
sshkeys: 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILJkVm98B71lD5XHfihwcYHE9TVpsJmK1vR1JcaU82L+'
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.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: true
- name: Restart VM
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
name: spynal
node: sabrewulf
state: restarted
- name: Convert VM to template
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
name: spynal
node: sabrewulf
state: template
- name: Convert VM to template (stop VM if running)
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
name: spynal
node: sabrewulf
state: template
force: true
- 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: true
- name: Update VM configuration (incl. unsafe options)
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
name: spynal
node: sabrewulf
cores: 8
memory: 16384
net:
net0: virtio,bridge=vmbr1
update: true
update_unsafe: true
- 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'
- name: Migrate VM on second node
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
name: spynal
node: sabrewulf-2
migrate: true
- name: Add hookscript to existing VM
community.general.proxmox_kvm:
api_user: root@pam
api_password: secret
api_host: helldorado
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 |
---|---|
A short message Returned: always Sample: |
|
The current virtual machine status. Returned: success, not clone, not absent, not update Sample: |
|
The VM vmid. Returned: success Sample: |