Debian Codegraph @

ansible_collections/vmware/vmware_rest/plugins/lookup/host_moid.py

raw
1 # Copyright: (c) 2021, Alina Buzachis <@alinabuzachis>
2 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
3
4
5 from __future__ import absolute_import, division, print_function
6
7 __metaclass__ = type
8
9
10 DOCUMENTATION = r"""
11 name: host_moid
12 short_description: Look up MoID for vSphere host objects using vCenter REST API
13 description:
14 - Returns Managed Object Reference (MoID) of the vSphere host object contained in the specified path.
15 author:
16 - Alina Buzachis (@alinabuzachis)
17 version_added: 2.1.0
18 requirements:
19 - vSphere 7.0.3 or greater
20 - python >= 3.6
21 - aiohttp
22 notes:
23 - This plugin requires the cloud.common collection, which will not be installed automatically as a dependency.
24 extends_documentation_fragment:
25 - vmware.vmware_rest.moid
26 """
27
28
29 EXAMPLES = r"""
30 #
31 #
32 # The examples below assume you have a datacenter named 'my_dc', a cluster named 'my_cluster', and an ESXI host named 'my_host'.
33 # Replace these values as needed for your environment.
34 #
35 #
36
37 #
38 # Authentication / Connection Arguments
39 #
40 # You can explicitly set the connection arguments in each lookup. This may be clearer for some use cases
41 - name: Pass In Connection Arguments Explicitly
42 ansible.builtin.debug:
43 msg: >-
44 {{ lookup('vmware.vmware_rest.host_moid', '/my_dc/host/my_cluster/my_host',
45 vcenter_hostname="vcenter.test",
46 vcenter_username="[email protected]",
47 vcenter_password="1234") }}
48
49 # Alternatively, you can add the connection arguments to a dictionary variable, and then pass that variable to the
50 # lookup plugins. This makes the individual lookup plugin calls simpler
51 - name: Example Playbook
52 hosts: all
53 vars:
54 connection_args:
55 vcenter_hostname: "vcenter.test"
56 vcenter_username: "[email protected]"
57 vcenter_password: "1234"
58 tasks:
59 # Add more tasks or lookups as needed, referencing the same connection_args variable
60 - name: Lookup MoID of the object
61 ansible.builtin.debug:
62 msg: "{{ lookup('vmware.vmware_rest.host_moid', '/my_dc/host/my_cluster/my_host', **connection_args) }}"
63
64 # Finally, you can also leverage the environment variables associated with each connection arg, and avoid passing
65 # extra args to the lookup plugins
66 - name: Use a lookup plugin with VMWARE_* environment variables set
67 ansible.builtin.debug:
68 msg: "{{ lookup('vmware.vmware_rest.host_moid', '/my_dc/host/my_cluster/my_host') }}"
69
70 #
71 # Host Search Path Examples
72 #
73 # Hosts are located under the 'host' folder in a datacenter. They may also be under a cluster, which is
74 # under the host folder.
75 # The basic path for a host in a cluster should look like '/<datacenter-name>/host/<cluster-name>/<host-name>'
76 # The basic path for a host outside of a cluster should look like '/<datacenter-name>/host/<host-name>'
77 - name: Lookup Host named 'my_host' in a Cluster Named 'my_cluster' in Datacenter 'my_dc'
78 ansible.builtin.debug:
79 msg: "{{ lookup('vmware.vmware_rest.host_moid', '/my_dc/host/my_cluster/my_host') }}"
80
81 - name: Lookup Host named 'my_host' not in a Cluster but in Datacenter 'my_dc'
82 ansible.builtin.debug:
83 msg: "{{ lookup('vmware.vmware_rest.host_moid', '/my_dc/host/my_host') }}"
84
85 # If the host is in a user created 'host' type folder, the path shoud just include the
86 # datacenter and folder name.
87 - name: Lookup Host Named 'my_host' in Datacenter 'my_dc' in a Host folder 'production'
88 ansible.builtin.debug:
89 msg: "{{ lookup('vmware.vmware_rest.host_moid', '/my_dc/production/my_host') }}"
90
91 #
92 # Usage in Playbooks
93 #
94 #
95 # The lookup plugin can be used to simplify your playbook. Here is an example of how you might use it.
96 #
97 # Without the lookup, this takes two modules which both run on the remote host. This can slow down execution
98 # and adds extra steps to the playbook:
99 - name: Retrieve details about an ESXI host named 'my_host'
100 vmware.vmware_rest.vcenter_host_info:
101 names:
102 - my_host
103 register: my_host_info
104
105 - name: Create a VM
106 vmware.vmware_rest.vcenter_vm:
107 placement:
108 host: "{{ my_host_info.value[0].host }}"
109 name: test_vm1
110 guest_OS: RHEL_7_64
111 hardware_version: VMX_11
112 memory:
113 size_MiB: 1024
114 disks:
115 - type: SATA
116 new_vmdk:
117 name: first_disk
118 capacity: 3200
119
120 # With the lookup, playbooks are shorter, quicker, and more intuitive:
121 - name: Create a VM
122 vmware.vmware_rest.vcenter_vm:
123 placement:
124 cluster: "{{ lookup('vmware.vmware_rest.host_moid', '/my_dc/host/my_cluster/my_host') }}"
125 name: test_vm1
126 guest_OS: RHEL_7_64
127 hardware_version: VMX_11
128 memory:
129 size_MiB: 1024
130 disks:
131 - type: SATA
132 new_vmdk:
133 name: first_disk
134 capacity: 3200
135 """
136
137
138 RETURN = r"""
139 _raw:
140 description: MoID of the vSphere host object
141 type: str
142 sample: host-1014
143 """
144
145
146 from ansible.errors import AnsiblePluginError
147
148 try:
149 from ansible_collections.cloud.common.plugins.plugin_utils.turbo.lookup import (
150 TurboLookupBase as LookupBase,
151 )
152 except ImportError:
153 raise AnsiblePluginError(
154 message="This plugin requires the cloud.common collection."
155 )
156
157 from ansible_collections.vmware.vmware_rest.plugins.plugin_utils.lookup import Lookup
158
159
160 class LookupModule(LookupBase):
161 async def _run(self, terms, variables, **kwargs):
162 self.set_options(var_options=variables, direct=kwargs)
163 self.set_option("object_type", "host")
164 result = await Lookup.entry_point(terms, self._options)
165 return [result]
166
167 run = _run if not hasattr(LookupBase, "run_on_daemon") else LookupBase.run_on_daemon