Debian Codegraph @

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

raw
1 #!/usr/bin/python
2 """
3 create Autosupport module to enable, disable or modify
4 """
5
6 # (c) 2018-2025, NetApp, Inc
7 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
8 from __future__ import absolute_import, division, print_function
9 __metaclass__ = type
10
11 DOCUMENTATION = """
12 module: na_ontap_autosupport
13 short_description: NetApp ONTAP autosupport
14 extends_documentation_fragment:
15 - netapp.ontap.netapp.na_ontap
16 version_added: 2.7.0
17 description:
18 - Enable/Disable Autosupport
19 author: NetApp Ansible Team (@carchi8py) <[email protected]>
20 options:
21 state:
22 description:
23 - Specifies whether the AutoSupport daemon is to be enabled or disabled.
24 - When this setting is absent, delivery of all AutoSupport messages is turned off.
25 choices: ['present', 'absent']
26 type: str
27 default: present
28 node_name:
29 description:
30 - The name of the filer that owns the AutoSupport Configuration.
31 - Supported only with ZAPI.
32 type: str
33 transport:
34 description:
35 - The name of the transport protocol used to deliver AutoSupport messages.
36 choices: ['http', 'https', 'smtp']
37 type: str
38 noteto:
39 description:
40 - Specifies up to five recipients of short AutoSupport e-mail messages.
41 - Supported only with ZAPI.
42 type: list
43 elements: str
44 post_url:
45 description:
46 - The URL used to deliver AutoSupport messages via HTTP POST.
47 - Supported only with ZAPI.
48 type: str
49 mail_hosts:
50 description:
51 - List of mail server(s) used to deliver AutoSupport messages via SMTP.
52 - Both host names and IP addresses may be used as valid input.
53 type: list
54 elements: str
55 support:
56 description:
57 - Specifies whether AutoSupport notification to technical support is enabled.
58 type: bool
59 from_address:
60 description:
61 - specify the e-mail address from which the node sends AutoSupport messages.
62 version_added: 2.8.0
63 type: str
64 partner_addresses:
65 description:
66 - Specifies up to five partner vendor recipients of full AutoSupport e-mail messages.
67 version_added: 2.8.0
68 type: list
69 elements: str
70 to_addresses:
71 description:
72 - Specifies up to five recipients of full AutoSupport e-mail messages.
73 version_added: 2.8.0
74 type: list
75 elements: str
76 proxy_url:
77 description:
78 - specify an HTTP or HTTPS proxy if the 'transport' parameter is set to HTTP or HTTPS and your organization uses a proxy.
79 - If authentication is required, use the format "username:password@host:port".
80 version_added: 2.8.0
81 type: str
82 hostname_in_subject:
83 description:
84 - Specify whether the hostname of the node is included in the subject line of the AutoSupport message.
85 - Supported only with ZAPI.
86 type: bool
87 version_added: 2.8.0
88 nht_data_enabled:
89 description:
90 - Specify whether the disk health data is collected as part of the AutoSupport data.
91 - Supported only with ZAPI.
92 type: bool
93 version_added: '21.5.0'
94 perf_data_enabled:
95 description:
96 - Specify whether the performance data is collected as part of the AutoSupport data.
97 - Supported only with ZAPI.
98 type: bool
99 version_added: '21.5.0'
100 retry_count:
101 description:
102 - Specify the maximum number of delivery attempts for an AutoSupport message.
103 - Supported only with ZAPI.
104 type: int
105 version_added: '21.5.0'
106 reminder_enabled:
107 description:
108 - Specify whether AutoSupport reminders are enabled or disabled.
109 - Supported only with ZAPI.
110 type: bool
111 version_added: '21.5.0'
112 max_http_size:
113 description:
114 - Specify delivery size limit for the HTTP transport protocol (in bytes).
115 - Supported only with ZAPI.
116 type: int
117 version_added: '21.5.0'
118 max_smtp_size:
119 description:
120 - Specify delivery size limit for the SMTP transport protocol (in bytes).
121 - Supported only with ZAPI.
122 type: int
123 version_added: '21.5.0'
124 private_data_removed:
125 description:
126 - Specify the removal of customer-supplied data.
127 - Supported only with ZAPI.
128 type: bool
129 version_added: '21.5.0'
130 local_collection_enabled:
131 description:
132 - Specify whether collection of AutoSupport data when the AutoSupport daemon is disabled.
133 - Supported only with ZAPI.
134 type: bool
135 version_added: '21.5.0'
136 ondemand_enabled:
137 description:
138 - Specify whether the AutoSupport OnDemand Download feature is enabled.
139 type: bool
140 version_added: '21.5.0'
141 validate_digital_certificate:
142 description:
143 - When set to true each node will validate the digital certificates that it receives.
144 - Supported only with ZAPI.
145 type: bool
146 version_added: '21.5.0'
147 is_minimal:
148 description:
149 - Specifies whether the system information is collected in compliant form, to remove private data or in complete form, to enhance diagnostics.
150 - Supported only with REST.
151 type: bool
152 version_added: '23.2.0'
153 smtp_encryption:
154 description:
155 - The encryption protocol used to deliver AutoSupport messages via SMTP to the configured mail_hosts.
156 - Supported only with REST.
157 choices: ['none', 'start_tls']
158 type: str
159 version_added: '23.2.0'
160 force:
161 description:
162 - Set the force flag to true to modify some of the AutoSupport configurations that are otherwise blocked when the automatic update feature is enabled.
163 - Without this flag set to true, an attempt to disable AutoSupport, modify the transport to SMTP,
164 or disable the AutoSupport OnDemand feature fails if the automatic update feature is enabled.
165 type: bool
166 version_added: '23.2.0'
167 """
168
169 EXAMPLES = """
170 - name: Enable autosupport - ZAPI
171 netapp.ontap.na_ontap_autosupport:
172 hostname: "{{ netapp_hostname }}"
173 username: "{{ netapp_username }}"
174 password: "{{ netapp_password }}"
175 state: present
176 node_name: test
177 transport: https
178 noteto: [email protected],[email protected]
179 mail_hosts: 1.2.3.4,5.6.7.8
180 support: false
181 post_url: url/1.0/post
182
183 - name: Modify autosupport proxy_url with password - ZAPI
184 netapp.ontap.na_ontap_autosupport:
185 hostname: "{{ netapp_hostname }}"
186 username: "{{ netapp_username }}"
187 password: "{{ netapp_password }}"
188 state: present
189 node_name: test
190 transport: https
191 proxy_url: username:[email protected]:8000
192
193 - name: Modify autosupport proxy_url without password - ZAPI
194 netapp.ontap.na_ontap_autosupport:
195 hostname: "{{ netapp_hostname }}"
196 username: "{{ netapp_username }}"
197 password: "{{ netapp_password }}"
198 state: present
199 node_name: test
200 transport: https
201 proxy_url: [email protected]:8000
202
203 - name: Disable autosupport - ZAPI
204 netapp.ontap.na_ontap_autosupport:
205 hostname: "{{ netapp_hostname }}"
206 username: "{{ netapp_username }}"
207 password: "{{ netapp_password }}"
208 state: absent
209 node_name: test
210
211 - name: Enable autosupport - REST
212 netapp.ontap.na_ontap_autosupport:
213 hostname: "{{ netapp_hostname }}"
214 username: "{{ netapp_username }}"
215 password: "{{ netapp_password }}"
216 transport: https
217 mail_hosts: 1.2.3.4,5.6.7.8
218 proxy_url: proxyhost.local.com
219 to_addresses: [email protected]
220 from_address: [email protected]
221 ondemand_enabled: true
222 support: true
223 state: present
224 force: true
225 is_minimal: true
226 smtp_encryption: none
227 partner_addresses: [email protected]
228
229 - name: Modify autosupport - REST
230 netapp.ontap.na_ontap_autosupport:
231 hostname: "{{ netapp_hostname }}"
232 username: "{{ netapp_username }}"
233 password: "{{ netapp_password }}"
234 transport: smtp
235 mail_hosts: 1.2.3.4:25
236 proxy_url: proxyhost.local.com
237 to_addresses: [email protected],[email protected]
238 from_address: [email protected]
239 ondemand_enabled: false
240 support: false
241 state: present
242 is_minimal: false
243 smtp_encryption: start_tls
244 partner_addresses: [email protected]
245 force: true
246
247 - name: Disable autosupport - REST
248 netapp.ontap.na_ontap_autosupport:
249 hostname: "{{ netapp_hostname }}"
250 username: "{{ netapp_username }}"
251 password: "{{ netapp_password }}"
252 state: absent
253 """
254
255 RETURN = """
256 """
257 import re
258 import traceback
259
260 from ansible.module_utils.basic import AnsibleModule
261 from ansible.module_utils._text import to_native
262 import ansible_collections.netapp.ontap.plugins.module_utils.netapp as netapp_utils
263 from ansible_collections.netapp.ontap.plugins.module_utils.netapp_module import NetAppModule
264 from ansible_collections.netapp.ontap.plugins.module_utils.netapp import OntapRestAPI
265 from ansible_collections.netapp.ontap.plugins.module_utils import rest_generic
266
267
268 class NetAppONTAPasup:
269 """Class with autosupport methods"""
270
271 def __init__(self):
272
273 self.argument_spec = netapp_utils.na_ontap_host_argument_spec()
274 self.argument_spec.update(dict(
275 state=dict(required=False, type='str', choices=['present', 'absent'], default='present'),
276 node_name=dict(required=False, type='str'),
277 transport=dict(required=False, type='str', choices=['smtp', 'http', 'https']),
278 noteto=dict(required=False, type='list', elements='str'),
279 post_url=dict(required=False, type='str'),
280 support=dict(required=False, type='bool'),
281 mail_hosts=dict(required=False, type='list', elements='str'),
282 from_address=dict(required=False, type='str'),
283 partner_addresses=dict(required=False, type='list', elements='str'),
284 to_addresses=dict(required=False, type='list', elements='str'),
285 # proxy_url may contain a password: user:password@url
286 proxy_url=dict(required=False, type='str', no_log=True),
287 hostname_in_subject=dict(required=False, type='bool'),
288 nht_data_enabled=dict(required=False, type='bool'),
289 perf_data_enabled=dict(required=False, type='bool'),
290 retry_count=dict(required=False, type='int'),
291 reminder_enabled=dict(required=False, type='bool'),
292 max_http_size=dict(required=False, type='int'),
293 max_smtp_size=dict(required=False, type='int'),
294 private_data_removed=dict(required=False, type='bool'),
295 local_collection_enabled=dict(required=False, type='bool'),
296 ondemand_enabled=dict(required=False, type='bool'),
297 validate_digital_certificate=dict(required=False, type='bool'),
298 is_minimal=dict(required=False, type='bool'),
299 smtp_encryption=dict(required=False, type='str', choices=['none', 'start_tls']),
300 force=dict(required=False, type='bool'),
301 ))
302
303 self.module = AnsibleModule(
304 argument_spec=self.argument_spec,
305 supports_check_mode=True
306 )
307
308 self.na_helper = NetAppModule()
309 self.parameters = self.na_helper.set_parameters(self.module.params)
310 if 'state' in self.parameters:
311 if self.parameters.get('state') == 'present':
312 self.parameters['enabled'] = True
313 else:
314 self.parameters['enabled'] = False
315 # present or absent requires modifying state to enabled or disabled
316 if 'enabled' in self.parameters:
317 self.parameters['service_state'] = 'started' if self.parameters.get('enabled') is True else 'stopped'
318 self.set_playbook_zapi_key_map()
319
320 self.rest_api = OntapRestAPI(self.module)
321 unsupported_rest_properties = ['node_name', 'retry_count', 'max_http_size', 'max_smtp_size',
322 'noteto', 'hostname_in_subject', 'nht_data_enabled',
323 'perf_data_enabled', 'reminder_enabled', 'private_data_removed',
324 'local_collection_enabled', 'validate_digital_certificate']
325 partially_supported_rest_properties = [['smtp_encryption', (9, 15, 1)], ['ondemand_enabled', (9, 16, 1)], ['force', (9, 16, 1)]]
326 self.use_rest = self.rest_api.is_rest_supported_properties(self.parameters, unsupported_rest_properties, partially_supported_rest_properties)
327 unsupported_zapi_properties = ['smtp_encryption', 'is_minimal', 'force']
328
329 if not self.use_rest:
330 if netapp_utils.has_netapp_lib() is False:
331 self.module.fail_json(msg=netapp_utils.netapp_lib_is_required())
332 if 'node_name' not in self.parameters:
333 self.module.fail_json(msg="Error: The option 'node_name' is required when using ZAPI.")
334 used_unsupported_zapi_properties = [option for option in unsupported_zapi_properties if option in self.parameters]
335 if used_unsupported_zapi_properties:
336 self.module.fail_json(msg="Error: %s options supported only with REST." % ", ".join(used_unsupported_zapi_properties))
337 self.server = netapp_utils.setup_na_ontap_zapi(module=self.module)
338
339 def set_playbook_zapi_key_map(self):
340 self.na_helper.zapi_string_keys = {
341 'node_name': 'node-name',
342 'transport': 'transport',
343 'post_url': 'post-url',
344 'from_address': 'from',
345 'proxy_url': 'proxy-url'
346 }
347 self.na_helper.zapi_int_keys = {
348 'retry_count': 'retry-count',
349 'max_http_size': 'max-http-size',
350 'max_smtp_size': 'max-smtp-size'
351 }
352 self.na_helper.zapi_list_keys = {
353 'noteto': ('noteto', 'mail-address'),
354 'mail_hosts': ('mail-hosts', 'string'),
355 'partner_addresses': ('partner-address', 'mail-address'),
356 'to_addresses': ('to', 'mail-address')
357 }
358 self.na_helper.zapi_bool_keys = {
359 'support': 'is-support-enabled',
360 'hostname_in_subject': 'is-node-in-subject',
361 'nht_data_enabled': 'is-nht-data-enabled',
362 'perf_data_enabled': 'is-perf-data-enabled',
363 'reminder_enabled': 'is-reminder-enabled',
364 'private_data_removed': 'is-private-data-removed',
365 'local_collection_enabled': 'is-local-collection-enabled',
366 'ondemand_enabled': 'is-ondemand-enabled',
367 'validate_digital_certificate': 'validate-digital-certificate'
368 }
369
370 def get_autosupport_config(self):
371 """
372 get current autosupport details
373 :return: dict()
374 """
375 asup_info = {}
376 if self.use_rest:
377 api = "support/autosupport"
378 query = {
379 'fields': 'transport,mail_hosts,proxy_url,partner_addresses,to,is_minimal,from,contact_support,enabled,'
380 }
381 if self.rest_api.meets_rest_minimum_version(self.use_rest, 9, 15, 1):
382 query['fields'] += 'smtp_encryption,'
383 if self.rest_api.meets_rest_minimum_version(self.use_rest, 9, 16, 1):
384 query['fields'] += 'ondemand_enabled,'
385 record, error = rest_generic.get_one_record(self.rest_api, api, query)
386 if error:
387 self.module.fail_json(msg='Error fetching auto support configuration info: %s' % error)
388 if record:
389 return {
390 'transport': self.na_helper.safe_get(record, ['transport']),
391 'mail_hosts': self.na_helper.safe_get(record, ['mail_hosts']),
392 'smtp_encryption': self.na_helper.safe_get(record, ['smtp_encryption']),
393 'proxy_url': self.na_helper.safe_get(record, ['proxy_url']),
394 'partner_addresses': record['partner_addresses'] if 'partner_addresses' in record else list(),
395 'to_addresses': record['to'] if 'to' in record else list(),
396 'is_minimal': record['is_minimal'] in ['enable', True] if 'is_minimal' in record else False,
397 'from_address': record['from'] if 'from' in record else "",
398 'ondemand_enabled': record['ondemand_enabled'] in ['enable', True] if 'ondemand_enabled' in record else False,
399 'support': record['contact_support'] in ['enable', True] if 'contact_support' in record else False,
400 'enabled': record['enabled'] in ['enable', True] if 'enabled' in record else False,
401 }
402 return record
403 else:
404 asup_details = netapp_utils.zapi.NaElement('autosupport-config-get')
405 asup_details.add_new_child('node-name', self.parameters['node_name'])
406 try:
407 result = self.server.invoke_successfully(asup_details, enable_tunneling=True)
408 except netapp_utils.zapi.NaApiError as error:
409 self.module.fail_json(msg='Error fetching info: %s' % to_native(error), exception=traceback.format_exc())
410 # zapi invoke successful
411 asup_attr_info = result.get_child_by_name('attributes').get_child_by_name('autosupport-config-info')
412 asup_info['service_state'] = 'started' if asup_attr_info['is-enabled'] == 'true' else 'stopped'
413 for item_key, zapi_key in self.na_helper.zapi_string_keys.items():
414 value = asup_attr_info.get_child_content(zapi_key)
415 asup_info[item_key] = value if value is not None else ""
416 for item_key, zapi_key in self.na_helper.zapi_int_keys.items():
417 value = asup_attr_info.get_child_content(zapi_key)
418 if value is not None:
419 asup_info[item_key] = self.na_helper.get_value_for_int(from_zapi=True, value=value)
420 for item_key, zapi_key in self.na_helper.zapi_bool_keys.items():
421 value = asup_attr_info.get_child_content(zapi_key)
422 if value is not None:
423 asup_info[item_key] = self.na_helper.get_value_for_bool(from_zapi=True, value=value)
424 for item_key, zapi_key in self.na_helper.zapi_list_keys.items():
425 parent, dummy = zapi_key
426 asup_info[item_key] = self.na_helper.get_value_for_list(from_zapi=True, zapi_parent=asup_attr_info.get_child_by_name(parent))
427 return asup_info
428
429 def modify_autosupport_config(self, modify):
430 """
431 modify autosupport config
432 @return: modfied attributes / FAILURE with an error_message
433 """
434
435 if self.use_rest:
436 api = "support/autosupport"
437 body = {}
438 query = {}
439 if 'transport' in modify:
440 body['transport'] = modify['transport']
441 if 'mail_hosts' in modify:
442 body['mail_hosts'] = modify['mail_hosts']
443 if 'smtp_encryption' in modify:
444 body['smtp_encryption'] = modify['smtp_encryption']
445 if 'proxy_url' in modify:
446 body['proxy_url'] = modify['proxy_url']
447 if 'partner_addresses' in modify:
448 body['partner_addresses'] = modify['partner_addresses']
449 if 'from_address' in modify:
450 body['from'] = modify.pop('from_address')
451 if 'to_addresses' in modify:
452 body['to'] = modify.pop('to_addresses')
453 if 'ondemand_enabled' in modify:
454 body['ondemand_enabled'] = modify['ondemand_enabled']
455 if 'is_minimal' in modify:
456 body['is_minimal'] = modify['is_minimal']
457 if 'support' in modify:
458 body['contact_support'] = modify['support']
459 if 'enabled' in modify:
460 body['enabled'] = modify['enabled']
461 if 'force' in self.parameters:
462 query['force'] = self.parameters.get('force')
463 dummy, error = rest_generic.patch_async(self.rest_api, api, None, body, query)
464
465 if error:
466 self.module.fail_json(msg='Error modifying auto support configuration: %s' % error)
467 else:
468 asup_details = {'node-name': self.parameters['node_name']}
469 if modify.get('service_state'):
470 asup_details['is-enabled'] = 'true' if modify.get('service_state') == 'started' else 'false'
471 asup_config = netapp_utils.zapi.NaElement('autosupport-config-modify')
472 for item_key in modify:
473 if item_key in self.na_helper.zapi_string_keys:
474 zapi_key = self.na_helper.zapi_string_keys.get(item_key)
475 asup_details[zapi_key] = modify[item_key]
476 elif item_key in self.na_helper.zapi_int_keys:
477 zapi_key = self.na_helper.zapi_int_keys.get(item_key)
478 asup_details[zapi_key] = modify[item_key]
479 elif item_key in self.na_helper.zapi_bool_keys:
480 zapi_key = self.na_helper.zapi_bool_keys.get(item_key)
481 asup_details[zapi_key] = self.na_helper.get_value_for_bool(from_zapi=False, value=modify[item_key])
482 elif item_key in self.na_helper.zapi_list_keys:
483 parent_key, child_key = self.na_helper.zapi_list_keys.get(item_key)
484 asup_config.add_child_elem(self.na_helper.get_value_for_list(
485 from_zapi=False, zapi_parent=parent_key, zapi_child=child_key, data=modify.get(item_key)))
486
487 asup_config.translate_struct(asup_details)
488 try:
489 return self.server.invoke_successfully(asup_config, enable_tunneling=True)
490 except netapp_utils.zapi.NaApiError as error:
491 self.module.fail_json(msg='Error modifying asup: %s' % to_native(error), exception=traceback.format_exc())
492
493 @staticmethod
494 def strip_password(url):
495 ''' if url matches user:password@address return user@address
496 otherwise return None
497 '''
498 if url:
499 needle = r'(.*):(.*)@(.*)'
500 matched = re.match(needle, url)
501 if matched:
502 return matched.group(1, 3)
503 return None, None
504
505 def idempotency_check(self, current, modify):
506 sanitized_modify = dict(modify)
507 if 'proxy_url' in modify:
508 user_url_m = self.strip_password(modify['proxy_url'])
509 user_url_c = self.strip_password(current.get('proxy_url'))
510 if user_url_m == user_url_c and user_url_m != (None, None):
511 # change in password, it can be a false positive as password is replaced with ********* by ONTAP
512 self.module.warn('na_ontap_autosupport is not idempotent because the password value in proxy_url cannot be compared.')
513 if user_url_m != (None, None):
514 # password was found in proxy_url, sanitize it, use something different than ZAPI *********
515 sanitized_modify['proxy_url'] = "%s:XXXXXXXX@%s" % user_url_m
516 return sanitized_modify
517
518 def apply(self):
519 """
520 Apply action to autosupport
521 """
522 current = self.get_autosupport_config()
523 modify = self.na_helper.get_modified_attributes(current, self.parameters)
524 sanitized_modify = self.idempotency_check(current, modify)
525 if self.na_helper.changed and not self.module.check_mode:
526 self.modify_autosupport_config(modify)
527 result = netapp_utils.generate_result(self.na_helper.changed, modify=sanitized_modify)
528 self.module.exit_json(**result)
529
530
531 def main():
532 """Execute action"""
533 asup_obj = NetAppONTAPasup()
534 asup_obj.apply()
535
536
537 if __name__ == '__main__':
538 main()