Debian Codegraph @

ansible_collections/netapp/ontap/plugins/module_utils/netapp.py

raw
1 # This code is part of Ansible, but is an independent component.
2 # This particular file snippet, and this file snippet only, is BSD licensed.
3 # Modules you write using this snippet, which is embedded dynamically by Ansible
4 # still belong to the author of the module, and may assign their own license
5 # to the complete work.
6 #
7 # Copyright (c) 2017, Sumit Kumar <[email protected]>
8 # Copyright (c) 2017, Michael Price <[email protected]>
9 # Copyright (c) 2017-2026, NetApp, Inc
10 # All rights reserved.
11 #
12 # Redistribution and use in source and binary forms, with or without modification,
13 # are permitted provided that the following conditions are met:
14 #
15 # * Redistributions of source code must retain the above copyright
16 # notice, this list of conditions and the following disclaimer.
17 # * Redistributions in binary form must reproduce the above copyright notice,
18 # this list of conditions and the following disclaimer in the documentation
19 # and/or other materials provided with the distribution.
20 #
21 # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
22 # ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
23 # WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
24 # IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
25 # INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26 # PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
27 # INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 # LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
29 # USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30
31 '''
32 netapp.py
33 '''
34
35 from __future__ import (absolute_import, division, print_function)
36 __metaclass__ = type
37
38 import base64
39 import json
40 import logging
41 import os
42 import ssl
43 import time
44 from ansible.module_utils.basic import missing_required_lib
45 from ansible.module_utils._text import to_native
46
47 try:
48 from ansible.module_utils.ansible_release import __version__ as ANSIBLE_VERSION
49 except ImportError:
50 ANSIBLE_VERSION = 'unknown'
51
52 COLLECTION_VERSION = "23.5.0"
53 CLIENT_APP_VERSION = "%s/%s" % ("%s", COLLECTION_VERSION)
54 IMPORT_EXCEPTION = None
55
56 try:
57 from netapp_lib.api.zapi import zapi
58 HAS_NETAPP_LIB = True
59 except ImportError as exc:
60 HAS_NETAPP_LIB = False
61 IMPORT_EXCEPTION = exc
62
63 try:
64 import requests
65 HAS_REQUESTS = True
66 except ImportError:
67 HAS_REQUESTS = False
68
69 try:
70 import boto3
71 HAS_BOTO3 = True
72 except ImportError:
73 HAS_BOTO3 = False
74
75 HAS_SF_SDK = False
76 SF_BYTE_MAP = dict(
77 # Management GUI displays 1024 ** 3 as 1.1 GB, thus use 1000.
78 bytes=1,
79 b=1,
80 kb=1000,
81 mb=1000 ** 2,
82 gb=1000 ** 3,
83 tb=1000 ** 4,
84 pb=1000 ** 5,
85 eb=1000 ** 6,
86 zb=1000 ** 7,
87 yb=1000 ** 8
88 )
89
90 POW2_BYTE_MAP = dict(
91 # Here, 1 kb = 1024
92 bytes=1,
93 b=1,
94 k=1024,
95 m=1024 ** 2,
96 g=1024 ** 3,
97 t=1024 ** 4,
98 p=1024 ** 5,
99 e=1024 ** 6,
100 z=1024 ** 7,
101 y=1024 ** 8,
102 kb=1024,
103 mb=1024 ** 2,
104 gb=1024 ** 3,
105 tb=1024 ** 4,
106 pb=1024 ** 5,
107 eb=1024 ** 6,
108 zb=1024 ** 7,
109 yb=1024 ** 8,
110 )
111
112 ERROR_MSG = dict(
113 no_cserver='This module is expected to run as cluster admin'
114 )
115
116 LOG = logging.getLogger(__name__)
117 LOG_FILE = '/tmp/ontap_apis.log'
118 ZAPI_DEPRECATION_MESSAGE = "The 'netapp-lib' library is no longer maintained. Proceed at your own risk. "\
119 "While the original deprecation date has been deferred due to continued consumer usage and feedback, "\
120 "ONTAPI (ZAPI) are considered legacy. "\
121 "All new features, fixes, and improvements will be developed for the modules having REST API support. "\
122 "To ensure continued support, please migrate to the REST API."
123
124 try:
125 from solidfire.factory import ElementFactory
126 HAS_SF_SDK = True
127 except ImportError:
128 HAS_SF_SDK = False
129
130
131 def has_netapp_lib():
132 return HAS_NETAPP_LIB
133
134
135 def netapp_lib_is_required():
136 return "Error: the python NetApp-Lib module is required. Import error: %s" % str(IMPORT_EXCEPTION)
137
138
139 def has_sf_sdk():
140 return HAS_SF_SDK
141
142
143 def na_ontap_zapi_only_spec():
144 # This is used for Zapi only Modules.
145
146 return dict(
147 hostname=dict(required=True, type='str'),
148 username=dict(required=False, type='str', aliases=['user']),
149 password=dict(required=False, type='str', aliases=['pass'], no_log=True),
150 https=dict(required=False, type='bool', default=False),
151 validate_certs=dict(required=False, type='bool', default=True),
152 http_port=dict(required=False, type='int'),
153 ontapi=dict(required=False, type='int'),
154 use_rest=dict(required=False, type='str', default='never'),
155 feature_flags=dict(required=False, type='dict'),
156 cert_filepath=dict(required=False, type='str'),
157 key_filepath=dict(required=False, type='str', no_log=False),
158 )
159
160
161 def na_ontap_host_argument_spec():
162 # This is used for Zapi + REST Modules.
163
164 return dict(
165 hostname=dict(required=True, type='str'),
166 username=dict(required=False, type='str', aliases=['user']),
167 password=dict(required=False, type='str', aliases=['pass'], no_log=True),
168 https=dict(required=False, type='bool', default=False),
169 validate_certs=dict(required=False, type='bool', default=True),
170 http_port=dict(required=False, type='int'),
171 ontapi=dict(required=False, type='int'),
172 use_rest=dict(required=False, type='str', default='always'),
173 feature_flags=dict(required=False, type='dict'),
174 cert_filepath=dict(required=False, type='str'),
175 key_filepath=dict(required=False, type='str', no_log=False),
176 force_ontap_version=dict(required=False, type='str'),
177 use_lambda=dict(required=False, type='bool', default=False)
178 )
179
180
181 def na_ontap_rest_only_spec():
182 # This is used for REST only Modules.
183
184 return dict(
185 hostname=dict(required=True, type='str'),
186 username=dict(required=False, type='str', aliases=['user']),
187 password=dict(required=False, type='str', aliases=['pass'], no_log=True),
188 https=dict(required=False, type='bool', default=False),
189 validate_certs=dict(required=False, type='bool', default=True),
190 http_port=dict(required=False, type='int'),
191 use_rest=dict(required=False, type='str', default='always'),
192 feature_flags=dict(required=False, type='dict'),
193 cert_filepath=dict(required=False, type='str'),
194 key_filepath=dict(required=False, type='str', no_log=False),
195 force_ontap_version=dict(required=False, type='str'),
196 use_lambda=dict(required=False, type='bool', default=False)
197 )
198
199
200 def na_ontap_host_argument_spec_peer():
201 spec = na_ontap_host_argument_spec()
202 spec.pop('feature_flags')
203 # get rid of default values, as we'll use source values
204 for value in spec.values():
205 if 'default' in value:
206 value.pop('default')
207 return spec
208
209
210 def na_ontap_lambda_argument_spec():
211 # This is used for modules that support Lambda proxy functionality.
212 return dict(
213 lambda_config=dict(required=False, type='dict', options=dict(
214 function_name=dict(required=True, type='str'),
215 aws_region=dict(required=True, type='str'),
216 aws_profile=dict(required=False, type='str')
217 ))
218 )
219
220
221 def has_feature(module, feature_name):
222 feature = get_feature(module, feature_name)
223 if isinstance(feature, bool):
224 return feature
225 module.fail_json(msg="Error: expected bool type for feature flag: %s" % feature_name)
226
227
228 def get_feature(module, feature_name):
229 ''' if the user has configured the feature, use it
230 otherwise, use our default
231 '''
232 default_flags = dict(
233 strict_json_check=True, # when true, fail if response.content in not empty and is not valid json
234 trace_apis=False, # when true, append ZAPI and REST requests/responses to /tmp/ontap_zapi.txt
235 trace_headers=False, # when true, headers are not redacted in send requests
236 trace_auth_args=False, # when true, auth_args are not redacted in send requests
237 check_required_params_for_none=True,
238 classic_basic_authorization=False, # use ZAPI wrapper to send Authorization header
239 deprecation_warning=True,
240 sanitize_xml=True,
241 sanitize_code_points=[8], # unicode values, 8 is backspace
242 show_modified=True,
243 always_wrap_zapi=True, # for better error reporting
244 flexcache_delete_return_timeout=5, # ONTAP bug if too big?
245 # for SVM, whch protocols can be allowed
246 svm_allowable_protocols_rest=['cifs', 'fcp', 'iscsi', 'nvme', 'nfs', 'ndmp', 's3'],
247 svm_allowable_protocols_zapi=['cifs', 'fcp', 'iscsi', 'nvme', 'nfs', 'ndmp', 'http'],
248 max_files_change_threshold=1, # percentage of increase/decrease required to trigger a modify action
249 warn_or_fail_on_fabricpool_backend_change='fail',
250 no_cserver_ems=False # when True, don't attempt to find cserver and don't send cserver EMS
251 )
252
253 if module.params['feature_flags'] is not None and feature_name in module.params['feature_flags']:
254 return module.params['feature_flags'][feature_name]
255 if feature_name in default_flags:
256 return default_flags[feature_name]
257 module.fail_json(msg="Internal error: unexpected feature flag: %s" % feature_name)
258
259
260 def create_sf_connection(module, port=None, host_options=None):
261 if not HAS_SF_SDK:
262 module.fail_json(msg="the python SolidFire SDK module is required")
263
264 if host_options is None:
265 host_options = module.params
266 msg, msg2 = None, None
267 missing_options = [option for option in ('hostname', 'username', 'password') if not host_options.get(option)]
268 if missing_options:
269 verb = 'are' if len(missing_options) > 1 else 'is'
270 msg = "%s %s required for ElementSW connection." % (', '.join(missing_options), verb)
271 extra_options = [option for option in ('cert_filepath', 'key_filepath') if host_options.get(option)]
272 if extra_options:
273 verb = 'are' if len(extra_options) > 1 else 'is'
274 msg2 = "%s %s not supported for ElementSW connection." % (', '.join(extra_options), verb)
275 msg = "%s %s" % (msg, msg2) if msg and msg2 else msg or msg2
276 if msg:
277 module.fail_json(msg=msg)
278 hostname = host_options.get('hostname')
279 username = host_options.get('username')
280 password = host_options.get('password')
281
282 try:
283 return ElementFactory.create(hostname, username, password, port=port)
284 except Exception as exc:
285 raise Exception("Unable to create SF connection: %s" % exc)
286
287
288 def set_auth_method(module, username, password, cert_filepath, key_filepath):
289 error = None
290 auth_method = None
291 # defaults to cert authentication if both basic and client certificate authentication parameters are given
292 if cert_filepath is not None:
293 auth_method = 'single_cert' if key_filepath is None else 'cert_key'
294 else:
295 if password is None and username is None:
296 error = ('Error: cannot have a key file without a cert file' if key_filepath is not None
297 else 'Error: ONTAP module requires username/password or SSL certificate file(s)')
298 elif password is not None and username is not None:
299 auth_method = 'basic_auth' if has_feature(module, 'classic_basic_authorization') else 'speedy_basic_auth'
300 else:
301 error = 'Error: username and password have to be provided together'
302 if error:
303 module.fail_json(msg=error)
304 return auth_method
305
306
307 def setup_host_options_from_module_params(host_options, module, keys):
308 '''if an option is not set, use primary value.
309 but don't mix up basic and certificate authentication methods
310
311 host_options is updated in place
312 option values are read from module.params
313 keys is a list of keys that need to be added/updated/left alone in host_options
314 '''
315 password_keys = ['username', 'password']
316 certificate_keys = ['cert_filepath', 'key_filepath']
317 use_password = any(host_options.get(x) is not None for x in password_keys)
318 use_certificate = any(host_options.get(x) is not None for x in certificate_keys)
319 if use_password and use_certificate:
320 module.fail_json(
321 msg='Error: host cannot have both basic authentication (username/password) and certificate authentication (cert/key files).')
322 if use_password:
323 exclude_keys = certificate_keys
324 elif use_certificate:
325 exclude_keys = password_keys
326 else:
327 exclude_keys = []
328 for key in keys:
329 if host_options.get(key) is None and key not in exclude_keys:
330 # use same value as source if no value is given for dest
331 host_options[key] = module.params[key]
332
333
334 def set_zapi_port_and_transport(server, https, port, validate_certs):
335 # default is HTTP
336 if https:
337 if port is None:
338 port = 443
339 transport_type = 'HTTPS'
340 # HACK to bypass certificate verification
341 if validate_certs is False and not os.environ.get('PYTHONHTTPSVERIFY', '') and getattr(ssl, '_create_unverified_context', None):
342 ssl._create_default_https_context = ssl._create_unverified_context
343 else:
344 if port is None:
345 port = 80
346 transport_type = 'HTTP'
347 server.set_transport_type(transport_type)
348 server.set_port(port)
349
350
351 def should_use_lambda(module):
352 """
353 Determine if the module should use Lambda proxy for ONTAP API calls.
354 :param module: Ansible module instance.
355 :return: Boolean indicating whether to use Lambda.
356 """
357 return module.params.get('use_lambda', False)
358
359
360 def setup_na_ontap_lambda(module):
361 """
362 Set up a Lambda proxy for ONTAP operations based on module parameters.
363 :param module: Ansible module instance.
364 :return: AwsLambda instance or None if Lambda is not enabled.
365 """
366 lambda_config = module.params.get('lambda_config', {})
367 return setup_na_ontap_lambda_with_config(module, lambda_config)
368
369
370 def setup_na_ontap_lambda_with_config(module, lambda_config, hostname=None):
371 """
372 Set up a Lambda proxy for ONTAP operations with specific configuration.
373 :param module: Ansible module instance.
374 :param lambda_config: Lambda configuration dictionary.
375 :param hostname: Optional hostname override for peer connections.
376 :return: AwsLambda instance or None if Lambda is not enabled.
377 """
378 if not HAS_BOTO3:
379 module.fail_json(msg="boto3 is required for Lambda functionality. Install with: pip install boto3")
380
381 try:
382 return AwsLambda(module, lambda_config, hostname)
383 except Exception as exc:
384 module.fail_json("Failed to create Lambda proxy: %s" % exc)
385
386
387 def setup_na_ontap_zapi(module, vserver=None, wrap_zapi=False, host_options=None):
388 module.warn(ZAPI_DEPRECATION_MESSAGE)
389 if host_options is None:
390 host_options = module.params
391 hostname = host_options.get('hostname')
392 username = host_options.get('username')
393 password = host_options.get('password')
394 cert_filepath = host_options.get('cert_filepath')
395 key_filepath = host_options.get('key_filepath')
396 https = host_options.get('https')
397 validate_certs = host_options.get('validate_certs')
398 port = host_options.get('http_port')
399 version = host_options.get('ontapi')
400 trace = has_feature(module, 'trace_apis')
401 if trace:
402 logging.basicConfig(filename=LOG_FILE, level=logging.DEBUG, format='%(asctime)s %(levelname)-8s %(message)s')
403 wrap_zapi |= has_feature(module, 'always_wrap_zapi')
404 auth_method = set_auth_method(module, username, password, cert_filepath, key_filepath)
405
406 if not HAS_NETAPP_LIB:
407 module.fail_json(msg=netapp_lib_is_required())
408
409 # set up zapi
410 if auth_method in ('single_cert', 'cert_key'):
411 # override NaServer in netapp-lib to enable certificate authentication
412 server = OntapZAPICx(hostname, module=module, username=username, password=password,
413 validate_certs=validate_certs, cert_filepath=cert_filepath,
414 key_filepath=key_filepath, style=zapi.NaServer.STYLE_CERTIFICATE,
415 auth_method=auth_method, trace=trace)
416 # SSL certificate authentication requires SSL
417 https = True
418 elif auth_method == 'speedy_basic_auth' or wrap_zapi:
419 # override NaServer in netapp-lib to add Authorization header preemptively
420 # use wrapper to handle parse error (mostly for na_ontap_command)
421 server = OntapZAPICx(hostname, module=module, username=username, password=password,
422 validate_certs=validate_certs, auth_method=auth_method, trace=trace)
423 else:
424 # legacy netapp-lib
425 server = zapi.NaServer(hostname, username=username, password=password, trace=trace)
426 if vserver:
427 server.set_vserver(vserver)
428 if host_options.get('use_rest') == 'always':
429 note = '' if https else ' Note: https is set to false.'
430 module.warn("Using ZAPI for %s, ignoring 'use_rest: always'.%s" % (module._name, note))
431
432 set_zapi_port_and_transport(server, https, port, validate_certs)
433 server.set_api_version(major=1, minor=(version or 110))
434 server.set_server_type('FILER')
435 return server
436
437
438 def is_zapi_connection_error(message):
439 ''' return True if it is a connection issue '''
440 # netapp-lib message may contain a tuple or a str!
441 try:
442 if isinstance(message, tuple) and isinstance(message[0], ConnectionError):
443 return True
444 except NameError:
445 # python 2.7 does not know about ConnectionError
446 pass
447 return isinstance(message, str) and message.startswith(('URLError', 'Unauthorized'))
448
449
450 def is_zapi_write_access_error(message):
451 ''' return True if it is a write access error '''
452 # netapp-lib message may contain a tuple or a str!
453 if isinstance(message, str) and message.startswith('Insufficient privileges:'):
454 return 'does not have write access' in message
455 return False
456
457
458 def is_zapi_missing_vserver_error(message):
459 ''' return True if it is a missing vserver error '''
460 # netapp-lib message may contain a tuple or a str!
461 return isinstance(message, str) and message in ('Vserver API missing vserver parameter.', 'Specified vserver not found')
462
463
464 def get_cserver_zapi(server):
465 ''' returns None if not run on the management or cluster IP '''
466 vserver_info = zapi.NaElement('vserver-get-iter')
467 query_details = zapi.NaElement.create_node_with_children('vserver-info', **{'vserver-type': 'admin'})
468 query = zapi.NaElement('query')
469 query.add_child_elem(query_details)
470 vserver_info.add_child_elem(query)
471 try:
472 result = server.invoke_successfully(vserver_info,
473 enable_tunneling=False)
474 except zapi.NaApiError as exc:
475 # Do not fail if we can't connect to the server.
476 # The module will report a better error when trying to get some data from ONTAP.
477 if is_zapi_connection_error(exc.message):
478 return None
479 # raise on other errors, as it may be a bug in calling the ZAPI
480 raise exc
481 attribute_list = result.get_child_by_name('attributes-list')
482 if attribute_list is not None:
483 vserver_list = attribute_list.get_child_by_name('vserver-info')
484 if vserver_list is not None:
485 return vserver_list.get_child_content('vserver-name')
486 return None
487
488
489 def classify_zapi_exception(error):
490 ''' return type of error '''
491 try:
492 # very unlikely to fail, but don't take any chance
493 err_code = int(error.code)
494 except (AttributeError, ValueError):
495 err_code = 0
496 try:
497 # very unlikely to fail, but don't take any chance
498 err_msg = error.message
499 except AttributeError:
500 err_msg = ""
501 if err_code == 13005 and err_msg.startswith('Unable to find API:') and 'data vserver' in err_msg:
502 return 'missing_vserver_api_error', 'Most likely running a cluster level API as vserver: %s' % to_native(error)
503 if err_code == 13001 and err_msg.startswith("RPC: Couldn't make connection"):
504 return 'rpc_error', to_native(error)
505 return "other_error", to_native(error)
506
507
508 def get_cserver(connection, is_rest=False):
509 if not is_rest:
510 return get_cserver_zapi(connection)
511
512 params = {'fields': 'type'}
513 api = "private/cli/vserver"
514 json, error = connection.get(api, params)
515 if json is None or error is not None:
516 # exit if there is an error or no data
517 return None
518 vservers = json.get('records')
519 if vservers is not None:
520 for vserver in vservers:
521 if vserver['type'] == 'admin': # cluster admin
522 return vserver['vserver']
523 if len(vservers) == 1: # assume vserver admin
524 return vservers[0]['vserver']
525
526 return None
527
528
529 def generate_result(changed, actions=None, modify=None, response=None, extra_responses=None):
530 result = dict(changed=changed)
531 if response is not None:
532 result['response'] = response
533 if modify:
534 result['modify'] = modify
535 if actions:
536 result['actions'] = actions
537 if extra_responses:
538 result.update(extra_responses)
539 return result
540
541
542 if HAS_NETAPP_LIB:
543 class OntapZAPICx(zapi.NaServer):
544 ''' override zapi NaServer class to:
545 - enable SSL certificate authentication
546 - ignore invalid XML characters in ONTAP output (when using CLI module)
547 - add Authorization header when using basic authentication
548 '''
549 def __init__(self, hostname=None, server_type=zapi.NaServer.SERVER_TYPE_FILER,
550 transport_type=zapi.NaServer.TRANSPORT_TYPE_HTTP,
551 style=zapi.NaServer.STYLE_LOGIN_PASSWORD, username=None,
552 password=None, port=None, trace=False, module=None,
553 cert_filepath=None, key_filepath=None, validate_certs=None,
554 auth_method=None):
555 # python 2.x syntax, but works for python 3 as well
556 super(OntapZAPICx, self).__init__(hostname, server_type=server_type,
557 transport_type=transport_type,
558 style=style, username=username,
559 password=password, port=port, trace=trace)
560 self.cert_filepath = cert_filepath
561 self.key_filepath = key_filepath
562 self.validate_certs = validate_certs
563 self.module = module
564 self.base64_creds = None
565 if auth_method == 'speedy_basic_auth':
566 auth = '%s:%s' % (username, password)
567 self.base64_creds = base64.b64encode(auth.encode()).decode()
568
569 def _create_certificate_auth_handler(self):
570 try:
571 context = ssl.create_default_context()
572 except AttributeError as exc:
573 self._fail_with_exc_info('SSL certificate authentication requires python 2.7 or later.', exc)
574
575 if not self.validate_certs:
576 context.check_hostname = False
577 context.verify_mode = ssl.CERT_NONE
578 try:
579 context.load_cert_chain(self.cert_filepath, keyfile=self.key_filepath)
580 except IOError as exc:
581 self._fail_with_exc_info('Cannot load SSL certificate, check files exist.', exc)
582
583 return zapi.urllib.request.HTTPSHandler(context=context)
584
585 def _fail_with_exc_info(self, arg0, exc):
586 msg = arg0
587 msg += ' More info: %s' % repr(exc)
588 self.module.fail_json(msg=msg)
589
590 def sanitize_xml(self, response):
591 # some ONTAP CLI commands return BEL on error
592 new_response = response.replace(b'\x07\n', b'')
593 # And 9.1 uses \r\n rather than \n !
594 new_response = new_response.replace(b'\x07\r\n', b'')
595 # And 9.7 may send backspaces
596 for code_point in get_feature(self.module, 'sanitize_code_points'):
597 if bytes([8]) == b'\x08': # python 3
598 byte = bytes([code_point])
599 elif chr(8) == b'\x08': # python 2
600 byte = chr(code_point)
601 else: # very unlikely, noop
602 byte = b'.'
603 new_response = new_response.replace(byte, b'.')
604 return new_response
605
606 def _parse_response(self, response):
607 ''' handling XML parsing exception '''
608 try:
609 return super(OntapZAPICx, self)._parse_response(response)
610 except zapi.etree.XMLSyntaxError as exc:
611 if has_feature(self.module, 'sanitize_xml'):
612 try:
613 return super(OntapZAPICx, self)._parse_response(self.sanitize_xml(response))
614 except Exception:
615 # ignore a second exception, we'll report the first one
616 pass
617 try:
618 # report first exception, but include full response
619 exc.msg += ". Received: %s" % response
620 except Exception:
621 # in case the response is very badly formatted, ignore it
622 pass
623 raise exc
624
625 def _create_request(self, na_element, enable_tunneling=False):
626 ''' intercept newly created request to add Authorization header '''
627 request, netapp_element = super(OntapZAPICx, self)._create_request(na_element, enable_tunneling=enable_tunneling)
628 request.add_header('X-Dot-Client-App', CLIENT_APP_VERSION % self.module._name)
629 if self.base64_creds is not None:
630 request.add_header('Authorization', 'Basic %s' % self.base64_creds)
631 return request, netapp_element
632
633 # as is from latest version of netapp-lib
634 def invoke_elem(self, na_element, enable_tunneling=False):
635 """Invoke the API on the server."""
636 if not na_element or not isinstance(na_element, zapi.NaElement):
637 raise ValueError('NaElement must be supplied to invoke API')
638
639 request, request_element = self._create_request(na_element,
640 enable_tunneling)
641
642 if self._trace:
643 zapi.LOG.debug("Request: %s", request_element.to_string(pretty=True))
644
645 if not hasattr(self, '_opener') or not self._opener \
646 or self._refresh_conn:
647 self._build_opener()
648 try:
649 if hasattr(self, '_timeout'):
650 response = self._opener.open(request, timeout=self._timeout)
651 else:
652 response = self._opener.open(request)
653 except zapi.urllib.error.HTTPError as exc:
654 raise zapi.NaApiError(exc.code, exc.reason)
655 except zapi.urllib.error.URLError as exc:
656 msg = 'URL error'
657 error = repr(exc)
658 try:
659 # ConnectionRefusedError is not defined in python 2.7
660 if isinstance(exc.reason, ConnectionRefusedError):
661 msg = 'Unable to connect'
662 error = exc.args
663 except Exception:
664 pass
665 raise zapi.NaApiError(msg, error)
666 except Exception as exc:
667 raise zapi.NaApiError('Unexpected error', repr(exc))
668
669 response_xml = response.read()
670 response_element = self._get_result(response_xml)
671
672 if self._trace:
673 zapi.LOG.debug("Response: %s", response_element.to_string(pretty=True))
674
675 return response_element
676
677
678 class OntapRestAPI(object):
679 ''' wrapper to send requests to ONTAP REST APIs '''
680 def __init__(self, module, timeout=60, host_options=None):
681 self.host_options = module.params if host_options is None else host_options
682 self.module = module
683 # either username/password or a certifcate with/without a key are used for authentication
684 self.username = self.host_options.get('username')
685 self.password = self.host_options.get('password')
686 self.hostname = self.host_options['hostname']
687 self.use_rest = self.host_options['use_rest'].lower()
688 self.cert_filepath = self.host_options.get('cert_filepath')
689 self.key_filepath = self.host_options.get('key_filepath')
690 self.verify = self.host_options['validate_certs']
691 self.timeout = timeout
692 port = self.host_options['http_port']
693 self.force_ontap_version = self.host_options.get('force_ontap_version')
694 if port is None:
695 self.url = 'https://%s/api/' % self.hostname
696 else:
697 self.url = 'https://%s:%d/api/' % (self.hostname, port)
698 self.is_rest_error = None
699 self.fallback_to_zapi_reason = None
700 self.ontap_version = dict(
701 full='unknown',
702 generation=-1,
703 major=-1,
704 minor=-1,
705 valid=False
706 )
707 self.errors = []
708 self.debug_logs = []
709 self.auth_method = set_auth_method(self.module, self.username, self.password, self.cert_filepath, self.key_filepath)
710 self.check_required_library()
711 if has_feature(module, 'trace_apis'):
712 logging.basicConfig(filename=LOG_FILE, level=logging.DEBUG, format='%(asctime)s %(levelname)-8s %(message)s')
713 self.log_headers = has_feature(module, 'trace_headers')
714 self.log_auth_args = has_feature(module, 'trace_auth_args')
715
716 # Initialize Lambda proxy if configured
717 self.lambda_proxy = None
718
719 # Check if host_options has its own Lambda configuration (for peer connections)
720 if host_options and host_options.get('use_lambda'):
721 # Use Lambda config from host_options (peer connection)
722 lambda_config = host_options.get('lambda_config', {})
723 if lambda_config:
724 self.lambda_proxy = setup_na_ontap_lambda_with_config(module, lambda_config, self.hostname)
725 elif should_use_lambda(module):
726 # Use Lambda config from main module (source connection)
727 self.lambda_proxy = setup_na_ontap_lambda(module)
728
729 def requires_ontap_9_6(self, module_name):
730 return self.requires_ontap_version(module_name)
731
732 def requires_ontap_version(self, module_name, version='9.6'):
733 suffix = " - %s" % self.is_rest_error if self.is_rest_error is not None else ""
734 return "%s only supports REST, and requires ONTAP %s or later.%s" % (module_name, version, suffix)
735
736 def options_require_ontap_version(self, options, version='9.6', use_rest=None):
737 current_version = self.get_ontap_version()
738 suffix = " - %s" % self.is_rest_error if self.is_rest_error is not None else ""
739 if current_version != (-1, -1, -1):
740 suffix += " - ONTAP version: %s.%s.%s" % current_version
741 if use_rest is not None:
742 suffix += " - using %s" % ('REST' if use_rest else 'ZAPI')
743 if isinstance(options, list) and len(options) > 1:
744 tag = "any of %s" % options
745 elif isinstance(options, list) and len(options) == 1:
746 tag = str(options[0])
747 else:
748 tag = str(options)
749 return 'using %s requires ONTAP %s or later and REST must be enabled%s.' % (tag, version, suffix)
750
751 def meets_rest_minimum_version(self, use_rest, minimum_generation, minimum_major, minimum_minor=0):
752 return use_rest and self.get_ontap_version() >= (minimum_generation, minimum_major, minimum_minor)
753
754 def fail_if_not_rest_minimum_version(self, module_name, minimum_generation, minimum_major, minimum_minor=0):
755 status_code = self.get_ontap_version_using_rest()
756 msgs = []
757 if self.use_rest == 'never':
758 msgs.append('Error: REST is required for this module, found: "use_rest: %s".' % self.use_rest)
759 # The module only supports REST, so make it required
760 self.use_rest = 'always'
761 if self.is_rest_error:
762 msgs.append('Error using REST for version, error: %s.' % self.is_rest_error)
763 if status_code != 200:
764 msgs.append('Error using REST for version, status_code: %s.' % status_code)
765 if msgs:
766 self.module.fail_json(msg=' '.join(msgs))
767 version = self.get_ontap_version()
768 if version < (minimum_generation, minimum_major, minimum_minor):
769 msg = 'Error: ' + self.requires_ontap_version(module_name, '%d.%d.%d' % (minimum_generation, minimum_major, minimum_minor))
770 msg += ' Found: %s.%s.%s.' % version
771 self.module.fail_json(msg=msg)
772
773 def check_required_library(self):
774 if not HAS_REQUESTS:
775 self.module.fail_json(msg=missing_required_lib('requests'))
776
777 def build_headers(self, accept=None, vserver_name=None, vserver_uuid=None):
778 headers = {'X-Dot-Client-App': CLIENT_APP_VERSION % self.module._name}
779 # accept is used to turn on/off HAL linking
780 if accept is not None:
781 headers['accept'] = accept
782 # vserver tunneling using vserver name and/or UUID
783 if vserver_name is not None:
784 headers['X-Dot-SVM-Name'] = vserver_name
785 if vserver_uuid is not None:
786 headers['X-Dot-SVM-UUID'] = vserver_uuid
787 return headers
788
789 def send_request(self, method, api, params, json=None, headers=None, files=None):
790 ''' send http request and process reponse, including error conditions '''
791 if self.lambda_proxy:
792 status_code, json_dict, error_details = self.lambda_proxy._send_request(method, api, params, json, headers, files)
793 self.log_debug("proxy:", status_code)
794 self.log_debug("json_dict:", json_dict)
795 return status_code, json_dict, error_details
796
797 def get_auth_args():
798 if self.auth_method == 'single_cert':
799 kwargs = dict(cert=self.cert_filepath)
800 elif self.auth_method == 'cert_key':
801 kwargs = dict(cert=(self.cert_filepath, self.key_filepath))
802 elif self.auth_method in ('basic_auth', 'speedy_basic_auth'):
803 # For Unicode passwords: Check if password contains non-ASCII characters
804 # If so, UTF-8 encoding is used instead of requests default (Latin-1)
805 def is_ascii_compatible(s):
806 try:
807 s.encode('ascii')
808 return True
809 except UnicodeEncodeError:
810 return False
811
812 if not (is_ascii_compatible(self.username) and is_ascii_compatible(self.password)):
813 auth_string = '%s:%s' % (self.username, self.password)
814 auth_bytes = base64.b64encode(auth_string.encode('utf-8')).decode('ascii')
815 kwargs = dict(headers={'Authorization': 'Basic %s' % auth_bytes})
816 else:
817 # Standard requests auth for ASCII-only passwords
818 kwargs = dict(auth=(self.username, self.password))
819 else:
820 raise KeyError(self.auth_method)
821 return kwargs
822
823 url = self.url + api
824 status_code, json_dict, error_details = self._send_request(method, url, params, json, headers, files, get_auth_args())
825
826 return status_code, json_dict, error_details
827
828 def _send_request(self, method, url, params, json, headers, files, auth_args):
829 status_code = None
830 json_dict = None
831 json_error = None
832 error_details = None
833 if headers is None:
834 headers = self.build_headers()
835
836 # Handles authentication headers from auth_args
837 if 'headers' in auth_args:
838 # Merge authentication headers with existing headers
839 headers.update(auth_args['headers'])
840 # Remove headers from auth_args to avoid passing them twice to request function
841 auth_args = {k: v for k, v in auth_args.items() if k != 'headers'}
842
843 def fail_on_non_empty_value(response):
844 '''json() may fail on an empty value, but it's OK if no response is expected.
845 To avoid false positives, only report an issue when we expect to read a value.
846 The first get will see it.
847 '''
848 if method == 'GET' and has_feature(self.module, 'strict_json_check'):
849 contents = response.content
850 if len(contents) > 0:
851 raise ValueError("Expecting json, got: %s" % contents)
852
853 def get_json(response):
854 ''' extract json, and error message if present '''
855 try:
856 json = response.json()
857 except ValueError:
858 fail_on_non_empty_value(response)
859 return None, None
860 return json, json.get('error')
861
862 self.log_debug('sending', repr(dict(method=method, url=url, verify=self.verify, params=params,
863 timeout=self.timeout, json=json,
864 headers=headers if self.log_headers else 'redacted',
865 auth_args=auth_args if self.log_auth_args else 'redacted')))
866 try:
867 response = requests.request(method, url, verify=self.verify, params=params,
868 timeout=self.timeout, json=json, headers=headers, files=files, **auth_args)
869 status_code = response.status_code
870 self.log_debug(status_code, response.content)
871 # If the response was successful, no Exception will be raised
872 response.raise_for_status()
873 json_dict, json_error = get_json(response)
874 except requests.exceptions.HTTPError as err:
875 try:
876 __, json_error = get_json(response)
877 except (AttributeError, ValueError):
878 json_error = None
879 if json_error is None:
880 self.log_error(status_code, 'HTTP error: %s' % err)
881 error_details = str(err)
882
883 # If an error was reported in the json payload, it is handled below
884 except requests.exceptions.ConnectionError as err:
885 self.log_error(status_code, 'Connection error: %s' % err)
886 error_details = str(err)
887 except Exception as err:
888 self.log_error(status_code, 'Other error: %s' % err)
889 error_details = str(err)
890 if json_error is not None:
891 self.log_error(status_code, 'Endpoint error: %d: %s' % (status_code, json_error))
892 error_details = json_error
893 if not error_details and not json_dict:
894 if json_dict is None:
895 json_dict = {}
896 if method == 'OPTIONS':
897 # OPTIONS provides the list of supported verbs
898 json_dict['Allow'] = response.headers.get('Allow')
899 if response.headers.get('Content-Type', '').startswith("multipart/form-data"):
900 json_dict['text'] = response.text
901 return status_code, json_dict, error_details
902
903 def _is_job_done(self, job_json, job_state, job_error, timed_out):
904 """ return (done, message, error)
905 done is True to indicate that the job is complete, or failed, or timed out
906 done is False when the job is still running
907 """
908 # a job looks like this
909 # {
910 # "uuid": "cca3d070-58c6-11ea-8c0c-005056826c14",
911 # "description": "POST /api/cluster/metrocluster",
912 # "state": "failure",
913 # "message": "There are not enough disks in Pool1.", **OPTIONAL**
914 # "code": 2432836,
915 # "start_time": "2020-02-26T10:35:44-08:00",
916 # "end_time": "2020-02-26T10:47:38-08:00",
917 # "_links": {
918 # "self": {
919 # "href": "/api/cluster/jobs/cca3d070-58c6-11ea-8c0c-005056826c14"
920 # }
921 # }
922 # }
923 done, error = False, None
924 message = job_json.get('message', '') if job_json else None
925 if job_state == 'failure':
926 # if the job has failed, return message as error
927 error = message
928 message = None
929 done = True
930 elif job_state not in ('queued', 'running', None):
931 error = job_error
932 done = True
933 elif timed_out:
934 # Would like to post a message to user (not sure how)
935 self.log_error(0, 'Timeout error: Process still running')
936 error = 'Timeout error: Process still running'
937 if job_error is not None:
938 error += ' - %s' % job_error
939 done = True
940 return done, message, error
941
942 def wait_on_job(self, job, timeout=600, increment=60):
943 try:
944 url = job['_links']['self']['href'].split('api/')[1]
945 except Exception as err:
946 self.log_error(0, 'URL Incorrect format: %s - Job: %s' % (err, job))
947 return None, 'URL Incorrect format: %s - Job: %s' % (err, job)
948 # Expecting job to be in the following format
949 # {'job':
950 # {'uuid': 'fde79888-692a-11ea-80c2-005056b39fe7',
951 # '_links':
952 # {'self':
953 # {'href': '/api/cluster/jobs/fde79888-692a-11ea-80c2-005056b39fe7'}
954 # }
955 # }
956 # }
957 error = None
958 errors = []
959 message = None
960 runtime = 0
961 retries = 0
962 max_retries = 3
963 done = False
964 while not done:
965 # Will run every <increment> seconds for <timeout> seconds
966 job_json, job_error = self.get(url, None)
967 job_state = job_json.get('state', None) if job_json else None
968 # ignore error if status is provided in the job
969 if job_error and job_state is None:
970 errors.append(str(job_error))
971 retries += 1
972 if retries > max_retries:
973 error = " - ".join(errors)
974 self.log_error(0, 'Job error: Reached max retries.')
975 done = True
976 else:
977 retries = 0
978 done, message, error = self._is_job_done(job_json, job_state, job_error, runtime >= timeout)
979 if not done:
980 time.sleep(increment)
981 runtime += increment
982 return message, error
983
984 def get(self, api, params=None, headers=None):
985 method = 'GET'
986 dummy, message, error = self.send_request(method, api, params, json=None, headers=headers)
987 return message, error
988
989 def post(self, api, body, params=None, headers=None, files=None):
990 method = 'POST'
991 retry = 3
992 while retry > 0:
993 dummy, message, error = self.send_request(method, api, params, json=body, headers=headers, files=files)
994 if error and isinstance(error, dict) and 'temporarily locked' in error.get('message', ''):
995 time.sleep(30)
996 retry = retry - 1
997 continue
998 break
999 return message, error
1000
1001 def patch(self, api, body, params=None, headers=None, files=None):
1002 method = 'PATCH'
1003 retry = 3
1004 while retry > 0:
1005 dummy, message, error = self.send_request(method, api, params, json=body, headers=headers, files=files)
1006 if error and isinstance(error, dict) and 'temporarily locked' in error.get('message', ''):
1007 time.sleep(30)
1008 retry = retry - 1
1009 continue
1010 break
1011 return message, error
1012
1013 def delete(self, api, body=None, params=None, headers=None):
1014 method = 'DELETE'
1015 dummy, message, error = self.send_request(method, api, params, json=body, headers=headers)
1016 return message, error
1017
1018 def options(self, api, params=None, headers=None):
1019 method = 'OPTIONS'
1020 dummy, message, error = self.send_request(method, api, params, json=None, headers=headers)
1021 return message, error
1022
1023 def set_version(self, message):
1024 try:
1025 version = message.get('version', 'not found')
1026 except AttributeError:
1027 self.ontap_version['valid'] = False
1028 self.ontap_version['full'] = 'unreadable message'
1029 return
1030 for key in self.ontap_version:
1031 try:
1032 self.ontap_version[key] = version.get(key, -1)
1033 except AttributeError:
1034 self.ontap_version[key] = -1
1035 self.ontap_version['valid'] = all(
1036 self.ontap_version[key] != -1 for key in self.ontap_version if key != 'valid'
1037 )
1038
1039 def get_ontap_version(self):
1040 if self.ontap_version['valid']:
1041 return self.ontap_version['generation'], self.ontap_version['major'], self.ontap_version['minor']
1042 return -1, -1, -1
1043
1044 def get_node_version_using_rest(self):
1045 # using GET rather than HEAD because the error messages are different,
1046 # and we need the version as some REST options are not available in earlier versions
1047 method = 'GET'
1048 api = 'cluster/nodes'
1049 if should_use_lambda(self.module):
1050 params = {'fields': 'version'}
1051 else:
1052 params = {'fields': ['version']}
1053 status_code, message, error = self.send_request(method, api, params=params)
1054 if message and 'records' in message and len(message['records']) > 0:
1055 message = message['records'][0]
1056 return status_code, message, error
1057
1058 def get_ontap_version_from_params(self):
1059 """ Provide a way to override the current version
1060 This is required when running a custom vsadmin role as ONTAP does not currently allow access to /api/cluster.
1061 This may also be interesting for testing :)
1062 Report a warning if API call failed to report version.
1063 Report a warning if current version could be fetched and is different.
1064 """
1065 try:
1066 version = [int(x) for x in self.force_ontap_version.split('.')]
1067 if len(version) == 2:
1068 version.append(0)
1069 gen, major, minor = version
1070 except (TypeError, ValueError) as exc:
1071 self.module.fail_json(
1072 msg='Error: unexpected format in force_ontap_version, expecting G.M.m or G.M, as in 9.10.1, got: %s, error: %s'
1073 % (self.force_ontap_version, exc))
1074
1075 warning = ''
1076 read_version = self.get_ontap_version()
1077 if read_version == (-1, -1, -1):
1078 warning = ', unable to read current version:'
1079 elif read_version != (gen, major, minor):
1080 warning = ' but current version is %s' % self.ontap_version['full']
1081 if warning:
1082 warning = 'Forcing ONTAP version to %s%s' % (self.force_ontap_version, warning)
1083 self.set_version({'version': {
1084 'generation': gen,
1085 'major': major,
1086 'minor': minor,
1087 'full': 'set by user to %s' % self.force_ontap_version,
1088 }})
1089 return warning
1090
1091 def get_ontap_version_using_rest(self):
1092 # using GET rather than HEAD because the error messages are different,
1093 # and we need the version as some REST options are not available in earlier versions
1094 method = 'GET'
1095 api = 'cluster'
1096 if should_use_lambda(self.module):
1097 params = {'fields': 'version'}
1098 else:
1099 params = {'fields': ['version']}
1100 status_code, message, error = self.send_request(method, api, params=params)
1101 try:
1102 if error and 'are available in precluster.' in error.get('message', ''):
1103 # in precluster mode, version is not available :(
1104 status_code, message, error = self.get_node_version_using_rest()
1105 if error and 'User is not authorized.' in error.get('message', ''):
1106 self.module.fail_json('User is not authorized.')
1107 except AttributeError:
1108 pass
1109 self.set_version(message)
1110 if error:
1111 self.log_error(status_code, str(error))
1112 if self.force_ontap_version:
1113 warning = self.get_ontap_version_from_params()
1114 if error:
1115 warning += ' error: %s, status_code: %s' % (error, status_code)
1116 if warning:
1117 self.module.warn(warning)
1118 msg = 'Forcing ONTAP version to %s' % self.force_ontap_version
1119 if error:
1120 self.log_error('INFO', msg)
1121 else:
1122 self.log_debug('INFO', msg)
1123 error = None
1124 status_code = 200
1125 self.is_rest_error = str(error) if error else None
1126 return status_code
1127
1128 def convert_parameter_keys_to_dot_notation(self, parameters):
1129 """ Get all variable set in a list and add them to a dict so that partially_supported_rest_properties works correctly """
1130 if isinstance(parameters, dict):
1131 temp = {}
1132 for parameter in parameters:
1133 if isinstance(parameters[parameter], list):
1134 if parameter not in temp:
1135 temp[parameter] = {}
1136 for adict in parameters[parameter]:
1137 if isinstance(adict, dict):
1138 for key in adict:
1139 temp[parameter + '.' + key] = 0
1140 parameters.update(temp)
1141 return parameters
1142
1143 def _is_rest(self, used_unsupported_rest_properties=None, partially_supported_rest_properties=None, parameters=None):
1144 if self.use_rest not in ['always', 'auto', 'never']:
1145 error = "use_rest must be one of: never, always, auto. Got: '%s'" % self.use_rest
1146 return False, error
1147 if self.use_rest == "always" and used_unsupported_rest_properties:
1148 error = "REST API currently does not support '%s'" % ', '.join(used_unsupported_rest_properties)
1149 return True, error
1150 if self.use_rest == 'never':
1151 # force ZAPI if requested
1152 return False, None
1153 # Check if ONTAP version is already known
1154 if self.ontap_version['valid']:
1155 status_code = 200
1156 else:
1157 status_code = self.get_ontap_version_using_rest()
1158 if self.use_rest == "always" and partially_supported_rest_properties:
1159 # If a variable is on a list we need to move it to a dict for this check to work correctly.
1160 temp_parameters = parameters.copy()
1161 temp_parameters = self.convert_parameter_keys_to_dot_notation(temp_parameters)
1162 error = '\n'.join(
1163 "Minimum version of ONTAP for %s is %s." % (property[0], str(property[1]))
1164 for property in partially_supported_rest_properties
1165 if self.get_ontap_version()[:3] < property[1] and property[0] in temp_parameters
1166 )
1167 if error != '':
1168 return True, 'Error: %s Current version: %s.' % (error, self.get_ontap_version())
1169 if self.use_rest == 'always':
1170 # ignore error, it will show up later when calling another REST API
1171 return True, None
1172 # we're now using 'auto'
1173 if used_unsupported_rest_properties:
1174 # force ZAPI if some parameter requires it
1175 if self.get_ontap_version()[:2] > (9, 5):
1176 self.fallback_to_zapi_reason =\
1177 'because of unsupported option(s) or option value(s) in REST: %s' % used_unsupported_rest_properties
1178 self.module.warn('Falling back to ZAPI %s' % self.fallback_to_zapi_reason)
1179 return False, None
1180 if partially_supported_rest_properties:
1181 # if ontap version is lower than partially_supported_rest_properties version, force ZAPI, only if the paramater is used
1182 # If a variable is on a list we need to move it to a dict for this check to work correctly.
1183 temp_parameters = parameters.copy()
1184 temp_parameters = self.convert_parameter_keys_to_dot_notation(temp_parameters)
1185 for property in partially_supported_rest_properties:
1186 if self.get_ontap_version()[:3] < property[1] and property[0] in temp_parameters:
1187 self.fallback_to_zapi_reason =\
1188 'because of unsupported option(s) or option value(s) "%s" in REST require %s' % (property[0], str(property[1]))
1189 self.module.warn('Falling back to ZAPI %s' % self.fallback_to_zapi_reason)
1190 return False, None
1191 if self.get_ontap_version()[:2] in ((9, 4), (9, 5)):
1192 # we can't trust REST support on 9.5, and not at all on 9.4
1193 return False, None
1194 return (True, None) if status_code == 200 else (False, None)
1195
1196 def is_rest_supported_properties(self, parameters, unsupported_rest_properties=None, partially_supported_rest_properties=None, report_error=False):
1197 used_unsupported_rest_properties = None
1198 if unsupported_rest_properties:
1199 used_unsupported_rest_properties = [x for x in unsupported_rest_properties if x in parameters]
1200 use_rest, error = self.is_rest(used_unsupported_rest_properties, partially_supported_rest_properties, parameters)
1201 if report_error:
1202 return use_rest, error
1203 if error:
1204 self.module.fail_json(msg=error)
1205 return use_rest
1206
1207 def is_rest(self, used_unsupported_rest_properties=None, partially_supported_rest_properties=None, parameters=None):
1208 ''' only return error if there is a reason to '''
1209 use_rest, error = self._is_rest(used_unsupported_rest_properties, partially_supported_rest_properties, parameters)
1210 if used_unsupported_rest_properties is None and partially_supported_rest_properties is None:
1211 return use_rest
1212 return use_rest, error
1213
1214 def log_error(self, status_code, message):
1215 LOG.error("%s: %s", status_code, message)
1216 self.errors.append(message)
1217 self.debug_logs.append((status_code, message))
1218
1219 def log_debug(self, status_code, content):
1220 LOG.debug("%s: %s", status_code, content)
1221 self.debug_logs.append((status_code, content))
1222
1223 def write_to_file(self, tag, data=None, filepath=None, append=True):
1224 '''
1225 This function is only for debug purposes, all calls to write_to_file should be removed
1226 before submitting.
1227 If data is None, tag is considered as data
1228 else tag is a label, and data is data.
1229 '''
1230 if filepath is None:
1231 filepath = '/tmp/ontap_log'
1232 mode = 'a' if append else 'w'
1233 with open(filepath, mode) as afile:
1234 if data is not None:
1235 afile.write("%s: %s\n" % (str(tag), str(data)))
1236 else:
1237 afile.write(str(tag))
1238 afile.write('\n')
1239
1240 def write_errors_to_file(self, tag=None, filepath=None, append=True):
1241 if tag is None:
1242 tag = 'Error'
1243 for error in self.errors:
1244 self.write_to_file(tag, error, filepath, append)
1245 if not append:
1246 append = True
1247
1248 def write_debug_log_to_file(self, tag=None, filepath=None, append=True):
1249 if tag is None:
1250 tag = 'Debug'
1251 for status_code, message in self.debug_logs:
1252 self.write_to_file(tag, status_code, filepath, append)
1253 if not append:
1254 append = True
1255 self.write_to_file(tag, message, filepath, append)
1256
1257
1258 class AwsLambda(OntapRestAPI):
1259 """
1260 AWS Lambda client for ONTAP API operations.
1261 Handles AWS Lambda invocation and ONTAP API request formatting.
1262 """
1263
1264 def __init__(self, module, lambda_config, hostname=None):
1265 """
1266 Initialize the Lambda proxy client.
1267 :param module: Ansible module instance.
1268 :param lambda_config: Dictionary containing Lambda configuration.
1269 :param hostname: Optional hostname override for peer connections.
1270 """
1271 self.module = module
1272 self.lambda_config = lambda_config
1273 self.lambda_client = None
1274 self.debug_logs = []
1275 # Use provided hostname or fall back to module parameter
1276 self.target_hostname = hostname or module.params.get('hostname')
1277
1278 if not HAS_BOTO3:
1279 module.fail_json(msg="boto3 is required for Lambda functionality. Install with: pip install boto3")
1280 self._setup_lambda_client()
1281
1282 def _setup_lambda_client(self):
1283 """Set up the AWS Lambda client with proper configuration."""
1284 region_name = self.lambda_config.get('aws_region')
1285 profile_name = self.lambda_config.get('aws_profile')
1286
1287 try:
1288 if profile_name:
1289 boto3.setup_default_session(profile_name=profile_name)
1290 self.lambda_client = boto3.client("lambda", region_name=region_name)
1291 except Exception as exc:
1292 self.module.fail_json("Failed to create Lambda client: %s" % exc)
1293
1294 def is_enabled(self):
1295 """Check if Lambda proxy is enabled and properly configured."""
1296 return (self.lambda_config.get('use_lambda', False) and
1297 self.lambda_config.get('function_name'))
1298
1299 def invoke_lambda_function(self, function_name, payload):
1300 """
1301 Invoke a Lambda function with the specified payload.
1302 :param function_name: Name of the Lambda function to invoke.
1303 :param payload: The payload to send to the Lambda function.
1304 :return: Response from the Lambda function.
1305 """
1306 try:
1307 response = self.lambda_client.invoke(
1308 FunctionName=function_name,
1309 InvocationType='RequestResponse', # Synchronous invocation
1310 Payload=json.dumps(payload)
1311 )
1312 return response
1313 except Exception as exc:
1314 self.module.fail_json("Error invoking Lambda function %s: %s" % (function_name, exc))
1315
1316 def _send_request(self, method, url, params, json_data, headers, files):
1317 """
1318 Send an HTTP request through Lambda proxy (compatible with OntapRestAPI._send_request signature).
1319 :param method: HTTP method (GET, POST, PATCH, DELETE).
1320 :param url: Full URL or API path.
1321 :param params: Optional query parameters.
1322 :param json_data: Optional JSON data for POST/PATCH requests.
1323 :param headers: Optional headers.
1324 :param files: Optional files (not supported in Lambda proxy).
1325 :return: Tuple of (status_code, json_response, error_details).
1326 """
1327
1328 # Extract API path from URL if it's a full URL
1329 if url.startswith('https://'):
1330 # Extract just the API path part
1331 api_path = url.split('/api/')[-1]
1332 else:
1333 # Already an API path
1334 api_path = url
1335
1336 function_name = self.lambda_config.get('function_name')
1337 hostname = self.target_hostname
1338 username = self.module.params.get('username')
1339 password = self.module.params.get('password')
1340
1341 if not function_name:
1342 return None, None, "lambda_config.function_name is required when using Lambda proxy"
1343
1344 if not all([hostname, username, password]):
1345 return None, None, "hostname, username, and password are required for Lambda ONTAP operations"
1346
1347 # Build the request URL with API path
1348 if api_path.startswith('/'):
1349 api_path = api_path[1:] # Remove leading slash
1350 api_url = "/api/%s" % api_path
1351
1352 # Add query parameters if provided
1353 if params:
1354 query_string = '&'.join(["%s=%s" % (k, v) for k, v in params.items()])
1355 api_url += "?%s" % query_string
1356
1357 # Prepare authentication
1358 credential = "%s:%s" % (username, password)
1359 base64_credential = base64.b64encode(credential.encode("utf-8")).decode("utf-8")
1360
1361 # Build Lambda payload
1362 payload = {
1363 "body": {
1364 "endpoint": hostname,
1365 "url": api_url,
1366 "method": method.upper(),
1367 "headers": {
1368 "Content-Type": "application/json",
1369 "Accept": "application/json",
1370 "Authorization": "Basic %s" % base64_credential
1371 },
1372 "requestType": "https"
1373 }
1374 }
1375
1376 # Add custom headers if provided
1377 if headers:
1378 payload["body"]["headers"].update(headers)
1379
1380 # Add data for POST/PATCH requests
1381 if json_data and method.upper() in ['POST', 'PATCH', 'PUT']:
1382 payload["body"]["data"] = json_data
1383
1384 try:
1385 # Invoke Lambda function
1386 lambda_response = self.invoke_lambda_function(function_name, payload)
1387 self.log_debug("lambda_response: ", lambda_response)
1388 # Parse Lambda response
1389 if lambda_response and 'Payload' in lambda_response:
1390 response_data = json.loads(lambda_response['Payload'].read())
1391 self.log_debug("response_data: ", response_data)
1392
1393 # Extract status code, JSON response, and error from Lambda response
1394 status_code = response_data.get('status', 500)
1395
1396 # Try to parse the body as JSON
1397 body = response_data.get('data', '{}')
1398 if isinstance(body, str):
1399 try:
1400 json_response = json.loads(body)
1401 except json.JSONDecodeError:
1402 json_response = {"raw_response": body}
1403 else:
1404 json_response = body
1405
1406 # Check for errors
1407 error_details = None
1408 if status_code >= 400:
1409 error_details = json_response.get('error', "HTTP %d error" % status_code)
1410 elif 'error' in json_response:
1411 error_details = json_response['error']
1412
1413 return status_code, json_response, error_details
1414 else:
1415 return 500, None, "Invalid Lambda response format"
1416
1417 except Exception as exc:
1418 return 500, None, "Lambda request failed: %s" % exc