vmware.vmware_rest.cluster_moid lookup – Look up MoID for vSphere cluster objects using vCenter REST API
Note
This lookup plugin is part of the vmware.vmware_rest collection (version 4.1.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.cluster_moid.
New in vmware.vmware_rest 2.1.0
Synopsis
Returns Managed Object Reference (MoID) of the vSphere cluster 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.cluster_moid', key1=value1, key2=value2, ...) and query('vmware.vmware_rest.cluster_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.cluster_moid', term1, term2, key1=value1, key2=value2)andquery('vmware.vmware_rest.cluster_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 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_rest.cluster_moid', '/my_dc/host/my_cluster',
vcenter_hostname="vcenter.test",
vcenter_username="administrator@vsphere.local",
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: "administrator@vsphere.local"
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.cluster_moid', '/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
- name: Use a lookup plugin with VMWARE_* environment variables set
ansible.builtin.debug:
msg: "{{ lookup('vmware.vmware_rest.cluster_moid', '/my_dc/host/my_cluster') }}"
#
# Cluster Search Path Examples
#
# Clusters are located under the 'host' folder in a datacenter.
# The basic path for a cluster should look like '/<datacenter-name>/host/<cluster-name>'
- name: Lookup Cluster Named 'my_cluster' in Datacenter 'my_dc'
ansible.builtin.debug:
msg: "{{ lookup('vmware.vmware_rest.cluster_moid', '/my_dc/host/my_cluster') }}"
#
# 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_rest.cluster_moid', '/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: |