vmware.vmware.vms inventory – Create an inventory containing VMware VMs

Note

This inventory plugin is part of the vmware.vmware collection (version 1.10.1).

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. You need further requirements to be able to use this inventory plugin, see Requirements for details.

To use it in a playbook, specify: vmware.vmware.vms.

Synopsis

  • Create a dynamic inventory of VMware VMs from a vCenter or ESXi environment.

  • Uses any file which ends with vms.yml, vms.yaml, vmware_vms.yml, or vmware_vms.yaml as a YAML configuration file.

Requirements

The below requirements are needed on the local controller node that executes this inventory.

  • vSphere Automation SDK (when gather_tags is True)

Parameters

Parameter

Comments

cache

boolean

Toggle to enable/disable the caching of the inventory’s source data, requires a cache plugin setup to work.

Choices:

  • false ← (default)

  • true

Configuration:

cache_connection

string

Cache connection data or path, read cache plugin documentation for specifics.

Configuration:

cache_plugin

string

Cache plugin to use for the inventory’s source data.

Default: "memory"

Configuration:

cache_prefix

string

Prefix to use for cache plugin files/tables.

Default: "ansible_inventory_"

Configuration:

cache_timeout

integer

Cache duration in seconds.

Default: 3600

Configuration:

compose

dictionary

Create vars from jinja2 expressions.

Default: {}

flatten_nested_properties

boolean

If true, flatten any nested properties into their dot notation names.

For example ‘summary[“runtime”][“powerState”]’ would become “summary.runtime.powerState”

Choices:

  • false ← (default)

  • true

gather_tags

boolean

If true, gather any tags attached to the associated VMs

Requires ‘vSphere Automation SDK’ library to be installed on the Ansible controller machine.

Choices:

  • false ← (default)

  • true

group_by_paths

boolean

If true, groups will be created based on the VMware object’s paths.

Paths will be sanitized to match Ansible group name standards. For example, any slashes or dashes in the paths will be replaced by underscores in the group names.

A group is created for each step down in the path, with the group from the step above containing subsequent groups.

For example, a path /DC-01/vms/Cluster will create groups ‘DC_01’ which contains group ‘DC_01_vms’ which contains group ‘DC_01_vms_Cluster’

Choices:

  • false ← (default)

  • true

group_by_paths_prefix

string

If group_by_paths is true, set this variable if you want to add a prefix to any groups created based on paths.

By default, no prefix is added to the group names.

Default: ""

groups

dictionary

Add hosts to group based on Jinja2 conditionals.

Default: {}

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.

Configuration:

hostnames

list / elements=string

A list of templates evaluated in order to compose inventory_hostname.

Each value in the list should be a jinja template. You can see the examples section for more details.

Templates that result in an empty string or None value are ignored and the next template is evaluated.

You can use hostvars such as properties specified in properties as variables in the template.

Default: ["name"]

keyed_groups

list / elements=dictionary

Use the values of the VMware object properties or other hostvars to create and populate groups.

Default: [{"key": "config.guestId", "separator": ""}, {"key": "summary.runtime.powerState", "separator": ""}]

default_value

string

added in ansible-core 2.12

The default value when the host variable’s value is an empty string.

This option is mutually exclusive with keyed_groups[].trailing_separator.

key

string

The key from input dictionary used to generate groups.

parent_group

string

parent group for keyed group.

prefix

string

A keyed group name will start with this prefix.

Default: ""

separator

string

separator used to build the keyed group name.

Default: "_"

trailing_separator

boolean

added in ansible-core 2.12

Set this option to false to omit the keyed_groups[].separator after the host variable when the value is an empty string.

This option is mutually exclusive with keyed_groups[].default_value.

Choices:

  • false

  • true ← (default)

leading_separator

boolean

added in ansible-core 2.11

Use in conjunction with keyed_groups.

By default, a keyed group that does not have a prefix or a separator provided will have a name that starts with an underscore.

This is because the default prefix is "" and the default separator is "_".

Set this option to false to omit the leading underscore (or other separator) if no prefix is given.

If the group name is derived from a mapping the separator is still used to concatenate the items.

To not use a separator in the group name at all, set the separator for the keyed group to an empty string instead.

Choices:

  • false

  • true ← (default)

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.

Configuration:

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

Configuration:

properties

list / elements=string

Specify a list of VMware schema properties associated with the host to collect and return as hostvars.

Each value in the list can be a path to a specific property in a VMware object or a path to a collection of properties.

Please make sure that if you use a property in another parameter that it is included in this option.

Some properties are always returned, such as name, customValue, and summary.runtime.powerState

Use all to return all properties available for the VMware object.

Default: ["name", "config.cpuHotAddEnabled", "config.cpuHotRemoveEnabled", "config.instanceUuid", "config.hardware.numCPU", "config.template", "config.name", "config.uuid", "guest.hostName", "guest.ipAddress", "guest.guestId", "guest.guestState", "runtime.maxMemoryUsage", "customValue", "summary.runtime.powerState", "config.guestId"]

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.

