Debian Codegraph @

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

raw
1 #!/usr/bin/python
2 '''
3 # (c) 2020-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 from __future__ import absolute_import, division, print_function
8 __metaclass__ = type
9
10 DOCUMENTATION = '''
11 author: NetApp Ansible Team (@carchi8py) <[email protected]>
12 description:
13 - Call a ZAPI on ONTAP.
14 - Cluster ZAPIs are run using a cluster admin account.
15 - Vserver ZAPIs can be run using a vsadmin account or using vserver tunneling (cluster admin with I(vserver option)).
16 - In case of success, a json dictionary is returned as C(response).
17 - In case of a ZAPI error, C(status), C(errno), C(reason) are set to help with diagnosing the issue,
18 - and the call is reported as an error ('failed').
19 - Other errors (eg connection issues) are reported as Ansible error.
20 extends_documentation_fragment:
21 - netapp.ontap.netapp.na_ontap_zapi
22 module: na_ontap_zapit
23 short_description: NetApp ONTAP Run any ZAPI on ONTAP
24 version_added: "20.4.0"
25 options:
26 zapi:
27 description:
28 - A dictionary for the zapi and arguments.
29 - An XML tag I(<tag>value</tag>) is a dictionary with tag as the key.
30 - Value can be another dictionary, a list of dictionaries, a string, or nothing.
31 - eg I(<tag/>) is represented as I(tag:)
32 - A single zapi can be called at a time. Ansible warns if duplicate keys are found and only uses the last entry.
33 required: true
34 type: dict
35 vserver:
36 description:
37 - if provided, forces vserver tunneling. username identifies a cluster admin account.
38 type: str
39 '''
40
41 EXAMPLES = """
42 -
43 name: Ontap ZAPI
44 hosts: localhost
45 gather_facts: false
46 vars:
47 login: &login
48 hostname: "{{ netapp_hostname }}"
49 username: "{{ netapp_username }}"
50 password: "{{ netapp_password }}"
51 https: true
52 validate_certs: false
53 svm_login: &svm_login
54 hostname: "{{ svm_admin_ip }}"
55 username: "{{ svm_admin_username }}"
56 password: "{{ svm_admin_password }}"
57 https: true
58 validate_certs: false
59
60 tasks:
61 - name: Run ontap ZAPI command as cluster admin
62 netapp.ontap.na_ontap_zapit:
63 <<: *login
64 zapi:
65 system-get-version:
66 register: output
67 - name: Print info
68 ansible.builtin.debug:
69 var: output
70
71 - name: Run ontap ZAPI command as cluster admin
72 netapp.ontap.na_ontap_zapit:
73 <<: *login
74 zapi:
75 vserver-get-iter:
76 register: output
77
78 - name: Run ontap ZAPI command as cluster admin
79 netapp.ontap.na_ontap_zapit:
80 <<: *login
81 zapi:
82 vserver-get-iter:
83 desired-attributes:
84 vserver-info:
85 - aggr-list:
86 - aggr-name
87 - allowed-protocols:
88 - protocols
89 - vserver-aggr-info-list:
90 - vserser-aggr-info
91 - uuid
92 query:
93 vserver-info:
94 vserver-name: trident_svm
95 register: output
96
97 - name: Run ontap ZAPI command as vsadmin
98 netapp.ontap.na_ontap_zapit:
99 <<: *svm_login
100 zapi:
101 vserver-get-iter:
102 desired-attributes:
103 vserver-info:
104 - uuid
105 register: output
106
107 - name: Run ontap ZAPI command as vserver tunneling
108 netapp.ontap.na_ontap_zapit:
109 <<: *login
110 vserver: ansibleSVM
111 zapi:
112 vserver-get-iter:
113 desired-attributes:
114 vserver-info:
115 - uuid
116 register: output
117
118 - name: Run ontap active-directory ZAPI command
119 netapp.ontap.na_ontap_zapit:
120 <<: *login
121 vserver: ansibleSVM
122 zapi:
123 active-directory-account-create:
124 account-name: testaccount
125 admin-username: testuser
126 admin-password: testpass
127 domain: testdomain
128 organizational-unit: testou
129 register: output
130 ignore_errors: true
131 """
132
133 RETURN = """
134 response:
135 description:
136 - If successful, a json dictionary representing the data returned by the ZAPI.
137 - If the ZAPI was executed but failed, an empty dictionary.
138 - Not present if the ZAPI call cannot be performed.
139 returned: On success
140 type: dict
141 status:
142 description:
143 - If the ZAPI was executed but failed, the status set by the ZAPI.
144 - Not present if successful, or if the ZAPI call cannot be performed.
145 returned: On error
146 type: str
147 errno:
148 description:
149 - If the ZAPI was executed but failed, the error code set by the ZAPI.
150 - Not present if successful, or if the ZAPI call cannot be performed.
151 returned: On error
152 type: str
153 reason:
154 description:
155 - If the ZAPI was executed but failed, the error reason set by the ZAPI.
156 - Not present if successful, or if the ZAPI call cannot be performed.
157 returned: On error
158 type: str
159 """
160
161 import traceback
162 from ansible.module_utils.basic import AnsibleModule
163 from ansible.module_utils._text import to_native
164 import ansible_collections.netapp.ontap.plugins.module_utils.netapp as netapp_utils
165
166 try:
167 import xmltodict
168 HAS_XMLTODICT = True
169 except ImportError:
170 HAS_XMLTODICT = False
171
172 try:
173 import json
174 HAS_JSON = True
175 except ImportError:
176 HAS_JSON = False
177
178
179 class NetAppONTAPZapi:
180 ''' calls a ZAPI command '''
181
182 def __init__(self):
183 self.argument_spec = netapp_utils.na_ontap_zapi_only_spec()
184 self.argument_spec.update(dict(
185 zapi=dict(required=True, type='dict'),
186 vserver=dict(required=False, type='str'),
187 ))
188 self.module = AnsibleModule(
189 argument_spec=self.argument_spec,
190 supports_check_mode=False
191 )
192 parameters = self.module.params
193 # set up state variables
194 self.zapi = parameters['zapi']
195 self.vserver = parameters['vserver']
196
197 if not HAS_JSON:
198 self.module.fail_json(msg="the python json module is required")
199 if not netapp_utils.has_netapp_lib():
200 self.module.fail_json(msg=netapp_utils.netapp_lib_is_required())
201 if not HAS_XMLTODICT:
202 self.module.fail_json(msg="the python xmltodict module is required")
203
204 if self.vserver is not None:
205 self.server = netapp_utils.setup_na_ontap_zapi(module=self.module, vserver=self.vserver)
206 else:
207 self.server = netapp_utils.setup_na_ontap_zapi(module=self.module)
208
209 def jsonify_and_parse_output(self, xml_data):
210 ''' convert from XML to JSON
211 extract status and error fields is present
212 '''
213 try:
214 as_str = xml_data.to_string()
215 except Exception as exc:
216 self.module.fail_json(msg='Error running zapi in to_string: %s' %
217 str(exc))
218 try:
219 as_dict = xmltodict.parse(as_str, xml_attribs=True)
220 except Exception as exc:
221 self.module.fail_json(msg='Error running zapi in xmltodict: %s: %s' %
222 (as_str, str(exc)))
223 try:
224 as_json = json.loads(json.dumps(as_dict))
225 except Exception as exc:
226 self.module.fail_json(msg='Error running zapi in json load/dump: %s: %s' %
227 (as_dict, str(exc)))
228
229 if 'results' not in as_json:
230 self.module.fail_json(msg='Error running zapi, no results field: %s: %s' %
231 (as_str, repr(as_json)))
232
233 # set status, and if applicable errno/reason, and remove attribute fields
234 errno = None
235 reason = None
236 response = as_json.pop('results')
237 status = response.get('@status', 'no_status_attr')
238 if status != 'passed':
239 # collect errno and reason
240 errno = response.get('@errno', None)
241 if errno is None:
242 errno = response.get('errorno', None)
243 if errno is None:
244 errno = 'ESTATUSFAILED'
245 reason = response.get('@reason', None)
246 if reason is None:
247 reason = response.get('reason', None)
248 if reason is None:
249 reason = 'Execution failure with unknown reason.'
250
251 for key in ('@status', '@errno', '@reason', '@xmlns'):
252 try:
253 # remove irrelevant info
254 del response[key]
255 except KeyError:
256 pass
257 return response, status, errno, reason
258
259 def run_zapi(self):
260 ''' calls the ZAPI '''
261 zapi_struct = self.zapi
262 error = None
263 if not isinstance(zapi_struct, dict):
264 error = 'A directory entry is expected, eg: system-get-version: '
265 zapi = zapi_struct
266 else:
267 zapi = list(zapi_struct.keys())
268 if len(zapi) != 1:
269 error = 'A single ZAPI can be called at a time'
270 else:
271 zapi = zapi[0]
272
273 # log first, then error out as needed
274 if error:
275 self.module.fail_json(msg='%s, received: %s' % (error, zapi))
276
277 zapi_obj = netapp_utils.zapi.NaElement(zapi)
278 attributes = zapi_struct[zapi]
279 if attributes is not None and attributes != 'None':
280 zapi_obj.translate_struct(attributes)
281
282 try:
283 output = self.server.invoke_elem(zapi_obj, True)
284 except netapp_utils.zapi.NaApiError as error:
285 self.module.fail_json(msg='Error running zapi %s: %s' %
286 (zapi, to_native(error)),
287 exception=traceback.format_exc())
288
289 return self.jsonify_and_parse_output(output)
290
291 def apply(self):
292 ''' calls the zapi and returns json output '''
293 response, status, errno, reason = self.run_zapi()
294 if status == 'passed':
295 self.module.exit_json(changed=True, response=response)
296 msg = 'ZAPI failure: check errno and reason.'
297 self.module.fail_json(changed=False, response=response, status=status, errno=errno, reason=reason, msg=msg)
298
299
300 def main():
301 """
302 Execute action from playbook
303 """
304 zapi = NetAppONTAPZapi()
305 zapi.apply()
306
307
308 if __name__ == '__main__':
309 main()