vmware.vmware_rest.vm_moid lookup – Look up MoID for vSphere vm objects using vCenter REST API
Note
This lookup plugin 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 lookup plugin,
see Requirements for details.
To use it in a playbook, specify: vmware.vmware_rest.vm_moid.
New in vmware.vmware_rest 2.1.0
Synopsis
Returns Managed Object Reference (MoID) of the vSphere vm object contained in the specified path.
Requirements
The below requirements are needed on the local controller node that executes this lookup.
vSphere 7.0.3 or greater
python >= 3.6
aiohttp
Terms
Parameter |
Comments |
|---|---|
The absolute folder path to the object you would like to lookup. Folder paths always start with the datacenter name, and then the object type (host, vm, network, datastore). If the object is in a sub folder, the sub folder path should be added after the object type (for example /my_dc/vm/some/sub_folder/vm_name_to_lookup). Enter the object or folder names as seen in the VCenter GUI. Do not escape spaces or special characters. |
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_rest.vm_moid', key1=value1, key2=value2, ...) and query('vmware.vmware_rest.vm_moid', key1=value1, key2=value2, ...)
Parameter |
Comments |
|---|---|
Should not be set by the user, it is set internally when using a specific lookup plugin. Describes the type of object to lookup. Example, cluster, datacenter, datastore, etc. Default: |
|
You can use this optional parameter to set the location of a log file. This file will be used to record the HTTP REST interactions. The file will be stored on the host that runs the module. Configuration:
|
|
Allows connection when SSL certificates are not valid. Set to Choices:
Configuration:
|
Notes
Note
When keyword and positional parameters are used together, positional parameters must be listed before keyword parameters:
lookup('vmware.vmware_rest.vm_moid', term1, term2, key1=value1, key2=value2)andquery('vmware.vmware_rest.vm_moid', term1, term2, key1=value1, key2=value2)Lookup plugins are run on the ansible controller and are used to lookup information from an external resource. See https://docs.ansible.com/ansible/latest/plugins/lookup.html#lookup-plugins
This collection’s plugins allow you to quickly gather VMWare resource identifiers and either store or use them, instead of requiring multiple modules and tasks to do the same thing. See the examples section for a comparison.
Examples
#
#
# The examples below assume you have a datacenter named 'my_dc' and a vm named 'my_vm'.
# 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_rest.vm_moid', '/my_dc/vm/my_cluster/my_vm',
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_rest.vm_moid', '/my_dc/vm/my_cluster/my_vm', **connection_args) }}"
# Finally, you can also leverage the environment variables associated with each connection arg, and avoid passing
# extra args to the lookup plugins
- name: Use a lookup plugin with VMWARE_* environment variables set
ansible.builtin.debug:
msg: "{{ lookup('vmware.vmware_rest.vm_moid', '/my_dc/vm/my_cluster/my_vm') }}"
#
# VM Search Path Examples
#
# VMs are located under the 'vm' folder in a datacenter. If they are not in a folder, the path
# should include the cluster name.
# The basic path for a VM should look like '/<datacenter-name>/vm/<cluster-name>/<vm-name>'
- name: Lookup VM Named 'my_vm' in Datacenter 'my_dc' in Cluster 'my_cluster'
ansible.builtin.debug:
msg: "{{ lookup('vmware.vmware_rest.folder_moid', '/my_dc/vm/my_cluster/my_vm') }}"
# If the VM is in a user created VM folder, you just include the folder name.
- name: Lookup VM Named 'my_vm' in Datacenter 'my_dc' in Folder 'production' (also in Cluster 'my_cluster')
ansible.builtin.debug:
msg: "{{ lookup('vmware.vmware_rest.folder_moid', '/my_dc/production/my_vm') }}"
#
# 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: Look up the VM called 'my_vm' in the inventory
vmware.vmware_rest.vcenter_vm_info:
filter_names:
- my_vm
register: my_vm_info
- name: Delete a VM
vmware.vmware_rest.vcenter_vm:
vm: '{{ my_vm_info.value[0].vm }}'
state: absent
# With the lookup, playbooks are shorter, quicker, and more intuitive:
- name: Delete a VM
vmware.vmware_rest.vcenter_vm:
vm: "{{ lookup('vmware.vmware_rest.vm_moid', '/my_dc/vm/my_vm') }}"
state: absent
Return Value
Key |
Description |
|---|---|
MoID of the vSphere vm object Returned: success Sample: |