vmware.vmware.moid_from_path lookup – Look up MoID for vSphere objects based on the inventory path
Note
This lookup plugin is part of the vmware.vmware collection (version 2.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.
To use it in a playbook, specify: vmware.vmware.moid_from_path.
Synopsis
Returns Managed Object Reference (MoID) of the vSphere object contained in the specified path.
Multiple objects can be returned if the path ends in slash, indicating that the path is a container and its contents should be queried.
Terms
Parameter |
Comments |
|---|---|
vSPhere inventory path to the object(s) to look up. Inventory paths are unique for objects in vSphere. The format should be ‘/<datacenter>/<folder type>/….’, where folder type is one of vm, host, network, or datastore. If the path ends in a slash, the path is treated as a container and objects inside of the container are returned. If the path ends in a slash, the return value will be a string of comma separated MoIDs. You can return a list with `wantlist=true` |
Keyword parameters
This describes keyword parameters of the lookup. These are the values key1=value1, key2=value2 and so on in the following
examples: lookup('vmware.vmware.moid_from_path', key1=value1, key2=value2, ...) and query('vmware.vmware.moid_from_path', key1=value1, key2=value2, ...)
Parameter |
Comments |
|---|---|
If true, the plugin will raise a failure if the specified path cannot be found in vCenter. If false, the plugin silently continues and returns nothing if the specified path does not exist. Choices:
|
|
The hostname or IP address of the vSphere vCenter server. If the value is not specified in the task, the value of environment variable Configuration:
|
|
The password of the vSphere vCenter server. If the value is not specified in the task, the value of environment variable Configuration:
|
|
The port number of the vSphere vCenter server. If the value is not specified in the task, the value of environment variable Default: Configuration:
|
|
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 Configuration:
|
|
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 Configuration:
|
|
Limits the types of objects to include in the search results. If this not supplied and the inventory path is a container, all types of objects in the container will be included. This is only used when the search path ends in a slash (/). Choices:
|
|
The username of the vSphere vCenter server. If the value is not specified in the task, the value of environment variable Configuration:
|
|
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:
Configuration:
|
|
If true, the plugin will return a list instead of a string. If multiple objects are found and wantlist is false, the values are returned as a comma separated string. Choices:
|
Notes
Note
When keyword and positional parameters are used together, positional parameters must be listed before keyword parameters:
lookup('vmware.vmware.moid_from_path', term1, term2, key1=value1, key2=value2)andquery('vmware.vmware.moid_from_path', term1, term2, key1=value1, key2=value2)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’
Examples
#
#
# The examples below assume you have a datacenter named 'my_dc' and a cluster named 'my_cluster'.
# Replace these values as needed for your environment.
#
#
#
# Authentication / Connection Arguments
#
# You can explicitly set the connection arguments in each lookup. This may be clearer for some use cases
- name: Pass In Connection Arguments Explicitly
ansible.builtin.debug:
msg: >-
{{ lookup('vmware.vmware.moid_from_path', '/my_dc/host/my_cluster',
vcenter_hostname="vcenter.test",
vcenter_username="[email protected]",
vcenter_password="1234") }}
# Alternatively, you can add the connection arguments to a dictionary variable, and then pass that variable to the
# lookup plugins. This makes the individual lookup plugin calls simpler
- name: Example Playbook
hosts: all
vars:
connection_args:
vcenter_hostname: "vcenter.test"
vcenter_username: "[email protected]"
vcenter_password: "1234"
tasks:
# Add more tasks or lookups as needed, referencing the same connection_args variable
- name: Lookup MoID of the object
ansible.builtin.debug:
msg: "{{ lookup('vmware.vmware.moid_from_path', '/my_dc/host/my_cluster', **connection_args) }}"
# Finally, you can also leverage the environment variables associated with each connection arg, and avoid passing
# extra args to the lookup plugins. The environment variables must be exposed on the Ansible controller. You cannot
# set them in the playbook
- name: Use a lookup plugin with VMWARE_* environment variables set
ansible.builtin.debug:
msg: "{{ lookup('vmware.vmware.moid_from_path', '/my_dc/host/my_cluster') }}"
#
# Search Path Examples
#
# There are four key folder types, which contain a subset of vSphere types
# host - ESXi, clusters, resource pools, folders
# network - network, folders
# datastore - datastores, folders
# vm - VMs, folders
# Folder paths should be /<datacenter name>/<folder type>/.....
- name: Lookup Datacenter 'my_dc'
ansible.builtin.debug:
msg: "{{ lookup('vmware.vmware.moid_from_path', '/my_dc') }}"
- name: Lookup All Datacenters
ansible.builtin.debug:
msg: "{{ lookup('vmware.vmware.moid_from_path', '/') }}"
- name: Lookup Cluster Named 'my_cluster' in Datacenter 'my_dc'
ansible.builtin.debug:
msg: "{{ lookup('vmware.vmware.moid_from_path', '/my_dc/host/my_cluster') }}"
- name: Lookup All Clusters In Datacenter 'my_dc'
ansible.builtin.debug:
msg: "{{ lookup('vmware.vmware.moid_from_path', '/my_dc/host/', type='cluster') }}"
- name: Lookup VM Named 'my_vm' in Datacenter 'my_dc', folder 'production'
ansible.builtin.debug:
msg: "{{ lookup('vmware.vmware.moid_from_path', '/my_dc/vm/production/my_vm') }}"
- name: Lookup All VMs in Datacenter 'my_dc', folder 'production'
ansible.builtin.debug:
msg: "{{ lookup('vmware.vmware.moid_from_path', '/my_dc/vm/production/', type='vm') }}"
- name: Lookup Datastore Named 'my_ds' in Datacenter 'my_dc'
ansible.builtin.debug:
msg: "{{ lookup('vmware.vmware.moid_from_path', '/my_dc/datastore/my_ds') }}"
- name: Lookup Network Named 'my_net' in Datacenter 'my_dc'
ansible.builtin.debug:
msg: "{{ lookup('vmware.vmware.moid_from_path', '/my_dc/network/my_net') }}"
- name: Lookup All Resource Pools in Datacenter 'my_dc', cluster 'my_cluser' (this is not recursive!)
ansible.builtin.debug:
msg: "{{ lookup('vmware.vmware.moid_from_path', '/my_dc/host/my_cluster/', type='resource_pool', wantlist=true) }}"
- name: Lookup All ESXi Hosts in Datacenter 'my_dc', cluster 'my_cluser' (this is not recursive!)
ansible.builtin.debug:
msg: "{{ lookup('vmware.vmware.moid_from_path', '/my_dc/host/my_cluster/', type='host', wantlist=true) }}"
#
# Usage in Playbooks
#
#
# The lookup plugin can be used to simplify your playbook. Here is an example of how you might use it.
#
# Without the lookup, this takes two modules which both run on the remote host. This can slow down execution
# and adds extra steps to the playbook:
- name: Retrieve details about a cluster named 'my_cluster'
vmware.vmware_rest.vcenter_cluster_info:
names:
- my_cluster
register: my_cluster_info
- name: Create a VM
vmware.vmware_rest.vcenter_vm:
placement:
cluster: "{{ my_cluster_info.value[0].cluster }}"
name: test_vm1
guest_OS: RHEL_7_64
hardware_version: VMX_11
memory:
size_MiB: 1024
disks:
- type: SATA
new_vmdk:
name: first_disk
capacity: 3200
# With the lookup, playbooks are shorter, quicker, and more intuitive:
- name: Create a VM
vmware.vmware_rest.vcenter_vm:
placement:
cluster: "{{ lookup('vmware.vmware.moid_from_path', '/my_dc/host/my_cluster') }}"
name: test_vm1
guest_OS: RHEL_7_64
hardware_version: VMX_11
memory:
size_MiB: 1024
disks:
- type: SATA
new_vmdk:
name: first_disk
capacity: 3200
Return Value
Key |
Description |
|---|---|
MoID of the vSphere cluster object Returned: success Sample: |