vmware_guest – Manages virtual machines in vCenter
New in version 2.2.
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.
Requirements
The below requirements are needed on the host that executes this module.
- python >= 2.6
- PyVmomi
Parameters
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 virtual machine.
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 is a required parameter, if
esxi_hostname is not set.
esxi_hostname and
cluster are mutually exclusive parameters.
This parameter is case sensitive.
|
|
customization
-
added in 2.3
|
Parameters for OS customization when cloning from the template or the virtual machine.
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.
Common parameters (Linux/Windows):
-
dns_servers (list): List of DNS servers to configure.
-
dns_suffix (list): List of domain suffixes, also known as 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 virtual machine 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.
|
datastore
-
added in 2.7
|
Specify datastore or datastore cluster to provision virtual machine.
This will take precendence over "disk.datastore" parameter.
This parameter is useful to override datastore or datastore cluster setting.
For example, when user has different datastore or datastore cluster for templates and virtual machines.
Please see example for more usage.
|
|
disk
-
|
A list of disks to add.
This parameter is case sensitive.
Resizing disks is not supported.
Removing existing disks of the 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.5
Default:
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.
-
disk_mode (string): Type of disk mode. Added in version 2.6
- Available options are :
-
persistent : Changes are immediately and permanently written to the virtual disk. This is default.
-
independent_persistent : Same as persistent, but not affected by snapshots.
-
independent_nonpersistent : Changes to virtual disk are made to a redo log and discarded at power off, but not affected by snapshots.
|
|
esxi_hostname
-
|
The ESXi hostname where the virtual machine will run.
This is a required parameter, if
cluster is not set.
esxi_hostname and
cluster are mutually exclusive parameters.
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.
This parameter is required, while deploying new virtual machine. version_added 2.5.
If multiple machines are found with same name, this parameter is used to identify uniqueness of the virtual machine. version_added 2.5
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
boolean
|
|
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
state is set to
absent .
|
guest_id
-
added in 2.3
|
Set the guest ID.
This parameter is case sensitive.
Examples:
virtual machine with RHEL7 64 bit, will be 'rhel7_64Guest'
virtual machine with CensOS 64 bit, will be 'centos64Guest'
virtual machine with Ubuntu 64 bit, will be 'ubuntu64Guest'
This field is required when creating a virtual machine.
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 virtual machine is running.
-
hotremove_cpu (boolean): Allow virtual CPUs to be removed while the virtual machine is running. version_added: 2.5
-
hotadd_memory (boolean): Allow memory to be added while the virtual machine 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 the virtual machine will always be equal to the virtual machine'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 equal to the given version then no action is taken. version_added: 2.6
-
boot_firmware (string): Choose which firmware should be used to boot the virtual machine. Allowed values are "bios" and "efi". version_added: 2.7
|
|
hostname
string
|
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 support added in version 2.6.
|
|
is_template
boolean
added in 2.3
|
|
Flag the instance as a template.
This will mark the given virtual machine as template.
|
linked_clone
boolean
added in 2.4
|
|
Whether to create a linked clone from the snapshot specified.
If specified, then
snapshot_src is required parameter.
|
name
- /
required
|
Name of the virtual machine to work with.
Virtual machine names in vCenter are not necessarily unique, which may be problematic, see
name_match .
If multiple virtual machines with same name exists, then
folder is required parameter to identify uniqueness of the virtual machine.
This parameter is required, if
state is set to
poweredon ,
poweredoff ,
present ,
restarted ,
suspended and virtual machine does not exists.
This parameter is case sensitive.
|
|
name_match
-
|
|
If multiple virtual machines matching the name, use the first or last found.
|
networks
-
added in 2.3
|
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 sensetive.
One of the below parameters is required per entry:
-
name (string): Name of the portgroup or distributed virtual portgroup for this interface. When specifying distributed virtual portgroup make sure given
esxi_hostname or
cluster is associated with it.
-
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.
-
dvswitch_name (string): Name of the distributed vSwitch. This value is required if multiple distributed portgroups exists with the same name. version_added 2.7
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
string
|
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 support added in version 2.6.
aliases: pass, pwd |
|
port
integer
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 support added in version 2.6.
|
resource_pool
-
added in 2.3
|
Use the given resource pool for virtual machine operation.
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 virtual machine.
This parameter is case sensitive.
While creating linked clone using
linked_clone parameter, this parameter is required.
|
|
state
-
|
|
Specify state of the virtual machine be in.
If
state is set to
present and virtual machine exists, ensure the virtual machine configurations conforms to task arguments.
If
state is set to
absent and virtual machine exists, then the specified virtual machine is removed with its associated components.
If
state is set to one of the following
poweredon ,
poweredoff ,
present ,
restarted ,
suspended and virtual machine does not exists, then virtual machine is deployed with given parameters.
If
state is set to
poweredon and virtual machine exists with powerstate other than powered on, then the specified virtual machine is powered on.
If
state is set to
poweredoff and virtual machine exists with powerstate other than powered off, then the specified virtual machine is powered off.
If
state is set to
restarted and virtual machine exists, then the virtual machine is restarted.
If
state is set to
suspended and virtual machine exists, then the virtual machine is set to suspended mode.
If
state is set to
shutdownguest and virtual machine exists, then the virtual machine is shutdown.
If
state is set to
rebootguest and virtual machine exists, then the virtual machine is rebooted.
|
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 virtual machine 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 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.
aliases: template_src |
|
username
string
|
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 support added in version 2.6.
aliases: admin, user |
|
uuid
-
|
UUID of the virtual machine to manage if known, this is VMware's unique identifier.
This is required if
name is not supplied.
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.
|
|
validate_certs
boolean
|
|
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 support added in version 2.6.
If set to
yes , please make sure Python >= 2.7.9 is installed on the given machine.
|
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
boolean
|
|
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.
|
Notes
Note
- Please make sure the user used for vmware_guest should have 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.
- Tested on vSphere 5.5, 6.0 and 6.5
- For additional information please visit Ansible VMware community wiki - https://github.com/ansible/community/wiki/VMware.
Examples
- name: Create a virtual machine on given ESXi hostname vmware_guest: hostname: "{{ vcenter_hostname }}" username: "{{ vcenter_username }}" password: "{{ vcenter_password }}" validate_certs: no 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: yes delegate_to: localhost register: deploy_vm - name: Create a virtual machine from a template vmware_guest: hostname: "{{ vcenter_hostname }}" username: "{{ vcenter_username }}" password: "{{ vcenter_password }}" 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 virtual machine boot_firmware: "efi" 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 virtual machine from Windows template and customize vmware_guest: hostname: "{{ vcenter_hostname }}" username: "{{ vcenter_username }}" password: "{{ vcenter_password }}" 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: Clone a virtual machine from Linux template and customize vmware_guest: hostname: "{{ vcenter_hostname }}" username: "{{ vcenter_username }}" password: "{{ vcenter_password }}" validate_certs: no 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 delegate_to: localhost - name: Rename a virtual machine (requires the virtual machine's uuid) vmware_guest: hostname: "{{ vcenter_hostname }}" username: "{{ vcenter_username }}" password: "{{ vcenter_password }}" validate_certs: no uuid: "{{ vm_uuid }}" name: new_name state: present delegate_to: localhost - name: Remove a virtual machine by uuid vmware_guest: hostname: "{{ vcenter_hostname }}" username: "{{ vcenter_username }}" password: "{{ vcenter_password }}" validate_certs: no uuid: "{{ vm_uuid }}" state: absent delegate_to: localhost - name: Manipulate vApp properties vmware_guest: hostname: "{{ vcenter_hostname }}" username: "{{ vcenter_username }}" password: "{{ vcenter_password }}" validate_certs: no 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 vmware_guest: hostname: "{{ vcenter_hostname }}" username: "{{ vcenter_username }}" password: "{{ vcenter_password }}" validate_certs: no uuid: "{{ vm_uuid }}" state: poweredoff delegate_to: localhost - name: Deploy a virtual machine in a datastore different from the datastore of the template 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
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key | Returned | Description |
---|---|---|
instance
dictionary
|
always |
metadata about the new virtual machine
Sample:
None
|
Status
- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]
Authors
- Loic Blot (@nerzhul) <loic.blot@unix-experience.fr>
- Philippe Dellaert (@pdellaert) <philippe@dellaert.org>
- Abhijeet Kasurde (@Akasurde) <akasurde@redhat.com>
Hint
If you notice any issues in this documentation you can edit this document to improve it.
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.7/modules/vmware_guest_module.html