Debian Codegraph @

ansible_collections/vmware/vmware_rest/plugins/modules/vcenter_folder_info.py

raw
1 #!/usr/bin/python
2 # -*- coding: utf-8 -*-
3 # Copyright: (c) 2021, Ansible Project
4 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
5 # template: header.j2
6 # This module is autogenerated using the ansible.content_builder.
7 # See: https://github.com/ansible-community/ansible.content_builder
8
9
10 DOCUMENTATION = r"""
11 module: vcenter_folder_info
12 short_description: Returns information about at most 1000 visible (subject to permission
13 checks) folders in vCenter matching the Folder.FilterSpec.
14 description: Returns information about at most 1000 visible (subject to permission
15 checks) folders in vCenter matching the Folder.FilterSpec.
16 options:
17 datacenters:
18 aliases:
19 - filter_datacenters
20 description:
21 - Datacenters that must contain the folder for the folder to match the filter.
22 - If unset or empty, folder in any datacenter match the filter.
23 - When clients pass a value of this structure as a parameter, the field must
24 contain the id of resources returned by M(vmware.vmware_rest.vcenter_datacenter_info).
25 elements: str
26 type: list
27 folders:
28 aliases:
29 - filter_folders
30 description:
31 - Identifiers of folders that can match the filter.
32 - If unset or empty, folders with any identifier match the filter.
33 - When clients pass a value of this structure as a parameter, the field must
34 contain the id of resources returned by M(vmware.vmware_rest.vcenter_folder_info).
35 elements: str
36 type: list
37 names:
38 aliases:
39 - filter_names
40 description:
41 - Names that folders must have to match the filter (see I(name)).
42 - If unset or empty, folders with any name match the filter.
43 elements: str
44 type: list
45 parent_folders:
46 description:
47 - Folders that must contain the folder for the folder to match the filter.
48 - If unset or empty, folder in any folder match the filter.
49 - When clients pass a value of this structure as a parameter, the field must
50 contain the id of resources returned by M(vmware.vmware_rest.vcenter_folder_info).
51 elements: str
52 type: list
53 session_timeout:
54 description:
55 - 'Timeout settings for client session. '
56 - 'The maximal number of seconds for the whole operation including connection
57 establishment, request sending and response. '
58 - The default value is 300s.
59 type: float
60 version_added: 2.1.0
61 type:
62 aliases:
63 - filter_type
64 choices:
65 - DATACENTER
66 - DATASTORE
67 - HOST
68 - NETWORK
69 - VIRTUAL_MACHINE
70 description:
71 - The I(type) enumerated type defines the type of a vCenter Server folder.
72 The type of a folder determines what what kinds of children can be contained
73 in the folder.
74 type: str
75 vcenter_hostname:
76 description:
77 - The hostname or IP address of the vSphere vCenter
78 - If the value is not specified in the task, the value of environment variable
79 C(VMWARE_HOST) will be used instead.
80 required: true
81 type: str
82 vcenter_password:
83 description:
84 - The vSphere vCenter password
85 - If the value is not specified in the task, the value of environment variable
86 C(VMWARE_PASSWORD) will be used instead.
87 required: true
88 type: str
89 vcenter_rest_log_file:
90 description:
91 - 'You can use this optional parameter to set the location of a log file. '
92 - 'This file will be used to record the HTTP REST interaction. '
93 - 'The file will be stored on the host that runs the module. '
94 - 'If the value is not specified in the task, the value of '
95 - environment variable C(VMWARE_REST_LOG_FILE) will be used instead.
96 type: str
97 vcenter_username:
98 description:
99 - The vSphere vCenter username
100 - If the value is not specified in the task, the value of environment variable
101 C(VMWARE_USER) will be used instead.
102 required: true
103 type: str
104 vcenter_validate_certs:
105 default: true
106 description:
107 - Allows connection when SSL certificates are not valid. Set to C(false) when
108 certificates are not trusted.
109 - If the value is not specified in the task, the value of environment variable
110 C(VMWARE_VALIDATE_CERTS) will be used instead.
111 type: bool
112 author:
113 - Ansible Cloud Team (@ansible-collections)
114 version_added: 0.1.0
115 requirements:
116 - vSphere 7.0.3 or greater
117 - python >= 3.6
118 - aiohttp
119 notes:
120 - Tested on vSphere 7.0.3
121 """
122
123 EXAMPLES = r"""
124 - name: Build a list of all the folders
125 vmware.vmware_rest.vcenter_folder_info:
126 register: my_folders
127
128 - name: Build a list of all the folders with the type VIRTUAL_MACHINE and called vm
129 vmware.vmware_rest.vcenter_folder_info:
130 filter_type: VIRTUAL_MACHINE
131 filter_names:
132 - vm
133 register: my_folders
134 """
135 RETURN = r"""
136 # content generated by the update_return_section callback# task: Build a list of all the folders with the type VIRTUAL_MACHINE and called vm
137 value:
138 description: Build a list of all the folders with the type VIRTUAL_MACHINE and called
139 vm
140 returned: On success
141 sample:
142 - folder: group-v1002
143 name: vm
144 type: VIRTUAL_MACHINE
145 type: list
146 """
147
148
149 # This structure describes the format of the data expected by the end-points
150 PAYLOAD_FORMAT = {
151 "list": {
152 "query": {
153 "datacenters": "datacenters",
154 "folders": "folders",
155 "names": "names",
156 "parent_folders": "parent_folders",
157 "type": "type",
158 },
159 "body": {},
160 "path": {},
161 }
162 } # pylint: disable=line-too-long
163
164 from ansible.module_utils.basic import env_fallback
165 import os
166
167 if os.getenv("VMWARE_ENABLE_TURBO", False):
168 try:
169 from ansible_collections.cloud.common.plugins.module_utils.turbo.module import (
170 AnsibleTurboModule as AnsibleModule,
171 )
172
173 AnsibleModule.collection_name = "vmware.vmware_rest"
174 except ImportError:
175 from ansible.module_utils.basic import AnsibleModule
176 else:
177 from ansible.module_utils.basic import AnsibleModule
178
179 from ansible_collections.vmware.vmware_rest.plugins.module_utils.vmware_rest import (
180 gen_args,
181 open_session,
182 session_timeout,
183 update_changed_flag,
184 )
185
186
187 def prepare_argument_spec():
188 argument_spec = {
189 "vcenter_hostname": dict(
190 type="str",
191 required=True,
192 fallback=(env_fallback, ["VMWARE_HOST"]),
193 ),
194 "vcenter_username": dict(
195 type="str",
196 required=True,
197 fallback=(env_fallback, ["VMWARE_USER"]),
198 ),
199 "vcenter_password": dict(
200 type="str",
201 required=True,
202 no_log=True,
203 fallback=(env_fallback, ["VMWARE_PASSWORD"]),
204 ),
205 "vcenter_validate_certs": dict(
206 type="bool",
207 required=False,
208 default=True,
209 fallback=(env_fallback, ["VMWARE_VALIDATE_CERTS"]),
210 ),
211 "vcenter_rest_log_file": dict(
212 type="str",
213 required=False,
214 fallback=(env_fallback, ["VMWARE_REST_LOG_FILE"]),
215 ),
216 "session_timeout": dict(
217 type="float",
218 required=False,
219 fallback=(env_fallback, ["VMWARE_SESSION_TIMEOUT"]),
220 ),
221 }
222
223 argument_spec["datacenters"] = {
224 "aliases": ["filter_datacenters"],
225 "type": "list",
226 "elements": "str",
227 }
228 argument_spec["folders"] = {
229 "aliases": ["filter_folders"],
230 "type": "list",
231 "elements": "str",
232 }
233 argument_spec["names"] = {
234 "aliases": ["filter_names"],
235 "type": "list",
236 "elements": "str",
237 }
238 argument_spec["parent_folders"] = {"type": "list", "elements": "str"}
239 argument_spec["type"] = {
240 "aliases": ["filter_type"],
241 "type": "str",
242 "choices": ["DATACENTER", "DATASTORE", "HOST", "NETWORK", "VIRTUAL_MACHINE"],
243 }
244
245 return argument_spec
246
247
248 async def main():
249 required_if = list([])
250
251 module_args = prepare_argument_spec()
252 module = AnsibleModule(
253 argument_spec=module_args, required_if=required_if, supports_check_mode=True
254 )
255 if not module.params["vcenter_hostname"]:
256 module.fail_json("vcenter_hostname cannot be empty")
257 if not module.params["vcenter_username"]:
258 module.fail_json("vcenter_username cannot be empty")
259 if not module.params["vcenter_password"]:
260 module.fail_json("vcenter_password cannot be empty")
261 try:
262 session = await open_session(
263 vcenter_hostname=module.params["vcenter_hostname"],
264 vcenter_username=module.params["vcenter_username"],
265 vcenter_password=module.params["vcenter_password"],
266 validate_certs=module.params["vcenter_validate_certs"],
267 log_file=module.params["vcenter_rest_log_file"],
268 )
269 except Exception as err:
270 if hasattr(err, "get_message"):
271 module.fail_json(err.get_message())
272 else:
273 module.fail_json(str(err))
274 result = await entry_point(module, session)
275 module.exit_json(**result)
276
277
278 # template: info_list_and_get_module.j2
279 def build_url(params):
280 import yarl
281
282 _in_query_parameters = PAYLOAD_FORMAT["list"]["query"].keys()
283 return yarl.URL(
284 ("https://{vcenter_hostname}" "/api/vcenter/folder").format(**params)
285 + gen_args(params, _in_query_parameters),
286 encoded=True,
287 )
288
289
290 async def entry_point(module, session):
291 url = build_url(module.params)
292 async with session.get(url, **session_timeout(module.params)) as resp:
293 _json = await resp.json()
294
295 if "value" not in _json: # 7.0.2+
296 _json = {"value": _json}
297
298 return await update_changed_flag(_json, resp.status, "get")
299
300
301 if __name__ == "__main__":
302 import asyncio
303
304 current_loop = asyncio.new_event_loop()
305 try:
306 asyncio.set_event_loop(current_loop)
307 current_loop.run_until_complete(main())
308 finally:
309 current_loop.close()