updating lookup documentation and examples (ansible-collections#503)

SUMMARY
The lookup plugin documentation needs to be updated. Its missing useful examples, inconsistent, and can be vague. These changes should address those issues.
ISSUE TYPE

Docs Pull Request

COMPONENT NAME
all lookup plugins (plugins/lookup/*)

Reviewed-by: Brian Coca
Reviewed-by: mikemorency
Reviewed-by: Alina Buzachis

changelogs/fragments/503_mm-feature_update_lookup_docs.yml

@@ -0,0 +1,10 @@
+---
+minor_changes:
+  - cluster_moid - updated documentation around lookup plugin usage
+  - datacenter_moid - updated documentation around lookup plugin usage
+  - datastore_moid - updated documentation around lookup plugin usage
+  - folder_moid - updated documentation around lookup plugin usage
+  - host_moid - updated documentation around lookup plugin usage
+  - network_moid - updated documentation around lookup plugin usage
+  - resource_pool_moid - updated documentation around lookup plugin usage
+  - vm_moid - updated documentation around lookup plugin usage

plugins/doc_fragments/moid.py

@@ -9,9 +9,24 @@
 class ModuleDocFragment(object):
     # Parameters for the Lookup Managed Object Reference (MoID) plugins
     DOCUMENTATION = r"""
+    notes:
+        - >-
+            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.
+
     options:
         _terms:
-            description: Path to query.
+            description:
+                - 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.
             required: True
             type: string
         vcenter_hostname:
@@ -51,4 +66,11 @@ class ModuleDocFragment(object):
             env:
                 - name: VMWARE_VALIDATE_CERTS
             type: boolean
+        object_type:
+            description:
+                - 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'
+            type: str
+            required: False
 """

plugins/lookup/cluster_moid.py

@@ -11,33 +11,113 @@
 name: cluster_moid
 short_description: Look up MoID for vSphere cluster objects using vCenter REST API
 description:
-    - Returns Managed Object Reference (MoID) of the vSphere cluster object contained in the specified path.
+  - Returns Managed Object Reference (MoID) of the vSphere cluster object contained in the specified path.
 author:
-    - Alina Buzachis (@alinabuzachis)
+  - Alina Buzachis (@alinabuzachis)
 version_added: 2.1.0
 requirements:
-    - vSphere 7.0.3 or greater
-    - python >= 3.6
-    - aiohttp
+  - vSphere 7.0.3 or greater
+  - python >= 3.6
+  - aiohttp
 extends_documentation_fragment:
-- vmware.vmware_rest.moid
+  - vmware.vmware_rest.moid
 """
 
 
 EXAMPLES = r"""
-# lookup sample
-- name: set connection info
-  ansible.builtin.set_fact:
+#
+#
+# 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"
-
-- name: lookup MoID of the object
-  ansible.builtin.debug: msg="{{ lookup('vmware.vmware_rest.cluster_moid', '/my_dc/host/my_cluster', **connection_args) }}"
-
-- name: lookup MoID of the object inside the path
-  ansible.builtin.debug: msg="{{ lookup('vmware.vmware_rest.cluster_moid', '/my_dc/host/') }}"
+  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
 """
 
 

plugins/lookup/datacenter_moid.py

@@ -11,33 +11,112 @@
 name: datacenter_moid
 short_description: Look up MoID for vSphere datacenter objects using vCenter REST API
 description:
-    - Returns Managed Object Reference (MoID) of the vSphere datacenter object contained in the specified path.
+  - Returns Managed Object Reference (MoID) of the vSphere datacenter object contained in the specified path.
 author:
-    - Alina Buzachis (@alinabuzachis)
+  - Alina Buzachis (@alinabuzachis)
 version_added: 2.1.0
 requirements:
-    - vSphere 7.0.3 or greater
-    - python >= 3.6
-    - aiohttp
+  - vSphere 7.0.3 or greater
+  - python >= 3.6
+  - aiohttp
 extends_documentation_fragment:
-- vmware.vmware_rest.moid
+  - vmware.vmware_rest.moid
 """
 
 
 EXAMPLES = r"""
-# lookup sample
-- name: set connection info
-  ansible.builtin.set_fact:
+#
+#
+# The examples below assume you have a datacenter named 'my_dc'.
+# 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.datacenter_moid', '/my_dc',
+      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"
-
-- name: lookup MoID of the object
-  ansible.builtin.debug: msg="{{ lookup('vmware.vmware_rest.datacenter_moid', '/my_dc', **connection_args) }}"
-
-- name: lookup MoID of the object inside the path
-  ansible.builtin.debug: msg="{{ lookup('vmware.vmware_rest.datacenter_moid', '/my_folder/') }}"
+      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.datacenter_moid', '/my_dc', **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.datacenter_moid', '/my_dc') }}"
+
+#
+# Datacenter Search Path Examples
+#
+# Datacenters are located at the root of VMWare paths.
+# The basic path for a datacenter should look like '/<datacenter-name>'
+- name: Lookup Datacenter 'my_dc'
+  ansible.builtin.debug:
+    msg: "{{ lookup('vmware.vmware_rest.datacenter_moid', '/my_dc') }}"
+
+# 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 datacenter named 'my_dc'
+  vmware.vmware_rest.vcenter_datacenter_info:
+    names:
+      - my_dc
+  register: my_dc_info
+
+- name: Create a VM
+  vmware.vmware_rest.vcenter_vm:
+    placement:
+      datacenter: "{{ my_dc_info.value[0].datacebter }}"
+    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:
+      datacenter: "{{ lookup('vmware.vmware_rest.datacenter_moid', '/my_dc') }}"
+    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
 """