vmware_guest - Manages virtual machines in vCenter
New in version 2.2.
Synopsis
- Create new virtual machines (from templates or not).
- Power on/power off/restart a virtual machine.
- Modify, rename or remove a virtual machine.
Requirements (on host that executes module)
- python >= 2.6
- PyVmomi
Options
| parameter | required | default | choices | comments |
|---|---|---|---|---|
| annotation
(added in 2.3)
|
no |
A note or annotation to include in the VM.
|
||
| cluster
(added in 2.3)
|
no |
The cluster name where the VM will run.
|
||
| customization
(added in 2.3)
|
no |
Parameters for OS customization when cloning from template.
Common parameters (Linux/Windows):
-
dns_servers (list): List of DNS servers to configure.
-
dns_suffix (list): List of domain suffixes, aka DNS search path (default:
domain parameter).
-
domain (string): DNS domain name to use.
-
hostname (string): Computer hostname (default: shorted
name parameter).
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).
|
||
| customvalues
(added in 2.3)
|
no |
Define a list of customvalues to set on VM.
A customvalue object takes 2 fields
key and
value.
|
||
| datacenter |
no | ha-datacenter |
Destination datacenter for the deploy operation.
|
|
| disk |
no |
A list of disks to add.
Valid attributes are:
-
size_[tb,gb,mb,kb] (integer): Disk storage size in specified unit.
-
type (string): Valid value is
thin (default: None).
-
datastore (string): Datastore to use for the disk. If
autoselect_datastore is enabled, filter datastore selection.
-
autoselect_datastore (bool): select the less used datastore.
|
||
| esxi_hostname |
no |
The ESXi hostname where the VM will run.
|
||
| folder |
no | /vm |
Destination folder, absolute or relative path to find an existing guest or create the new guest.
The folder should include the datacenter. ESX's datacenter is ha-datacenter
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
folder: vm/folder2
folder: folder2
|
|
| force |
no | no |
|
Ignore warnings and complete the actions.
|
| guest_id
(added in 2.3)
|
no |
Set the guest ID (Debian, RHEL, Windows...).
This field is required when creating a VM.
Valid values are referenced here: https://www.vmware.com/support/developer/converter-sdk/conv55_apireference/vim.vm.GuestOsDescriptor.GuestOsIdentifier.html
|
||
| hardware |
no |
Manage some VM hardware attributes.
Valid attributes are:
-
memory_mb (integer): Amount of memory in MB.
-
num_cpus (integer): Number of CPUs.
-
scsi (string): Valid values are
buslogic,
lsilogic,
lsilogicsas and
paravirtual (default).
|
||
| hostname |
yes |
The hostname or IP address of the vSphere vCenter.
|
||
| is_template
(added in 2.3)
|
no | no |
|
Flag the instance as a template.
|
| linked_clone
(added in 2.4)
|
no | no |
|
Whether to create a Linked Clone from the snapshot specified.
|
| name |
yes |
Name of the VM to work with.
VM names in vCenter are not necessarily unique, which may be problematic, see
name_match.
|
||
| name_match |
no | first |
|
If multiple VMs matching the name, use the first or last found.
|
| networks
(added in 2.3)
|
no |
A list of networks (in the order of the NICs).
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).
-
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).
|
||
| password |
yes |
The password of the vSphere vCenter.
aliases: pass, pwd
|
||
| resource_pool
(added in 2.3)
|
no |
Affect machine to the given resource pool.
Resource pool should be child of the selected host parent.
|
||
| snapshot_src
(added in 2.4)
|
no |
Name of an existing snapshot to use to create a clone of a VM.
|
||
| state |
yes |
|
What state should the virtual machine be in?
If
state is set to
present and VM exists, ensure the VM configuration conforms to task arguments.
|
|
| template |
no |
Template 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.
|
||
| username |
yes |
The username of the vSphere vCenter.
aliases: user, admin
|
||
| uuid |
no |
UUID of the instance to manage if known, this is VMware's unique identifier.
This is required if name is not supplied.
|
||
| validate_certs |
no | True |
|
Allows connection when SSL certificates are not valid. Set to false when certificates are not trusted.
|
| wait_for_ip_address |
no | no |
|
Wait until vCenter detects an IP address for the VM.
This requires vmware-tools (vmtoolsd) to properly work after creation.
|
Examples
- name: Create a VM from a template
vmware_guest:
hostname: 192.0.2.44
username: [email protected]
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: 1
scsi: paravirtual
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: [email protected]
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: [email protected]
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: [email protected]
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: [email protected]
password: vmware
uuid: 421e4592-c069-924d-ce20-7e7533fab926
state: absent
delegate_to: localhost
Return Values
Common return values are documented here Return Values, the following are the fields unique to this module:
| name | description | returned | type | sample |
|---|---|---|---|---|
| instance |
metadata about the new virtualmachine
|
always | dict | None |
Notes
Note
- Tested on vSphere 5.5 and 6.0
Status
This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.
For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Testing Ansible and Developing Modules.
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.4/vmware_guest_module.html
