community.vmware.vmware_guest module – Manages virtual machines in vCenter
Note
This module is part of the community.vmware collection (version 4.2.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.vmware.
To use it in a playbook, specify: community.vmware.vmware_guest.
Synopsis
This module can be used to create new virtual machines from templates or other virtual machines, manage power state of virtual machine such as power on, power off, suspend, shutdown, reboot, restart etc., modify various virtual machine components like network, disk, customization etc., rename a virtual machine and remove a virtual machine with associated components.
Parameters
Parameter |
Comments |
|---|---|
Define a list of advanced settings to be added to the VMX config. An advanced settings object takes the two fields Incorrect key and values will be ignored. Default: |
|
A note or annotation to include in the virtual machine. |
|
A list of CD-ROM configurations for the virtual machine. For Default: |
|
For For |
|
When set to Choices:
|
|
The datastore path to the ISO file to use, in the form of Required if type is set |
|
If set to Choices:
|
|
The type of CD-ROM. With Choices:
|
|
For For
|
|
The cluster name where the virtual machine will run. This is a required parameter, if
This parameter is case sensitive. |
|
Specify convert disk type while cloning template or virtual machine. Choices:
|
|
Parameters for OS customization when cloning from the template or the virtual machine, or apply to the existing virtual machine directly. Not all operating systems are supported for customization with respective vCenter version, please check VMware documentation for respective OS customization. For supported customization operating system matrix, (see http://partnerweb.vmware.com/programs/guestOS/guest-os-customization-matrix.pdf) All parameters and VMware object names are case sensitive. Linux based OSes requires Perl package to be installed for OS customizations. Default: |
|
Auto logon after virtual machine customization. Specific to Windows customization. Choices:
|
|
Number of autologon after reboot. Specific to Windows customization. Ignored if If unset, 1 will be used. |
|
List of DNS servers to configure. Common for Linux and Windows customization. |
|
List of domain suffixes, also known as DNS search path. Default Common for Linux and Windows customization. |
|
DNS domain name to use. Common for Linux and Windows customization. |
|
User used to join in AD domain. Required if Specific to Windows customization. |
|
Password used to join in AD domain. Required if Specific to Windows customization. |
|
If set to Common for Linux and Windows customization. Choices:
|
|
Server owner name. Specific to Windows customization. If unset, “Administrator” will be used as a fall-back. |
|
Computer hostname. Default is shortened Allowed characters are alphanumeric (uppercase and lowercase) and minus, rest of the characters are dropped as per RFC 952. Common for Linux and Windows customization. |
|
Specifies whether the hardware clock is in UTC or local time. Specific to Linux customization. Choices:
|
|
AD domain to join. Not compatible with Specific to Windows customization. |
|
Workgroup to join. Not compatible with Specific to Windows customization. If unset, “WORKGROUP” will be used as a fall-back. |
|
Organisation name. Specific to Windows customization. If unset, “ACME” will be used as a fall-back. |
|
Local administrator password. If not defined, the password will be set to blank (that is, no password). Specific to Windows customization. |
|
Product ID. Specific to Windows customization. |
|
List of commands to run at first user logon. Specific to Windows customization. |
|
Script to run with shebang. Needs to be enabled in vmware tools with vmware-toolbox-cmd config set deployPkg enable-custom-scripts true Specific to Linux customization. |
|
Timezone. See List of supported time zones for different vSphere versions in Linux/Unix. Common for Linux and Windows customization. |
|
Unique name identifying the requested customization specification. This parameter is case sensitive. If set, then overrides |
|
Define a list of custom values to set on virtual machine. A custom value object takes the two fields Incorrect key and values will be ignored. Default: |
|
Destination datacenter for the deploy operation. This parameter is case sensitive. Default: |
|
Specify datastore or datastore cluster to provision virtual machine. This parameter takes precedence over This parameter can be used to override datastore or datastore cluster setting of the virtual machine when deployed from the template. Please see example for more usage. |
|
Whether to delete Virtual machine from inventory or delete from disk. Choices:
|
|
A list of disks to add. This parameter is case sensitive. Shrinking disks is not supported. Removing existing disks of the virtual machine is not supported. Attributes Default: |
|
Select the less used datastore.
Choices:
|
|
Disk controller bus number. The maximum number of same type controller is 4 per VM. Choices:
|
|
Type of disk controller. Set this type on not supported ESXi or VM hardware version will lead to failure in deployment. When set to If set to Choices:
|
|
The name of datastore which will be used for the disk. If |
|
Type of disk mode. If If If Choices:
|
|
Existing disk image to be used. Filename must already exist on the datastore. Specify filename string in |
|
Disk storage size. Please specify storage unit like [kb, mb, gb, tb]. |
|
Disk storage size in gb. |
|
Disk storage size in kb. |
|
Disk storage size in mb. |
|
Disk storage size in tb. |
|
Type of disk. If not specified, disk type is inherited from the source VM or template when cloned and thick disk, no eagerzero otherwise. Choices:
|
|
Disk Unit Number. Valid value range from 0 to 15 for SCSI controller, except 7. Valid value range from 0 to 14 for NVME controller. Valid value range from 0 to 29 for SATA controller.
When creating new VM, the first configured disk in the |
|
Manage virtual machine encryption settings All parameters case sensitive. Default: |
|
Controls encryption for fault tolerance replication Choices:
|
|
Controls encryption for live migrations with vmotion Choices:
|
|
The ESXi hostname where the virtual machine will run. This is a required parameter, if
This parameter is case sensitive. |
|
Destination folder, absolute path to find an existing guest or create the new guest. The folder should include the datacenter. ESXi’s datacenter is ha-datacenter. This parameter is case sensitive. If multiple machines are found with same name, this parameter is used to identify uniqueness of the virtual machine. Examples:
|
|
Ignore warnings and complete the actions. This parameter is useful while removing virtual machine which is powered on state. This module reflects the VMware vCenter API and UI workflow, as such, in some cases the `force` flag will be mandatory to perform the action to ensure you are certain the action has to be taken, no matter what the consequence. This is specifically the case for removing a powered on the virtual machine when Choices:
|
|
Set the guest ID. This parameter is case sensitive. This field is required when creating a virtual machine, not required when creating from the template. Valid values are referenced here: https://code.vmware.com/apis/358/doc/vim.vm.GuestOsDescriptor.GuestOsIdentifier.html |
|
Manage virtual machine’s hardware attributes. All parameters case sensitive. Default: |
|
Choose which firmware should be used to boot the virtual machine. Choices:
|
|
The CPU utilization of a virtual machine will not exceed this limit. Unit is MHz. |
|
The amount of CPU resource that is guaranteed available to the virtual machine. |
|
The number of shares of CPU allocated to this virtual machine cpu_shares_level will automatically be set to ‘custom’ |
|
The allocation level of CPU resources for the virtual machine. Choices:
|
|
Allow virtual CPUs to be added while the virtual machine is running. Choices:
|
|
Allow memory to be added while the virtual machine is running. Choices:
|
|
Allow virtual CPUs to be removed while the virtual machine is running. Choices:
|
|
Flag to specify if I/O MMU is enabled for this virtual machine. Choices:
|
|
Maximum number of active remote display connections for the virtual machines. |
|
The memory utilization of a virtual machine will not exceed this limit. Unit is MB. |
|
The amount of memory resource that is guaranteed available to the virtual machine. |
|
The number of shares of memory allocated to this virtual machine mem_shares_level will automatically be set to ‘custom’ |
|
The allocation level of memory resources for the virtual machine. Choices:
|
|
Amount of memory in MB. |
|
If set Choices:
|
|
Enable nested virtualization. Choices:
|
|
Number of Cores Per Socket. |
|
Number of CPUs. Must be a multiple of For example, to create a VM with 2 sockets of 4 cores, specify |
|
Valid values are
Choices:
|
|
Whether to enable or disable (U)EFI secure boot. Choices:
|
|
The Virtual machine hardware versions. Default is 10 (ESXi 5.5 and onwards). If set to Please check VMware documentation for correct virtual machine hardware version. Incorrect hardware version may lead to failure in deployment. If hardware version is already equal to the given. |
|
Enable Virtualization Based Security feature for Windows on ESXi 6.7 and later, from hardware version 14. Supported Guest OS are Windows 10 64 bit, Windows Server 2016, Windows Server 2019 and later. The firmware of virtual machine must be EFI and secure boot must be enabled. Virtualization Based Security depends on nested virtualization and Intel Virtualization Technology for Directed I/O. Deploy on unsupported ESXi, hardware version or firmware may lead to failure or deployed VM with unexpected configurations. Choices:
|
|
Enable virtual CPU Performance Counters. Choices:
|
|
The hostname or IP address of the vSphere vCenter or ESXi server. If the value is not specified in the task, the value of environment variable |
|
Flag the instance as a template. This will mark the given virtual machine as template. Note, this may need to be done in a dedicated task invocation that is not making any other changes. For example, user cannot change the state from powered-on to powered-off AND save as template in the same task. See community.vmware.vmware_guest source for more details. Choices:
|
|
Whether to create a linked clone from the snapshot specified. If specified, then Choices:
|
|
Name of the virtual machine to work with. Virtual machine names in vCenter are not necessarily unique, which may be problematic, see If multiple virtual machines with same name exists, then This parameter is required, if This parameter is case sensitive. |
|
If multiple virtual machines matching the name, use the first or last found. Choices:
|
|
A list of networks (in the order of the NICs). Removing NICs is not allowed, while reconfiguring the virtual machine. All parameters and VMware object names are case sensitive. The type, ip, netmask, gateway, domain, dns_servers options don’t set to a guest when creating a blank new virtual machine. They are set by the customization via vmware-tools. If you want to set the value of the options to a guest, you need to clone from a template with installed OS and vmware-tools(also Perl when Linux). Default: |
|
Indicates whether the NIC is currently connected. Choices:
|
|
Virtual network device. Valid value can be one of
Optional per entry. Used for virtual hardware. |
|
DNS servers for this network interface (Windows). Optional per entry. Used for OS customization. |
|
Domain name for this network interface (Windows). Optional per entry. Used for OS customization. |
|
Name of the distributed vSwitch. Optional per entry. Used for virtual hardware. |
|
Static gateway. Optional per entry. Used for OS customization. |
|
Static gateway. Optional per entry. Used for OS customization. |
|
Static IP address. Implies Optional per entry. Used for OS customization. |
|
Static IP address. Implies Optional per entry. Used for OS customization. |
|
Customize MAC address. Optional per entry. Used for virtual hardware. |
|
Name of the portgroup or distributed virtual portgroup for this interface. Required per entry. When specifying distributed virtual portgroup make sure given |
|
Static netmask required for Optional per entry. Used for OS customization. |
|
Static netmask required for Optional per entry. Used for OS customization. |
|
Specifies whether or not to connect the device when the virtual machine starts. Choices:
|
|
Type of IP assignment. Valid values are one of
Optional per entry. Used for OS customization. |
|
Type of IP assignment. Valid values are one of
Optional per entry. Used for OS customization. |
|
VLAN number for this interface. Required per entry. |
|
Add or remove a virtual NVDIMM device to the virtual machine. VM virtual hardware version must be 14 or higher on vSphere 6.7 or later. Verify that guest OS of the virtual machine supports PMem before adding virtual NVDIMM device. Verify that you have the Datastore.Allocate space privilege on the virtual machine. Make sure that the host or the cluster on which the virtual machine resides has available PMem resources. To add or remove virtual NVDIMM device to the existing virtual machine, it must be in power off state. Default: |
|
The label of the virtual NVDIMM device to be removed or configured, e.g., “NVDIMM 1”. This parameter is required when |
|
Virtual NVDIMM device size in MB. Default: |
|
If set to Choices:
|
|
The password of the vSphere vCenter or ESXi server. If the value is not specified in the task, the value of environment variable |
|
The port number of the vSphere vCenter or ESXi server. If the value is not specified in the task, the value of environment variable Default: |
|
Address of a proxy that will receive all HTTPS requests and relay them. The format is a hostname or a IP. If the value is not specified in the task, the value of environment variable |
|
Port of the HTTP proxy that will receive all HTTPS requests and relay them. If the value is not specified in the task, the value of environment variable |
|
Use the given resource pool for virtual machine operation. This parameter is case sensitive. Resource pool should be child of the selected host parent. When not specified Resources is taken as default value. |
|
Name of the existing snapshot to use to create a clone of a virtual machine. This parameter is case sensitive. While creating linked clone using |
|
Specify the state the virtual machine should be in. If If If set to one of If set to If set to If set to If set to If set to If set to Choices:
|
|
If the If this argument is set to a positive integer, the module will instead wait for the virtual machine to reach the poweredoff state. The value sets a timeout in seconds for the module to wait for the state change. Default: |
|
Template or existing virtual machine used to create new virtual machine. If this value is not set, virtual machine is created without using a template. If the virtual machine already exists, this parameter will be ignored. This parameter is case sensitive. From version 2.8 onwards, absolute path to virtual machine or template can be used. |
|
Whether to use the VMware instance UUID rather than the BIOS UUID. Choices:
|
|
The username of the vSphere vCenter or ESXi server. If the value is not specified in the task, the value of environment variable |
|
UUID of the virtual machine to manage if known, this is VMware’s unique identifier. This is required if If virtual machine does not exists, then this parameter is ignored. Please note that a supplied UUID will be ignored on virtual machine creation, as VMware creates the UUID internally. |
|
Allows connection when SSL certificates are not valid. Set to If the value is not specified in the task, the value of environment variable Choices:
|
|
A list of vApp properties. For full list of attributes and types refer to: https://code.vmware.com/apis/704/vsphere/vim.vApp.PropertyInfo.html Default: |
|
Property ID. Required per entry. |
|
The |
|
Value type, string type by default. |
|
Property value. |
|
Wait until vCenter detects all guest customizations as successfully completed. When enabled, the VM will automatically be powered on. If vCenter does not detect guest customization start or succeed, failed events after time Choices:
|
|
Define a timeout (in seconds) for the wait_for_customization parameter. Be careful when setting this value since the time guest customization took may differ among guest OSes. Default: |
|
Wait until vCenter detects an IP address for the virtual machine. This requires vmware-tools (vmtoolsd) to properly work after creation. vmware-tools needs to be installed on the given virtual machine in order to work with this parameter. Choices:
|
|
Define a timeout (in seconds) for the wait_for_ip_address parameter. Default: |
Notes
Note
Please make sure that the user used for community.vmware.vmware_guest has the correct level of privileges.
For example, following is the list of minimum privileges required by users to create virtual machines.
DataStore > Allocate Space
Virtual Machine > Configuration > Add New Disk
Virtual Machine > Configuration > Add or Remove Device
Virtual Machine > Inventory > Create New
Network > Assign Network
Resource > Assign Virtual Machine to Resource Pool
Module may require additional privileges as well, which may be required for gathering facts - e.g. ESXi configurations.
Use SCSI disks instead of IDE when you want to expand online disks by specifying a SCSI controller.
Uses SysPrep for Windows VM (depends on ‘guest_id’ parameter match ‘win’) with PyVmomi.
In order to change the VM’s parameters (e.g. number of CPUs), the VM must be powered off unless the hot-add support is enabled and the
state=presentmust be used to apply the changes.For additional information please visit Ansible VMware community wiki - https://github.com/ansible/community/wiki/VMware.
All modules requires API write access and hence is not supported on a free ESXi license.
Examples
- name: Create a virtual machine on given ESXi hostname
community.vmware.vmware_guest:
hostname: "{{ vcenter_hostname }}"
username: "{{ vcenter_username }}"
password: "{{ vcenter_password }}"
folder: /DC1/vm/
name: test_vm_0001
state: poweredon
guest_id: centos64Guest
# This is hostname of particular ESXi server on which user wants VM to be deployed
esxi_hostname: "{{ esxi_hostname }}"
disk:
- size_gb: 10
type: thin
datastore: datastore1
hardware:
memory_mb: 512
num_cpus: 4
scsi: paravirtual
networks:
- name: VM Network
mac: aa:bb:dd:aa:00:14
ip: 10.10.10.100
netmask: 255.255.255.0
device_type: vmxnet3
wait_for_ip_address: true
wait_for_ip_address_timeout: 600
delegate_to: localhost
register: deploy_vm
- name: Create a virtual machine from a template
community.vmware.vmware_guest:
hostname: "{{ vcenter_hostname }}"
username: "{{ vcenter_username }}"
password: "{{ vcenter_password }}"
folder: /testvms
name: testvm_2
state: poweredon
template: template_el7
disk:
- size_gb: 10
type: thin
datastore: g73_datastore
# Add another disk from an existing VMDK
- filename: "[datastore1] testvms/testvm_2_1/testvm_2_1.vmdk"
hardware:
memory_mb: 512
num_cpus: 6
num_cpu_cores_per_socket: 3
scsi: paravirtual
memory_reservation_lock: true
mem_limit: 8096
mem_reservation: 4096
cpu_shares_level: "high"
mem_shares_level: "high"
cpu_limit: 8096
cpu_reservation: 4096
max_connections: 5
hotadd_cpu: true
hotremove_cpu: true
hotadd_memory: false
version: 12 # Hardware version of virtual machine
boot_firmware: "efi"
cdrom:
- controller_number: 0
unit_number: 0
state: present
type: iso
iso_path: "[datastore1] livecd.iso"
networks:
- name: VM Network
mac: aa:bb:dd:aa:00:14
wait_for_ip_address: true
delegate_to: localhost
register: deploy
- name: Clone a virtual machine from Windows template and customize
community.vmware.vmware_guest:
hostname: "{{ vcenter_hostname }}"
username: "{{ vcenter_username }}"
password: "{{ vcenter_password }}"
datacenter: datacenter1
cluster: cluster
name: testvm-2
template: template_windows
networks:
- name: VM Network
ip: 192.168.1.100
netmask: 255.255.255.0
gateway: 192.168.1.1
mac: aa:bb:dd:aa:00:14
domain: my_domain
dns_servers:
- 192.168.1.1
- 192.168.1.2
- vlan: 1234
type: dhcp
customization:
autologon: true
dns_servers:
- 192.168.1.1
- 192.168.1.2
domain: my_domain
password: new_vm_password
runonce:
- powershell.exe -ExecutionPolicy Unrestricted -File C:\Windows\Temp\ConfigureRemotingForAnsible.ps1 -ForceNewSSLCert -EnableCredSSP
delegate_to: localhost
- name: Clone a virtual machine from Linux template and customize
community.vmware.vmware_guest:
hostname: "{{ vcenter_hostname }}"
username: "{{ vcenter_username }}"
password: "{{ vcenter_password }}"
datacenter: "{{ datacenter }}"
state: present
folder: /DC1/vm
template: "{{ template }}"
name: "{{ vm_name }}"
cluster: DC1_C1
networks:
- name: VM Network
ip: 192.168.10.11
netmask: 255.255.255.0
wait_for_ip_address: true
customization:
domain: "{{ guest_domain }}"
dns_servers:
- 8.9.9.9
- 7.8.8.9
dns_suffix:
- example.com
- example2.com
script_text: |
#!/bin/bash
touch /tmp/touch-from-playbook
delegate_to: localhost
- name: Rename a virtual machine (requires the virtual machine's uuid)
community.vmware.vmware_guest:
hostname: "{{ vcenter_hostname }}"
username: "{{ vcenter_username }}"
password: "{{ vcenter_password }}"
uuid: "{{ vm_uuid }}"
name: new_name
state: present
delegate_to: localhost
- name: Remove a virtual machine by uuid
community.vmware.vmware_guest:
hostname: "{{ vcenter_hostname }}"
username: "{{ vcenter_username }}"
password: "{{ vcenter_password }}"
uuid: "{{ vm_uuid }}"
state: absent
delegate_to: localhost
- name: Remove a virtual machine from inventory
community.vmware.vmware_guest:
hostname: "{{ vcenter_hostname }}"
username: "{{ vcenter_username }}"
password: "{{ vcenter_password }}"
name: vm_name
delete_from_inventory: true
state: absent
delegate_to: localhost
- name: Manipulate vApp properties
community.vmware.vmware_guest:
hostname: "{{ vcenter_hostname }}"
username: "{{ vcenter_username }}"
password: "{{ vcenter_password }}"
name: vm_name
state: present
vapp_properties:
- id: remoteIP
category: Backup
label: Backup server IP
type: string
value: 10.10.10.1
- id: old_property
operation: remove
delegate_to: localhost
- name: Set powerstate of a virtual machine to poweroff by using UUID
community.vmware.vmware_guest:
hostname: "{{ vcenter_hostname }}"
username: "{{ vcenter_username }}"
password: "{{ vcenter_password }}"
uuid: "{{ vm_uuid }}"
state: poweredoff
delegate_to: localhost
- name: Deploy a virtual machine in a datastore different from the datastore of the template
community.vmware.vmware_guest:
hostname: "{{ vcenter_hostname }}"
username: "{{ vcenter_username }}"
password: "{{ vcenter_password }}"
name: "{{ vm_name }}"
state: present
template: "{{ template_name }}"
# Here datastore can be different which holds template
datastore: "{{ virtual_machine_datastore }}"
hardware:
memory_mb: 512
num_cpus: 2
scsi: paravirtual
delegate_to: localhost
- name: Create a diskless VM
community.vmware.vmware_guest:
hostname: "{{ vcenter_hostname }}"
username: "{{ vcenter_username }}"
password: "{{ vcenter_password }}"
datacenter: "{{ dc1 }}"
state: poweredoff
cluster: "{{ ccr1 }}"
name: diskless_vm
folder: /Asia-Datacenter1/vm
guest_id: centos64Guest
datastore: "{{ ds1 }}"
hardware:
memory_mb: 1024
num_cpus: 2
num_cpu_cores_per_socket: 1
- name: Create a VM with multiple disks of different disk controller types
community.vmware.vmware_guest:
hostname: "{{ vcenter_hostname }}"
username: "{{ vcenter_username }}"
password: "{{ vcenter_password }}"
folder: /DC1/vm/
name: test_vm_multi_disks
state: poweredoff
guest_id: centos64Guest
datastore: datastore1
disk:
- size_gb: 10
controller_type: 'nvme'
controller_number: 0
unit_number: 0
- size_gb: 10
controller_type: 'paravirtual'
controller_number: 0
unit_number: 1
- size_gb: 10
controller_type: 'sata'
controller_number: 0
unit_number: 2
hardware:
memory_mb: 512
num_cpus: 4
version: 14
networks:
- name: VM Network
device_type: vmxnet3
delegate_to: localhost
register: deploy_vm
- name: Create a VM with NVDIMM device
community.vmware.vmware_guest:
hostname: "{{ vcenter_hostname }}"
username: "{{ vcenter_username }}"
password: "{{ vcenter_password }}"
folder: /DC1/vm/
name: test_vm_nvdimm
state: poweredoff
guest_id: centos7_64Guest
datastore: datastore1
hardware:
memory_mb: 512
num_cpus: 4
version: 14
networks:
- name: VM Network
device_type: vmxnet3
nvdimm:
state: present
size_mb: 2048
delegate_to: localhost
register: deploy_vm
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
metadata about the new virtual machine Returned: always Sample: |