Debian Codegraph @

ansible_collections/vmware/vmware_rest/plugins/modules/vcenter_ovf_libraryitem.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_ovf_libraryitem
12 short_description: Creates a library item in content library from a virtual machine
13 or virtual appliance
14 description: This operation creates a library item in content library whose content
15 is an OVF package derived from a source virtual machine or virtual appliance,
16 using the supplied create specification. For an existing library item whose
17 content is updated by this operation, the original content is overwritten. Meta
18 data such as name and description is not updated for the existing library item.
19 PLease see the examples for a workaround if you need to update the description.
20 options:
21 client_token:
22 description:
23 - Client-generated token used to retry a request if the client fails to get
24 a response from the server. If the original request succeeded, the result
25 of that request will be returned, otherwise the operation will be retried.
26 - If unset, the server will create a token.
27 type: str
28 create_spec:
29 description:
30 - Information used to create the OVF package from the source virtual machine
31 or virtual appliance. Required with I(state=['present'])
32 - 'Valid attributes are:'
33 - ' - C(name) (str): Name to use in the OVF descriptor stored in the library
34 item.'
35 - If unset, the server will use source's current name. (['present'])
36 - ' - C(description) (str): Description to use in the OVF descriptor stored
37 in the library item.'
38 - If unset, the server will use source's current annotation. (['present'])
39 - ' - C(flags) (list): Flags to use for OVF package creation. The supported
40 flags can be obtained using ExportFlag.list.'
41 - If unset, no flags will be used. (['present'])
42 type: dict
43 deployment_spec:
44 description:
45 - Specification of how the OVF package should be deployed to the target. Required
46 with I(state=['deploy'])
47 - 'Valid attributes are:'
48 - ' - C(name) (str): Name assigned to the deployed target virtual machine
49 or virtual appliance.'
50 - If unset, the server will use the name from the OVF package. (['deploy'])
51 - ' - C(annotation) (str): Annotation assigned to the deployed target virtual
52 machine or virtual appliance.'
53 - If unset, the server will use the annotation from the OVF package. (['deploy'])
54 - ' - C(accept_all_EULA) (bool): Whether to accept all End User License Agreements.
55 See I() ([''deploy''])'
56 - ' This key is required with [''deploy''].'
57 - ' - C(network_mappings) (dict): Specification of the target network to use
58 for sections of type ovf:NetworkSection in the OVF descriptor. The key
59 in the map is the section identifier of the ovf:NetworkSection section
60 in the OVF descriptor and the value is the target network to be used for
61 deployment.'
62 - If unset, the server will choose a network mapping.
63 - When clients pass a value of this structure as a parameter, the value in
64 the field map must be the id of a resource returned by M(vmware.vmware_rest.vcenter_network_info).
65 (['deploy'])
66 - ' - C(storage_mappings) (dict): Specification of the target storage to use
67 for sections of type vmw:StorageGroupSection in the OVF descriptor. The
68 key in the map is the section identifier of the ovf:StorageGroupSection
69 section in the OVF descriptor and the value is the target storage specification
70 to be used for deployment. See I()'
71 - If unset, the server will choose a storage mapping. (['deploy'])
72 - ' - C(storage_provisioning) (str): This option defines the virtual disk
73 provisioning types that can be set for a disk on the target platform.
74 ([''deploy''])'
75 - ' - Accepted values:'
76 - ' - eagerZeroedThick'
77 - ' - thick'
78 - ' - thin'
79 - ' - C(storage_profile_id) (str): Default storage profile to use for all
80 sections of type vmw:StorageSection in the OVF descriptor.'
81 - If unset, the server will choose the default profile.
82 - When clients pass a value of this structure as a parameter, the field must
83 be the id of a resource returned by M(vmware.vmware_rest.vcenter_storage_policies_info).
84 (['deploy'])
85 - ' - C(locale) (str): The locale to use for parsing the OVF descriptor.'
86 - If unset, the server locale will be used. (['deploy'])
87 - ' - C(flags) (list): Flags to be use for deployment. The supported flag
88 values can be obtained using ImportFlag.list.'
89 - If unset, no flags will be used. (['deploy'])
90 - ' - C(additional_parameters) (list): Additional OVF parameters that may
91 be needed for the deployment. Additional OVF parameters may be required
92 by the OVF descriptor of the OVF package in the library item. Examples
93 of OVF parameters that can be specified through this field include, but
94 are not limited to: '
95 - ' - DeploymentOptionParams'
96 - ' - ExtraConfigParams'
97 - ' - IpAllocationParams'
98 - ' - PropertyParams'
99 - ' - ScaleOutParams'
100 - ' - VcenterExtensionParams'
101 - ' '
102 - If unset, the server will choose default settings for all parameters necessary
103 for the LibraryItem.deploy operation. See LibraryItem.deploy.
104 - When clients pass a value of this structure as a parameter, the field must
105 contain all the attributes defined in OvfParams. (['deploy'])
106 - ' - C(default_datastore_id) (str): Default datastore to use for all sections
107 of type vmw:StorageSection in the OVF descriptor.'
108 - If unset, the server will choose the default datastore.
109 - When clients pass a value of this structure as a parameter, the field must
110 be the id of a resource returned by M(vmware.vmware_rest.vcenter_datastore_info).
111 (['deploy'])
112 - ' - C(vm_config_spec) (dict): The I(resource_pool_deployment_spec).vm-config-spec
113 is used for virtual machine configuration settings including hardware
114 specifications to use in place of the OVF descriptor. If set, the OVF
115 descriptor acts as a disk descriptor. Fields in the I(resource_pool_deployment_spec)
116 parameters such as I(resource_pool_deployment_spec).name that overlap
117 with settings in the I(resource_pool_deployment_spec).vm-config-spec are
118 not overridden and will continue to be used. Similarly, storage settings
119 in the I(resource_pool_deployment_spec) that affect the disks on the virtual
120 machine namely I(resource_pool_deployment_spec).storage-mappings, I(resource_pool_deployment_spec).storage-profile-id,
121 I(resource_pool_deployment_spec).storage-provisioning and I(resource_pool_deployment_spec).default-datastore-id
122 will also be honored.'
123 - If unset, the relevant virtual machine specifications in the OVF descriptor
124 of the OVF template will be used. (['deploy'])
125 - ' - Accepted keys:'
126 - ' - provider (string): The I(vm_config_spec_provider) is used to provide
127 the optional I(vm_config_spec) used when deploying an OVF template.'
128 - 'Accepted value for this field:'
129 - ' - C(XML)'
130 - ' - xml (string): The I(xml) is a conditional configuration made available
131 upon selecting the XML. It is used to pass in a vim.vm.ConfigSpec for
132 a virtual machine that has been serialized to XML and base64 encoded.'
133 - This field is optional and it is only relevant when the value of I(provider)
134 is XML.
135 type: dict
136 ovf_library_item_id:
137 description:
138 - Identifier of the content library item containing the OVF package to be
139 deployed.
140 - The parameter must be the id of a resource returned by M(vmware.vmware_rest.content_library_item_info).
141 Required with I(state=['deploy', 'filter'])
142 type: str
143 session_timeout:
144 description:
145 - 'Timeout settings for client session. '
146 - 'The maximal number of seconds for the whole operation including connection
147 establishment, request sending and response. '
148 - The default value is 300s.
149 type: float
150 version_added: 2.1.0
151 source:
152 description:
153 - Identifier of the virtual machine or virtual appliance to use as the source.
154 Required with I(state=['present'])
155 - 'Valid attributes are:'
156 - ' - C(type) (str): Type of the deployable resource.'
157 - When clients pass a value of this structure as a parameter, the field must
158 be one of VirtualMachine or VirtualApp. (['present'])
159 - ' This key is required with [''present''].'
160 - ' - C(id) (str): Identifier of the deployable resource.'
161 - 'When clients pass a value of this structure as a parameter, the field must
162 be an identifier for one of these resource types: VirtualMachine or VirtualApp.
163 ([''present''])'
164 - ' This key is required with [''present''].'
165 type: dict
166 state:
167 choices:
168 - deploy
169 - filter
170 - present
171 default: present
172 description: []
173 type: str
174 target:
175 description:
176 - Specification of the target content library and library item. This parameter
177 is mandatory.
178 - 'Valid attributes are:'
179 - ' - C(library_id) (str): Identifier of the library in which a new library
180 item should be created. This field is not used if the I(library_item_id)
181 field is specified.'
182 - 'This field is currently required. '
183 - ' In the future, if unset, the I(library_item_id) field must be specified. '
184 - ''
185 - When clients pass a value of this structure as a parameter, the field must
186 be the id of a resource returned by M(vmware.vmware_rest.content_library_info).
187 (['present'])
188 - ' - C(library_item_id) (str): Identifier of the library item that should
189 be should be updated.'
190 - If unset, a new library item will be created. The I(library_id) field must
191 be specified if this field is set.
192 - When clients pass a value of this structure as a parameter, the field must
193 be the id of a resource returned by M(vmware.vmware_rest.content_library_item_info).
194 (['present'])
195 - ' - C(resource_pool_id) (str): Identifier of the resource pool to which
196 the virtual machine or virtual appliance should be attached.'
197 - When clients pass a value of this structure as a parameter, the field must
198 be the id of a resource returned by M(vmware.vmware_rest.vcenter_resourcepool_info).
199 (['deploy', 'filter'])
200 - ' This key is required with [''deploy'', ''filter''].'
201 - ' - C(host_id) (str): Identifier of the target host on which the virtual
202 machine or virtual appliance will run. The target host must be a member
203 of the cluster that contains the resource pool identified by I()'
204 - If unset, the server will automatically select a target host from the resource
205 pool if I(resource_pool_id) is a stand-alone host or a cluster with Distributed
206 Resource Scheduling (DRS) enabled.
207 - When clients pass a value of this structure as a parameter, the field must
208 be the id of a resource returned by M(vmware.vmware_rest.vcenter_host_info).
209 (['deploy', 'filter'])
210 - ' - C(folder_id) (str): Identifier of the vCenter folder that should contain
211 the virtual machine or virtual appliance. The folder must be virtual machine
212 folder.'
213 - If unset, the server will choose the deployment folder.
214 - When clients pass a value of this structure as a parameter, the field must
215 be the id of a resource returned by M(vmware.vmware_rest.vcenter_folder_info).
216 (['deploy', 'filter'])
217 required: true
218 type: dict
219 vcenter_hostname:
220 description:
221 - The hostname or IP address of the vSphere vCenter
222 - If the value is not specified in the task, the value of environment variable
223 C(VMWARE_HOST) will be used instead.
224 required: true
225 type: str
226 vcenter_password:
227 description:
228 - The vSphere vCenter password
229 - If the value is not specified in the task, the value of environment variable
230 C(VMWARE_PASSWORD) will be used instead.
231 required: true
232 type: str
233 vcenter_rest_log_file:
234 description:
235 - 'You can use this optional parameter to set the location of a log file. '
236 - 'This file will be used to record the HTTP REST interaction. '
237 - 'The file will be stored on the host that runs the module. '
238 - 'If the value is not specified in the task, the value of '
239 - environment variable C(VMWARE_REST_LOG_FILE) will be used instead.
240 type: str
241 vcenter_username:
242 description:
243 - The vSphere vCenter username
244 - If the value is not specified in the task, the value of environment variable
245 C(VMWARE_USER) will be used instead.
246 required: true
247 type: str
248 vcenter_validate_certs:
249 default: true
250 description:
251 - Allows connection when SSL certificates are not valid. Set to C(false) when
252 certificates are not trusted.
253 - If the value is not specified in the task, the value of environment variable
254 C(VMWARE_VALIDATE_CERTS) will be used instead.
255 type: bool
256 author:
257 - Ansible Cloud Team (@ansible-collections)
258 version_added: 2.0.0
259 requirements:
260 - vSphere 7.0.3 or greater
261 - python >= 3.6
262 - aiohttp
263 notes:
264 - Tested on vSphere 7.0.3
265 """
266
267 EXAMPLES = r"""
268 ---
269 - name: Export the VM as an OVF on the library
270 vmware.vmware_rest.vcenter_ovf_libraryitem:
271 session_timeout: 2900
272 source:
273 type: VirtualMachine
274 id: "{{ lookup('vmware.vmware_rest.vm_moid', 'My VM') }}"
275 target:
276 library_id: 1111111-1111111-1111111-111111
277 create_spec:
278 name: Golden Image
279 description: A golden image for templating
280 flags: []
281 state: present
282
283 # Due to an issue with the generated module code and the REST API limitations,
284 # updating existing template descriptions must be done by removing the create_spec.name
285 # attribute.
286 #
287 # Note that omitting the create_spec.name attribute will force the OVF template to be replaced.
288 # Thus, the second task will always report as changed
289 - name: Export the VM as an OVF on the library
290 vmware.vmware_rest.vcenter_ovf_libraryitem:
291 session_timeout: 2900
292 source:
293 type: VirtualMachine
294 id: "{{ lookup('vmware.vmware_rest.vm_moid', 'My VM') }}"
295 target:
296 library_id: 1111111-1111111-1111111-111111
297 create_spec:
298 name: Golden Image
299 description: Some unhelpful description
300 flags: []
301 state: present
302 register: _ovf_item
303
304 - name: Update The Template Description
305 vmware.vmware_rest.vcenter_ovf_libraryitem:
306 session_timeout: 2900
307 source:
308 type: VirtualMachine
309 id: "{{ lookup('vmware.vmware_rest.vm_moid', 'My VM') }}"
310 target:
311 library_id: 1111111-1111111-1111111-111111
312 library_item_id: "{{ _ovf_item.value.ovf_library_item_id }}"
313 create_spec:
314 description: A much better description for this template
315 flags: []
316 """
317
318 RETURN = r"""
319 id:
320 description: The ID of the OVF template
321 returned: On success and not changed
322 type: str
323 sample:
324 id: "3994f858-2d45-4dac-b407-0643a29308bd"
325
326
327 value:
328 description: Details about the OVF if it was created, or an ID if the OVF was updated
329 returned: On success
330 type: dict
331 sample:
332 # Values returned if OVF already exists and is unchanged
333 cached: true
334 certificate_verification_info:
335 status: "INTERNAL"
336 content_version: "3"
337 creation_time: "2024-11-26T20:08:07.108Z"
338 description: "an OVF example"
339 id: "3994f858-2d45-4dac-b407-0643a29308bd"
340 last_modified_time: "2024-12-02T15:43:24.882Z"
341 library_id: "fbcc0f38-b7d9-4243-95f6-fb28f1ab35a6"
342 metadata_version: "1"
343 name: "golden"
344 security_compliance: true
345 size: 875576749
346 type: "ovf"
347 version: "1"
348
349 # Values returned if OVF is changed
350 error:
351 errors: []
352 information: []
353 warnings: []
354 ovf_library_item_id: "3994f858-2d45-4dac-b407-0643a29308bd"
355 succeeded: true
356 """
357
358
359 # This structure describes the format of the data expected by the end-points
360 PAYLOAD_FORMAT = {
361 "filter": {
362 "query": {},
363 "body": {"target": "target"},
364 "path": {"ovf_library_item_id": "ovf_library_item_id"},
365 },
366 "create": {
367 "query": {"client_token": "client_token"},
368 "body": {"create_spec": "create_spec", "source": "source", "target": "target"},
369 "path": {},
370 },
371 "deploy": {
372 "query": {"client_token": "client_token"},
373 "body": {"deployment_spec": "deployment_spec", "target": "target"},
374 "path": {"ovf_library_item_id": "ovf_library_item_id"},
375 },
376 } # pylint: disable=line-too-long
377
378 from ansible.module_utils.basic import env_fallback
379 import os
380
381 if os.getenv("VMWARE_ENABLE_TURBO", False):
382 try:
383 from ansible_collections.cloud.common.plugins.module_utils.turbo.module import (
384 AnsibleTurboModule as AnsibleModule,
385 )
386
387 AnsibleModule.collection_name = "vmware.vmware_rest"
388 except ImportError:
389 from ansible.module_utils.basic import AnsibleModule
390 else:
391 from ansible.module_utils.basic import AnsibleModule
392
393 from ansible_collections.vmware.vmware_rest.plugins.module_utils.vmware_rest import (
394 exists,
395 gen_args,
396 get_device_info,
397 get_subdevice_type,
398 open_session,
399 prepare_payload,
400 session_timeout,
401 update_changed_flag,
402 )
403
404
405 def prepare_argument_spec():
406 argument_spec = {
407 "vcenter_hostname": dict(
408 type="str",
409 required=True,
410 fallback=(env_fallback, ["VMWARE_HOST"]),
411 ),
412 "vcenter_username": dict(
413 type="str",
414 required=True,
415 fallback=(env_fallback, ["VMWARE_USER"]),
416 ),
417 "vcenter_password": dict(
418 type="str",
419 required=True,
420 no_log=True,
421 fallback=(env_fallback, ["VMWARE_PASSWORD"]),
422 ),
423 "vcenter_validate_certs": dict(
424 type="bool",
425 required=False,
426 default=True,
427 fallback=(env_fallback, ["VMWARE_VALIDATE_CERTS"]),
428 ),
429 "vcenter_rest_log_file": dict(
430 type="str",
431 required=False,
432 fallback=(env_fallback, ["VMWARE_REST_LOG_FILE"]),
433 ),
434 "session_timeout": dict(
435 type="float",
436 required=False,
437 fallback=(env_fallback, ["VMWARE_SESSION_TIMEOUT"]),
438 ),
439 }
440
441 argument_spec["client_token"] = {"no_log": True, "type": "str"}
442 argument_spec["create_spec"] = {"type": "dict"}
443 argument_spec["deployment_spec"] = {"type": "dict"}
444 argument_spec["ovf_library_item_id"] = {"type": "str"}
445 argument_spec["source"] = {"type": "dict"}
446 argument_spec["state"] = {
447 "type": "str",
448 "choices": ["deploy", "filter", "present"],
449 "default": "present",
450 }
451 argument_spec["target"] = {"required": True, "type": "dict"}
452
453 return argument_spec
454
455
456 async def main():
457 required_if = list([])
458
459 module_args = prepare_argument_spec()
460 module = AnsibleModule(
461 argument_spec=module_args, required_if=required_if, supports_check_mode=False
462 )
463 if not module.params["vcenter_hostname"]:
464 module.fail_json("vcenter_hostname cannot be empty")
465 if not module.params["vcenter_username"]:
466 module.fail_json("vcenter_username cannot be empty")
467 if not module.params["vcenter_password"]:
468 module.fail_json("vcenter_password cannot be empty")
469 try:
470 session = await open_session(
471 vcenter_hostname=module.params["vcenter_hostname"],
472 vcenter_username=module.params["vcenter_username"],
473 vcenter_password=module.params["vcenter_password"],
474 validate_certs=module.params["vcenter_validate_certs"],
475 log_file=module.params["vcenter_rest_log_file"],
476 )
477 except Exception as err:
478 if hasattr(err, "get_message"):
479 module.fail_json(err.get_message())
480 else:
481 module.fail_json(str(err))
482 result = await entry_point(module, session)
483 module.exit_json(**result)
484
485
486 # template: default_module.j2
487 def build_url(params):
488 return ("https://{vcenter_hostname}" "/api/vcenter/ovf/library-item").format(
489 **params
490 )
491
492
493 async def entry_point(module, session):
494
495 if module.params["state"] == "present":
496 if "_create" in globals():
497 operation = "create"
498 else:
499 operation = "update"
500 elif module.params["state"] == "absent":
501 operation = "delete"
502 else:
503 operation = module.params["state"]
504
505 func = globals()["_" + operation]
506
507 return await func(module.params, session)
508
509
510 async def _create(params, session):
511
512 library_id = (
513 params["target"]["library_id"] if "library_id" in params["target"] else None
514 )
515 lookup_url = f"https://{params['vcenter_hostname']}/api/content/library/item?library_id={library_id}"
516 per_id_url = "https://{vcenter_hostname}/api/content/library/item".format(**params)
517 uniquity_keys = None
518
519 def comp_func(device):
520 return device["value"]["name"] == params["create_spec"].get("name")
521
522 _json = None
523
524 if not _json and (uniquity_keys or comp_func):
525 _json = await exists(
526 params,
527 session,
528 url=lookup_url,
529 uniquity_keys=uniquity_keys,
530 per_id_url=per_id_url,
531 comp_func=comp_func,
532 )
533
534 if _json:
535 if "value" not in _json: # 7.0.2+
536 _json = {"value": _json}
537 if "_update" in globals():
538 params["None"] = _json["id"]
539 return await globals()["_update"](params, session)
540
541 return await update_changed_flag(_json, 200, "get")
542
543 payload = prepare_payload(params, PAYLOAD_FORMAT["create"])
544 _url = ("https://{vcenter_hostname}" "/api/vcenter/ovf/library-item").format(
545 **params
546 )
547 async with session.post(_url, json=payload, **session_timeout(params)) as resp:
548 if resp.status == 500:
549 text = await resp.text()
550 raise Exception(f"Request has failed: status={resp.status}, {text}")
551 try:
552 if resp.headers["Content-Type"] == "application/json":
553 _json = await resp.json()
554 except KeyError:
555 _json = {}
556
557 if (resp.status in [200, 201]) and "error" not in _json:
558 if isinstance(_json, str): # 7.0.2 and greater
559 _id = _json # TODO: fetch the object
560 elif isinstance(_json, dict) and "value" not in _json:
561 _id = list(_json["value"].values())[0]
562 elif isinstance(_json, dict) and "value" in _json:
563 _id = _json["value"]
564 _json_device_info = await get_device_info(session, _url, _id)
565 if _json_device_info:
566 _json = _json_device_info
567
568 return await update_changed_flag(_json, resp.status, "create")
569
570
571 async def _deploy(params, session):
572 _in_query_parameters = PAYLOAD_FORMAT["deploy"]["query"].keys()
573 payload = prepare_payload(params, PAYLOAD_FORMAT["deploy"])
574 subdevice_type = get_subdevice_type(
575 "/api/vcenter/ovf/library-item/{ovf_library_item_id}?action=deploy"
576 )
577 if subdevice_type and not params[subdevice_type]:
578 _json = await exists(params, session, build_url(params))
579 if _json:
580 params[subdevice_type] = _json["id"]
581 _url = (
582 "https://{vcenter_hostname}"
583 # aa
584 "/api/vcenter/ovf/library-item/{ovf_library_item_id}?action=deploy"
585 ).format(**params) + gen_args(params, _in_query_parameters)
586 async with session.post(_url, json=payload, **session_timeout(params)) as resp:
587 try:
588 if resp.headers["Content-Type"] == "application/json":
589 _json = await resp.json()
590 except KeyError:
591 _json = {}
592 if "value" not in _json: # 7.0.2
593 _json = {"value": _json}
594
595 return await update_changed_flag(_json, resp.status, "deploy")
596
597
598 async def _filter(params, session):
599 _in_query_parameters = PAYLOAD_FORMAT["filter"]["query"].keys()
600 payload = prepare_payload(params, PAYLOAD_FORMAT["filter"])
601 subdevice_type = get_subdevice_type(
602 "/api/vcenter/ovf/library-item/{ovf_library_item_id}?action=filter"
603 )
604 if subdevice_type and not params[subdevice_type]:
605 _json = await exists(params, session, build_url(params))
606 if _json:
607 params[subdevice_type] = _json["id"]
608 _url = (
609 "https://{vcenter_hostname}"
610 # aa
611 "/api/vcenter/ovf/library-item/{ovf_library_item_id}?action=filter"
612 ).format(**params) + gen_args(params, _in_query_parameters)
613 async with session.post(_url, json=payload, **session_timeout(params)) as resp:
614 try:
615 if resp.headers["Content-Type"] == "application/json":
616 _json = await resp.json()
617 except KeyError:
618 _json = {}
619 if "value" not in _json: # 7.0.2
620 _json = {"value": _json}
621
622 return await update_changed_flag(_json, resp.status, "filter")
623
624
625 if __name__ == "__main__":
626 import asyncio
627
628 current_loop = asyncio.new_event_loop()
629 try:
630 asyncio.set_event_loop(current_loop)
631 current_loop.run_until_complete(main())
632 finally:
633 current_loop.close()