vmware.vmware._vm_stub module – This is a partial implementation of a module. It is not intended for use.

Note

This module is part of the vmware.vmware collection (version 2.4.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_stub.

Synopsis

  • This module is currently in development. It is not intended for public use.

  • Although this module will attempt to validate your configuration, it is not feasible to validate all possible combinations of parameters. You may encounter errors when starting VMs with invalid configurations.

  • Error messages may not always be very helpful. Checking the vCenter task logs or VM edit settings page may have additional messages.

Parameters

Parameter

Comments

allow_power_cycling

boolean

Whether to allow the VM to be powered off and on when required by the changes detected by the module.

For example, if the module detects CPU changes and hot add is not enabled, you can enable this parameter to allow the VM to be powered off, updated, and then powered on automatically.

If this is set to false, a failure will occur if the VM needs to be powered off before changes can be applied.

A “hard” power off is performed when the VM is powered off. If you do not want this, you could use this module in check mode, vmware.vmware.vm_powerstate module to power off the VM if needed, and then this module again to apply the changes .

Choices:

  • false ← (default)

  • true

cluster

aliases: cluster_name

string

The cluster in which to place the VM.

This is required when creating a new VM.

You cannot use this module to modify the placement of a VM once it has been created. This parameter is ignored if the VM already exists.

cpu

dictionary

Options related to CPU resource allocation.

This is required when creating a new VM.

cores

integer

The number of CPU cores to add to the VM.

This is required when creating a new VM.

cores_per_socket

integer

The number of cores per socket to use for the VM.

If this is defined, cpu.cores must be a multiple of cpu.cores_per_socket.

enable_hot_add

boolean

Whether to enable CPU hot add. This allows you to add CPUs to the VM while it is powered on.

Choices:

  • false

  • true

enable_hot_remove

boolean

Whether to enable CPU hot remove. This allows you to remove CPUs from the VM while it is powered on.

Choices:

  • false

  • true

enable_performance_counters

boolean

Whether to enable Virtual CPU Performance Monitoring Counters (VPMC).

Choices:

  • false

  • true

limit

integer

The maximum amount of CPU resources the VM can use.

reservation

integer

The amount of CPU resource that is guaranteed available to the virtual machine.

shares

integer

The custom number of shares of CPU allocated to this virtual machine.

You can set cpu.shares_level and omit this parameter to use a pre-defined value.

If this is defined, cpu.shares_level will be ignored.

shares_level

string

The allocation level of CPU resources for the virtual machine.

If cpu.shares is defined, cpu.shares_level will automatically be set to ‘custom’ and this parameter will be ignored.

Choices:

  • "low"

  • "normal"

  • "high"

datacenter

aliases: datacenter_name

string

The datacenter in which to place the VM.

This is required when creating a new VM.

You cannot use this module to modify the placement of a VM once it has been created. This parameter is ignored if the VM already exists.

datastore

string

The datastore on which to place the VM.

This is required when creating a new VM, or when creating new disks.

You cannot use this module to modify the placement of a VM once it has been created. This parameter is ignored if the VM or disk already exists.

datastore_cluster

string

The datastore cluster on which to place the VM.

This is required when creating a new VM.

This is required when creating a new VM, or when creating new disks.

You cannot use this module to modify the placement of a VM once it has been created. This parameter is ignored if the VM or disk already exists.

disks

list / elements=dictionary

Disks to manage on the VM.

If a disk is not specified, it will be removed from the VM.

Reducing disk size is not supported.

At least one disk is required when creating a new VM.

Controllers (except IDE) referenced by the disks[].device_node parameter must be configured in the corresponding controller section.

device_node

string / required

Specifies the controller, bus, and unit number of the disk.

The format of this value should be like ‘SCSI(0:0)’ or ‘IDE(0:1)’.

Disk controllers referenced in this attribute must be configured in the corresponding controller section. The exception to this are the two IDE controllers, which are automatically added to the VM.

mode

string

The mode of the disk.

Choices:

  • "persistent" ← (default)

  • "independent_persistent"

  • "independent_nonpersistent"

provisioning

string

The provisioning type of the disk.

Choices:

  • "thin" ← (default)

  • "thick"

  • "eagerzeroedthick"

size

string / required

The size of the disk.

The format of this value should be like ‘100gb’ or ‘100mb’.

Supported units are ‘kb’, ‘mb’, ‘gb’, ‘tb’.

esxi_host

string

The ESXi host on which to place the VM.

This is required when creating a new VM.

You cannot use this module to modify the placement of a VM once it has been created. This parameter is ignored if the VM already exists.

folder

aliases: vm_folder

string

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.

guest_id

string

The guest ID of the VM.

Guest IDs are pre-defined by VMware. For example see https://developer.broadcom.com/xapis/vsphere-web-services-api/latest/vim.vm.GuestOsDescriptor.GuestOsIdentifier.html

This is required when creating a new VM.

hostname

string

The hostname or IP address of the vSphere vCenter server.

If the value is not specified in the task, the value of environment variable VMWARE_HOST will be used instead.

memory

dictionary

Options related to memory resource allocation.

This is required when creating a new VM.

enable_hot_add

boolean

Whether to enable memory hot add. This allows you to add memory to the VM while it is powered on.

Choices:

  • false

  • true

limit

integer

The maximum amount of memory the VM can use.

reservation

integer

The amount of memory resource that is guaranteed available to the VM.

Only one of memory.reservation or memory.reserve_all_memory can be set.

This value must be less than or equal to the VMs total memory in MB.

reserve_all_memory

boolean

Whether to reserve (lock) all memory allocated for the VM.

Only one of memory.reservation or memory.reserve_all_memory can be set.

This will cause VMware to reserve all memory allocated for the VM, meaning that the memory will not be available to other VMs even if this VM is not actively using it.

Choices:

  • false

  • true

shares

integer

The custom number of shares of memory allocated to this virtual machine.

You can set memory.shares_level and omit this parameter to use a pre-defined value.

If this is defined, memory.shares_level will be ignored.

shares_level

string

The allocation level of memory resources for the virtual machine.

If memory.shares is defined, memory.shares_level will automatically be set to ‘custom’ and this parameter will be ignored.

Choices:

  • "low"

  • "normal"

  • "high"

size_mb

integer

The amount of memory to add to the VM.

Memory cannot be changed while the VM is powered on, unless memory hot add is already enabled.

This parameter is required when creating a new VM.

moid

string

Managed Object ID of the instance to manage if known, this is a unique identifier only within a single vCenter instance.

This is required if name or uuid is not supplied.

name

string

Name of the virtual machine to work with.

Virtual machine names in vCenter are not necessarily unique, which may be problematic, see name_match.

This is required when the VM does not exist, or if moid or uuid is not supplied.

name_match

string

If multiple virtual machines matching the name, use the first or last found.

Choices:

  • "first" ← (default)

  • "last"

network_adapter_remove_unmanaged

boolean

Whether to remove network adapters that are not specified in the network_adapters parameter.

If this is set to true, any network adapters that are not specified in the network_adapters parameter will be removed.

If this is set to false, the module will ignore network adapters beyond those listed in the network_adapters parameter.

Choices:

  • false ← (default)

  • true

network_adapters

list / elements=dictionary

A list of network adapters to manage on the VM.

Due to limitations in the VMware API, you cannot change the type of a network adapter once it has been created using this module.

The network adapter types defined in this parameter must match the types of any existing adapters on the VM, in the same order that they are specified. For example, the first adapter in this list must have the same type as the first adapter attached to the VM (if one exists).

Any adapters in this list that do not exist on the VM will be created.

Portgroups must already exist; this module does not create them.

adapter_type

string

The type of the adapter.

This is required when creating a new adapter.

Note that this cannot be changed once the adapter has been created.

Choices:

  • "e1000"

  • "e1000e"

  • "pcnet32"

  • "vmxnet2"

  • "vmxnet3"

  • "sriov"

connect_at_power_on

boolean

Specifies whether or not to connect the network adapter when the virtual machine starts.

Choices:

  • false

  • true

connected

boolean

Indicates whether the NIC is currently connected.

Choices:

  • false

  • true

limit

integer

The maximum amount of network resources the network adapter can use.

The unit is Mbps.

mac_address

string

The MAC address of the network adapter.

If you want to use a generated or automatic mac address, set this to ‘automatic’.

If not specified and this is a new adapter, a random MAC address will be assigned.

If not specified and this is an existing adapter, the MAC address will not be changed.

network

string / required

The name or MOID of the standard or distributed virtual portgroup for this interface.

The portgroup must already exist.

reservation

integer

The amount of network resources reserved for the network adapter.

The unit is Mbps.

shares

integer

The percentage of network resources allocated to the network adapter.

If setting this, it should be between 0 and 100.

Only one of network_adapters[].shares or network_adapters[].shares_level can be set.

shares_level

string

The pre-defined allocation level of network resources for the network adapter.

Only one of network_adapters[].shares or network_adapters[].shares_level can be set.

Choices:

  • "low"

  • "normal"

  • "high"

nvme_controllers

list / elements=dictionary

NVMe device controllers to manage on the VM.

If a controller is not specified, it will be removed from the VM.

You may only specify four NVMe controllers per VM.

Controllers are added to the VM in the order they are specified. For example, the first controller specified will be assigned bus 0, the second controller will be assigned bus 1, etc.

bus_sharing

string

The bus sharing mode of the controller.

Choices:

  • "noSharing" ← (default)

  • "exclusive"

password

aliases: pass, pwd

string

The password of the vSphere vCenter server.

If the value is not specified in the task, the value of environment variable VMWARE_PASSWORD will be used instead.

port

integer

The port number of the vSphere vCenter server.

If the value is not specified in the task, the value of environment variable VMWARE_PORT will be used instead.

Default: 443

proxy_host

string

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 VMWARE_PROXY_HOST will be used instead.

proxy_port

integer

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 VMWARE_PROXY_PORT will be used instead.

resource_pool

string

The resource pool in which to place the VM.

This is required when creating a new VM.

You cannot use this module to modify the placement of a VM once it has been created. This parameter is ignored if the VM already exists.

sata_controller_count

integer

The number of SATA controllers to add to the VM.

Since there are no configurable options for SATA controllers, you just need to specify the number of controllers to have on the VM.

You may only specify four SATA controllers per VM.

Default: 0

scsi_controllers

list / elements=dictionary

SCSI device controllers to manage on the VM.

If a controller is not specified, it will be removed from the VM.

You may only specify four SCSI controllers per VM.

Controllers are added to the VM in the order they are specified. For example, the first controller specified will be assigned bus 0, the second controller will be assigned bus 1, etc.

bus_sharing

string

The bus sharing mode of the controller.

Choices:

  • "noSharing" ← (default)

  • "exclusive"

controller_type

string / required

The type of the controller.

Choices:

  • "buslogic"

  • "lsiLogic"

  • "lsiLogicSAS"

  • "pvscsi"

  • "virtio"

state

string

Whether to ensure the VM is present or absent.

Choices:

  • "present" ← (default)

  • "absent"

timeout

integer

The timeout in seconds for the module to wait for the VM to be created or updated.

Default: 600

usb_controllers

list / elements=dictionary

USB device controllers to manage on the VM.

If a controller is not specified, it will be removed from the VM.

You may only specify two USB controllers per VM.

Controllers are added to the VM in the order they are specified. For example, the first controller specified will be assigned bus 0, the second controller will be assigned bus 1, etc.

controller_type

string

The type of the controller.

Choices:

  • "usb2"

  • "usb3" ← (default)

use_instance_uuid

boolean

Whether to use the VMware instance UUID rather than the BIOS UUID.

Choices:

  • false ← (default)

  • true

username

aliases: admin, user

string

The username of the vSphere vCenter server.

If the value is not specified in the task, the value of environment variable VMWARE_USER will be used instead.

uuid

string

UUID of the instance to manage if known, this is VMware’s unique identifier.

This is required if name or moid is not supplied.

validate_certs

boolean

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.

Choices:

  • false

  • true ← (default)

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’

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

vm

dictionary

Information about the target VM

Returned: On success

Sample: {"moid": "vm-79828,", "name": "test-d9c1-vm"}

Authors

  • Ansible Cloud Team (@ansible-collections)