Debian Codegraph @

ansible_collections/netapp/ontap/plugins/modules/na_ontap_software_update.py

raw
1 #!/usr/bin/python
2
3 # (c) 2018-2025, NetApp, Inc
4 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
5
6 '''
7 na_ontap_software_update
8 '''
9
10 from __future__ import absolute_import, division, print_function
11 __metaclass__ = type
12
13
14 DOCUMENTATION = '''
15 author: NetApp Ansible Team (@carchi8py) <[email protected]>
16 description:
17 - Update ONTAP software
18 - Requires an https connection and is not supported over http
19 extends_documentation_fragment:
20 - netapp.ontap.netapp.na_ontap
21 module: na_ontap_software_update
22 options:
23 state:
24 choices: ['present', 'absent']
25 description:
26 - This module downloads and optionally installs ONTAP software on a cluster.
27 - The software package is deleted after a successful installation.
28 - If the software package is already present, it is not downloaded and not replaced.
29 - When state is absent, the package is deleted from disk.
30 default: present
31 type: str
32 https:
33 description:
34 - Enable and disable https.
35 type: bool
36 default: true
37 nodes:
38 description:
39 - List of nodes to be updated, the nodes have to be a part of a HA Pair.
40 - Requires ONTAP 9.9 with REST.
41 aliases:
42 - node
43 - nodes_to_update
44 type: list
45 elements: str
46 package_version:
47 required: true
48 description:
49 - Specifies the package version to update ONTAP software to, or to be deleted.
50 type: str
51 package_url:
52 type: str
53 description:
54 - Specifies the package URL to download the package.
55 - Required when state is present unless the package is already present on disk.
56 ignore_validation_warning:
57 description:
58 - Allows the update to continue if warnings are encountered during the validation phase.
59 default: False
60 type: bool
61 aliases:
62 - skip_warnings
63 download_only:
64 description:
65 - Allows to download image without update.
66 default: False
67 type: bool
68 version_added: 20.4.0
69 validate_after_download:
70 description:
71 - By default validation is not run after download, as it is already done in the update step.
72 - For MetroCluster systems, the C(download_only) parameter should be run first on one of the sites of the MetroCluster.
73 After the job completes, update the other sites.
74 default: False
75 type: bool
76 version_added: 21.11.0
77 stabilize_minutes:
78 description:
79 - Number of minutes that the update should wait after a takeover or giveback is completed.
80 - Requires ONTAP 9.8 with REST.
81 type: int
82 version_added: 20.6.0
83 timeout:
84 description:
85 - how long to wait for the update to complete, in seconds.
86 default: 1800
87 type: int
88 force_update:
89 description:
90 - force an update, even if package_version matches what is reported as installed.
91 default: false
92 type: bool
93 version_added: 20.11.0
94 short_description: NetApp ONTAP Update Software
95 version_added: 2.7.0
96 notes:
97 - ONTAP expects the nodes to be in HA pairs to perform non disruptive updates.
98 - In a single node setup, the node is updated, and rebooted.
99 - Supports ZAPI and REST.
100 - Support check_mode.
101 '''
102
103 EXAMPLES = """
104 - name: start ONTAP software update Precheck on Metrocluster DR Site B
105 netapp.ontap.na_ontap_software_update:
106 state: present
107 nodes: "{{ nodes }}"
108 package_url: "{{ url }}"
109 download_only: true
110 validate_after_download: true
111 package_version: "9.16.1P4"
112 ignore_validation_warning: true
113 timeout: 36000
114 hostname: "{{ netapp_hostname }}"
115 username: "{{ netapp_username }}"
116 password: "{{ netapp_password }}"
117
118 - name: start ONTAP software update on DR Site A
119 netapp.ontap.na_ontap_software_update:
120 state: present
121 nodes: "{{ nodes }}"
122 package_url: "{{ url }}"
123 package_version: "9.16.1P4"
124 ignore_validation_warning: true
125 timeout: 36000
126 hostname: "{{ netapp_hostname }}"
127 username: "{{ netapp_username }}"
128 password: "{{ netapp_password }}"
129 """
130
131 RETURN = """
132 validation_reports:
133 description: C(validation_reports_after_update) as a string, for backward compatibility.
134 returned: always
135 type: str
136 validation_reports_after_download:
137 description:
138 - List of validation reports, after downloading the software package.
139 - Note that it is different from the validation checks reported after attempting an update.
140 returned: always
141 type: list
142 validation_reports_after_updates:
143 description:
144 - List of validation reports, after attemting to update the software package.
145 returned: always
146 type: list
147 """
148
149 import time
150 import traceback
151 from ansible.module_utils.basic import AnsibleModule
152 from ansible.module_utils._text import to_native
153 import ansible_collections.netapp.ontap.plugins.module_utils.netapp as netapp_utils
154 from ansible_collections.netapp.ontap.plugins.module_utils.netapp import OntapRestAPI
155 from ansible_collections.netapp.ontap.plugins.module_utils.netapp_module import NetAppModule
156 from ansible_collections.netapp.ontap.plugins.module_utils import rest_generic
157
158 HAS_NETAPP_LIB = netapp_utils.has_netapp_lib()
159
160
161 class NetAppONTAPSoftwareUpdate:
162 """
163 Class with ONTAP software update methods
164 """
165
166 def __init__(self):
167 self.argument_spec = netapp_utils.na_ontap_host_argument_spec()
168 self.argument_spec.update(dict(
169 state=dict(required=False, type='str', choices=['present', 'absent'], default='present'),
170 https=dict(required=False, type='bool', default=True),
171 nodes=dict(required=False, type='list', elements='str', aliases=["node", "nodes_to_update"]),
172 package_version=dict(required=True, type='str'),
173 package_url=dict(required=False, type='str'),
174 ignore_validation_warning=dict(required=False, type='bool', default=False, aliases=["skip_warnings"]),
175 download_only=dict(required=False, type='bool', default=False),
176 stabilize_minutes=dict(required=False, type='int'),
177 timeout=dict(required=False, type='int', default=1800),
178 force_update=dict(required=False, type='bool', default=False),
179 validate_after_download=dict(required=False, type='bool', default=False),
180 ))
181
182 self.module = AnsibleModule(
183 argument_spec=self.argument_spec,
184 supports_check_mode=True
185 )
186
187 self.na_helper = NetAppModule()
188 self.parameters = self.na_helper.set_parameters(self.module.params)
189 if self.parameters.get('https') is not True:
190 self.module.fail_json(msg='Error: https parameter must be True')
191 self.validation_reports_after_download = ['only available if validate_after_download is true']
192 self.versions = ['not available with force_update']
193 self.rest_api = OntapRestAPI(self.module)
194 partially_supported_rest_properties = [['stabilize_minutes', (9, 8)], ['nodes', (9, 9)]]
195 self.use_rest = self.rest_api.is_rest_supported_properties(self.parameters, None, partially_supported_rest_properties)
196 if not self.use_rest:
197 if netapp_utils.has_netapp_lib() is False:
198 self.module.fail_json(msg=netapp_utils.netapp_lib_is_required())
199 self.server = netapp_utils.setup_na_ontap_zapi(module=self.module)
200
201 @staticmethod
202 def cluster_image_get_iter():
203 """
204 Compose NaElement object to query current version
205 :return: NaElement object for cluster-image-get-iter with query
206 """
207 cluster_image_get = netapp_utils.zapi.NaElement('cluster-image-get-iter')
208 query = netapp_utils.zapi.NaElement('query')
209 cluster_image_info = netapp_utils.zapi.NaElement('cluster-image-info')
210 query.add_child_elem(cluster_image_info)
211 cluster_image_get.add_child_elem(query)
212 return cluster_image_get
213
214 def cluster_image_get_versions(self):
215 """
216 Get current cluster image versions for each node
217 :return: list of tuples (node_id, node_version) or empty list
218 """
219 if self.use_rest:
220 return self.cluster_image_get_rest('versions')
221 cluster_image_get_iter = self.cluster_image_get_iter()
222 try:
223 result = self.server.invoke_successfully(cluster_image_get_iter, enable_tunneling=True)
224 except netapp_utils.zapi.NaApiError as error:
225 self.module.fail_json(msg='Error fetching cluster image details: %s: %s'
226 % (self.parameters['package_version'], to_native(error)),
227 exception=traceback.format_exc())
228 return ([(image_info.get_child_content('node-id'), image_info.get_child_content('current-version'))
229 for image_info in result.get_child_by_name('attributes-list').get_children()]
230 if result.get_child_by_name('num-records') and int(result.get_child_content('num-records')) > 0 else [])
231
232 def cluster_image_get_for_node(self, node_name):
233 """
234 Get current cluster image info for given node
235 """
236 cluster_image_get = netapp_utils.zapi.NaElement('cluster-image-get')
237 cluster_image_get.add_new_child('node-id', node_name)
238 try:
239 result = self.server.invoke_successfully(cluster_image_get, enable_tunneling=True)
240 except netapp_utils.zapi.NaApiError as error:
241 self.module.fail_json(msg='Error fetching cluster image details for %s: %s'
242 % (node_name, to_native(error)),
243 exception=traceback.format_exc())
244 # return cluster image version
245 image_info = self.na_helper.safe_get(result, ['attributes', 'cluster-image-info'])
246 if image_info:
247 return image_info.get_child_content('node-id'), image_info.get_child_content('current-version')
248 return None, None
249
250 @staticmethod
251 def get_localname(tag):
252 return netapp_utils.zapi.etree.QName(tag).localname
253
254 def cluster_image_update_progress_get(self, ignore_connection_error=True):
255 """
256 Get current cluster image update progress info
257 :return: Dictionary of cluster image update progress if query successful, else return None
258 """
259 cluster_update_progress_get = netapp_utils.zapi.NaElement('cluster-image-update-progress-info')
260 cluster_update_progress_info = {}
261 try:
262 result = self.server.invoke_successfully(cluster_update_progress_get, enable_tunneling=True)
263 except netapp_utils.zapi.NaApiError as error:
264 # return empty dict on error to satisfy package delete upon image update
265 if ignore_connection_error:
266 return cluster_update_progress_info
267 self.module.fail_json(msg='Error fetching cluster image update progress details: %s' % (to_native(error)),
268 exception=traceback.format_exc())
269 # return cluster image update progress details
270 if result.get_child_by_name('attributes').get_child_by_name('ndu-progress-info'):
271 update_progress_info = result.get_child_by_name('attributes').get_child_by_name('ndu-progress-info')
272 cluster_update_progress_info['overall_status'] = update_progress_info.get_child_content('overall-status')
273 cluster_update_progress_info['completed_node_count'] = update_progress_info.\
274 get_child_content('completed-node-count')
275 reports = update_progress_info.get_child_by_name('validation-reports')
276 if reports:
277 cluster_update_progress_info['validation_reports'] = []
278 for report in reports.get_children():
279 checks = {}
280 for check in report.get_children():
281 checks[self.get_localname(check.get_name())] = check.get_content()
282 cluster_update_progress_info['validation_reports'].append(checks)
283 return cluster_update_progress_info
284
285 def cluster_image_update(self):
286 """
287 Update current cluster image
288 """
289 cluster_update_info = netapp_utils.zapi.NaElement('cluster-image-update')
290 cluster_update_info.add_new_child('package-version', self.parameters['package_version'])
291 cluster_update_info.add_new_child('ignore-validation-warning',
292 str(self.parameters['ignore_validation_warning']))
293 if self.parameters.get('stabilize_minutes'):
294 cluster_update_info.add_new_child('stabilize-minutes',
295 self.na_helper.get_value_for_int(False, self.parameters['stabilize_minutes']))
296 if self.parameters.get('nodes'):
297 cluster_nodes = netapp_utils.zapi.NaElement('nodes')
298 for node in self.parameters['nodes']:
299 cluster_nodes.add_new_child('node-name', node)
300 cluster_update_info.add_child_elem(cluster_nodes)
301 try:
302 self.server.invoke_successfully(cluster_update_info, enable_tunneling=True)
303 except netapp_utils.zapi.NaApiError as error:
304 msg = 'Error updating cluster image for %s: %s' % (self.parameters['package_version'], to_native(error))
305 cluster_update_progress_info = self.cluster_image_update_progress_get(ignore_connection_error=True)
306 validation_reports = cluster_update_progress_info.get('validation_reports')
307 if validation_reports is None:
308 validation_reports = self.cluster_image_validate()
309 self.module.fail_json(
310 msg=msg,
311 validation_reports=str(validation_reports),
312 validation_reports_after_download=self.validation_reports_after_download,
313 validation_reports_after_update=validation_reports,
314 exception=traceback.format_exc())
315
316 def cluster_image_package_download(self):
317 """
318 Get current cluster image package download
319 :return: True if package already exists, else return False
320 """
321 cluster_image_package_download_info = netapp_utils.zapi.NaElement('cluster-image-package-download')
322 cluster_image_package_download_info.add_new_child('package-url', self.parameters['package_url'])
323 try:
324 self.server.invoke_successfully(cluster_image_package_download_info, enable_tunneling=True)
325 except netapp_utils.zapi.NaApiError as error:
326 # Error 18408 denotes Package image with the same name already exists
327 if to_native(error.code) == "18408":
328 return self.check_for_existing_package(error)
329 else:
330 self.module.fail_json(msg='Error downloading cluster image package for %s: %s'
331 % (self.parameters['package_url'], to_native(error)),
332 exception=traceback.format_exc())
333 return False
334
335 def cluster_image_package_delete(self):
336 """
337 Delete current cluster image package
338 """
339 if self.use_rest:
340 return self.cluster_image_package_delete_rest()
341 cluster_image_package_delete_info = netapp_utils.zapi.NaElement('cluster-image-package-delete')
342 cluster_image_package_delete_info.add_new_child('package-version', self.parameters['package_version'])
343 try:
344 self.server.invoke_successfully(cluster_image_package_delete_info, enable_tunneling=True)
345 except netapp_utils.zapi.NaApiError as error:
346 self.module.fail_json(msg='Error deleting cluster image package for %s: %s'
347 % (self.parameters['package_version'], to_native(error)),
348 exception=traceback.format_exc())
349
350 def cluster_image_package_download_progress(self):
351 """
352 Get current cluster image package download progress
353 :return: Dictionary of cluster image download progress if query successful, else return None
354 """
355 cluster_image_package_download_progress_info = netapp_utils.zapi.\
356 NaElement('cluster-image-get-download-progress')
357 try:
358 result = self.server.invoke_successfully(
359 cluster_image_package_download_progress_info, enable_tunneling=True)
360 except netapp_utils.zapi.NaApiError as error:
361 self.module.fail_json(msg='Error fetching cluster image package download progress for %s: %s'
362 % (self.parameters['package_url'], to_native(error)),
363 exception=traceback.format_exc())
364 # return cluster image download progress details
365 cluster_download_progress_info = {}
366 if result.get_child_by_name('progress-status'):
367 cluster_download_progress_info['progress_status'] = result.get_child_content('progress-status')
368 cluster_download_progress_info['progress_details'] = result.get_child_content('progress-details')
369 cluster_download_progress_info['failure_reason'] = result.get_child_content('failure-reason')
370 return cluster_download_progress_info
371 return None
372
373 def cluster_image_validate(self):
374 """
375 Validate that NDU is feasible.
376 :return: List of dictionaries
377 """
378 if self.use_rest:
379 return self.cluster_image_validate_rest()
380 cluster_image_validation_info = netapp_utils.zapi.NaElement('cluster-image-validate')
381 cluster_image_validation_info.add_new_child('package-version', self.parameters['package_version'])
382 try:
383 result = self.server.invoke_successfully(
384 cluster_image_validation_info, enable_tunneling=True)
385 except netapp_utils.zapi.NaApiError as error:
386 return 'Error running cluster image validate: %s' % to_native(error)
387 # return cluster validation report
388 cluster_report_info = []
389 if result.get_child_by_name('cluster-image-validation-report-list'):
390 for report in result.get_child_by_name('cluster-image-validation-report-list').get_children():
391 info = self.na_helper.safe_get(report, ['required-action', 'required-action-info'])
392 required_action = {}
393 if info:
394 for action in info.get_children():
395 if action.get_content():
396 required_action[self.get_localname(action.get_name())] = action.get_content()
397 cluster_report_info.append(dict(
398 ndu_check=report.get_child_content('ndu-check'),
399 ndu_status=report.get_child_content('ndu-status'),
400 required_action=required_action
401 ))
402 return cluster_report_info
403
404 def is_update_required(self):
405 ''' return True if at least one node is not at the correct version '''
406 if self.parameters.get('nodes') and not self.use_rest:
407 self.versions = [self.cluster_image_get_for_node(node) for node in self.parameters['nodes']]
408 else:
409 self.versions = self.cluster_image_get_versions()
410 # set comnprehension not supported on 2.6
411 current_versions = set([x[1] for x in self.versions])
412 if len(current_versions) != 1:
413 # mixed set, need to update
414 return True
415 # only update if versions differ
416 return current_versions.pop() != self.parameters['package_version']
417
418 def download_software(self):
419 if self.use_rest:
420 return self.download_software_rest()
421 package_exists = self.cluster_image_package_download()
422 if package_exists is False:
423 cluster_download_progress = self.cluster_image_package_download_progress()
424 while cluster_download_progress is None or cluster_download_progress.get('progress_status') == 'async_pkg_get_phase_running':
425 time.sleep(10)
426 cluster_download_progress = self.cluster_image_package_download_progress()
427 if cluster_download_progress.get('progress_status') != 'async_pkg_get_phase_complete':
428 self.module.fail_json(msg='Error downloading package: %s - installed versions: %s'
429 % (cluster_download_progress['failure_reason'], self.versions))
430
431 def update_software(self):
432 if self.use_rest:
433 return self.update_software_rest()
434 self.cluster_image_update()
435 # delete package once update is completed
436 cluster_update_progress = {}
437 time_left = self.parameters['timeout']
438 polling_interval = 25
439 # assume in_progress if dict is empty
440 while time_left > 0 and cluster_update_progress.get('overall_status', 'in_progress') == 'in_progress':
441 time.sleep(polling_interval)
442 time_left -= polling_interval
443 cluster_update_progress = self.cluster_image_update_progress_get(ignore_connection_error=True)
444
445 if cluster_update_progress.get('overall_status') != 'completed':
446 cluster_update_progress = self.cluster_image_update_progress_get(ignore_connection_error=False)
447
448 validation_reports = cluster_update_progress.get('validation_reports')
449
450 if cluster_update_progress.get('overall_status') == 'completed':
451 self.cluster_image_package_delete()
452 return validation_reports
453
454 if cluster_update_progress.get('overall_status') == 'in_progress':
455 msg = 'Timeout error'
456 action = ' Should the timeout value be increased? Current value is %d seconds.' % self.parameters['timeout']
457 action += ' The software update continues in background.'
458 else:
459 msg = 'Error'
460 action = ''
461 msg += ' updating image using ZAPI: overall_status: %s.' % (cluster_update_progress.get('overall_status', 'cannot get status'))
462 msg += action
463 self.module.fail_json(
464 msg=msg,
465 validation_reports=str(validation_reports),
466 validation_reports_after_download=self.validation_reports_after_download,
467 validation_reports_after_update=validation_reports)
468
469 def cluster_image_get_rest(self, what, fail_on_error=True):
470 """return field information for:
471 - nodes if what == versions
472 - validation_results if what == validation_results
473 - state if what == state
474 - any other field if what is a valid field name
475 call fail_json when there is an error and fail_on_error is True
476 return a tuple (info, error) when fail_on_error is False
477 return info when fail_on_error is Trie
478 """
479 api = 'cluster/software'
480 field = 'nodes' if what == 'versions' else what
481 record, error = rest_generic.get_one_record(self.rest_api, api, fields=field)
482 # record can be empty or these keys may not be present when validation is still in progress
483 optional_fields = ['validation_results']
484 info, error_msg = None, None
485 if error or not record:
486 if error or field not in optional_fields:
487 error_msg = "Error fetching software information for %s: %s" % (field, error or 'no record calling %s' % api)
488 elif what == 'versions' and 'nodes' in record:
489 nodes = self.parameters.get('nodes')
490 if nodes:
491 known_nodes = [node['name'] for node in record['nodes']]
492 unknown_nodes = [node for node in nodes if node not in known_nodes]
493 if unknown_nodes:
494 error_msg = 'Error: node%s not found in cluster: %s.' % ('s' if len(unknown_nodes) > 1 else '', ', '.join(unknown_nodes))
495 info = [(node['name'], node['version']) for node in record['nodes'] if nodes is None or node['name'] in nodes]
496 elif field in record:
497 info = record[field]
498 elif field not in optional_fields:
499 error_msg = "Unexpected results for what: %s, record: %s" % (what, record)
500 if fail_on_error and error_msg:
501 self.module.fail_json(msg=error_msg)
502 return info if fail_on_error else (info, error_msg)
503
504 def check_for_existing_package(self, error):
505 ''' ONTAP returns 'Package image with the same name already exists'
506 if a file with the same name already exists.
507 We need to confirm the version: if the version matches, we're good,
508 otherwise we need to error out.
509 '''
510 versions, error2 = self.cluster_image_packages_get_rest()
511 if self.parameters['package_version'] in versions:
512 return True
513 if versions:
514 self.module.fail_json(msg='Error: another package with the same file name exists: found: %s' % ', '.join(versions))
515 self.module.fail_json(msg='Error: ONTAP reported package already exists, but no package found: %s, getting versions: %s' % (error, error2))
516
517 def cluster_image_download_get_rest(self):
518 api = 'cluster/software/download'
519 field = 'message,state'
520 record, error = rest_generic.get_one_record(self.rest_api, api, fields=field)
521 if record:
522 return record.get('state'), record.get('message'), error
523 return None, None, error
524
525 def download_software_rest(self):
526 api = 'cluster/software/download'
527 body = {
528 'url': self.parameters['package_url']
529 }
530 dummy, error = rest_generic.post_async(self.rest_api, api, body, timeout=0, job_timeout=self.parameters['timeout'])
531 if error:
532 if 'Package image with the same name already exists' in error:
533 return self.check_for_existing_package(error)
534 if 'Software get operation already in progress' in error:
535 self.module.warn("A download is already in progress. Resuming existing download.")
536 return self.wait_for_condition(self.is_download_complete_rest, 'image download state')
537 self.module.fail_json(msg="Error downloading software: %s - current versions: %s" % (error, self.versions))
538 return False
539
540 def is_download_complete_rest(self):
541 state, dummy, error = self.cluster_image_download_get_rest()
542 if error:
543 return None, None, error
544 return state in ['success', 'failure'], state, error
545
546 def cluster_image_validate_rest(self):
547 api = 'cluster/software'
548 body = {
549 'version': self.parameters['package_version']
550 }
551 query = {
552 'validate_only': 'true'
553 }
554 dummy, error = rest_generic.patch_async(self.rest_api, api, None, body, query, timeout=0, job_timeout=self.parameters['timeout'])
555 if error:
556 return "Error validating software: %s" % error
557
558 validation_results = None
559 for __ in range(30):
560 time.sleep(10)
561 validation_results = self.cluster_image_get_rest('validation_results')
562 if validation_results is not None:
563 break
564 return validation_results
565
566 def update_software_rest(self):
567 """install the software and invoke clean up and reporting function
568 """
569 state = self.cluster_image_update_rest()
570 self.post_update_tasks_rest(state)
571
572 def post_update_tasks_rest(self, state):
573 """delete software package when installation is successful
574 report validation_results whether update succeeded or failed
575 """
576 # fetch validation results
577 (validation_reports, error) = self.cluster_image_get_rest('validation_results', fail_on_error=False)
578
579 # success: delete and return
580 if state == 'completed':
581 self.cluster_image_package_delete()
582 return error or validation_reports
583
584 # report error
585 if state == 'in_progress':
586 msg = 'Timeout error'
587 action = ' Should the timeout value be increased? Current value is %d seconds.' % self.parameters['timeout']
588 action += ' The software update continues in background.'
589 else:
590 msg = 'Error'
591 action = ''
592 msg += ' updating image using REST: state: %s.' % state
593 msg += action
594 self.module.fail_json(
595 msg=msg,
596 validation_reports_after_download=self.validation_reports_after_download,
597 validation_reports_after_update=(error or validation_reports))
598
599 def error_is_fatal(self, error):
600 ''' a node may not be available during reboot, or the job may be lost '''
601 if not error:
602 return False
603 self.rest_api.log_debug('transient_error', error)
604 error_messages = [
605 "entry doesn't exist", # job not found
606 "Max retries exceeded with url: /api/cluster/jobs" # connection errors
607 ]
608 return all(error_message not in error for error_message in error_messages)
609
610 def cluster_image_update_rest(self):
611 api = 'cluster/software'
612 body = {
613 'version': self.parameters['package_version']
614 }
615 query = {}
616 params_to_rest = {
617 # module keys to REST keys
618 'ignore_validation_warning': 'skip_warnings',
619 'nodes': 'nodes_to_update',
620 'stabilize_minutes': 'stabilize_minutes',
621 }
622 for (param_key, rest_key) in params_to_rest.items():
623 value = self.parameters.get(param_key)
624 if value is not None:
625 query[rest_key] = ','.join(value) if rest_key == 'nodes_to_update' else value
626 # With ONTAP 9.8, the job persists until the node is rebooted
627 # With ONTAP 9.9, the job returns quickly
628 dummy, error = rest_generic.patch_async(self.rest_api, api, None, body, query=query or None, timeout=0, job_timeout=self.parameters['timeout'])
629 if self.error_is_fatal(error):
630 validation_results, v_error = self.cluster_image_get_rest('validation_results', fail_on_error=False)
631 self.module.fail_json(msg="Error updating software: %s - validation results: %s" % (error, v_error or validation_results))
632
633 return self.wait_for_condition(self.is_update_complete_rest, 'image update state')
634
635 def is_update_complete_rest(self):
636 state, error = self.cluster_image_get_rest('state', fail_on_error=False)
637 if error:
638 return None, None, error
639 return state in ['paused_by_user', 'paused_on_error', 'completed', 'canceled', 'failed'], state, error
640
641 def wait_for_condition(self, is_task_complete, description):
642 ''' loop until a condition is met
643 is_task_complete is a function that returns (is_complete, state, error)
644 if is_complete is True, the condition is met and state is returned
645 if is complete is False, the task is called until a timeout is reached
646 errors are ignored unless there are too many or a timeout is reached
647 '''
648 errors = []
649 for __ in range(1 + self.parameters['timeout'] // 60): # floor division
650 time.sleep(60)
651 is_complete, state, error = is_task_complete()
652 if error:
653 self.rest_api.log_debug('transient_error', error)
654 errors.append(error)
655 if len(errors) < 20:
656 continue
657 break
658 errors = []
659 if is_complete:
660 break
661 if errors:
662 msg = "Error: unable to read %s, using timeout %s." % (description, self.parameters['timeout'])
663 msg += " Last error: %s" % error
664 msg += " All errors: %s" % ' -- '.join(errors)
665 self.module.fail_json(msg=msg)
666 return state
667
668 def cluster_image_packages_get_zapi(self):
669 versions = []
670 packages_obj = netapp_utils.zapi.NaElement('cluster-image-package-local-get-iter')
671 try:
672 result = self.server.invoke_successfully(packages_obj, True)
673 except netapp_utils.zapi.NaApiError as error:
674 self.module.fail_json(msg='Error getting list of local packages: %s' % to_native(error), exception=traceback.format_exc())
675 if result.get_child_by_name('num-records') and int(result.get_child_content('num-records')) > 0:
676 packages_info = result.get_child_by_name('attributes-list')
677 versions = [packages_details.get_child_content('package-version') for packages_details in packages_info.get_children()]
678 return versions, None
679
680 def cluster_image_packages_get_rest(self):
681 if not self.use_rest:
682 return self.cluster_image_packages_get_zapi()
683 api = 'cluster/software/packages'
684 records, error = rest_generic.get_0_or_more_records(self.rest_api, api, fields='version')
685 return [record.get('version') for record in records] if records else [], error
686
687 def cluster_image_package_delete_rest(self):
688 api = 'cluster/software/packages'
689 dummy, error = rest_generic.delete_async(self.rest_api, api, self.parameters['package_version'])
690 if error:
691 self.module.fail_json(msg='Error deleting cluster software package for %s: %s' % (self.parameters['package_version'], error))
692
693 def apply(self):
694 """
695 Apply action to update ONTAP software
696 """
697 # TODO: cluster image update only works for HA configurations.
698 # check if node image update can be used for other cases.
699 versions, error = self.cluster_image_packages_get_rest()
700 already_downloaded = not error and self.parameters['package_version'] in versions
701 if self.parameters['state'] == 'absent':
702 if error:
703 self.module.fail_json(msg='Error: unable to fetch local package list: %s' % error)
704 changed = already_downloaded
705 else:
706 if already_downloaded:
707 self.module.warn('Package %s is already present, skipping download.' % self.parameters['package_version'])
708 elif not self.parameters.get('package_url'):
709 self.module.fail_json(msg='Error: packague_url is a required parameter to download the software package.')
710 changed = self.parameters['force_update'] or self.is_update_required()
711 validation_reports_after_update = ['only available after update']
712
713 results = {}
714 if not self.module.check_mode and changed:
715 if self.parameters['state'] == 'absent':
716 self.cluster_image_package_delete()
717 else:
718 if not already_downloaded:
719 already_downloaded = self.download_software()
720 if self.parameters['validate_after_download']:
721 self.validation_reports_after_download = self.cluster_image_validate()
722 if self.parameters['download_only']:
723 changed = not already_downloaded
724 else:
725 validation_reports_after_update = self.update_software()
726 results = {
727 'validation_reports': str(validation_reports_after_update),
728 'validation_reports_after_download': self.validation_reports_after_download,
729 'validation_reports_after_update': validation_reports_after_update
730 }
731
732 self.module.exit_json(changed=changed, **results)
733
734
735 def main():
736 """Execute action"""
737 package_obj = NetAppONTAPSoftwareUpdate()
738 package_obj.apply()
739
740
741 if __name__ == '__main__':
742 main()