vmware.vmware_rest.host_moid lookup – Look up MoID for vSphere host objects using vCenter REST API

Note

This lookup plugin is part of the vmware.vmware_rest collection (version 3.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.host_moid.

New in vmware.vmware_rest 2.1.0

Synopsis

  • Returns Managed Object Reference (MoID) of the vSphere host 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

Terms

string / required

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.host_moid', key1=value1, key2=value2, ...) and query('vmware.vmware_rest.host_moid', key1=value1, key2=value2, ...)

Parameter

Comments

object_type

string

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: "cluster"

vcenter_hostname

string / required

The hostname or IP address of the vSphere vCenter.

Configuration:

vcenter_password

string / required

The vSphere vCenter password.

Configuration:

vcenter_rest_log_file

string

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:

vcenter_username

string / required

The vSphere vCenter username.

Configuration:

vcenter_validate_certs

boolean

Allows connection when SSL certificates are not valid. Set to false when certificates are not trusted.

Choices:

  • false

  • true ← (default)

Configuration:

Notes

Note

  • When keyword and positional parameters are used together, positional parameters must be listed before keyword parameters: lookup('vmware.vmware_rest.host_moid', term1, term2, key1=value1, key2=value2) and query('vmware.vmware_rest.host_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', a cluster named 'my_cluster', and an ESXI host named 'my_host'.
# 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.host_moid', '/my_dc/host/my_cluster/my_host',
      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.host_moid', '/my_dc/host/my_cluster/my_host', **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.host_moid', '/my_dc/host/my_cluster/my_host') }}"

#
# Host Search Path Examples
#
# Hosts are located under the 'host' folder in a datacenter. They may also be under a cluster, which is
# under the host folder.
# The basic path for a host in a cluster should look like '/<datacenter-name>/host/<cluster-name>/<host-name>'
# The basic path for a host outside of a cluster should look like '/<datacenter-name>/host/<host-name>'
- name: Lookup Host named 'my_host' in a Cluster Named 'my_cluster' in Datacenter 'my_dc'
  ansible.builtin.debug:
    msg: "{{ lookup('vmware.vmware_rest.host_moid', '/my_dc/host/my_cluster/my_host') }}"

- name: Lookup Host named 'my_host' not in a Cluster but in Datacenter 'my_dc'
  ansible.builtin.debug:
    msg: "{{ lookup('vmware.vmware_rest.host_moid', '/my_dc/host/my_host') }}"

# If the host is in a user created 'host' type folder, the path shoud just include the
# datacenter and folder name.
- name: Lookup Host Named 'my_host' in Datacenter 'my_dc' in a Host folder 'production'
  ansible.builtin.debug:
    msg: "{{ lookup('vmware.vmware_rest.host_moid', '/my_dc/production/my_host') }}"

#
# 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 an ESXI host named 'my_host'
  vmware.vmware_rest.vcenter_host_info:
    names:
      - my_host
  register: my_host_info

- name: Create a VM
  vmware.vmware_rest.vcenter_vm:
    placement:
      host: "{{ my_host_info.value[0].host }}"
    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.host_moid', '/my_dc/host/my_cluster/my_host') }}"
    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

Return value

string

MoID of the vSphere host object

Returned: success

Sample: "host-1014"

Authors

  • Alina Buzachis (@alinabuzachis)

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.