Debian Codegraph @

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

raw
1 #!/usr/bin/python
2
3 # (c) 2019-2025, NetApp, Inc
4 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
5
6 '''
7 na_ontap_ports
8 '''
9
10 from __future__ import absolute_import, division, print_function
11
12 __metaclass__ = type
13
14 DOCUMENTATION = '''
15
16 module: na_ontap_ports
17 short_description: NetApp ONTAP add/remove ports
18 extends_documentation_fragment:
19 - netapp.ontap.netapp.na_ontap
20 version_added: 2.9.0
21 author: NetApp Ansible Team (@carchi8py) <[email protected]>
22
23 description:
24 - Add or remove ports for broadcast domain and portset.
25
26 options:
27 state:
28 description:
29 - Whether the specified port should be added or removed.
30 choices: ['present', 'absent']
31 default: present
32 type: str
33
34 vserver:
35 description:
36 - Name of the SVM.
37 - Specify this option when operating on portset.
38 type: str
39
40 names:
41 description:
42 - List of ports.
43 type: list
44 elements: str
45 required: true
46
47 resource_name:
48 description:
49 - name of the portset or broadcast domain.
50 type: str
51 required: true
52
53 resource_type:
54 description:
55 - type of the resource to add a port to or remove a port from.
56 - adding or removing ports in portset requires ONTAP version 9.9 or later in REST
57 choices: ['broadcast_domain', 'portset']
58 required: true
59 type: str
60
61 ipspace:
62 description:
63 - Specify the required ipspace for the broadcast domain.
64 - A domain ipspace can not be modified after the domain has been created.
65 type: str
66
67 portset_type:
68 description:
69 - Protocols accepted for portset.
70 choices: ['fcp', 'iscsi', 'mixed']
71 type: str
72
73 '''
74
75 EXAMPLES = '''
76 - name: Broadcast domain remove port
77 netapp.ontap.na_ontap_ports:
78 state: absent
79 names: test-vsim1:e0d-1,test-vsim1:e0d-2
80 resource_type: broadcast_domain
81 resource_name: ansible_domain
82 hostname: "{{ netapp_hostname }}"
83 username: "{{ netapp_username }}"
84 password: "{{ netapp_password }}"
85 https: true
86
87 - name: Broadcast domain add port
88 netapp.ontap.na_ontap_ports:
89 state: present
90 names: test-vsim1:e0d-1,test-vsim1:e0d-2
91 resource_type: broadcast_domain
92 resource_name: ansible_domain
93 ipspace: Default
94 hostname: "{{ netapp_hostname }}"
95 username: "{{ netapp_username }}"
96 password: "{{ netapp_password }}"
97 https: true
98
99 - name: Portset remove port
100 netapp.ontap.na_ontap_ports:
101 state: absent
102 names: lif_2
103 resource_type: portset
104 resource_name: portset_1
105 vserver: "{{ vserver }}"
106 hostname: "{{ netapp_hostname }}"
107 username: "{{ netapp_username }}"
108 password: "{{ netapp_password }}"
109 https: true
110
111 - name: Portset add port
112 netapp.ontap.na_ontap_ports:
113 state: present
114 names: lif_2
115 resource_type: portset
116 resource_name: portset_1
117 portset_type: iscsi
118 vserver: "{{ vserver }}"
119 hostname: "{{ netapp_hostname }}"
120 username: "{{ netapp_username }}"
121 password: "{{ netapp_password }}"
122 https: true
123 '''
124
125 RETURN = '''
126 '''
127
128 import traceback
129
130 from ansible.module_utils.basic import AnsibleModule
131 from ansible.module_utils._text import to_native
132 import ansible_collections.netapp.ontap.plugins.module_utils.netapp as netapp_utils
133 from ansible_collections.netapp.ontap.plugins.module_utils.netapp_module import NetAppModule
134 from ansible_collections.netapp.ontap.plugins.module_utils.netapp import OntapRestAPI
135 from ansible_collections.netapp.ontap.plugins.module_utils import rest_generic
136
137
138 class NetAppOntapPorts:
139
140 def __init__(self):
141 self.argument_spec = netapp_utils.na_ontap_host_argument_spec()
142 self.argument_spec.update(dict(
143 state=dict(required=False, choices=['present', 'absent'], default='present'),
144 vserver=dict(required=False, type='str'),
145 names=dict(required=True, type='list', elements='str'),
146 resource_name=dict(required=True, type='str'),
147 resource_type=dict(required=True, type='str', choices=['broadcast_domain', 'portset']),
148 ipspace=dict(required=False, type='str'),
149 portset_type=dict(required=False, type='str', choices=['fcp', 'iscsi', 'mixed']),
150 ))
151
152 self.module = AnsibleModule(
153 argument_spec=self.argument_spec,
154 required_if=[
155 ('resource_type', 'portset', ['vserver']),
156 ],
157 supports_check_mode=True
158 )
159
160 self.na_helper = NetAppModule()
161 self.parameters = self.na_helper.set_parameters(self.module.params)
162
163 # Set up Rest API
164 self.rest_api = OntapRestAPI(self.module)
165 self.use_rest = self.rest_api.is_rest()
166 self.desired_ports = None
167 self.desired_lifs = None
168
169 if self.use_rest and 'ipspace' not in self.parameters and self.parameters['resource_type'] == 'broadcast_domain':
170 error_msg = "Error: ipspace space is a required option with REST"
171 self.module.fail_json(msg=error_msg)
172
173 if self.use_rest and not self.rest_api.meets_rest_minimum_version(self.use_rest, 9, 9) and self.parameters['resource_type'] == 'portset':
174 self.module.fail_json(msg='Error: adding or removing ports in portset requires ONTAP version 9.9 or later in REST')
175
176 if 'names' in self.parameters:
177 self.parameters['names'] = list(set([port.strip() for port in self.parameters['names']]))
178 if self.use_rest and self.parameters['resource_type'] == 'broadcast_domain':
179 self.desired_ports = self.get_ports_rest(self.parameters['names'])
180 if self.use_rest and self.parameters['resource_type'] == 'portset':
181 self.desired_lifs = self.get_san_lifs_rest(self.parameters['names'])
182
183 if not self.use_rest:
184 if not netapp_utils.has_netapp_lib():
185 self.module.fail_json(msg=netapp_utils.netapp_lib_is_required())
186 if self.parameters['resource_type'] == 'broadcast_domain':
187 self.server = netapp_utils.setup_na_ontap_zapi(module=self.module)
188 elif self.parameters['resource_type'] == 'portset':
189 self.server = netapp_utils.setup_na_ontap_zapi(module=self.module, vserver=self.parameters['vserver'])
190
191 def add_broadcast_domain_ports(self, ports):
192 """
193 Add broadcast domain ports
194 :param: ports to be added.
195 """
196 domain_obj = netapp_utils.zapi.NaElement('net-port-broadcast-domain-add-ports')
197 domain_obj.add_new_child("broadcast-domain", self.parameters['resource_name'])
198 if self.parameters.get('ipspace'):
199 domain_obj.add_new_child("ipspace", self.parameters['ipspace'])
200 ports_obj = netapp_utils.zapi.NaElement('ports')
201 domain_obj.add_child_elem(ports_obj)
202 for port in ports:
203 ports_obj.add_new_child('net-qualified-port-name', port)
204 try:
205 self.server.invoke_successfully(domain_obj, True)
206 return True
207 except netapp_utils.zapi.NaApiError as error:
208 self.module.fail_json(msg='Error adding port for broadcast domain %s: %s' %
209 (self.parameters['resource_name'], to_native(error)),
210 exception=traceback.format_exc())
211
212 def add_broadcast_domain_ports_rest(self, ports):
213 """
214 Add broadcast domain ports in rest.
215 :param: ports to be added or moved.
216 """
217 api = 'network/ethernet/ports'
218 body = {
219 'broadcast_domain': {
220 'name': self.parameters['resource_name'],
221 'ipspace': {'name': self.parameters['ipspace']}
222 }
223 }
224 for port in ports:
225 dummy, error = rest_generic.patch_async(self.rest_api, api, port['uuid'], body)
226 if error:
227 self.module.fail_json(msg=error)
228
229 def remove_broadcast_domain_ports(self, ports):
230 """
231 Deletes broadcast domain ports
232 :param: ports to be removed.
233 """
234 domain_obj = netapp_utils.zapi.NaElement('net-port-broadcast-domain-remove-ports')
235 domain_obj.add_new_child("broadcast-domain", self.parameters['resource_name'])
236 if self.parameters.get('ipspace'):
237 domain_obj.add_new_child("ipspace", self.parameters['ipspace'])
238 ports_obj = netapp_utils.zapi.NaElement('ports')
239 domain_obj.add_child_elem(ports_obj)
240 for port in ports:
241 ports_obj.add_new_child('net-qualified-port-name', port)
242 try:
243 self.server.invoke_successfully(domain_obj, True)
244 return True
245 except netapp_utils.zapi.NaApiError as error:
246 self.module.fail_json(msg='Error removing port for broadcast domain %s: %s' %
247 (self.parameters['resource_name'], to_native(error)),
248 exception=traceback.format_exc())
249
250 def remove_broadcast_domain_ports_rest(self, ports, ipspace):
251 body = {'ports': ports}
252 api = "private/cli/network/port/broadcast-domain/remove-ports"
253 query = {'broadcast-domain': self.parameters['resource_name'], 'ipspace': ipspace}
254 response, error = rest_generic.patch_async(self.rest_api, api, None, body, query)
255 if error:
256 self.module.fail_json(msg='Error removing ports: %s' % error)
257
258 def get_broadcast_domain_ports(self):
259 """
260 Return details about the broadcast domain ports.
261 :return: Details about the broadcast domain ports. [] if not found.
262 :rtype: list
263 """
264 if self.use_rest:
265 return self.get_broadcast_domain_ports_rest()
266 domain_get_iter = netapp_utils.zapi.NaElement('net-port-broadcast-domain-get-iter')
267 broadcast_domain_info = netapp_utils.zapi.NaElement('net-port-broadcast-domain-info')
268 broadcast_domain_info.add_new_child('broadcast-domain', self.parameters['resource_name'])
269 query = netapp_utils.zapi.NaElement('query')
270 query.add_child_elem(broadcast_domain_info)
271 domain_get_iter.add_child_elem(query)
272 result = self.server.invoke_successfully(domain_get_iter, True)
273 ports = []
274 if result.get_child_by_name('num-records') and \
275 int(result.get_child_content('num-records')) == 1:
276 domain_info = result.get_child_by_name('attributes-list').get_child_by_name('net-port-broadcast-domain-info')
277 domain_ports = domain_info.get_child_by_name('ports')
278 if domain_ports is not None:
279 ports = [port.get_child_content('port') for port in domain_ports.get_children()]
280 return ports
281
282 def get_broadcast_domain_ports_rest(self):
283 """
284 Return details about the broadcast domain ports.
285 :return: Details about the broadcast domain ports. [] if not found.
286 :rtype: list
287 """
288 api = 'network/ethernet/broadcast-domains'
289 query = {'name': self.parameters['resource_name'], 'ipspace.name': self.parameters['ipspace']}
290 fields = 'ports'
291 record, error = rest_generic.get_one_record(self.rest_api, api, query, fields)
292 if error:
293 self.module.fail_json(msg=error)
294 ports = []
295 if record and 'ports' in record:
296 ports = ['%s:%s' % (port['node']['name'], port['name']) for port in record['ports']]
297 return ports
298
299 def remove_portset_ports(self, port, portset_uuid=None):
300 """
301 Removes all existing ports from portset
302 :return: None
303 """
304 if self.use_rest:
305 return self.remove_portset_ports_rest(port, portset_uuid)
306 options = {'portset-name': self.parameters['resource_name'],
307 'portset-port-name': port.strip()}
308
309 portset_modify = netapp_utils.zapi.NaElement.create_node_with_children('portset-remove', **options)
310
311 try:
312 self.server.invoke_successfully(portset_modify, enable_tunneling=True)
313 except netapp_utils.zapi.NaApiError as error:
314 self.module.fail_json(msg='Error removing port in portset %s: %s' %
315 (self.parameters['resource_name'], to_native(error)), exception=traceback.format_exc())
316
317 def remove_portset_ports_rest(self, port, portset_uuid):
318 """
319 Removes all existing ports from portset
320 :return: None
321 """
322 api = 'protocols/san/portsets/%s/interfaces' % portset_uuid
323 dummy, error = rest_generic.delete_async(self.rest_api, api, self.desired_lifs[port]['uuid'])
324 if error:
325 self.module.fail_json(msg=error)
326
327 def add_portset_ports(self, port):
328 """
329 Add the list of ports to portset
330 :return: None
331 """
332 options = {'portset-name': self.parameters['resource_name'],
333 'portset-port-name': port.strip()}
334
335 portset_modify = netapp_utils.zapi.NaElement.create_node_with_children('portset-add', **options)
336
337 try:
338 self.server.invoke_successfully(portset_modify, enable_tunneling=True)
339 except netapp_utils.zapi.NaApiError as error:
340 self.module.fail_json(msg='Error adding port in portset %s: %s' %
341 (self.parameters['resource_name'], to_native(error)), exception=traceback.format_exc())
342
343 def add_portset_ports_rest(self, portset_uuid, ports_to_add):
344 """
345 Add the list of ports to portset
346 :return: None
347 """
348 api = 'protocols/san/portsets/%s/interfaces' % portset_uuid
349 body = {'records': []}
350 for port in ports_to_add:
351 body['records'].append({self.desired_lifs[port]['lif_type']: {'name': port}})
352 dummy, error = rest_generic.post_async(self.rest_api, api, body)
353 if error:
354 self.module.fail_json(msg=error)
355
356 def portset_get_iter(self):
357 """
358 Compose NaElement object to query current portset using vserver, portset-name and portset-type parameters
359 :return: NaElement object for portset-get-iter with query
360 """
361 portset_get = netapp_utils.zapi.NaElement('portset-get-iter')
362 query = netapp_utils.zapi.NaElement('query')
363 portset_info = netapp_utils.zapi.NaElement('portset-info')
364 portset_info.add_new_child('vserver', self.parameters['vserver'])
365 portset_info.add_new_child('portset-name', self.parameters['resource_name'])
366 if self.parameters.get('portset_type'):
367 portset_info.add_new_child('portset-type', self.parameters['portset_type'])
368 query.add_child_elem(portset_info)
369 portset_get.add_child_elem(query)
370 return portset_get
371
372 def portset_get(self):
373 """
374 Get current portset info
375 :return: List of current ports if query successful, else return []
376 """
377 portset_get_iter = self.portset_get_iter()
378 result, ports = None, []
379 try:
380 result = self.server.invoke_successfully(portset_get_iter, enable_tunneling=True)
381 except netapp_utils.zapi.NaApiError as error:
382 self.module.fail_json(msg='Error fetching portset %s: %s'
383 % (self.parameters['resource_name'], to_native(error)),
384 exception=traceback.format_exc())
385 # return portset details
386 if result.get_child_by_name('num-records') and int(result.get_child_content('num-records')) > 0:
387 portset_get_info = result.get_child_by_name('attributes-list').get_child_by_name('portset-info')
388 if int(portset_get_info.get_child_content('portset-port-total')) > 0:
389 port_info = portset_get_info.get_child_by_name('portset-port-info')
390 ports = [port.get_content() for port in port_info.get_children()]
391 return ports
392
393 def portset_get_rest(self):
394 """
395 Get current portset info
396 :return: List of current ports if query successful, else return {}
397 """
398 api = 'protocols/san/portsets'
399 query = {
400 'svm.name': self.parameters['vserver'],
401 'name': self.parameters['resource_name']
402 }
403 if self.parameters.get('portset_type'):
404 query['protocol'] = self.parameters['portset_type']
405 fields = 'interfaces'
406 record, error = rest_generic.get_one_record(self.rest_api, api, query, fields)
407 if error:
408 self.module.fail_json(msg=error)
409 current = {}
410 if record:
411 current['uuid'] = record['uuid']
412 if 'interfaces' in record:
413 # This will form ports list for fcp, iscsi and mixed protocols.
414 ports = [lif.get('ip', lif.get('fc'))['name'] for lif in record['interfaces']]
415 current['ports'] = ports
416 if not current and self.parameters['state'] == 'present':
417 error_msg = "Error: Portset '%s' does not exist" % self.parameters['resource_name']
418 self.module.fail_json(msg=error_msg)
419 return current
420
421 def modify_broadcast_domain_ports(self):
422 """
423 compare current and desire ports. Call add or remove ports methods if needed.
424 :return: None.
425 """
426 current_ports = self.get_broadcast_domain_ports()
427 cd_ports = self.parameters['names']
428 if self.parameters['state'] == 'present':
429 ports_to_add = [port for port in cd_ports if port not in current_ports]
430 if len(ports_to_add) > 0:
431 if not self.module.check_mode:
432 if self.use_rest:
433 self.add_broadcast_domain_ports_rest(self.ports_to_add_from_desired(ports_to_add))
434 else:
435 self.add_broadcast_domain_ports(ports_to_add)
436 self.na_helper.changed = True
437
438 if self.parameters['state'] == 'absent':
439 ports_to_remove = [port for port in cd_ports if port in current_ports]
440 if len(ports_to_remove) > 0:
441 if not self.module.check_mode:
442 if self.use_rest:
443 self.remove_broadcast_domain_ports_rest(ports_to_remove, self.parameters['ipspace'])
444 else:
445 self.remove_broadcast_domain_ports(ports_to_remove)
446 self.na_helper.changed = True
447
448 def modify_portset_ports(self):
449 uuid = None
450 if self.use_rest:
451 current = self.portset_get_rest()
452 if 'uuid' in current:
453 uuid = current['uuid']
454 current_ports = current['ports'] if 'ports' in current else []
455 else:
456 current_ports = self.portset_get()
457 cd_ports = self.parameters['names']
458 if self.parameters['state'] == 'present':
459 ports_to_add = [port for port in cd_ports if port not in current_ports]
460 if len(ports_to_add) > 0:
461 if not self.module.check_mode:
462 if self.use_rest:
463 self.add_portset_ports_rest(uuid, ports_to_add)
464 else:
465 for port in ports_to_add:
466 self.add_portset_ports(port)
467 self.na_helper.changed = True
468
469 if self.parameters['state'] == 'absent':
470 ports_to_remove = [port for port in cd_ports if port in current_ports]
471 if len(ports_to_remove) > 0:
472 if not self.module.check_mode:
473 for port in ports_to_remove:
474 self.remove_portset_ports(port, uuid)
475 self.na_helper.changed = True
476
477 def get_ports_rest(self, ports):
478 # list of desired ports not present in the node.
479 missing_ports = []
480 # list of uuid information of each desired port should present in broadcast domain.
481 desired_ports = []
482 for port in ports:
483 current = self.get_net_port_rest(port)
484 if current is None:
485 missing_ports.append(port)
486 else:
487 desired_ports.append(current)
488 # Error if any of provided ports are not found.
489 if missing_ports and self.parameters['state'] == 'present':
490 self.module.fail_json(msg='Error: ports: %s not found' % ', '.join(missing_ports))
491 return desired_ports
492
493 def get_net_port_rest(self, port):
494 if ':' not in port:
495 error_msg = "Error: Invalid value specified for port: %s, provide port name as node_name:port_name" % port
496 self.module.fail_json(msg=error_msg)
497 node_name, port_name = port.split(':')
498 api = 'network/ethernet/ports'
499 query = {
500 'name': port_name,
501 'node.name': node_name,
502 }
503 fields = 'name,uuid'
504 record, error = rest_generic.get_one_record(self.rest_api, api, query, fields)
505 if error:
506 self.module.fail_json(msg=error)
507 if record:
508 current = {'uuid': record['uuid'], 'name': '%s:%s' % (record['node']['name'], record['name'])}
509 return current
510 return None
511
512 def ports_to_add_from_desired(self, ports):
513 ports_to_add = []
514 for port in ports:
515 for port_to_add in self.desired_ports:
516 if port == port_to_add['name']:
517 ports_to_add.append({'uuid': port_to_add['uuid']})
518 return ports_to_add
519
520 def get_san_lifs_rest(self, san_lifs):
521 # list of lifs not present in the vserver
522 missing_lifs = []
523 # dict with each key is lif name, value contains lif type - fc or ip and uuid.
524 desired_lifs = {}
525 record, record2, error, error2 = None, None, None, None
526 for lif in san_lifs:
527 if self.parameters.get('portset_type') in [None, 'mixed', 'iscsi']:
528 record, error = self.get_san_lif_type(lif, 'ip')
529 if self.parameters.get('portset_type') in [None, 'mixed', 'fcp']:
530 record2, error2 = self.get_san_lif_type(lif, 'fc')
531 if error is None and error2 is not None and record:
532 # ignore error on fc if ip interface is found
533 error2 = None
534 if error2 is None and error is not None and record2:
535 # ignore error on ip if fc interface is found
536 error = None
537 if error or error2:
538 errors = [to_native(err) for err in (error, error2) if err]
539 self.module.fail_json(msg='Error fetching lifs details for %s: %s' % (lif, ' - '.join(errors)),
540 exception=traceback.format_exc())
541 if record:
542 desired_lifs[lif] = {'lif_type': 'ip', 'uuid': record['uuid']}
543 if record2:
544 desired_lifs[lif] = {'lif_type': 'fc', 'uuid': record2['uuid']}
545 if record is None and record2 is None:
546 missing_lifs.append(lif)
547 if missing_lifs and self.parameters['state'] == 'present':
548 error_msg = 'Error: lifs: %s of type %s not found in vserver %s' % \
549 (', '.join(missing_lifs), self.parameters.get('portset_type', 'fcp or iscsi'), self.parameters['vserver'])
550 self.module.fail_json(msg=error_msg)
551 return desired_lifs
552
553 def get_san_lif_type(self, lif, portset_type):
554 api = 'network/%s/interfaces' % portset_type
555 query = {'name': lif, 'svm.name': self.parameters['vserver']}
556 record, error = rest_generic.get_one_record(self.rest_api, api, query)
557 return record, error
558
559 def apply(self):
560 if self.parameters['resource_type'] == 'broadcast_domain':
561 self.modify_broadcast_domain_ports()
562 elif self.parameters['resource_type'] == 'portset':
563 self.modify_portset_ports()
564 self.module.exit_json(changed=self.na_helper.changed)
565
566
567 def main():
568 portset_obj = NetAppOntapPorts()
569 portset_obj.apply()
570
571
572 if __name__ == '__main__':
573 main()