vmware.vmware.vm_apply_customization module – Applies a customization specification to a virtual machine.
Note
This module is part of the vmware.vmware collection (version 2.9.0).
You might already have this collection installed if you are using the ansible package.
It is not included in ansible-core.
To check whether it is installed, run ansible-galaxy collection list.
To install it, use: ansible-galaxy collection install vmware.vmware.
To use it in a playbook, specify: vmware.vmware.vm_apply_customization.
Synopsis
This module is used to apply a customization specification to a virtual machine. It always applies the specification defined here, and always reports a change.
Customization specifications are run once when a VM is powered on or rebooted. This module just applies the customization specification to the VM, making sure that it will be run during the next power cycle.
Since customization is run asynchronously, you should check the VM logs to ensure that the customization was applied successfully. See the examples for ways to ensure the customization was applied successfully in a playbook.
Once the VM is started, the pending customization is applied. Even if that fails, the customization is then cleared. Meaning, you need to re-apply the customization spec in order to try again. Simply rebooting the VM will not change anything.
Customization leverages VMWare Tools to inject the customization specification into the VM. For a list of supported operating systems, see the Broadcom documentation http://partnerweb.vmware.com/programs/guestOS/guest-os-customization-matrix.pdf
Custom script execution is disabled by default. To enable it, you can run as an administrator ‘vmware-toolbox-cmd config set deployPkg enable-custom-scripts true’
Parameters
Parameter |
Comments |
|---|---|
The cloud-init configuration to apply to the VM. Only applicable for Linux guests. The OS must already have cloud-init and perl installed. One and only one of |
|
The instance data to apply to the VM. Instance data includes the network, instance id and hostname that cloud-init processes to configure the VM. It is in json or yaml format. The max size of the instance data is 524288 bytes. For more information see https://cloudinit.readthedocs.io/en/latest/explanation/instancedata.html This option expects the instance data to be passed in as a dictionary. It is mutually exclusive with One of |
|
Similar to One of |
|
The user data script to apply to the VM. This is usually a cloud-config yaml file or shell script. The max size of the userdata is 524288 bytes. For more information see https://cloudinit.readthedocs.io/en/latest/topics/format.html |
|
The datacenter in which to search for the VM. |
|
The name of the existing customization specification in vSphere to apply to the VM. One and only one of |
|
Destination folder, absolute or relative path to find an existing guest. Should be the full folder path, with or without the ‘datacenter/vm/’ prefix For example ‘datacenter_name/vm/path/to/folder’ or ‘path/to/folder’. You cannot use this module to modify the placement of a VM once it has been created. |
|
If true, any folder path parameters are treated as absolute paths. If false, modules will try to intelligently determine if the path is absolute or relative. This option is useful when your environment has a complex folder structure. By default, modules will try to intelligently determine if the path is absolute or relative. They may mistakenly prepend the datacenter name or other folder names, and this option can be used to avoid this. Choices:
|
|
The global DNS configuration to apply to the VM. These apply to any network adapter this is not explicitly configured. |
|
A list of DNS name resolution suffixes to use. This list applies to both Windows and Linux guest customization. |
|
A list of DNS servers to use. If this list is empty or not specified then the guest operating system is expected to use a DHCP server to get its DNS server settings. These DNS server settings are listed in order of preference. |
|
The hostname or IP address of the vSphere vCenter server. If the value is not specified in the task, the value of environment variable |
|
Name of the virtual machine to manage. Virtual machine names in vCenter are not necessarily unique, which may be problematic, see This is required when the VM does not exist, or if |
|
If multiple virtual machines matching the name, use the first or last found. Choices:
|
|
Specify settings for specific network adapters. This setting is required if If this setting is used, you need to specify an item in this list for all network adapters on your VM due to VMware’s API requirements. |
|
A list of DNS servers to use for this network adapter. |
|
Specify the IPv4 address to use for a virtual network adapter. This section must be specified but it can be left empty to use DHCP. |
|
Specify the IP address to use for a virtual network adapter, essentially assigning a static IP address. If this is not specified, DHCP will be used. This is required if |
|
Specify a list of gateways, in order of preference, to use for the IP address. |
|
Specify the subnet mask to use for a virtual network adapter with a static IP address. This should be a string in CIDR notation, for example ‘255.255.255.0’ This is required if |
|
Specify the IPv6 address to use for a virtual network adapter. |
|
Specify the IPv6 address to use for a virtual network adapter, essentially assigning a static IP address. If this is not specified, DHCP will be used. This is required if |
|
Specify a list of gateways, in order of preference, to use for the IP address. |
|
Specify the subnet mask to use for a virtual network adapter with a static IP address. This is required if This should be an integer representing the prefix length, for example 64. |
|
Specify the MAC address of the network adapter to manage. This is using the MAC address as an identifier. You cannot change the MAC address of an adapter with this module. You should either specify the MAC address for all items in this list, or none of them. If you do not specify the MAC address, the customizations will be applied to network adapters in the same order as they are defined here (for example, the first item in this list will be applied to the first network adapter on the VM). |
|
Specify the NetBIOS mode to use. This only applies to Windows guests. Choices:
|
|
Specify the IP address of the primary WINS server to use. This only applies to Windows guests. |
|
A DNS suffix to use for this network adapter. |
|
Specify the IP address of the secondary WINS server to use. This only applies to Windows guests. |
|
The password of the vSphere vCenter server. If the value is not specified in the task, the value of environment variable |
|
The port number of the vSphere vCenter server. If the value is not specified in the task, the value of environment variable Default: |
|
The 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 |
|
The 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 |
|
The Unix Prep configuration to apply to the VM. Only applicable for Linux guests. The OS must already have perl installed. One and only one of |
|
The fully qualified domain name for the machine. |
|
Whether to set the hardware clock to UTC or use the local timezone. If true, the hardware clock will be set to UTC. Choices:
|
|
The hostname to set for the machine. |
|
The script to run before and after the GOS customization process. Specify the script as a string, including the shebang line. The script is executed as the root user. |
|
The case sensitive name of the timezone to set for the machine. For a list of valid timezone values, see the Broadcom documentation, https://developer.broadcom.com/xapis/vsphere-web-services-api/8.0.3/timezone.html |
|
If true, DHCPv4 will be used for all network adapters on the VM. If false, you must specify all adapters in Choices:
|
|
Whether to use the VMware instance UUID rather than the BIOS UUID. Choices:
|
|
The username of the vSphere vCenter server. If the value is not specified in the task, the value of environment variable |
|
Allows connection when SSL certificates are not valid. Set to If the value is not specified in the task, the value of environment variable Choices:
|
|
The Windows Sysprep configuration to apply to the VM. Only applicable for Windows guests. One and only one of |
|
If true, the machine will automatically log on as Administrator. If this is true, Choices:
|
|
Specify the number of times the machine should automatically log on as Administrator, if Generally it should be 1, but if your setup requires a number of reboots, you may want to increase it. Default: |
|
The name of the domain for the machine to join. Only one of |
|
The username of the domain user to use to join the domain. This user does not need to be a domain administrator, but it must have the ability to join computers to the domain. |
|
The password of the domain user to use to join the domain. Required if |
|
The name of the domain to join. |
|
Specify the full LDAP path name of the OU to which the computer should belong. For example, OU=MyOu,DC=MyDom,DC=MyCompany,DC=com Only available for vSphere API Release 8.0.2.0 and later. |
|
A list of commands to run once the GUI is available. This occurs at first user logon, after guest customization has completed. Default: |
|
Specify the host, or compute, name for this machine. Computer name may contain letters (A-Z), numbers(0-9) and hyphens (-) but no spaces or periods (.). The name may not consists entirely of digits. Hostname is restricted to 15 characters in length. If the hostname is longer than 15 characters, it will be truncated to 15 characters. |
|
The local Administrator password for the machine. You must specify a password. If there is no password, meaning it should be blank, set this value to ‘’. If the password is null, you cannot use |
|
The power-related action to take once the sysprep process is complete. This is either a reboot, a shutdown, or nothing at all. Choices:
|
|
Microsoft Sysprep requires that a valid serial number be included in the answer file when mini-setup runs. This serial number is ignored if the original guest operating system was installed using a volume-licensed CD. |
|
The timezone to set for the machine. This should be an integer value matching the index from the Microsoft documentation. For example, index 000 would be just be 0. See the Microsoft documentation for a list of valid timezone index values, https://support.microsoft.com/en-us/help/973627/microsoft-time-zone-index-values |
|
The full name of the user to be associated with this machine. |
|
The organization name of the user to be associated with this machine. |
|
The name of the workgroup for the machine to join. Only one of |
Notes
Note
All modules require API write access and hence are not supported on a free ESXi license.
All variables and VMware object names are case sensitive.
Modules may rely on the ‘requests’ python library, which does not use the system certificate store by default. You can specify the certificate store by setting the REQUESTS_CA_BUNDLE environment variable. Note having this variable set may cause a ‘false’ value for the ‘validate_certs’ option to be ignored in some cases. Example: ‘export REQUESTS_CA_BUNDLE=/path/to/your/ca_bundle.pem’
Examples
# Full deployment example
- name: Deploy a VM from a template
vmware.vmware.deploy_folder_template:
hostname: "https://vcenter"
username: "username"
password: "password"
datacenter: "my-datacenter"
vm_name: "my_vm"
template_name: "my_template"
register: _deploy_vm
- name: Set VM hardware settings
vmware.vmware.vm:
moid: "{{ _deploy_vm.vm.moid }}"
cpu:
cores: 4
cores_per_socket: 2
memory:
size_mb: 8096
disks:
- size: 80gb
provisioning: thin
device_node: SCSI(0:0)
- size: 10gb
provisioning: thick
device_node: SCSI(0:1)
- size: 1tb
provisioning: thin
device_node: SCSI(1:0)
datastore: ArchiveDatastore
scsi_controllers:
- controller_type: paravirtual
bus_number: 0
- controller_type: paravirtual
bus_number: 1
bus_sharing: virtualSharing
network_adapters:
- network: VM Network
adapter_type: vmxnet3
connected: true
connect_at_power_on: true
- network: Management
adapter_type: vmxnet3
connected: true
connect_at_power_on: true
mac_address: 11:11:11:11:11:11
- name: Set VM customization spec
vmware.vmware.vm_apply_customization:
moid: "{{ _deploy_vm.vm.moid }}"
datacenter: "my-datacenter"
use_dhcpv4_for_all_nics: true
cloud_init:
instance_data:
instance-id: "{{ _deploy_vm.vm.moid }}"
hostname: "{{ _deploy_vm.vm.name }}"
network:
version: 2
ethernets:
nics:
match:
name: e*
dhcp4: true
dhcp6: false
public_ssh_keys:
- "{{ lookup('ansible.builtin.file', vmware_vm_ssh_public_key_file_path) }}"
user_data_string: |
#cloud-config
hostname: {{ _deploy_vm.vm.name }}
fqdn: {{ _deploy_vm.vm.name }}.contoso.com
disable_root: false
ssh_pwauth: false
ssh_deletekeys: true
ssh:
emit_keys_to_console: false
no_ssh_fingerprints: false
ssh_authorized_keys:
- {{ lookup('ansible.builtin.file', vmware_vm_ssh_public_key_file_path) }}
users:
- name: root
ssh_authorized_keys:
- {{ lookup('ansible.builtin.file', vmware_vm_ssh_public_key_file_path) }}
lock_passwd: false
write_files:
- path: /etc/cloud/cloud-init.disabled
permissions: "0644"
content: ""
- name: Power on VM
vmware.vmware.vm_powerstate:
moid: "{{ _deploy_vm.vm.moid }}"
datacenter: "my-datacenter"
state: powered-on
- name: Wait for customization to complete
ansible.builtin.wait_for:
path: /etc/cloud/cloud-init.disabled
state: present
delegate_to: "{{ _deploy_vm.vm.name }}"
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
Information about the target VM Returned: On success Sample: |