Debian Codegraph @

ansible_collections/vmware/vmware_rest/plugins/plugin_utils/lookup.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 import asyncio
11 import urllib
12
13 from ansible.errors import AnsibleLookupError
14 from ansible.module_utils._text import to_native
15 from ansible_collections.vmware.vmware_rest.plugins.module_utils.vmware_rest import (
16 gen_args,
17 open_session,
18 )
19
20
21 class InvalidVspherePathError(Exception):
22 def __init__(self, container_name, object_type):
23 self.container_name = container_name
24 self.object_type = object_type
25 super().__init__(
26 "VSphere object '%s' cannot hold objects of type '%s'"
27 % (container_name, object_type)
28 )
29
30
31 FILTER_MAPPINGS = {
32 "resource_pool": {
33 "parent_resource_pools": "parent_resource_pools",
34 "resource_pools": "resource_pools",
35 },
36 "datacenter": {
37 "parent_folders": "folders",
38 },
39 "folder": {},
40 "cluster": {
41 "parent_folders": "folders",
42 },
43 "host": {
44 "parent_folders": "folders",
45 },
46 "datastore": {
47 "parent_folders": "folders",
48 },
49 "vm": {
50 "parent_folders": "folders",
51 },
52 "network": {"parent_folders": "folders"},
53 }
54
55
56 class VcenterApi:
57 def __init__(self, hostname, session):
58 self.hostname = hostname
59 self.session = session
60
61 def build_url(self, object_type, filters):
62 corrected_filters_for_query = self.correct_filter_names(filters, object_type)
63 object_type = object_type.replace("_", "-")
64
65 return (f"https://{self.hostname}/api/vcenter/{object_type}") + gen_args(
66 corrected_filters_for_query, corrected_filters_for_query.keys()
67 )
68
69 def correct_filter_names(self, filters, object_type):
70 """
71 Objects in vSphere have slightly different filter names. For example, some use 'parent_folders' and some use 'folders'.
72 Its easier to read the code if we do all of the filter corrections at the end using a map.
73 Params:
74 filters: dict, The active filters that should be applied to the REST request
75 """
76 if object_type not in FILTER_MAPPINGS.keys():
77 raise AnsibleLookupError(
78 "object_type must be one of [%s]."
79 % ", ".join(list(FILTER_MAPPINGS.keys()))
80 )
81 corrected_filters = {}
82 for filter_key, filter_value in filters.items():
83 try:
84 corrected_filters[FILTER_MAPPINGS[object_type][filter_key]] = (
85 filter_value
86 )
87 except KeyError:
88 corrected_filters[filter_key] = filter_value
89
90 return corrected_filters
91
92 async def fetch_object_with_filters(self, object_type, filters):
93 _url = self.build_url(object_type, filters)
94 async with self.session.get(_url) as response:
95 return await response.json()
96
97
98 class Lookup:
99 def __init__(self, options, session):
100 self._options = options
101 self.api = VcenterApi(options["vcenter_hostname"], session)
102 self.active_filters = {}
103 self.object_type = options["object_type"]
104 # this is an internal flag that indicates if we tried to find the datacenter or not
105 # if its true, we stop trying and save some api calls.
106 # see add_intermediate_path_part_to_filter_spec
107 self._searched_for_datacenter = False
108
109 @classmethod
110 async def entry_point(cls, terms, options):
111 if not terms or not terms[0]:
112 raise AnsibleLookupError(
113 "Option _terms is required but no object has been specified"
114 )
115 session = None
116 try:
117 session = await open_session(
118 vcenter_hostname=options["vcenter_hostname"],
119 vcenter_username=options["vcenter_username"],
120 vcenter_password=options["vcenter_password"],
121 validate_certs=options.get("vcenter_validate_certs"),
122 log_file=options.get("vcenter_rest_log_file"),
123 )
124 except Exception as e:
125 raise AnsibleLookupError(
126 f'Unable to connect to vCenter or ESXi API at {options["vcenter_hostname"]}: {to_native(e)}'
127 )
128
129 lookup = cls(options, session)
130 lookup._options["_terms"] = terms[0]
131
132 try:
133 task = asyncio.create_task(lookup.search_for_object_moid_top_down())
134 return await task
135 except InvalidVspherePathError:
136 return ""
137
138 async def search_for_object_moid_top_down(self):
139 """
140 Searches for the lookup term in VSphere. Uses a top down approach to progress
141 through the path (for example /datacenter/vm/foo/bar/my-vm) until it reaches the
142 desired object. This guarantees we find the correct object even if multiple have the
143 same name, possibly at the cost of performance.
144 """
145 object_path = self._options["_terms"]
146 return_all_children = object_path.endswith("/")
147 path_parts = [_part for _part in object_path.split("/") if _part]
148
149 for index, path_part in enumerate(path_parts):
150 if index == len(path_parts) - 1:
151 # were at the end of the object path. Either return the object, or return
152 # all of the objects it contains (for example, the children inside of a folder)
153 if return_all_children:
154 await self.add_intermediate_path_part_to_filter_spec(path_part)
155 return await self.get_all_children_in_object()
156 else:
157 return await self.get_object_moid_by_name_and_type(path_part)
158
159 else:
160 # were in the middle of an object path, lookup the object at this level
161 # and add it to the filters for the next round of searching
162 await self.add_intermediate_path_part_to_filter_spec(path_part)
163 continue
164
165 raise AnsibleLookupError(
166 "No objects could be found due to an invalid search path"
167 )
168
169 async def add_intermediate_path_part_to_filter_spec(self, intermediate_object_name):
170 """
171 The intermediate object name is part of the search path that the user provided. This method tries to determine
172 what that intermediate object is based on its name and the type of lookup were doing. If the object is found,
173 its added to the final lookup filter spec.
174 If no object is found, that means the path is invalid for the lookup type, and we raise an error.
175 To find an objects filter spec definition, visit the VMware API docs.
176 Params:
177 intermediate_object_name: str, The name of the current object to search for
178 Returns:
179 None
180 """
181 # If we havnt searched for a datacenter yet, this is the first item in the path and its likely
182 # the datacenter. If its not, continue the search as normal and dont search for the datacenter
183 # again
184 if not self._searched_for_datacenter:
185 if await self.__add_datacenter_to_filter_spec_if_exists(
186 intermediate_object_name
187 ):
188 return
189
190 # Resource pools can only be in the vm filter spec
191 if self.object_type == "vm":
192 if await self.__add_object_to_filter_spec_if_exists(
193 intermediate_object_name, "resource_pool", "resource_pools"
194 ):
195 return
196
197 # Clusters can be used in the vm, host, or resource pool filter specs
198 if self.object_type in ("vm", "host", "resource_pool"):
199 if await self.__add_object_to_filter_spec_if_exists(
200 intermediate_object_name, "cluster", "clusters"
201 ):
202 return
203
204 # Hosts can be in the filter spec for vms, networks, datastores, or resource pools
205 if self.object_type in ("vm", "network", "datastore", "resource_pool"):
206 if await self.__add_object_to_filter_spec_if_exists(
207 intermediate_object_name, "host", "hosts"
208 ):
209 return
210
211 # Folders can be used in the filter spec for everything except resource pools
212 if self.object_type != "resource_pool":
213 if await self.__add_object_to_filter_spec_if_exists(
214 intermediate_object_name, "folder", "parent_folders"
215 ):
216 return
217
218 raise InvalidVspherePathError(
219 container_name=intermediate_object_name, object_type=self.object_type
220 )
221
222 async def __add_datacenter_to_filter_spec_if_exists(self, object_name):
223 """
224 Search for an object name as a datacenter. If found, add the datacenter to the
225 active filter spec.
226 Params:
227 object_name: str, The name of the current object to search for
228 Returns:
229 Datacenter MOID or None
230 """
231 self._searched_for_datacenter = True
232 result = await self.get_object_moid_by_name_and_type(object_name, "datacenter")
233 if result:
234 self.active_filters["datacenters"] = result
235 return result
236
237 async def __add_object_to_filter_spec_if_exists(
238 self, object_name, object_type, filter_key
239 ):
240 """
241 Search for an object name as a specific object type. If found, add the object ID to the
242 active filter spec.
243 Params:
244 object_name: str, The name of the current object to search for
245 object_type: str, The type of object to search for
246 filter_key: str, The key in the filter spec that the result will be stored under
247 Returns:
248 Object MOID or None
249 """
250 result = await self.get_object_moid_by_name_and_type(object_name, object_type)
251 if result:
252 self.active_filters[filter_key] = result
253 return result
254
255 async def get_object_moid_by_name_and_type(self, object_name, _object_type=None):
256 """
257 Returns a single object MoID with a specific type, name, and filter set. If more than one object
258 is found, and error is thrown.
259 Params:
260 object_name: str, the name of the object to search for
261 _object_type: str, Optional name of the object type to search for. Defaults to the lookup plugin type
262 Returns:
263 str, a single MoID
264 """
265 if not _object_type:
266 _object_type = self.object_type
267
268 if _object_type == "datacenter":
269 _filters = {"folders": "group-d1"}
270 else:
271 _filters = self.active_filters.copy()
272
273 _filters["names"] = object_name
274 _result = await self.api.fetch_object_with_filters(_object_type, _filters)
275
276 object_moid = self.get_single_moid_from_result(
277 _result, _object_type, object_name
278 )
279 return object_moid
280
281 @staticmethod
282 def get_single_moid_from_result(result, object_type, object_name=None):
283 """
284 Parses vSphere returns query results as a json list, validates the results and extracts
285 the correct MoID
286 Params:
287 object_type: str, The type of object to search the results for
288 object_name: str, The name of the object to search the results for
289 Returns:
290 str or None, a single MoID or none if nothing was found
291 """
292 if not result or not object_name:
293 return None
294
295 object_name_decoded = urllib.parse.unquote(object_name)
296 if object_name_decoded not in result[0].values():
297 return None
298
299 results_with_decoded_names = []
300 for obj in result:
301 if "%2f" in obj["name"]:
302 continue
303 results_with_decoded_names.append((obj["name"], obj[object_type]))
304
305 if len(results_with_decoded_names) > 1:
306 raise AnsibleLookupError(
307 "More than one object found with matching name: [%s]."
308 % ", ".join(
309 [f"{item[0]} => {item[1]}" for item in results_with_decoded_names]
310 )
311 )
312
313 try:
314 return results_with_decoded_names[0][1]
315 except (TypeError, KeyError, IndexError) as e:
316 raise AnsibleLookupError(to_native(e))
317
318 async def get_all_children_in_object(self):
319 results = await self.api.fetch_object_with_filters(
320 self.object_type, self.active_filters
321 )
322
323 try:
324 return [result[self.object_type] for result in results]
325 except KeyError:
326 return None