Skip to content

Commit 618a19d

Browse files
mikemorencymikemorency
authored
updating lookup documentation and examples (#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
1 parent e13cee0 commit 618a19d

File tree

10 files changed

+837
-144
lines changed

10 files changed

+837
-144
lines changed

‎changelogs/fragments/503_mm-feature_update_lookup_docs.yml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
minor_changes:
3+
- cluster_moid - updated documentation around lookup plugin usage
4+
- datacenter_moid - updated documentation around lookup plugin usage
5+
- datastore_moid - updated documentation around lookup plugin usage
6+
- folder_moid - updated documentation around lookup plugin usage
7+
- host_moid - updated documentation around lookup plugin usage
8+
- network_moid - updated documentation around lookup plugin usage
9+
- resource_pool_moid - updated documentation around lookup plugin usage
10+
- vm_moid - updated documentation around lookup plugin usage

‎plugins/doc_fragments/moid.py

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,24 @@
99
class ModuleDocFragment(object):
1010
# Parameters for the Lookup Managed Object Reference (MoID) plugins
1111
DOCUMENTATION = r"""
12+
notes:
13+
- >-
14+
Lookup plugins are run on the ansible controller and are used to lookup information from an external
15+
resource. See https://docs.ansible.com/ansible/latest/plugins/lookup.html#lookup-plugins
16+
- >-
17+
This collection's plugins allow you to quickly gather VMWare resource identifiers and either store or
18+
use them, instead of requiring multiple modules and tasks to do the same thing.
19+
See the examples section for a comparison.
20+
1221
options:
1322
_terms:
14-
description: Path to query.
23+
description:
24+
- The absolute folder path to the object you would like to lookup.
25+
- Folder paths always start with the datacenter name, and then the object type (host, vm, network, datastore).
26+
- >-
27+
If the object is in a sub folder, the sub folder path should be added after the object type
28+
(for example /my_dc/vm/some/sub_folder/vm_name_to_lookup).
29+
- Enter the object or folder names as seen in the VCenter GUI. Do not escape spaces or special characters.
1530
required: True
1631
type: string
1732
vcenter_hostname:
@@ -51,4 +66,11 @@ class ModuleDocFragment(object):
5166
env:
5267
- name: VMWARE_VALIDATE_CERTS
5368
type: boolean
69+
object_type:
70+
description:
71+
- Should not be set by the user, it is set internally when using a specific lookup plugin.
72+
- Describes the type of object to lookup. Example, cluster, datacenter, datastore, etc.
73+
default: 'cluster'
74+
type: str
75+
required: False
5476
"""

‎plugins/lookup/cluster_moid.py

Lines changed: 95 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -11,33 +11,113 @@
1111
name: cluster_moid
1212
short_description: Look up MoID for vSphere cluster objects using vCenter REST API
1313
description:
14-
- Returns Managed Object Reference (MoID) of the vSphere cluster object contained in the specified path.
14+
- Returns Managed Object Reference (MoID) of the vSphere cluster object contained in the specified path.
1515
author:
16-
- Alina Buzachis (@alinabuzachis)
16+
- Alina Buzachis (@alinabuzachis)
1717
version_added: 2.1.0
1818
requirements:
19-
- vSphere 7.0.3 or greater
20-
- python >= 3.6
21-
- aiohttp
19+
- vSphere 7.0.3 or greater
20+
- python >= 3.6
21+
- aiohttp
2222
extends_documentation_fragment:
23-
- vmware.vmware_rest.moid
23+
- vmware.vmware_rest.moid
2424
"""
2525

2626

2727
EXAMPLES = r"""
28-
# lookup sample
29-
- name: set connection info
30-
ansible.builtin.set_fact:
28+
#
29+
#
30+
# The examples below assume you have a datacenter named 'my_dc' and a cluster named 'my_cluster'.
31+
# Replace these values as needed for your environment.
32+
#
33+
#
34+
35+
#
36+
# Authentication / Connection Arguments
37+
#
38+
# You can explicitly set the connection arguments in each lookup. This may be clearer for some use cases
39+
- name: Pass In Connection Arguments Explicitly
40+
ansible.builtin.debug:
41+
msg: >-
42+
{{ lookup('vmware.vmware_rest.cluster_moid', '/my_dc/host/my_cluster',
43+
vcenter_hostname="vcenter.test",
44+
vcenter_username="[email protected]",
45+
vcenter_password="1234") }}
46+
47+
# Alternatively, you can add the connection arguments to a dictionary variable, and then pass that variable to the
48+
# lookup plugins. This makes the individual lookup plugin calls simpler
49+
- name: Example Playbook
50+
hosts: all
51+
vars:
3152
connection_args:
3253
vcenter_hostname: "vcenter.test"
3354
vcenter_username: "[email protected]"
3455
vcenter_password: "1234"
35-
36-
- name: lookup MoID of the object
37-
ansible.builtin.debug: msg="{{ lookup('vmware.vmware_rest.cluster_moid', '/my_dc/host/my_cluster', **connection_args) }}"
38-
39-
- name: lookup MoID of the object inside the path
40-
ansible.builtin.debug: msg="{{ lookup('vmware.vmware_rest.cluster_moid', '/my_dc/host/') }}"
56+
tasks:
57+
# Add more tasks or lookups as needed, referencing the same connection_args variable
58+
- name: Lookup MoID of the object
59+
ansible.builtin.debug:
60+
msg: "{{ lookup('vmware.vmware_rest.cluster_moid', '/my_dc/host/my_cluster', **connection_args) }}"
61+
62+
# Finally, you can also leverage the environment variables associated with each connection arg, and avoid passing
63+
# extra args to the lookup plugins
64+
- name: Use a lookup plugin with VMWARE_* environment variables set
65+
ansible.builtin.debug:
66+
msg: "{{ lookup('vmware.vmware_rest.cluster_moid', '/my_dc/host/my_cluster') }}"
67+
68+
#
69+
# Cluster Search Path Examples
70+
#
71+
# Clusters are located under the 'host' folder in a datacenter.
72+
# The basic path for a cluster should look like '/<datacenter-name>/host/<cluster-name>'
73+
- name: Lookup Cluster Named 'my_cluster' in Datacenter 'my_dc'
74+
ansible.builtin.debug:
75+
msg: "{{ lookup('vmware.vmware_rest.cluster_moid', '/my_dc/host/my_cluster') }}"
76+
77+
#
78+
# Usage in Playbooks
79+
#
80+
#
81+
# The lookup plugin can be used to simplify your playbook. Here is an example of how you might use it.
82+
#
83+
# Without the lookup, this takes two modules which both run on the remote host. This can slow down execution
84+
# and adds extra steps to the playbook:
85+
- name: Retrieve details about a cluster named 'my_cluster'
86+
vmware.vmware_rest.vcenter_cluster_info:
87+
names:
88+
- my_cluster
89+
register: my_cluster_info
90+
91+
- name: Create a VM
92+
vmware.vmware_rest.vcenter_vm:
93+
placement:
94+
cluster: "{{ my_cluster_info.value[0].cluster }}"
95+
name: test_vm1
96+
guest_OS: RHEL_7_64
97+
hardware_version: VMX_11
98+
memory:
99+
size_MiB: 1024
100+
disks:
101+
- type: SATA
102+
new_vmdk:
103+
name: first_disk
104+
capacity: 3200
105+
106+
# With the lookup, playbooks are shorter, quicker, and more intuitive:
107+
- name: Create a VM
108+
vmware.vmware_rest.vcenter_vm:
109+
placement:
110+
cluster: "{{ lookup('vmware.vmware_rest.cluster_moid', '/my_dc/host/my_cluster') }}"
111+
name: test_vm1
112+
guest_OS: RHEL_7_64
113+
hardware_version: VMX_11
114+
memory:
115+
size_MiB: 1024
116+
disks:
117+
- type: SATA
118+
new_vmdk:
119+
name: first_disk
120+
capacity: 3200
41121
"""
42122

43123

‎plugins/lookup/datacenter_moid.py

Lines changed: 97 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -11,33 +11,112 @@
1111
name: datacenter_moid
1212
short_description: Look up MoID for vSphere datacenter objects using vCenter REST API
1313
description:
14-
- Returns Managed Object Reference (MoID) of the vSphere datacenter object contained in the specified path.
14+
- Returns Managed Object Reference (MoID) of the vSphere datacenter object contained in the specified path.
1515
author:
16-
- Alina Buzachis (@alinabuzachis)
16+
- Alina Buzachis (@alinabuzachis)
1717
version_added: 2.1.0
1818
requirements:
19-
- vSphere 7.0.3 or greater
20-
- python >= 3.6
21-
- aiohttp
19+
- vSphere 7.0.3 or greater
20+
- python >= 3.6
21+
- aiohttp
2222
extends_documentation_fragment:
23-
- vmware.vmware_rest.moid
23+
- vmware.vmware_rest.moid
2424
"""
2525

2626

2727
EXAMPLES = r"""
28-
# lookup sample
29-
- name: set connection info
30-
ansible.builtin.set_fact:
28+
#
29+
#
30+
# The examples below assume you have a datacenter named 'my_dc'.
31+
# Replace these values as needed for your environment.
32+
#
33+
#
34+
35+
#
36+
# Authentication / Connection Arguments
37+
#
38+
# You can explicitly set the connection arguments in each lookup. This may be clearer for some use cases
39+
- name: Pass In Connection Arguments Explicitly
40+
ansible.builtin.debug:
41+
msg: >-
42+
{{ lookup('vmware.vmware_rest.datacenter_moid', '/my_dc',
43+
vcenter_hostname="vcenter.test",
44+
vcenter_username="[email protected]",
45+
vcenter_password="1234") }}
46+
47+
# Alternatively, you can add the connection arguments to a dictionary variable, and then pass that variable to the
48+
# lookup plugins. This makes the individual lookup plugin calls simpler
49+
- name: Example Playbook
50+
hosts: all
51+
vars:
3152
connection_args:
32-
vcenter_hostname: "vcenter.test"
33-
vcenter_username: "[email protected]"
34-
vcenter_password: "1234"
35-
36-
- name: lookup MoID of the object
37-
ansible.builtin.debug: msg="{{ lookup('vmware.vmware_rest.datacenter_moid', '/my_dc', **connection_args) }}"
38-
39-
- name: lookup MoID of the object inside the path
40-
ansible.builtin.debug: msg="{{ lookup('vmware.vmware_rest.datacenter_moid', '/my_folder/') }}"
53+
vcenter_hostname: "vcenter.test"
54+
vcenter_username: "[email protected]"
55+
vcenter_password: "1234"
56+
tasks:
57+
# Add more tasks or lookups as needed, referencing the same connection_args variable
58+
- name: Lookup MoID of the object
59+
ansible.builtin.debug:
60+
msg: "{{ lookup('vmware.vmware_rest.datacenter_moid', '/my_dc', **connection_args) }}"
61+
62+
# Finally, you can also leverage the environment variables associated with each connection arg, and avoid passing
63+
# extra args to the lookup plugins
64+
- name: Use a lookup plugin with VMWARE_* environment variables set
65+
ansible.builtin.debug:
66+
msg: "{{ lookup('vmware.vmware_rest.datacenter_moid', '/my_dc') }}"
67+
68+
#
69+
# Datacenter Search Path Examples
70+
#
71+
# Datacenters are located at the root of VMWare paths.
72+
# The basic path for a datacenter should look like '/<datacenter-name>'
73+
- name: Lookup Datacenter 'my_dc'
74+
ansible.builtin.debug:
75+
msg: "{{ lookup('vmware.vmware_rest.datacenter_moid', '/my_dc') }}"
76+
77+
# Usage in Playbooks
78+
#
79+
#
80+
# The lookup plugin can be used to simplify your playbook. Here is an example of how you might use it.
81+
#
82+
# Without the lookup, this takes two modules which both run on the remote host. This can slow down execution
83+
# and adds extra steps to the playbook:
84+
- name: Retrieve details about a datacenter named 'my_dc'
85+
vmware.vmware_rest.vcenter_datacenter_info:
86+
names:
87+
- my_dc
88+
register: my_dc_info
89+
90+
- name: Create a VM
91+
vmware.vmware_rest.vcenter_vm:
92+
placement:
93+
datacenter: "{{ my_dc_info.value[0].datacebter }}"
94+
name: test_vm1
95+
guest_OS: RHEL_7_64
96+
hardware_version: VMX_11
97+
memory:
98+
size_MiB: 1024
99+
disks:
100+
- type: SATA
101+
new_vmdk:
102+
name: first_disk
103+
capacity: 3200
104+
105+
# With the lookup, playbooks are shorter, quicker, and more intuitive:
106+
- name: Create a VM
107+
vmware.vmware_rest.vcenter_vm:
108+
placement:
109+
datacenter: "{{ lookup('vmware.vmware_rest.datacenter_moid', '/my_dc') }}"
110+
name: test_vm1
111+
guest_OS: RHEL_7_64
112+
hardware_version: VMX_11
113+
memory:
114+
size_MiB: 1024
115+
disks:
116+
- type: SATA
117+
new_vmdk:
118+
name: first_disk
119+
capacity: 3200
41120
"""
42121

43122

0 commit comments

Comments
 (0)