vmware_guest – Manages virtual machines in vCenter¶

Synopsis
Requirements
Parameters
Notes
Examples
Return Values
Status

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 -		A note or annotation to include in the virtual machine.
cdrom - added in 2.5		A CD-ROM configuration for the virtual machine. Or a list of CD-ROMs configuration for the virtual machine. Added in version 2.9. Parameters `controller_type`, `controller_number`, `unit_number`, `state` are added for a list of CD-ROMs configuration support. 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`. - `controller_type` (string): Default value is `ide`. Only `ide` controller type for CD-ROM is supported for now, will add SATA controller type in the future. - `controller_number` (int): For `ide` controller, valid value is 0 or 1. - `unit_number` (int): For CD-ROM device attach to `ide` controller, valid value is 0 or 1. `controller_number` and `unit_number` are mandatory attributes. - `state` (string): Valid value is `present` or `absent`. Default is `present`. If set to `absent`, then the specified CD-ROM will be removed. For `ide` controller, hot-add or hot-remove CD-ROM is not supported.
cluster -		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.
convert - added in 2.8	Choices: thin thick eagerzeroedthick	Specify convert disk type while cloning template or virtual machine.
customization -		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): - `existing_vm` (bool): If set to `True`, do OS customization on the specified virtual machine directly. If set to `False` or not specified, do OS customization when cloning from the template or the virtual machine. version_added: 2.8 - `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 Linux customization: - `timezone` (string): Timezone (See List of supported time zones for different vSphere versions in Linux/Unix systems (2145518) https://kb.vmware.com/s/article/2145518). version_added: 2.9 - `hwclockUTC` (bool): Specifies whether the hardware clock is in UTC or local time. True when the hardware clock is in UTC, False when the hardware clock is in local time. version_added: 2.9 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 -		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 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: - `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): The name of datastore which will be used for the disk. If `autoselect_datastore` is set to True, then will select the less used datastore whose name contains this "disk.datastore" string. - `filename` (string): Existing disk image to be used. Filename must already exist on the datastore. Specify filename string in `[datastore_name] path/to/file.vmdk` format. Added in version 2.8. - `autoselect_datastore` (bool): select the less used datastore. "disk.datastore" and "disk.autoselect_datastore" will not be used if `datastore` is specified outside this `disk` configuration. - `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	Choices: no ← yes	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 -		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, not required when creating from the template. Valid values are referenced here: https://code.vmware.com/apis/358/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. `num_cpus` must be a multiple of `num_cpu_cores_per_socket`. For example to create a VM with 2 sockets of 4 cores, specify `num_cpus`: 8 and `num_cpu_cores_per_socket`: 4 - `scsi` (string): Valid values are `buslogic`, `lsilogic`, `lsilogicsas` and `paravirtual` (default). - `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. `memory_reservation` is alias to this. 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 - `virt_based_security` (bool): Enable Virtualization Based Security feature for Windows 10. (Support from Virtual machine hardware version 14, Guest OS Windows 10 64 bit, Windows Server 2016)
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 Ansible 2.6.
is_template boolean	Choices: no ← yes	Flag the instance as a template. This will mark the given virtual machine as template.
linked_clone boolean added in 2.4	Choices: no ← yes	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 -	Choices: first ← last	If multiple virtual machines matching the name, use the first or last found.
networks -		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: - `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 - `start_connected` (bool): Indicates that virtual network adapter starts with associated virtual machine powers on. version_added: 2.5 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 - `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 Ansible 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 Ansible 2.6.
proxy_host string added in 2.9		Address of a proxy that will receive all HTTPS requests and relay them. The format is a hostname or a IP. If the value is not specified in the task, the value of environment variable `VMWARE_PROXY_HOST` will be used instead. This feature depends on a version of pyvmomi greater than v6.7.1.2018.12
proxy_port integer added in 2.9		Port of the HTTP proxy that will receive all HTTPS requests and relay them. If the value is not specified in the task, the value of environment variable `VMWARE_PROXY_PORT` will be used instead.
resource_pool -		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 -	Choices: present ← absent poweredon poweredoff restarted suspended shutdownguest rebootguest	Specify the state the virtual machine should 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. You can also specify template or VM UUID for identifying source. version_added 2.8. Use `hw_product_uuid` from vmware_guest_facts as UUID value. From version 2.8 onwards, absolute path to virtual machine or template can be used. aliases: template_src
use_instance_uuid boolean added in 2.8	Choices: no ← yes	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 `VMWARE_USER` will be used instead. Environment variable support added in Ansible 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	Choices: no yes ←	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 Ansible 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_customization boolean added in 2.8	Choices: no ← yes	Wait until vCenter detects all guest customizations as successfully completed. When enabled, the VM will automatically be powered on.
wait_for_ip_address boolean	Choices: no ← yes	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) <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.

vmware_guest – Manages virtual machines in vCenter¶

Synopsis¶

Requirements¶

Parameters¶

Notes¶

Examples¶

Return Values¶

Status¶