Debian Codegraph @

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

raw
1 #!/usr/bin/python
2
3 # (c) 2018-2025, NetApp, Inc
4 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
5
6 from __future__ import absolute_import, division, print_function
7
8 __metaclass__ = type
9
10
11 DOCUMENTATION = '''
12 short_description: NetApp ONTAP Create/Delete portset
13 author: NetApp Ansible Team (@carchi8py) <[email protected]>
14 description:
15 - Create/Delete ONTAP portset, modify ports in a portset.
16 - Modify type(protocol) is not supported in ONTAP.
17 extends_documentation_fragment:
18 - netapp.ontap.netapp.na_ontap
19 module: na_ontap_portset
20 options:
21 state:
22 description:
23 - If you want to create a portset.
24 default: present
25 type: str
26 vserver:
27 required: true
28 description:
29 - Name of the SVM.
30 type: str
31 name:
32 required: true
33 description:
34 - Name of the port set to create.
35 type: str
36 type:
37 description:
38 - Required for create in ZAPI.
39 - Default value is mixed if not specified at the time of creation in REST.
40 - Protocols accepted for this portset.
41 choices: ['fcp', 'iscsi', 'mixed']
42 type: str
43 force:
44 description:
45 - If 'false' or not specified, the request will fail if there are any igroups bound to this portset.
46 - If 'true', forcibly destroy the portset, even if there are existing igroup bindings.
47 type: bool
48 default: False
49 ports:
50 description:
51 - Specify the ports associated with this portset. Should be comma separated.
52 - It represents the expected state of a list of ports at any time, and replaces the current value of ports.
53 - Adds a port if it is specified in expected state but not in current state.
54 - Deletes a port if it is in current state but not in expected state.
55 type: list
56 elements: str
57 version_added: 2.8.0
58
59 '''
60
61 EXAMPLES = """
62 - name: Create Portset
63 netapp.ontap.na_ontap_portset:
64 state: present
65 vserver: vserver_name
66 name: portset_name
67 ports: a1
68 type: "{{ protocol type }}"
69 hostname: "{{ netapp_hostname }}"
70 username: "{{ netapp_username }}"
71 password: "{{ netapp_password }}"
72
73 - name: Modify ports in portset
74 netapp.ontap.na_ontap_portset:
75 state: present
76 vserver: vserver_name
77 name: portset_name
78 ports: a1,a2
79 hostname: "{{ netapp_hostname }}"
80 username: "{{ netapp_username }}"
81 password: "{{ netapp_password }}"
82
83 - name: Delete Portset
84 netapp.ontap.na_ontap_portset:
85 state: absent
86 vserver: vserver_name
87 name: portset_name
88 force: true
89 type: "{{ protocol type }}"
90 hostname: "{{ netapp_hostname }}"
91 username: "{{ netapp_username }}"
92 password: "{{ netapp_password }}"
93 """
94
95 RETURN = """
96 """
97
98 import traceback
99
100 from ansible.module_utils.basic import AnsibleModule
101 from ansible.module_utils._text import to_native
102 import ansible_collections.netapp.ontap.plugins.module_utils.netapp as netapp_utils
103 from ansible_collections.netapp.ontap.plugins.module_utils.netapp_module import NetAppModule
104 from ansible_collections.netapp.ontap.plugins.module_utils.netapp import OntapRestAPI
105 from ansible_collections.netapp.ontap.plugins.module_utils import rest_generic
106
107
108 class NetAppONTAPPortset:
109 """
110 Methods to create or delete portset
111 """
112
113 def __init__(self):
114 self.argument_spec = netapp_utils.na_ontap_host_argument_spec()
115 self.argument_spec.update(dict(
116 state=dict(required=False, type='str', default='present'),
117 vserver=dict(required=True, type='str'),
118 name=dict(required=True, type='str'),
119 type=dict(required=False, type='str', choices=[
120 'fcp', 'iscsi', 'mixed']),
121 force=dict(required=False, type='bool', default=False),
122 ports=dict(required=False, type='list', elements='str')
123 ))
124
125 self.module = AnsibleModule(
126 argument_spec=self.argument_spec,
127 supports_check_mode=True
128 )
129
130 self.na_helper = NetAppModule()
131 self.parameters = self.na_helper.set_parameters(self.module.params)
132 if 'ports' in self.parameters:
133 self.parameters['ports'] = list(set([port.strip() for port in self.parameters['ports']]))
134 if '' in self.parameters['ports'] and self.parameters['state'] == 'present':
135 self.module.fail_json(msg="Error: invalid value specified for ports")
136
137 # Setup REST API.
138 self.rest_api = OntapRestAPI(self.module)
139 self.use_rest = self.rest_api.is_rest()
140 self.uuid, self.lifs_info = None, {}
141 if self.use_rest and not self.rest_api.meets_rest_minimum_version(self.use_rest, 9, 9, 1):
142 msg = 'REST requires ONTAP 9.9.1 or later for portset APIs.'
143 if self.parameters['use_rest'].lower() == 'always':
144 self.module.fail_json(msg='Error: %s' % msg)
145 if self.parameters['use_rest'].lower() == 'auto':
146 self.module.warn('Falling back to ZAPI: %s' % msg)
147 self.use_rest = False
148
149 if not self.use_rest:
150 if not netapp_utils.has_netapp_lib():
151 self.module.fail_json(msg=netapp_utils.netapp_lib_is_required())
152 self.server = netapp_utils.setup_na_ontap_zapi(module=self.module, vserver=self.parameters['vserver'])
153
154 def portset_get_iter(self):
155 """
156 Compose NaElement object to query current portset using vserver, portset-name and portset-type parameters
157 :return: NaElement object for portset-get-iter with query
158 """
159 portset_get = netapp_utils.zapi.NaElement('portset-get-iter')
160 query = netapp_utils.zapi.NaElement('query')
161 portset_info = netapp_utils.zapi.NaElement('portset-info')
162 portset_info.add_new_child('vserver', self.parameters['vserver'])
163 portset_info.add_new_child('portset-name', self.parameters['name'])
164 query.add_child_elem(portset_info)
165 portset_get.add_child_elem(query)
166 return portset_get
167
168 def portset_get(self):
169 """
170 Get current portset info
171 :return: Dictionary of current portset details if query successful, else return None
172 """
173 if self.use_rest:
174 return self.portset_get_rest()
175 portset_get_iter = self.portset_get_iter()
176 result, portset_info = None, dict()
177 try:
178 result = self.server.invoke_successfully(portset_get_iter, enable_tunneling=True)
179 except netapp_utils.zapi.NaApiError as error:
180 self.module.fail_json(msg='Error fetching portset %s: %s'
181 % (self.parameters['name'], to_native(error)),
182 exception=traceback.format_exc())
183 # return portset details
184 if result.get_child_by_name('num-records') and int(result.get_child_content('num-records')) > 0:
185 portset_get_info = result.get_child_by_name('attributes-list').get_child_by_name('portset-info')
186 portset_info['type'] = portset_get_info.get_child_content('portset-type')
187 if int(portset_get_info.get_child_content('portset-port-total')) > 0:
188 ports = portset_get_info.get_child_by_name('portset-port-info')
189 portset_info['ports'] = [port.get_content() for port in ports.get_children()]
190 else:
191 portset_info['ports'] = []
192 return portset_info
193 return None
194
195 def create_portset(self):
196 """
197 Create a portset
198 """
199 if self.use_rest:
200 return self.create_portset_rest()
201 if self.parameters.get('type') is None:
202 self.module.fail_json(msg='Error: Missing required parameter for create (type)')
203 portset_info = netapp_utils.zapi.NaElement("portset-create")
204 portset_info.add_new_child("portset-name", self.parameters['name'])
205 portset_info.add_new_child("portset-type", self.parameters['type'])
206 try:
207 self.server.invoke_successfully(
208 portset_info, enable_tunneling=True)
209 except netapp_utils.zapi.NaApiError as error:
210 self.module.fail_json(msg="Error creating portset %s: %s" %
211 (self.parameters['name'], to_native(error)),
212 exception=traceback.format_exc())
213
214 def delete_portset(self):
215 """
216 Delete a portset
217 """
218 if self.use_rest:
219 return self.delete_portset_rest()
220 portset_info = netapp_utils.zapi.NaElement("portset-destroy")
221 portset_info.add_new_child("portset-name", self.parameters['name'])
222 if self.parameters.get('force'):
223 portset_info.add_new_child("force", str(self.parameters['force']))
224 try:
225 self.server.invoke_successfully(
226 portset_info, enable_tunneling=True)
227 except netapp_utils.zapi.NaApiError as error:
228 self.module.fail_json(msg="Error deleting portset %s: %s" %
229 (self.parameters['name'], to_native(error)),
230 exception=traceback.format_exc())
231
232 def remove_ports(self, ports):
233 """
234 Removes all existing ports from portset
235 :return: None
236 """
237 for port in ports:
238 self.modify_port(port, 'portset-remove', 'removing')
239
240 def add_ports(self, ports=None):
241 """
242 Add the list of ports to portset
243 :return: None
244 """
245 if ports is None:
246 ports = self.parameters.get('ports')
247 # don't add if ports is None
248 if ports is None:
249 return
250 for port in ports:
251 self.modify_port(port, 'portset-add', 'adding')
252
253 def modify_port(self, port, zapi, action):
254 """
255 Add or remove an port to/from a portset
256 """
257 options = {'portset-name': self.parameters['name'],
258 'portset-port-name': port}
259
260 portset_modify = netapp_utils.zapi.NaElement.create_node_with_children(zapi, **options)
261
262 try:
263 self.server.invoke_successfully(portset_modify, enable_tunneling=True)
264 except netapp_utils.zapi.NaApiError as error:
265 self.module.fail_json(msg='Error %s port in portset %s: %s' % (action, self.parameters['name'],
266 to_native(error)),
267 exception=traceback.format_exc())
268
269 def portset_get_rest(self):
270 api = "protocols/san/portsets"
271 query = {'name': self.parameters['name'], 'svm.name': self.parameters['vserver']}
272 fields = 'uuid,protocol,interfaces'
273 record, error = rest_generic.get_one_record(self.rest_api, api, query, fields)
274 if error:
275 self.module.fail_json(msg='Error fetching portset %s: %s'
276 % (self.parameters['name'], to_native(error)))
277 portset_info = None
278 if record:
279 portset_info = self.form_portset_info(record)
280 return portset_info
281
282 def form_portset_info(self, record):
283 self.uuid = record['uuid']
284 # if type is not set, assign current type
285 # for avoiding incompatible network interface error in modify portset.
286 if self.parameters.get('type') is None:
287 self.parameters['type'] = record['protocol']
288 portset_info = {
289 'type': record['protocol'],
290 'ports': []
291 }
292 if 'interfaces' in record:
293 for lif in record['interfaces']:
294 for key, value in lif.items():
295 if key in ['fc', 'ip']:
296 # add current lifs type and uuid to self.lifs for modify and delete purpose.
297 self.lifs_info[value['name']] = {'lif_type': key, 'uuid': value['uuid']}
298 # This will form ports list for fcp, iscsi and mixed protocols.
299 portset_info['ports'].append(value['name'])
300 return portset_info
301
302 def create_portset_rest(self):
303 api = "protocols/san/portsets"
304 body = {'name': self.parameters['name'], 'svm.name': self.parameters['vserver']}
305 if 'type' in self.parameters:
306 body['protocol'] = self.parameters['type']
307 if self.lifs_info:
308 body['interfaces'] = [{self.lifs_info[lif]['lif_type']: {'name': lif}} for lif in self.lifs_info]
309 dummy, error = rest_generic.post_async(self.rest_api, api, body)
310 if error:
311 self.module.fail_json(msg="Error creating portset %s: %s" %
312 (self.parameters['name'], to_native(error)))
313
314 def delete_portset_rest(self):
315 api = "protocols/san/portsets"
316 # Default value is False if 'force' not in parameters.
317 query = {'allow_delete_while_bound': self.parameters.get('force', False)}
318 dummy, error = rest_generic.delete_async(self.rest_api, api, self.uuid, query)
319 if error:
320 self.module.fail_json(msg="Error deleting portset %s: %s" %
321 (self.parameters['name'], to_native(error)))
322
323 def modify_portset_rest(self, ports_to_add, ports_to_remove):
324 if ports_to_add:
325 self.add_ports_to_portset(ports_to_add)
326 for port in ports_to_remove:
327 self.remove_port_from_portset(port)
328
329 def add_ports_to_portset(self, ports_to_add):
330 api = 'protocols/san/portsets/%s/interfaces' % self.uuid
331 body = {'records': [{self.lifs_info[port]['lif_type']: {'name': port}} for port in ports_to_add]}
332 dummy, error = rest_generic.post_async(self.rest_api, api, body)
333 if error:
334 self.module.fail_json(msg='Error adding port in portset %s: %s' % (self.parameters['name'],
335 to_native(error)))
336
337 def remove_port_from_portset(self, port_to_remove):
338 api = 'protocols/san/portsets/%s/interfaces' % self.uuid
339 dummy, error = rest_generic.delete_async(self.rest_api, api, self.lifs_info[port_to_remove]['uuid'])
340 if error:
341 self.module.fail_json(msg='Error removing port in portset %s: %s' % (self.parameters['name'],
342 to_native(error)))
343
344 def get_san_lifs_rest(self, san_lifs):
345 # list of lifs not present in the vserver
346 missing_lifs = []
347 record, record2, error, error2 = None, None, None, None
348 for lif in san_lifs:
349 if self.parameters.get('type') in [None, 'mixed', 'iscsi']:
350 record, error = self.get_san_lif_type_uuid(lif, 'ip')
351 if self.parameters.get('type') in [None, 'mixed', 'fcp']:
352 record2, error2 = self.get_san_lif_type_uuid(lif, 'fc')
353 if error is None and error2 is not None and record:
354 # ignore error on fc if ip interface is found
355 error2 = None
356 if error2 is None and error is not None and record2:
357 # ignore error on ip if fc interface is found
358 error = None
359 if error or error2:
360 errors = [to_native(err) for err in (error, error2) if err]
361 self.module.fail_json(msg='Error fetching lifs details for %s: %s' % (lif, ' - '.join(errors)),
362 exception=traceback.format_exc())
363 if record:
364 self.lifs_info[lif] = {'lif_type': 'ip', 'uuid': record['uuid']}
365 if record2:
366 self.lifs_info[lif] = {'lif_type': 'fc', 'uuid': record2['uuid']}
367 if record is None and record2 is None:
368 missing_lifs.append(lif)
369 if missing_lifs and self.parameters['state'] == 'present':
370 error_msg = 'Error: lifs: %s of type %s not found in vserver %s' % \
371 (', '.join(missing_lifs), self.parameters.get('type', 'fcp or iscsi'), self.parameters['vserver'])
372 self.module.fail_json(msg=error_msg)
373
374 def get_san_lif_type_uuid(self, lif, portset_type):
375 api = 'network/%s/interfaces' % portset_type
376 query = {'name': lif, 'svm.name': self.parameters['vserver']}
377 record, error = rest_generic.get_one_record(self.rest_api, api, query)
378 return record, error
379
380 def apply(self):
381 """
382 Applies action from playbook
383 """
384 current, modify = self.portset_get(), None
385 # get lifs type and uuid which is not present in current.
386 if self.use_rest and self.parameters['state'] == 'present':
387 self.get_san_lifs_rest([port for port in self.parameters['ports'] if port not in self.lifs_info])
388 cd_action = self.na_helper.get_cd_action(current, self.parameters)
389 if cd_action is None and self.parameters['state'] == 'present':
390 if self.parameters.get('type') and self.parameters['type'] != current['type']:
391 self.module.fail_json(msg="modify protocol(type) not supported and %s already exists in vserver %s under different type" %
392 (self.parameters['name'], self.parameters['vserver']))
393 modify = self.na_helper.get_modified_attributes(current, self.parameters)
394 if self.na_helper.changed and not self.module.check_mode:
395 if cd_action == 'create':
396 self.create_portset()
397 # REST handles create and add ports in create api call itself.
398 if not self.use_rest:
399 self.add_ports()
400 elif cd_action == 'delete':
401 self.delete_portset()
402 elif modify:
403 add_ports = set(self.parameters['ports']) - set(current['ports'])
404 remove_ports = set(current['ports']) - set(self.parameters['ports'])
405 if self.use_rest:
406 self.modify_portset_rest(add_ports, remove_ports)
407 else:
408 self.add_ports(add_ports)
409 self.remove_ports(remove_ports)
410 result = netapp_utils.generate_result(self.na_helper.changed, cd_action, modify)
411 self.module.exit_json(**result)
412
413
414 def main():
415 """
416 Execute action from playbook
417 """
418 portset_obj = NetAppONTAPPortset()
419 portset_obj.apply()
420
421
422 if __name__ == '__main__':
423 main()