vmware_guest – Manages virtual machines in vCenter
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: - - | |
cluster - added in 2.3 |
The cluster name where the virtual machine will run. This is a required parameter, if
This parameter is case sensitive. | |
convert - added in 2.8 |
|
Specify convert disk type while cloning template or virtual machine. |
customization - added in 2.3 |
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. Common parameters (Linux/Windows): - - - - - Parameters related to Windows customization: - - - - - - - - - - - - | |
customization_spec - added in 2.6 |
Unique name identifying the requested customization specification. This parameter is case sensitive. If set, then overrides | |
customvalues - added in 2.3 |
Define a list of custom values to set on virtual machine. A custom value object takes two fields 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 parameter takes precedence over "disk.datastore" parameter. 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. | |
disk - |
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. Valid attributes are: - - - - Default: - - Specify filename string in - - - Available options are : - - - | |
esxi_hostname - |
The ESXi hostname where the virtual machine will run. This is a required parameter, if
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 |
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 CentOS 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: - - - - - - - - - - - - - - - - - | |
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 Environment variable support added in Ansible 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 |
name - / required |
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. | |
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 sensitive. One of the below parameters is required per entry: - - Optional parameters per entry (used for virtual hardware): - - - - Optional parameters per entry (used for OS customization): - - - - - - - - | |
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 Environment variable support added in Ansible 2.6.
| |
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 Environment variable support added in Ansible 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 | |
state - |
|
Specify the state the virtual machine should be in. If If If If If If If If If |
state_change_timeout - added in 2.6 |
Default: 0 |
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. |
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. You can also specify template or VM UUID for identifying source. version_added 2.8. Use From version 2.8 onwards, absolute path to virtual machine or template can be used.
| |
use_instance_uuid boolean added in 2.8 |
|
Whether to use the VMWare instance UUID rather than the BIOS UUID. |
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 Environment variable support added in Ansible 2.6.
| |
uuid - |
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. | |
validate_certs boolean |
|
Allows connection when SSL certificates are not valid. Set to If the value is not specified in the task, the value of environment variable Environment variable support added in Ansible 2.6. If set to |
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: - - - - | |
wait_for_customization boolean added in 2.8 |
|
Wait until vCenter detects all guest customizations as successfully completed. When enabled, the VM will automatically be powered on. |
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 that the user used for 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.
- Tested on vSphere 5.5, 6.0, 6.5 and 6.7
- Use SCSI disks instead of IDE when you want to expand online disks by specifying a SCSI controller
- 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_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: str
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) <[email protected]>
- Philippe Dellaert (@pdellaert) <[email protected]>
- Abhijeet Kasurde (@Akasurde) <[email protected]>
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.8/modules/vmware_guest_module.html