Configuration:

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.

Configuration:

proxy_protocol

aliases: protocol

string

The proxy connection protocol to use.

This option is used if the correct proxy protocol cannot be automatically determined.

Choices:

  • "http"

  • "https" ← (default)

sanitize_property_names

boolean

If true, sanitize VMware object property names so they can safely be referenced within Ansible playbooks.

This option also transforms property names to snake case. For example, powerState would become power_state.

Choices:

  • false ← (default)

  • true

search_paths

list / elements=string

Specify a list of paths that should be searched recursively for VMware objects.

This effectively allows you to only include objects in certain datacenters, clusters, or folders.

Filtering is done before the initial object gathering query. If you have a large number of VMware objects, specifying a subset of paths to search can help speed up the inventory plugin.

The default value is an empty list, which means all paths (i.e. all datacenters) will be searched.

Default: []

strict

boolean

If yes make invalid entries a fatal error, otherwise skip and continue.

Since it is possible to use facts in the expressions they might not always be available and we ignore those errors by default.

Choices:

  • false ← (default)

  • true

use_extra_vars

boolean

added in ansible-core 2.11

Merge extra vars into the available variables for composition (highest precedence).

Choices:

  • false ← (default)

  • true

Configuration:

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.

Configuration:

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)

Configuration:

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. Example: ‘export REQUESTS_CA_BUNDLE=/path/to/your/ca_bundle.pem’

  • Inventories are not finalized at this stage, so the auto populated all and ungrouped groups will only reflect what previous inventory sources explicitly added to them.

  • Runtime ‘magic variables’ are not available during inventory construction. For example, groups and hostvars do not exist yet.

Examples

# Below are examples of inventory configuration files that can be used with this plugin.
# To test these and see the resulting inventory, save the snippet in a file named hosts.vmware_vms.yml and run:
# ansible-inventory -i hosts.vmware_vms.yml --list


# Simple configuration with in-file authentication parameters
plugin: vmware.vmware.vms
hostname: 10.65.223.31
username: [email protected]
password: Esxi@123$%
validate_certs: false


# More complex configuration. Authentication parameters are assumed to be set as environment variables.
plugin: vmware.vmware.vms
# Create groups based on host paths
group_by_paths: true
# Create a group with VMs that support CPU hot add using the cpuHotAddEnabled property,
# and groups based on VMware tools
properties: ["name", "config", "guest"]
groups:
  cpu_hot_add_enabled: config.cpuHotAddEnabled
keyed_groups:
  - key: guest.toolsStatus
    separator: ""
  - key: guest.toolsRunningStatus
    separator: ""
# Only gather VMs found in certain paths
search_paths:
  - /DC1/vm/ClusterA
  - /DC1/vm/ClusterC
  - /DC3
# Set custom inventory hostnames based on attributes
hostnames:
  - "'VM - ' + name + ' - ' + guest.ipAddress"
  - "'VM - ' + name + ' - ' + config.instanceUuid"
# Use compose to set variables for the hosts that we find
compose:
  ansible_user: "'root'"
  ansible_connection: "'ssh'"
  # assuming path is something like /MyDC/vms/MyCluster
  datacenter: "(path | split('/'))[1]"
  cluster: "(path | split('/'))[3]"


# Use Tags and Tag Categories to create groups
plugin: vmware.vmware.vms
gather_tags: true
keyed_groups:
  - key: tags_by_category.OS
    prefix: "vmware_tag_os_category_"
    separator: ""

# customizing hostnames based on VM's FQDN. The second hostnames template acts as a fallback mechanism.
plugin: vmware.vmware.vms
hostnames:
  - 'config.name+"."+guest.ipStack.0.dnsConfig.domainName'
  - 'config.name'
properties:
  - 'config.name'
  - 'config.guestId'
  - 'guest.hostName'
  - 'guest.ipAddress'
  - 'guest.guestFamily'
  - 'guest.ipStack'

# Select a specific IP address for use by ansible when multiple NICs are present on the VM
plugin: vmware.vmware.vms
compose:
  # Set the IP address used by ansible to one that starts by 10.42. or 10.43.
  ansible_host: >-
    guest.net
    | selectattr('ipAddress')
    | map(attribute='ipAddress')
    | flatten
    | select('match', '^10.42.*|^10.43.*')
    | list
    | first
  properties:
    - guest.net

# Group hosts using Jinja2 conditionals
plugin: vmware.vmware.vms
properties:
  - 'config.datastoreUrl'
groups:
  slow_storage: "'Nas01' in config.datastoreUrl[0].name"
  fast_storage: "'SSD' in config.datastoreUrl[0].name"

Authors

  • Ansible Cloud Team (@ansible-collections)

Hint

Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.