New in version 2.2.
The below requirements are needed on the host that executes this module.
| Parameter | Choices/Defaults | Comments |
|---|---|---|
|
annotation
(added in 2.3) |
A note or annotation to include in the virtual machine.
|
|
|
cdrom
(added in 2.5) |
A CD-ROM configuration for the VM.
Valid attributes are:
-
type (string): The type of CD-ROM, valid options are none, client or iso. With none the CD-ROM will be disconnected but present.-
iso_path (string): The datastore path to the ISO file to use, in the form of [datastore1] path/to/file.iso. Required if type is set iso. |
|
|
cluster
(added in 2.3) |
The cluster name where the virtual machine will run.
This parameter is case sensitive.
|
|
|
customization
(added in 2.3) |
Parameters for OS customization when cloning from the template or the virtual machine.
All parameters and VMware object names are case sensitive.
Linux based OS requires Perl to be installed for OS customization.
Common parameters (Linux/Windows):
-
dns_servers (list): List of DNS servers to configure.-
dns_suffix (list): List of domain suffixes, a.k.a. DNS search path (default: domain parameter).-
domain (string): DNS domain name to use.-
hostname (string): Computer hostname (default: shorted name parameter).Allowed characters are alphanumeric (uppercase and lowercase) and minus, rest of the characters are dropped as per RFC 952.
Parameters related to Windows customization:
-
autologon (bool): Auto logon after VM customization (default: False).-
autologoncount (int): Number of autologon after reboot (default: 1).-
domainadmin (string): User used to join in AD domain (mandatory with joindomain).-
domainadminpassword (string): Password used to join in AD domain (mandatory with joindomain).-
fullname (string): Server owner name (default: Administrator).-
joindomain (string): AD domain to join (Not compatible with joinworkgroup).-
joinworkgroup (string): Workgroup to join (Not compatible with joindomain, default: WORKGROUP).-
orgname (string): Organisation name (default: ACME).-
password (string): Local administrator password.-
productid (string): Product ID.-
runonce (list): List of commands to run at first user logon.-
timezone (int): Timezone (See https://msdn.microsoft.com/en-us/library/ms912391.aspx). |
|
|
customization_spec
(added in 2.6) |
Unique name identifying the requested customization specification.
This parameter is case sensitive.
If set, then overrides
customization parameter values. |
|
|
customvalues
(added in 2.3) |
Define a list of custom values to set on virtual machine.
A custom value object takes two fields
key and value.Incorrect key and values will be ignored.
|
|
| datacenter |
Default: ha-datacenter
|
Destination datacenter for the deploy operation.
This parameter is case sensitive.
|
| disk |
A list of disks to add.
This parameter is case sensitive.
Resizing disks is not supported.
Removing existing disks of virtual machine is not supported.
Valid attributes are:
-
size_[tb,gb,mb,kb] (integer): Disk storage size in specified unit.-
type (string): Valid values are:-
thin thin disk-
eagerzeroedthick eagerzeroedthick disk, added in version 2.5Default:
None thick disk, no eagerzero.-
datastore (string): Datastore to use for the disk. If autoselect_datastore is enabled, filter datastore selection.-
autoselect_datastore (bool): select the less used datastore. Specify only if datastore is not specified. |
|
| esxi_hostname |
The ESXi hostname where the virtual machine will run.
This parameter is case sensitive.
|
|
| folder |
Destination folder, absolute path to find an existing guest or create the new guest.
The folder should include the datacenter. ESX's datacenter is ha-datacenter.
This parameter is case sensitive.
Examples:
folder: /ha-datacenter/vm
folder: ha-datacenter/vm
folder: /datacenter1/vm
folder: datacenter1/vm
folder: /datacenter1/vm/folder1
folder: datacenter1/vm/folder1
folder: /folder1/datacenter1/vm
folder: folder1/datacenter1/vm
folder: /folder1/datacenter1/vm/folder2
|
|
| force |
|
Ignore warnings and complete the actions.
This parameter is useful while removing virtual machine which is powered on state.
|
|
guest_id
(added in 2.3) |
Set the guest ID.
This parameter is case sensitive.
Examples:
VM with RHEL7 64 bit, will be 'rhel7_64Guest'
VM with CensOS 64 bit, will be 'centos64Guest'
VM with Ubuntu 64 bit, will be 'ubuntu64Guest'
This field is required when creating a VM.
Valid values are referenced here: http://pubs.vmware.com/vsphere-6-5/topic/com.vmware.wssdk.apiref.doc/vim.vm.GuestOsDescriptor.GuestOsIdentifier.html
|
|
| hardware |
Manage virtual machine's hardware attributes.
All parameters case sensitive.
Valid attributes are:
-
hotadd_cpu (boolean): Allow virtual CPUs to be added while the VM is running.-
hotremove_cpu (boolean): Allow virtual CPUs to be removed while the VM is running. version_added: 2.5-
hotadd_memory (boolean): Allow memory to be added while the VM is running.-
memory_mb (integer): Amount of memory in MB.-
nested_virt (bool): Enable nested virtualization. version_added: 2.5-
num_cpus (integer): Number of CPUs.-
num_cpu_cores_per_socket (integer): Number of Cores Per Socket. Value should be multiple of num_cpus.-
scsi (string): Valid values are buslogic, lsilogic, lsilogicsas and paravirtual (default).-
memory_reservation (integer): Amount of memory in MB to set resource limits for memory. version_added: 2.5-
memory_reservation_lock (boolean): If set true, memory resource reservation for VM will always be equal to the VM's memory size. version_added: 2.5-
max_connections (integer): Maximum number of active remote display connections for the virtual machines. version_added: 2.5.-
mem_limit (integer): The memory utilization of a virtual machine will not exceed this limit. Unit is MB. version_added: 2.5-
mem_reservation (integer): The amount of memory resource that is guaranteed available to the virtual machine. Unit is MB. version_added: 2.5-
cpu_limit (integer): The CPU utilization of a virtual machine will not exceed this limit. Unit is MHz. version_added: 2.5-
cpu_reservation (integer): The amount of CPU resource that is guaranteed available to the virtual machine. Unit is MHz. version_added: 2.5-
version (integer): The Virtual machine hardware versions. Default is 10 (ESXi 5.5 and onwards). Please check VMware documentation for correct virtual machine hardware version. Incorrect hardware version may lead to failure in deployment. If hardware version is already to given version then no action is taken. version_added: 2.6 |
|
| hostname |
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
VMWARE_HOST will be used instead.Environment variable supported added in version 2.6.
|
|
|
is_template
(added in 2.3) |
|
Flag the instance as a template.
This will mark VM instance as template.
|
|
linked_clone
(added in 2.4) |
|
Whether to create a Linked Clone from the snapshot specified.
|
|
name
required |
Name of the VM to work with.
VM names in vCenter are not necessarily unique, which may be problematic, see
name_match.This parameter is case sensitive.
|
|
| name_match |
|
If multiple VMs matching the name, use the first or last found.
|
|
networks
(added in 2.3) |
A list of networks (in the order of the NICs).
All parameters and VMware object names are case sensetive.
One of the below parameters is required per entry:
-
name (string): Name of the portgroup for this interface.-
vlan (integer): VLAN number for this interface.Optional parameters per entry (used for virtual hardware):
-
device_type (string): Virtual network device (one of e1000, e1000e, pcnet32, vmxnet2, vmxnet3 (default), sriov).-
mac (string): Customize MAC address.Optional parameters per entry (used for OS customization):
-
type (string): Type of IP assignment (either dhcp or static). dhcp is default.-
ip (string): Static IP address (implies type: static).-
netmask (string): Static netmask required for ip.-
gateway (string): Static gateway.-
dns_servers (string): DNS servers for this network interface (Windows).-
domain (string): Domain name for this network interface (Windows).-
wake_on_lan (bool): Indicates if wake-on-LAN is enabled on this virtual network adapter. version_added: 2.5-
start_connected (bool): Indicates that virtual network adapter starts with associated virtual machine powers on. version_added: 2.5-
allow_guest_control (bool): Enables guest control over whether the connectable device is connected. version_added: 2.5 |
|
| password |
The password of the vSphere vCenter or ESXi server.
If the value is not specified in the task, the value of environment variable
VMWARE_PASSWORD will be used instead.Environment variable supported added in version 2.6.
aliases: pass, pwd |
|
|
port
(added in 2.5) |
Default: 443
|
The port number of the vSphere vCenter or ESXi server.
If the value is not specified in the task, the value of environment variable
VMWARE_PORT will be used instead.Environment variable supported added in version 2.6.
|
|
resource_pool
(added in 2.3) |
Affect machine to the given resource pool.
This parameter is case sensitive.
Resource pool should be child of the selected host parent.
|
|
|
snapshot_src
(added in 2.4) |
Name of the existing snapshot to use to create a clone of a VM.
This parameter is case sensitive.
|
|
| state |
|
Specify state of the virtual machine be in.
If
state is set to present and VM exists, ensure the VM configuration conforms to task arguments. |
|
state_change_timeout
(added in 2.6) |
Default: 0
|
If the
state is set to shutdownguest, by default the module will return immediately after sending the shutdown signal.If this argument is set to a positive integer, the module will instead wait for the VM to reach the poweredoff state.
The value sets a timeout in seconds for the module to wait for the state change.
|
| template |
Template or existing VM used to create VM.
If this value is not set, VM is created without using a template.
If the VM exists already this setting will be ignored.
This parameter is case sensitive.
aliases: template_src |
|
| username |
The username of the vSphere vCenter or ESXi server.
If the value is not specified in the task, the value of environment variable
VMWARE_USER will be used instead.Environment variable supported added in version 2.6.
aliases: user, admin |
|
| uuid |
UUID of the instance to manage if known, this is VMware's unique identifier.
This is required if name is not supplied.
Please note that a supplied UUID will be ignored on VM creation, as VMware creates the UUID internally.
|
|
| validate_certs |
True
|
Allows connection when SSL certificates are not valid. Set to
false when certificates are not trusted.If the value is not specified in the task, the value of environment variable
VMWARE_VALIDATE_CERTS will be used instead.Environment variable supported added in version 2.6.
|
|
vapp_properties
(added in 2.6) |
A list of vApp properties
For full list of attributes and types refer to: https://github.com/vmware/pyvmomi/blob/master/docs/vim/vApp/PropertyInfo.rst
Basic attributes are:
-
id (string): Property id - required.-
value (string): Property value.-
type (string): Value type, string type by default.-
operation: remove: This attribute is required only when removing properties. |
|
| wait_for_ip_address |
|
Wait until vCenter detects an IP address for the VM.
This requires vmware-tools (vmtoolsd) to properly work after creation.
vmware-tools needs to be installed on given virtual machine in order to work with this parameter.
|
- name: Create a VM from a template
vmware_guest:
hostname: 192.0.2.44
username: administrator@vsphere.local
password: vmware
validate_certs: no
folder: /testvms
name: testvm_2
state: poweredon
template: template_el7
disk:
- size_gb: 10
type: thin
datastore: g73_datastore
hardware:
memory_mb: 512
num_cpus: 6
num_cpu_cores_per_socket: 3
scsi: paravirtual
memory_reservation: 512
memory_reservation_lock: True
mem_limit: 8096
mem_reservation: 4096
cpu_limit: 8096
cpu_reservation: 4096
max_connections: 5
hotadd_cpu: True
hotremove_cpu: True
hotadd_memory: False
version: 12 # Hardware version of VM
cdrom:
type: iso
iso_path: "[datastore1] livecd.iso"
networks:
- name: VM Network
mac: aa:bb:dd:aa:00:14
wait_for_ip_address: yes
delegate_to: localhost
register: deploy
- name: Clone a VM from Template and customize
vmware_guest:
hostname: 192.168.1.209
username: administrator@vsphere.local
password: vmware
validate_certs: no
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: yes
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: Create a VM template
vmware_guest:
hostname: 192.0.2.88
username: administrator@vsphere.local
password: vmware
validate_certs: no
datacenter: datacenter1
cluster: vmware_cluster_esx
resource_pool: highperformance_pool
folder: /testvms
name: testvm_6
is_template: yes
guest_id: debian6_64Guest
disk:
- size_gb: 10
type: thin
datastore: g73_datastore
hardware:
memory_mb: 512
num_cpus: 1
scsi: lsilogic
delegate_to: localhost
register: deploy
- name: Rename a VM (requires the VM's uuid)
vmware_guest:
hostname: 192.168.1.209
username: administrator@vsphere.local
password: vmware
uuid: 421e4592-c069-924d-ce20-7e7533fab926
name: new_name
state: present
delegate_to: localhost
- name: Remove a VM by uuid
vmware_guest:
hostname: 192.168.1.209
username: administrator@vsphere.local
password: vmware
uuid: 421e4592-c069-924d-ce20-7e7533fab926
state: absent
delegate_to: localhost
- name: Manipulate vApp properties
vmware_guest:
hostname: 192.168.1.209
username: administrator@vsphere.local
password: vmware
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
Common return values are documented here, the following are the fields unique to this module:
| Key | Returned | Description |
|---|---|---|
|
instance
dict
|
always |
metadata about the new virtual machine
Sample:
None
|
This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.
Hint
If you notice any issues in this documentation you can edit this document to improve it.