Debian Codegraph @

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

raw
1 #!/usr/bin/python
2
3 # (c) 2018-2026, NetApp, Inc
4 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
5 from __future__ import absolute_import, division, print_function
6 __metaclass__ = type
7
8 DOCUMENTATION = '''
9 author: NetApp Ansible Team (@carchi8py) <[email protected]>
10 description:
11 - Create/Delete NVME subsystem
12 - Associate(modify) host/map to NVME subsystem
13 - NVMe service should be existing in the data vserver with NVMe protocol as a pre-requisite
14 extends_documentation_fragment:
15 - netapp.ontap.netapp.na_ontap
16 module: na_ontap_nvme_subsystem
17 options:
18 state:
19 choices: ['present', 'absent']
20 description:
21 - Whether the specified subsystem should exist or not.
22 default: present
23 type: str
24 vserver:
25 description:
26 - Name of the vserver to use.
27 required: true
28 type: str
29 subsystem:
30 description:
31 - Specifies the subsystem
32 required: true
33 type: str
34 ostype:
35 description:
36 - Specifies the ostype for initiators
37 choices: ['windows', 'linux', 'vmware', 'xen', 'hyper_v']
38 type: str
39 skip_host_check:
40 description:
41 - Skip host check
42 - Required to delete an NVMe Subsystem with attached NVMe namespaces
43 default: false
44 type: bool
45 skip_mapped_check:
46 description:
47 - Skip mapped namespace check
48 - Required to delete an NVMe Subsystem with attached NVMe namespaces
49 default: false
50 type: bool
51 hosts:
52 description:
53 - List of host NQNs (NVMe Qualification Name) associated to the controller.
54 type: list
55 elements: str
56 paths:
57 description:
58 - List of Namespace paths to be associated with the subsystem.
59 - For ASA r2 systems, The paths should match the format <name>[@<snapshot-name>].
60 type: list
61 elements: str
62 short_description: "NetApp ONTAP Manage NVME Subsystem"
63 version_added: 2.8.0
64 notes:
65 - Compatible with ASA r2 system when using REST for ONTAP releases 9.16.0x onwards.
66 '''
67
68 EXAMPLES = """
69 - name: Create NVME Subsystem
70 netapp.ontap.na_ontap_nvme_subsystem:
71 state: present
72 subsystem: test_sub
73 vserver: test_dest
74 ostype: linux
75 hostname: "{{ netapp_hostname }}"
76 username: "{{ netapp_username }}"
77 password: "{{ netapp_password }}"
78
79 - name: Delete NVME Subsystem
80 netapp.ontap.na_ontap_nvme_subsystem:
81 state: absent
82 subsystem: test_sub
83 vserver: test_dest
84 skip_host_check: true
85 skip_mapped_check: true
86 hostname: "{{ netapp_hostname }}"
87 username: "{{ netapp_username }}"
88 password: "{{ netapp_password }}"
89
90 - name: Associate NVME Subsystem host/map
91 netapp.ontap.na_ontap_nvme_subsystem:
92 state: present
93 subsystem: "{{ subsystem }}"
94 ostype: linux
95 hosts: nqn.1992-08.com.netapp:sn.3017cfc1e2ba11e89c55005056b36338:subsystem.ansible
96 paths: /vol/ansible/test,/vol/ansible/test1
97 vserver: "{{ vserver }}"
98 hostname: "{{ netapp_hostname }}"
99 username: "{{ netapp_username }}"
100 password: "{{ netapp_password }}"
101
102 - name: Modify NVME subsystem map
103 netapp.ontap.na_ontap_nvme_subsystem:
104 state: present
105 subsystem: test_sub
106 vserver: test_dest
107 skip_host_check: true
108 skip_mapped_check: true
109 paths: /vol/ansible/test
110 hostname: "{{ netapp_hostname }}"
111 username: "{{ netapp_username }}"
112 password: "{{ netapp_password }}"
113 """
114
115 RETURN = """
116 """
117
118 import traceback
119 from ansible.module_utils.basic import AnsibleModule
120 from ansible.module_utils._text import to_native
121 import ansible_collections.netapp.ontap.plugins.module_utils.netapp as netapp_utils
122 from ansible_collections.netapp.ontap.plugins.module_utils.netapp_module import NetAppModule
123 from ansible_collections.netapp.ontap.plugins.module_utils import rest_generic, rest_ontap_personality
124
125
126 class NetAppONTAPNVMESubsystem:
127 """
128 Class with NVME subsystem methods
129 """
130
131 def __init__(self):
132
133 self.subsystem_uuid = None
134 self.namespace_list = []
135 self.argument_spec = netapp_utils.na_ontap_host_argument_spec()
136 self.argument_spec.update(dict(
137 state=dict(required=False, type='str', choices=['present', 'absent'], default='present'),
138 vserver=dict(required=True, type='str'),
139 subsystem=dict(required=True, type='str'),
140 ostype=dict(required=False, type='str', choices=['windows', 'linux', 'vmware', 'xen', 'hyper_v']),
141 skip_host_check=dict(required=False, type='bool', default=False),
142 skip_mapped_check=dict(required=False, type='bool', default=False),
143 hosts=dict(required=False, type='list', elements='str'),
144 paths=dict(required=False, type='list', elements='str')
145 ))
146
147 self.module = AnsibleModule(
148 argument_spec=self.argument_spec,
149 supports_check_mode=True
150 )
151
152 self.na_helper = NetAppModule(self.module)
153 self.parameters = self.na_helper.set_parameters(self.module.params)
154 self.rest_api = netapp_utils.OntapRestAPI(self.module)
155 self.use_rest = self.rest_api.is_rest()
156 self.asa_r2_system = False
157 if self.use_rest:
158 if self.rest_api.meets_rest_minimum_version(True, 9, 16, 0):
159 self.asa_r2_system = rest_ontap_personality.is_asa_r2_system(self.rest_api, self.module)
160 if self.asa_r2_system:
161 if 'paths' in self.parameters:
162 self.module.warn('For ASA r2 systems, The paths should match the format <name>[@<snapshot-name>].'
163 'The name must begin with a letter or \"_\" and contain only \"_\" and alphanumeric character')
164 # If the path is passed as vol/vol1/ns it will be converted to ns for asa r2 systems.
165 self.parameters['paths'] = [item.split("/")[-1] for item in self.parameters['paths']]
166 if not self.use_rest:
167 if not netapp_utils.has_netapp_lib():
168 self.module.fail_json(msg=netapp_utils.netapp_lib_is_required())
169 self.server = netapp_utils.setup_na_ontap_zapi(module=self.module, vserver=self.parameters['vserver'])
170
171 def get_subsystem(self):
172 """
173 Get current subsystem details
174 :return: dict if subsystem exists, None otherwise
175 """
176 if self.use_rest:
177 return self.get_subsystem_rest()
178 result = self.get_zapi_info('nvme-subsystem-get-iter', 'nvme-subsystem-info')
179 if result.get_child_by_name('num-records') and int(result.get_child_content('num-records')) >= 1:
180 return True
181 return None
182
183 def create_subsystem(self):
184 """
185 Create a NVME Subsystem
186 """
187 if self.use_rest:
188 return self.create_subsystem_rest()
189 options = {'subsystem': self.parameters['subsystem'],
190 'ostype': self.parameters['ostype']
191 }
192 subsystem_create = netapp_utils.zapi.NaElement('nvme-subsystem-create')
193 subsystem_create.translate_struct(options)
194 try:
195 self.server.invoke_successfully(subsystem_create, enable_tunneling=True)
196 except netapp_utils.zapi.NaApiError as error:
197 self.module.fail_json(msg='Error creating subsystem for %s: %s'
198 % (self.parameters.get('subsystem'), to_native(error)),
199 exception=traceback.format_exc())
200
201 def delete_subsystem(self):
202 """
203 Delete a NVME subsystem
204 """
205 if self.use_rest:
206 return self.delete_subsystem_rest()
207 options = {'subsystem': self.parameters['subsystem'],
208 'skip-host-check': 'true' if self.parameters.get('skip_host_check') else 'false',
209 'skip-mapped-check': 'true' if self.parameters.get('skip_mapped_check') else 'false',
210 }
211 subsystem_delete = netapp_utils.zapi.NaElement.create_node_with_children('nvme-subsystem-delete', **options)
212 try:
213 self.server.invoke_successfully(subsystem_delete, enable_tunneling=True)
214 except netapp_utils.zapi.NaApiError as error:
215 self.module.fail_json(msg='Error deleting subsystem for %s: %s'
216 % (self.parameters.get('subsystem'), to_native(error)),
217 exception=traceback.format_exc())
218
219 def get_subsystem_host_map(self, type):
220 """
221 Get current subsystem host details
222 :return: list if host exists, None otherwise
223 """
224 if type == 'hosts':
225 zapi_get, zapi_info, zapi_type = 'nvme-subsystem-host-get-iter', 'nvme-target-subsystem-host-info', 'host-nqn'
226 elif type == 'paths':
227 zapi_get, zapi_info, zapi_type = 'nvme-subsystem-map-get-iter', 'nvme-target-subsystem-map-info', 'path'
228 result = self.get_zapi_info(zapi_get, zapi_info, zapi_type)
229 if result.get_child_by_name('num-records') and int(result.get_child_content('num-records')) >= 1:
230 attrs_list = result.get_child_by_name('attributes-list')
231 return_list = [item[zapi_type] for item in attrs_list.get_children()]
232 return {type: return_list}
233 return None
234
235 def get_zapi_info(self, zapi_get_method, zapi_info, zapi_type=None):
236 subsystem_get = netapp_utils.zapi.NaElement(zapi_get_method)
237 query = {
238 'query': {
239 zapi_info: {
240 'subsystem': self.parameters.get('subsystem'),
241 'vserver': self.parameters.get('vserver')
242 }
243 }
244 }
245 subsystem_get.translate_struct(query)
246 qualifier = " %s" % zapi_type if zapi_type else ""
247 try:
248 result = self.server.invoke_successfully(subsystem_get, enable_tunneling=False)
249 except netapp_utils.zapi.NaApiError as error:
250 self.module.fail_json(msg='Error fetching subsystem%s info: %s' % (qualifier, to_native(error)),
251 exception=traceback.format_exc())
252 return result
253
254 def add_subsystem_host_map(self, data, type):
255 """
256 Add a NVME Subsystem host/map
257 :param: data: list of hosts/paths to be added
258 :param: type: hosts/paths
259 """
260 if type == 'hosts':
261 zapi_add, zapi_type = 'nvme-subsystem-host-add', 'host-nqn'
262 elif type == 'paths':
263 zapi_add, zapi_type = 'nvme-subsystem-map-add', 'path'
264
265 for item in data:
266 options = {'subsystem': self.parameters['subsystem'],
267 zapi_type: item
268 }
269 subsystem_add = netapp_utils.zapi.NaElement.create_node_with_children(zapi_add, **options)
270 try:
271 self.server.invoke_successfully(subsystem_add, enable_tunneling=True)
272 except netapp_utils.zapi.NaApiError as error:
273 self.module.fail_json(msg='Error adding %s for subsystem %s: %s'
274 % (item, self.parameters.get('subsystem'), to_native(error)),
275 exception=traceback.format_exc())
276
277 def remove_subsystem_host_map(self, data, type):
278 """
279 Remove a NVME Subsystem host/map
280 :param: data: list of hosts/paths to be added
281 :param: type: hosts/paths
282 """
283 if type == 'hosts':
284 zapi_remove, zapi_type = 'nvme-subsystem-host-remove', 'host-nqn'
285 elif type == 'paths':
286 zapi_remove, zapi_type = 'nvme-subsystem-map-remove', 'path'
287
288 for item in data:
289 options = {'subsystem': self.parameters['subsystem'],
290 zapi_type: item
291 }
292 subsystem_remove = netapp_utils.zapi.NaElement.create_node_with_children(zapi_remove, **options)
293 try:
294 self.server.invoke_successfully(subsystem_remove, enable_tunneling=True)
295 except netapp_utils.zapi.NaApiError as error:
296 self.module.fail_json(msg='Error removing %s for subsystem %s: %s'
297 % (item, self.parameters.get('subsystem'), to_native(error)),
298 exception=traceback.format_exc())
299
300 def associate_host_map(self, types):
301 """
302 Check if there are hosts or paths to be associated with the subsystem
303 """
304 action_add_dict = {}
305 action_remove_dict = {}
306 for type in types:
307 current = None
308 if self.parameters.get(type):
309 if self.use_rest:
310 if self.subsystem_uuid:
311 current = self.get_subsystem_host_map_rest(type)
312 else:
313 current = self.get_subsystem_host_map(type)
314 if current:
315 add_items = self.na_helper.\
316 get_modified_attributes(current, self.parameters, get_list_diff=True).get(type)
317 remove_items = [item for item in current[type] if item not in self.parameters.get(type)]
318 else:
319 add_items = self.parameters[type]
320 remove_items = {}
321 if add_items:
322 action_add_dict[type] = add_items
323 self.na_helper.changed = True
324 if remove_items:
325 action_remove_dict[type] = remove_items
326 self.na_helper.changed = True
327 return action_add_dict, action_remove_dict
328
329 def modify_host_map(self, add_host_map, remove_host_map):
330 for type, data in sorted(add_host_map.items()):
331 if self.use_rest:
332 self.add_subsystem_host_map_rest(data, type)
333 else:
334 self.add_subsystem_host_map(data, type)
335 for type, data in sorted(remove_host_map.items()):
336 if self.use_rest:
337 self.remove_subsystem_host_map_rest(data, type)
338 else:
339 self.remove_subsystem_host_map(data, type)
340
341 def get_subsystem_rest(self):
342 api = 'protocols/nvme/subsystems'
343 params = {'svm.name': self.parameters['vserver'], 'name': self.parameters['subsystem']}
344 record, error = rest_generic.get_one_record(self.rest_api, api, params)
345 if error:
346 if self.na_helper.ignore_missing_vserver_on_delete(error):
347 return None
348 self.module.fail_json(msg='Error fetching subsystem info for vserver: %s, %s' % (self.parameters['vserver'], to_native(error)))
349 if record:
350 self.subsystem_uuid = record['uuid']
351 return record
352 return None
353
354 def get_subsystem_host_map_rest(self, type):
355 if type == 'hosts':
356 api = 'protocols/nvme/subsystems/%s/hosts' % self.subsystem_uuid
357 records, error = rest_generic.get_0_or_more_records(self.rest_api, api)
358 if error:
359 self.module.fail_json(msg='Error fetching subsystem host info for vserver: %s: %s' % (self.parameters['vserver'], to_native(error)))
360 if records is not None:
361 return {type: [record['nqn'] for record in records]}
362 return None
363 if type == 'paths':
364 api = 'protocols/nvme/subsystem-maps'
365 query = {'svm.name': self.parameters['vserver'], 'subsystem.name': self.parameters['subsystem']}
366 records, error = rest_generic.get_0_or_more_records(self.rest_api, api, query)
367 if error:
368 self.module.fail_json(msg='Error fetching subsystem map info for vserver: %s: %s' % (self.parameters['vserver'], to_native(error)))
369 if records is not None:
370 return_list = []
371 for each in records:
372 return_list.append(each['namespace']['name'])
373 self.namespace_list.append(each['namespace'])
374 return {type: return_list}
375 return None
376
377 def add_subsystem_host_map_rest(self, data, type):
378 if type == 'hosts':
379 records = [{'nqn': item} for item in data]
380 api = 'protocols/nvme/subsystems/%s/hosts' % self.subsystem_uuid
381 body = {'records': records}
382 dummy, error = rest_generic.post_async(self.rest_api, api, body)
383 if error:
384 self.module.fail_json(
385 msg='Error adding %s for subsystem %s: %s' % (records, self.parameters['subsystem'], to_native(error)), exception=traceback.format_exc())
386 elif type == 'paths':
387 api = 'protocols/nvme/subsystem-maps'
388 for item in data:
389 body = {'subsystem.name': self.parameters['subsystem'],
390 'svm.name': self.parameters['vserver'],
391 'namespace.name': item
392 }
393 dummy, error = rest_generic.post_async(self.rest_api, api, body)
394 if error:
395 self.module.fail_json(
396 msg='Error adding %s for subsystem %s: %s' % (item, self.parameters['subsystem'], to_native(error)), exception=traceback.format_exc())
397
398 def remove_subsystem_host_map_rest(self, data, type):
399 if type == 'hosts':
400 for item in data:
401 api = 'protocols/nvme/subsystems/%s/hosts/%s' % (self.subsystem_uuid, item)
402 dummy, error = rest_generic.delete_async(self.rest_api, api, None)
403 if error:
404 self.module.fail_json(msg='Error removing %s for subsystem %s: %s'
405 % (item, self.parameters['subsystem'], to_native(error)), exception=traceback.format_exc())
406 elif type == 'paths':
407 for item in data:
408 namespace_uuid = None
409 for each in self.namespace_list:
410 if each['name'] == item:
411 namespace_uuid = each['uuid']
412 api = 'protocols/nvme/subsystem-maps/%s/%s' % (self.subsystem_uuid, namespace_uuid)
413 body = {'subsystem.name': self.parameters['subsystem'],
414 'svm.name': self.parameters['vserver'],
415 'namespace.name': item
416 }
417 dummy, error = rest_generic.delete_async(self.rest_api, api, None, body=body)
418 if error:
419 self.module.fail_json(msg='Error removing %s for subsystem %s: %s'
420 % (item, self.parameters['subsystem'], to_native(error)), exception=traceback.format_exc())
421
422 def create_subsystem_rest(self):
423 api = 'protocols/nvme/subsystems'
424 body = {'svm.name': self.parameters['vserver'],
425 'os_type': self.parameters['ostype'],
426 'name': self.parameters['subsystem']}
427 dummy, error = rest_generic.post_async(self.rest_api, api, body)
428 if error:
429 self.module.fail_json(msg='Error creating subsystem for vserver %s: %s' % (self.parameters['vserver'], to_native(error)),
430 exception=traceback.format_exc())
431
432 def delete_subsystem_rest(self):
433 api = 'protocols/nvme/subsystems'
434 body = {'allow_delete_while_mapped': 'true' if self.parameters.get('skip_mapped_check') else 'false',
435 'allow_delete_with_hosts': 'true' if self.parameters.get('skip_host_check') else 'false'}
436 dummy, error = rest_generic.delete_async(self.rest_api, api, self.subsystem_uuid, body=body)
437 if error:
438 self.module.fail_json(msg='Error deleting subsystem for vserver %s: %s' % (self.parameters['vserver'], to_native(error)),
439 exception=traceback.format_exc())
440
441 def apply(self):
442 """
443 Apply action to NVME subsystem
444 """
445 types = ['hosts', 'paths']
446 current = self.get_subsystem()
447 add_host_map, remove_host_map = dict(), dict()
448 cd_action = self.na_helper.get_cd_action(current, self.parameters)
449 if cd_action == 'create' and self.parameters.get('ostype') is None:
450 self.module.fail_json(msg="Error: Missing required parameter 'ostype' for creating subsystem")
451 if cd_action != 'delete' and self.parameters['state'] == 'present':
452 add_host_map, remove_host_map = self.associate_host_map(types)
453 if self.na_helper.changed and not self.module.check_mode:
454 if cd_action == 'create':
455 self.create_subsystem()
456 self.get_subsystem()
457 self.modify_host_map(add_host_map, remove_host_map)
458 elif cd_action == 'delete':
459 self.delete_subsystem()
460 elif cd_action is None:
461 self.modify_host_map(add_host_map, remove_host_map)
462 result = netapp_utils.generate_result(self.na_helper.changed, cd_action)
463 self.module.exit_json(**result)
464
465
466 def main():
467 """Execute action"""
468 community_obj = NetAppONTAPNVMESubsystem()
469 community_obj.apply()
470
471
472 if __name__ == '__main__':
473 main()