Documentation

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

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 to customize 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: 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 (mandatory)
productid (string): Product ID
runonce (list): List of commands to run at first user logon
timezone (int): Timezone (default: 85) See https://msdn.microsoft.com/en-us/library/ms912391(v=winembedded.11).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], type, datastore and autoselect_datastore
type: Valid value is thin (default: None)
datastore: Datastore to use for the disk. If autoselect_datastore is True, filter datastore selection.
autoselect_datastore (bool): select the less used datastore.
esxi_hostname
no
The esxi hostname where the VM will run.
folder
no
Destination folder, absolute path to find an existing guest or create the new guest
force
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, num_cpus and scsi
scsi: 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
Flag the instance as a template
name
yes
Name of the VM to work with
name_match
no first
  • first
  • last
If multiple VMs matching the name, use the first or last found
networks
(added in 2.3)
no
Network to use should include name or vlan entry
Add an optional ip and netmask for network configuration
Add an optional gateway entry to configure a gateway
Add an optional mac entry to customize mac address
Add an optional dns_servers or domain entry per interface (Windows)
Add an optional device_type to configure the virtual NIC (pcnet32, vmxnet2, vmxnet3, e1000, e1000e)
password
yes
The password of the vSphere vCenter.

aliases: pass, pwd
resource_pool
(added in 2.3)
no None
Affect machine to the given resource pool
Resource pool should be child of the selected host parent
state
yes
  • present
  • absent
  • poweredon
  • poweredoff
  • restarted
  • suspended
  • shutdownguest
  • rebootguest
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
  • True
  • False
Allows connection when SSL certificates are not valid. Set to false when certificates are not trusted.
wait_for_ip_address
no
Wait until vCenter detects an IP address for the VM
This requires vmware-tools (vmtoolsd) to properly work after creation

Examples

# Create a VM from a template
  - name: create the VM
    vmware_guest:
      hostname: 192.0.2.44
      username: [email protected]
      password: vmware
      validate_certs: no
      esxi_hostname: 192.0.2.117
      datacenter: datacenter1
      folder: testvms
      name: testvm_2
      state: poweredon
      guest_id: centos64guest
      disk:
      - size_gb: 10
        type: thin
        datastore: g73_datastore
      hardware:
        memory_mb: 512
        num_cpus: 1
        scsi: paravirtual
      networks:
      - name: VM Network
        ip: 192.168.1.100
        netmask: 255.255.255.0
        mac: 'aa:bb:dd:aa:00:14'
      template: template_el7
      wait_for_ip_address: yes
    register: deploy

# Clone a VM from Template and customize
  - name: Clone 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
      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\Enable-WinRM.ps1 -ForceNewSSLCert

# Create a VM template
  - 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
      wait_for_ip_address: yes
    register: deploy

# 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

# 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

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 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.

Support

This module is community maintained without core committer oversight.

For more information on what this means please read Module Support

For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Helping Testing PRs and Developing Modules.