vmware.vmware_rest.vcenter_vm module – Creates a virtual machine.
Note
This module is part of the vmware.vmware_rest collection (version 4.2.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_rest
.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: vmware.vmware_rest.vcenter_vm
.
New in vmware.vmware_rest 0.1.0
Synopsis
Creates a virtual machine.
Requirements
The below requirements are needed on the host that executes this module.
vSphere 7.0.3 or greater
python >= 3.6
aiohttp
Parameters
Parameter |
Comments |
---|---|
128-bit SMBIOS UUID of a virtual machine represented as a hexadecimal string in “12345678-abcd-1234-cdef-123456789abc” format. If unset, will be generated. |
|
Boot configuration. If unset, guest-specific default values will be used. Valid attributes are:
If unset, defaults to value that is recommended for the guest OS and is supported for the virtual hardware version. ([‘present’])
If unset, default value is 0. ([‘present’])
If unset, default value is false. ([‘present’])
If unset, default value is 10000. ([‘present’])
If unset, the value is unchanged. ([‘present’]) |
|
Boot device configuration. If unset, a server-specific boot sequence will be used. Valid attributes are:
This key is required with [‘present’].
|
|
List of CD-ROMs. If unset, no CD-ROM devices will be created. Valid attributes are:
If unset, the server will choose an available address; if none is available, the request will fail. ([‘present’])
If unset, the server will choose a adapter with an available connection. If no IDE connections are available, the request will be rejected.
If unset, the server will choose an available connection type. If no IDE connections are available, the request will be rejected.
If unset, the server will choose an available address; if none is available, the request will fail. ([‘present’])
If unset, the server will choose an available unit number on the specified adapter. If there are no available connections on the adapter, the request will be rejected.
If unset, defaults to automatic detection of a suitable host device. ([‘present’])
Accepted value for this field:
This field is optional and it is only relevant when the value of type is ISO_FILE.
If unset, the virtual CD-ROM device will be configured to automatically detect a suitable host device.
Accepted value for this field:
Defaults to false if unset. ([‘present’])
Defaults to false if unset. ([‘present’]) |
|
CPU configuration. If unset, guest-specific default values will be used. Valid attributes are:
The supported range of CPU counts is constrained by the configured guest operating system and virtual hardware version of the virtual machine. If the virtual machine is running, the number of CPU cores may only be increased if hot_add_enabled is true, and may only be decreased if hot_remove_enabled is true. If unset, the value is unchanged. ([‘present’])
If unset, the value is unchanged. ([‘present’])
This field may only be modified if the virtual machine is powered off. If unset, the value is unchanged. ([‘present’])
This field may only be modified if the virtual machine is powered off. If unset, the value is unchanged. ([‘present’]) |
|
Identifier of the datastore on which the virtual machine’s configuration state is stored. If unset, path must also be unset and datastore_path must be set. When clients pass a value of this structure as a parameter, the field must be the id of a resource returned by vmware.vmware_rest.vcenter_datastore_info. |
|
Datastore path for the virtual machine’s configuration file in the format “[datastore name] path”. For example “[storage1] Test-VM/Test-VM.vmx”. If unset, both datastore and path must be set. |
|
Indicates whether all NICs on the destination virtual machine should be disconnected from the newtwork If unset, connection status of all NICs on the destination virtual machine will be the same as on the source virtual machine. Choices:
|
|
Individual disk relocation map. If unset, all disks will migrate to the datastore specified in the datastore field of When clients pass a value of this structure as a parameter, the key in the field map must be the id of a resource returned by vmware.vmware_rest.vcenter_vm_hardware_disk. Valid attributes are:
If unset, the server will choose an available address; if none is available, the request will fail. ([‘present’])
If unset, the server will choose a adapter with an available connection. If no IDE connections are available, the request will be rejected.
If unset, the server will choose an available connection type. If no IDE connections are available, the request will be rejected.
If unset, the server will choose an available address; if none is available, the request will fail. ([‘present’])
If unset, the server will choose an available unit number on the specified adapter. If there are no available connections on the adapter, the request will be rejected.
If unset, the server will choose an available address; if none is available, the request will fail. ([‘present’])
If unset, the server will choose an available unit number on the specified adapter. If there are no available connections on the adapter, the request will be rejected.
If unset, the server will choose an available address; if none is available, the request will fail. ([‘present’])
If unset, the server will choose an available unit number on the specified adapter. If there are no available connections on the adapter, the request will be rejected.
If unset, the virtual disk will not be connected to an existing backing. ([‘present’])
Accepted value for this field:
This field is optional and it is only relevant when the value of type is VMDK_FILE.
If unset, a new VMDK backing will not be created. ([‘present’])
If unset, a name (derived from the name of the virtual machine) will be chosen by the server.
If unset, defaults to a guest-specific capacity.
If unset the default storage policy of the target datastore (if applicable) is applied. Currently a default storage policy is only supported by object based datastores : VVol & vSAN. For non- object datastores, if unset then no storage policy would be associated with the VMDK file. |
|
Set of Disks to Remove. If unset, all disks will be copied. If the same identifier is in disks_to_update InvalidArgument fault will be returned. When clients pass a value of this structure as a parameter, the field must contain the id of resources returned by vmware.vmware_rest.vcenter_vm_hardware_disk. |
|
Map of Disks to Update. If unset, all disks will copied to the datastore specified in the datastore field of If the same identifier is in disks_to_remove InvalidArgument fault will be thrown. When clients pass a value of this structure as a parameter, the key in the field map must be the id of a resource returned by vmware.vmware_rest.vcenter_vm_hardware_disk. |
|
List of floppy drives. If unset, no floppy drives will be created. Valid attributes are:
If unset, defaults to automatic detection of a suitable host device. ([‘present’])
Accepted value for this field:
This field is optional and it is only relevant when the value of type is IMAGE_FILE.
If unset, the virtual floppy drive will be configured to automatically detect a suitable host device.
Defaults to false if unset. ([‘present’])
Defaults to false if unset. ([‘present’]) |
|
Guest customization spec to apply to the virtual machine after the virtual machine is deployed. If unset, the guest operating system is not customized after clone. Valid attributes are:
If unset, no guest customization is performed. ([‘clone’]) |
|
The GuestOS enumerated type defines the valid guest operating system types used for configuring a virtual machine. Required with state=[‘present’] Choices:
|
|
The version enumerated type defines the valid virtual hardware versions for a virtual machine. See https://kb.vmware.com/s/article/1003746 (Virtual machine hardware versions (1003746)). Choices:
|
|
Memory configuration. If unset, guest-specific default values will be used. Valid attributes are:
The supported range of memory sizes is constrained by the configured guest operating system and virtual hardware version of the virtual machine. If the virtual machine is running, this value may only be changed if hot_add_enabled is true, and the new memory size must satisfy the constraints specified by hot_add_increment_size_mib and If unset, the value is unchanged. ([‘present’])
Some guest operating systems may consume more resources or perform less efficiently when they run on hardware that supports adding memory while the machine is running. This field may only be modified if the virtual machine is not powered on. If unset, the value is unchanged. ([‘present’]) |
|
Virtual machine name. If unset, the display name from the virtual machine’s configuration file will be used. |
|
List of Ethernet adapters. If unset, no Ethernet adapters will be created. Valid attributes are:
If unset, UPT will not be enabled on the newly-created virtual Ethernet adapter. ([‘present’])
Workaround for PR1459647 ([‘present’])
If unset, the server will choose an available address when the virtual machine is powered on. ([‘present’])
Defaults to false if unset. ([‘present’])
If unset, the system may try to find an appropriate backing. If one is not found, the request will fail. ([‘present’])
Accepted value for this field:
This field is optional and it is only relevant when the value of type is one of STANDARD_PORTGROUP, DISTRIBUTED_PORTGROUP, or OPAQUE_NETWORK. When clients pass a value of this structure as a parameter, the field must be the id of a resource returned by vmware.vmware_rest.vcenter_network_info.
May be used to specify a port when the network specified on the network field is a static or early binding distributed portgroup. If unset, the port will be automatically assigned to the Ethernet adapter based on the policy embodied by the portgroup type.
Defaults to false if unset. ([‘present’])
Defaults to false if unset. ([‘present’]) |
|
Map of NICs to update. If unset, no NICs will be updated. When clients pass a value of this structure as a parameter, the key in the field map must be the id of a resource returned by vmware.vmware_rest.vcenter_vm_hardware_ethernet. |
|
List of NVMe adapters. If unset, any adapters necessary to connect the virtual machine’s storage devices will be created; this includes any devices that explicitly specify a NVMe host bus adapter, as well as any devices that do not specify a host bus adapter if the guest’s preferred adapter type is NVMe. Valid attributes are:
If unset, the server will choose an available bus number; if none is available, the request will fail. ([‘present’])
If unset, the server will choose an available address when the virtual machine is powered on. ([‘present’]) |
|
List of parallel ports. If unset, no parallel ports will be created. Valid attributes are:
If unset, defaults to automatic detection of a suitable host device. ([‘present’])
Accepted value for this field:
This field is optional and it is only relevant when the value of type is FILE.
If unset, the virtual parallel port will be configured to automatically detect a suitable host device.
Defaults to false if unset. ([‘present’])
Defaults to false if unset. ([‘present’]) |
|
Map of parallel ports to Update. If unset, no parallel ports will be updated. When clients pass a value of this structure as a parameter, the key in the field map must be the id of a resource returned by vmware.vmware_rest.vcenter_vm_hardware_parallel. |
|
Path to the virtual machine’s configuration file on the datastore corresponding to {@link #datastore). If unset, datastore must also be unset and datastore_path must be set. |
|
Virtual machine placement information. If this field is unset, the system will use the values from the source virtual machine. If specified, each field will be used for placement. If the fields result in disjoint placement the operation will fail. If the fields along with the other existing placement of the virtual machine result in disjoint placement the operation will fail. Valid attributes are:
If this field is unset, the virtual machine will stay in the current folder. When clients pass a value of this structure as a parameter, the field must be the id of a resource returned by vmware.vmware_rest.vcenter_folder_info. ([‘clone’, ‘instant_clone’, ‘present’, ‘register’, ‘relocate’])
If this field is unset, the virtual machine will stay in the current resource pool. When clients pass a value of this structure as a parameter, the field must be the id of a resource returned by vmware.vmware_rest.vcenter_resourcepool_info. ([‘clone’, ‘instant_clone’, ‘present’, ‘register’, ‘relocate’])
If host and resource_pool are both specified, resource_pool must belong to host. If host and cluster are both specified, host must be a member of cluster. If this field is unset, if resource_pool is unset, the virtual machine will remain on the current host. if resource_pool is set, and the target is a standalone host, the host is used. if resource_pool is set, and the target is a DRS cluster, a host will be picked by DRS. if resource_pool is set, and the target is a cluster without DRS, InvalidArgument will be thrown. When clients pass a value of this structure as a parameter, the field must be the id of a resource returned by vmware.vmware_rest.vcenter_host_info. ([‘clone’, ‘present’, ‘register’, ‘relocate’])
If cluster and resource_pool are both specified, resource_pool must belong to cluster. If cluster and host are both specified, host must be a member of cluster. If resource_pool or host is specified, it is recommended that this field be unset. When clients pass a value of this structure as a parameter, the field must be the id of a resource returned by vmware.vmware_rest.vcenter_cluster_info. ([‘clone’, ‘present’, ‘register’, ‘relocate’])
If this field is unset, the virtual machine will remain on the current datastore. When clients pass a value of this structure as a parameter, the field must be the id of a resource returned by vmware.vmware_rest.vcenter_datastore_info. ([‘clone’, ‘instant_clone’, ‘present’, ‘relocate’]) |
|
Attempt to perform a power_on after clone. If unset, the virtual machine will not be powered on. Choices:
|
|
List of SATA adapters. If unset, any adapters necessary to connect the virtual machine’s storage devices will be created; this includes any devices that explicitly specify a SATA host bus adapter, as well as any devices that do not specify a host bus adapter if the guest’s preferred adapter type is SATA. Valid attributes are:
If unset, the server will choose an available bus number; if none is available, the request will fail. ([‘present’])
If unset, the server will choose an available address when the virtual machine is powered on. ([‘present’]) |
|
List of SCSI adapters. If unset, any adapters necessary to connect the virtual machine’s storage devices will be created; this includes any devices that explicitly specify a SCSI host bus adapter, as well as any devices that do not specify a host bus adapter if the guest’s preferred adapter type is SCSI. The type of the SCSI adapter will be a guest-specific default type. Valid attributes are:
If unset, the server will choose an available bus number; if none is available, the request will fail. ([‘present’])
If unset, the server will choose an available address when the virtual machine is powered on. ([‘present’])
|
|
List of serial ports. If unset, no serial ports will be created. Valid attributes are:
If unset, defaults to false. ([‘present’])
If unset, defaults to automatic detection of a suitable host device. ([‘present’])
Accepted value for this field:
This field is optional and it is only relevant when the value of type is FILE.
If unset, the virtual serial port will be configured to automatically detect a suitable host device.
This field is optional and it is only relevant when the value of type is one of PIPE_SERVER or PIPE_CLIENT.
If unset, defaults to false.
This field is optional and it is only relevant when the value of type is one of NETWORK_SERVER or NETWORK_CLIENT.
If unset, no proxy service should be used.
Defaults to false if unset. ([‘present’])
Defaults to false if unset. ([‘present’]) |
|
Map of serial ports to Update. If unset, no serial ports will be updated. When clients pass a value of this structure as a parameter, the key in the field map must be the id of a resource returned by vmware.vmware_rest.vcenter_vm_hardware_serial. |
|
Timeout settings for client session. The maximal number of seconds for the whole operation including connection establishment, request sending and response. The default value is 300s. |
|
Virtual machine to InstantClone from. When clients pass a value of this structure as a parameter, the field must be the id of a resource returned by vmware.vmware_rest.vcenter_vm_info. Required with state=[‘clone’, ‘instant_clone’] |
|
Choices:
|
|
The storage_policy_spec structure contains information about the storage policy that is to be associated with the virtual machine home (which contains the configuration and log files). If unset the datastore default storage policy (if applicable) is applied. Currently a default storage policy is only supported by object datastores : VVol and vSAN. For non-object datastores, if unset then no storage policy would be associated with the virtual machine home. Required with state=[‘present’] Valid attributes are:
When clients pass a value of this structure as a parameter, the field must be the id of a resource returned by vmware.vmware_rest.vcenter_storage_policies_info. ([‘present’]) This key is required with [‘present’]. |
|
The hostname or IP address of the vSphere vCenter If the value is not specified in the task, the value of environment variable |
|
The vSphere vCenter password If the value is not specified in the task, the value of environment variable |
|
You can use this optional parameter to set the location of a log file. This file will be used to record the HTTP REST interaction. The file will be stored on the host that runs the module. If the value is not specified in the task, the value of environment variable |
|
The vSphere vCenter username 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:
|
|
Identifier of the virtual machine to be unregistered. The parameter must be the id of a resource returned by vmware.vmware_rest.vcenter_vm_info. Required with state=[‘absent’, ‘relocate’, ‘unregister’] |
Notes
Note
Tested on vSphere 7.0.3
Examples
- name: Create a VM
vmware.vmware_rest.vcenter_vm:
placement:
cluster: "{{ lookup('vmware.vmware_rest.cluster_moid', '/my_dc/host/my_cluster') }}"
datastore: "{{ lookup('vmware.vmware_rest.datastore_moid', '/my_dc/datastore/rw_datastore') }}"
folder: "{{ lookup('vmware.vmware_rest.folder_moid', '/my_dc/vm') }}"
resource_pool: "{{ lookup('vmware.vmware_rest.resource_pool_moid', '/my_dc/host/my_cluster/Resources') }}"
name: test_vm1
guest_OS: RHEL_7_64
hardware_version: VMX_11
memory:
hot_add_enabled: true
size_MiB: 1024
register: my_vm
- name: Create a VM
vmware.vmware_rest.vcenter_vm:
placement:
cluster: "{{ lookup('vmware.vmware_rest.cluster_moid', '/my_dc/host/my_cluster') }}"
datastore: "{{ lookup('vmware.vmware_rest.datastore_moid', '/my_dc/datastore/local') }}"
folder: "{{ lookup('vmware.vmware_rest.folder_moid', '/my_dc/vm') }}"
resource_pool: "{{ lookup('vmware.vmware_rest.resource_pool_moid', '/my_dc/host/my_cluster/Resources') }}"
name: test_vm1
guest_OS: RHEL_7_64
hardware_version: VMX_11
memory:
hot_add_enabled: true
size_MiB: 1024
disks:
- type: SATA
backing:
type: VMDK_FILE
vmdk_file: '[local] test_vm1/{{ disk_name }}.vmdk'
- type: SATA
new_vmdk:
name: second_disk
capacity: 32000000000
cdroms:
- type: SATA
sata:
bus: 0
unit: 2
nics:
- backing:
type: STANDARD_PORTGROUP
network: "{{ lookup('vmware.vmware_rest.network_moid', '/my_dc/network/VM Network') }}"
register: my_vm
- name: Create a content library based on a DataStore
vmware.vmware_rest.content_locallibrary:
name: my_library_on_datastore
description: automated
publish_info:
published: true
authentication_method: NONE
storage_backings:
- datastore_id: "{{ lookup('vmware.vmware_rest.datastore_moid', '/my_dc/datastore/local') }}"
type: DATASTORE
state: present
register: nfs_lib
- name: Get the list of items of the NFS library
vmware.vmware_rest.content_library_item_info:
library_id: '{{ nfs_lib.id }}'
register: lib_items
- name: Use the name to identify the item
set_fact:
my_template_item: "{{ lib_items.value | selectattr('name', 'equalto', 'golden-template')|first }}"
- name: Deploy a new VM based on the template
vmware.vmware_rest.vcenter_vmtemplate_libraryitems:
name: vm-from-template
library: '{{ nfs_lib.id }}'
template_library_item: '{{ my_template_item.id }}'
placement:
cluster: "{{ lookup('vmware.vmware_rest.cluster_moid', '/my_dc/host/my_cluster') }}"
folder: "{{ lookup('vmware.vmware_rest.folder_moid', '/my_dc/vm') }}"
resource_pool: "{{ lookup('vmware.vmware_rest.resource_pool_moid', '/my_dc/host/my_cluster/Resources') }}"
state: deploy
register: my_new_vm
- name: Retrieve all the details about the new VM
vmware.vmware_rest.vcenter_vm:
vm: '{{ my_new_vm.value }}'
register: my_new_vm_info
- name: Create an instant clone of a VM
vmware.vmware_rest.vcenter_vm:
placement:
datastore: "{{ lookup('vmware.vmware_rest.datastore_moid', '/my_dc/datastore/local') }}"
folder: "{{ lookup('vmware.vmware_rest.folder_moid', '/my_dc/vm') }}"
resource_pool: "{{ lookup('vmware.vmware_rest.resource_pool_moid', '/my_dc/host/my_cluster/Resources') }}"
source: '{{ my_vm.id }}'
name: test_vm2
state: instant_clone
register: my_instant_clone
- name: Create a clone of a VM
vmware.vmware_rest.vcenter_vm:
placement:
datastore: "{{ lookup('vmware.vmware_rest.datastore_moid', '/my_dc/datastore/local') }}"
folder: "{{ lookup('vmware.vmware_rest.folder_moid', '/my_dc/vm') }}"
resource_pool: "{{ lookup('vmware.vmware_rest.resource_pool_moid', '/my_dc/host/my_cluster/Resources') }}"
source: '{{ my_vm.id }}'
name: test_vm3
state: clone
register: my_clone_vm
- name: Build a list of all the clusters
vmware.vmware_rest.vcenter_cluster_info:
register: all_the_clusters
- name: Retrieve details about the first cluster
vmware.vmware_rest.vcenter_cluster_info:
cluster: '{{ all_the_clusters.value[0].cluster }}'
register: my_cluster_info
- name: Build a list of all the folders with the type VIRTUAL_MACHINE and called vm
vmware.vmware_rest.vcenter_folder_info:
filter_type: VIRTUAL_MACHINE
filter_names:
- vm
register: my_folders
- name: Set my_virtual_machine_folder
ansible.builtin.set_fact:
my_virtual_machine_folder: '{{ my_folders.value|first }}'
- name: Create a VM
vmware.vmware_rest.vcenter_vm:
placement:
cluster: '{{ my_cluster_info.id }}'
datastore: "{{ lookup('vmware.vmware_rest.datastore_moid', '/my_dc/datastore/local') }}"
folder: '{{ my_virtual_machine_folder.folder }}'
resource_pool: '{{ my_cluster_info.value.resource_pool }}'
name: test_vm1
guest_OS: DEBIAN_7_64
hardware_version: VMX_10
memory:
hot_add_enabled: true
size_MiB: 1024
register: my_vm
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
---|---|
moid of the resource Returned: On success Sample: |
|
Create an instant clone of a VM Returned: On success Sample: |