Debian Codegraph @

ansible_collections/netapp/ontap/plugins/modules/na_ontap_interface.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 '''
7 na_ontap_interface
8 '''
9
10 from __future__ import absolute_import, division, print_function
11
12 __metaclass__ = type
13
14 DOCUMENTATION = '''
15 module: na_ontap_interface
16 short_description: NetApp ONTAP LIF configuration
17 extends_documentation_fragment:
18 - netapp.ontap.netapp.na_ontap
19 version_added: 2.6.0
20 author: NetApp Ansible Team (@carchi8py) <[email protected]>
21 description:
22 - Creating / deleting and modifying the LIF.
23
24 options:
25 state:
26 description:
27 - Whether the specified interface should exist or not.
28 choices: ['present', 'absent']
29 default: 'present'
30 type: str
31
32 interface_name:
33 description:
34 - Specifies the logical interface (LIF) name.
35 required: true
36 type: str
37
38 home_node:
39 description:
40 - Specifies the LIF's home node.
41 - By default, the first node from the cluster is considered as home node.
42 type: str
43
44 current_node:
45 description:
46 - Specifies the LIF's current node.
47 - By default, this is home_node
48 type: str
49
50 home_port:
51 description:
52 - Specifies the LIF's home port.
53 - Requires ONTAP 9.8 or later with FC interfaces when using REST.
54 - With REST, at least one of home_port, home_node, or broadcast_domain is required to create IP interfaces.
55 - With REST, either home_port or current_port is required to create FC interfaces.
56 - With ZAPI, home_port is required to create IP and FC interfaces.
57 - home_port and broadcast_domain are mutually exclusive (REST and IP interfaces).
58 type: str
59
60 current_port:
61 description:
62 - Specifies the LIF's current port.
63 type: str
64
65 role:
66 description:
67 - Specifies the role of the LIF.
68 - When setting role as "intercluster" or "cluster", setting protocol is not supported.
69 - When creating a "cluster" role, the node name will appear as the prefix in the name of LIF.
70 - For example, if the specified name is clif and node name is node1, the LIF name appears in the ONTAP as node1_clif.
71 - Possible values are 'undef', 'cluster', 'data', 'node-mgmt', 'intercluster', 'cluster-mgmt'.
72 - Required when C(state=present) unless service_policy is present and ONTAP version is 9.8 or better.
73 - This option is deprecated in REST.
74 - With REST, the module tries to derive a service_policy and may error out.
75 type: str
76
77 address:
78 description:
79 - Specifies the LIF's IP address.
80 - ZAPI - Required when C(state=present) and is_ipv4_link_local if false and subnet_name is not set.
81 - REST - Required when C(state=present) and C(interface_type) is IP.
82 type: str
83
84 netmask:
85 description:
86 - Specifies the LIF's netmask.
87 - ZAPI - Required when C(state=present) and is_ipv4_link_local if false and subnet_name is not set.
88 - REST - Required when C(state=present) and C(interface_type) is IP.
89 type: str
90
91 is_ipv4_link_local:
92 description:
93 - Specifies the LIF's are to acquire a ipv4 link local address.
94 - Use case for this is when creating Cluster LIFs to allow for auto assignment of ipv4 link local address.
95 - Not supported in REST
96 version_added: '20.1.0'
97 type: bool
98
99 vserver:
100 description:
101 - The name of the vserver to use.
102 - Required with ZAPI.
103 - Required with REST for FC interfaces (data vservers).
104 - Required with REST for SVM-scoped IP interfaces (data vservers).
105 - Invalid with REST for cluster-scoped IP interfaces.
106 - To help with transition from ZAPI to REST, vserver is ignored when the role is set to 'cluster', 'node-mgmt', 'intercluster', 'cluster-mgmt'.
107 - Remove this option to suppress the warning.
108 required: false
109 type: str
110
111 firewall_policy:
112 description:
113 - Specifies the firewall policy for the LIF.
114 - This option is deprecated in REST.
115 - With REST, the module tries to derive a service_policy and may error out.
116 type: str
117
118 failover_policy:
119 description:
120 - Specifies the failover policy for the LIF.
121 - When using REST, this values are mapped to 'home_port_only', 'default', 'home_node_only', 'sfo_partners_only', 'broadcast_domain_only'.
122 choices: ['disabled', 'system-defined', 'local-only', 'sfo-partner-only', 'broadcast-domain-wide']
123 type: str
124
125 failover_scope:
126 description:
127 - Specifies the failover scope for the LIF.
128 - REST only, and only for IP interfaces. Not supported for FC interfaces.
129 choices: ['home_port_only', 'default', 'home_node_only', 'sfo_partners_only', 'broadcast_domain_only']
130 type: str
131 version_added: '21.13.0'
132
133 failover_group:
134 description:
135 - Specifies the failover group for the LIF.
136 - Not supported with REST.
137 version_added: '20.1.0'
138 type: str
139
140 subnet_name:
141 description:
142 - Subnet where the IP interface address is allocated from.
143 - If the option is not used, the IP address and netmask need to be provided.
144 - With REST, ONTAP 9.11.1 or later is required.
145 - With REST, ipspace must be set.
146 version_added: 2.8.0
147 type: str
148
149 fail_if_subnet_conflicts:
150 description:
151 - Creating or updating an IP Interface fails if the specified IP address falls within the address range of a named subnet.
152 - Set this value to false to use the specified IP address and to assign the subnet owning that address to the interface.
153 - This option is only supported with REST and requires ONTAP 9.11.1 or later.
154 version_added: 22.2.0
155 type: bool
156
157 admin_status:
158 choices: ['up', 'down']
159 description:
160 - Specifies the administrative status of the LIF.
161 type: str
162
163 is_auto_revert:
164 description:
165 - If true, data LIF will revert to its home node under certain circumstances such as startup,
166 - and load balancing migration capability is disabled automatically
167 type: bool
168
169 force_subnet_association:
170 description:
171 - Set this to true to acquire the address from the named subnet and assign the subnet to the LIF.
172 - not supported with REST.
173 version_added: 2.9.0
174 type: bool
175
176 protocols:
177 description:
178 - Specifies the list of data protocols configured on the LIF. By default, the values in this element are nfs, cifs and fcache.
179 - Other supported protocols are iscsi and fcp. A LIF can be configured to not support any data protocols by specifying 'none'.
180 - Protocol values of none, iscsi, fc-nvme or fcp can't be combined with any other data protocol(s).
181 - address, netmask and firewall_policy parameters are not supported for 'fc-nvme' option.
182 - This option is ignored with REST, though it can be used to derive C(interface_type) or C(data_protocol).
183 type: list
184 elements: str
185
186 data_protocol:
187 description:
188 - The data protocol for which the FC interface is configured.
189 - Ignored with ZAPI or for IP interfaces.
190 - Required to create a FC type interface.
191 type: str
192 choices: ['fcp', 'fc_nvme']
193
194 dns_domain_name:
195 description:
196 - Specifies the unique, fully qualified domain name of the DNS zone of this LIF.
197 - Supported from ONTAP 9.9.0 or later in REST.
198 - Not supported for FC interfaces.
199 version_added: 2.9.0
200 type: str
201
202 listen_for_dns_query:
203 description:
204 - If True, this IP address will listen for DNS queries for the dnszone specified.
205 - Not supported with REST.
206 version_added: 2.9.0
207 type: bool
208
209 is_dns_update_enabled:
210 description:
211 - Specifies if DNS update is enabled for this LIF. Dynamic updates will be sent for this LIF if updates are enabled at Vserver level.
212 - Supported from ONTAP 9.9.1 or later in REST.
213 - Not supported for FC interfaces.
214 version_added: 2.9.0
215 type: bool
216
217 service_policy:
218 description:
219 - Starting with ONTAP 9.5, you can configure LIF service policies to identify a single service or a list of services that will use a LIF.
220 - In ONTAP 9.5, you can assign service policies only for LIFs in the admin SVM.
221 - In ONTAP 9.6, you can additionally assign service policies for LIFs in the data SVMs.
222 - When you specify a service policy for a LIF, you need not specify the data protocol and role for the LIF.
223 - NOTE that role is still required because of a ZAPI issue. This limitation is removed in ONTAP 9.8.
224 - Creating LIFs by specifying the role and data protocols is also supported.
225 version_added: '20.4.0'
226 type: str
227
228 from_name:
229 description: name of the interface to be renamed
230 type: str
231 version_added: 21.11.0
232
233 interface_type:
234 description:
235 - type of the interface.
236 - IP is assumed if address or netmask are present.
237 - IP interfaces includes cluster, intercluster, management, and NFS, CIFS, iSCSI interfaces.
238 - FC interfaces includes FCP and NVME-FC interfaces.
239 - ignored with ZAPI.
240 - required with REST, but maybe derived from deprecated options like C(role), C(protocols), and C(firewall_policy).
241 type: str
242 choices: ['fc', 'ip']
243 version_added: 21.13.0
244
245 ipspace:
246 description:
247 - IPspace name is required with REST for cluster-scoped interfaces. It is optional with SVM scope.
248 - ignored with ZAPI.
249 - ignored for FC interface.
250 type: str
251 version_added: 21.13.0
252
253 broadcast_domain:
254 description:
255 - broadcast_domain name can be used to specify the location on an IP interface with REST, as an alternative to node or port.
256 - only used when creating an IP interface to select a node, ignored if the interface already exists.
257 - if the broadcast domain is not found, make sure to check the ipspace value.
258 - home_port and broadcast_domain are mutually exclusive. home_node may or may not be present.
259 - not supported for FC interface.
260 - ignored with ZAPI.
261 type: str
262 version_added: 21.21.0
263
264 ignore_zapi_options:
265 description:
266 - ignore unsupported options that should not be relevant.
267 - ignored with ZAPI.
268 choices: ['failover_group', 'force_subnet_association', 'listen_for_dns_query']
269 type: list
270 elements: str
271 default: ['force_subnet_association']
272 version_added: 21.13.0
273
274 probe_port:
275 description:
276 - Probe port for Cloud load balancer - only valid in the Azure environment.
277 - Not supported with ZAPI or with FC interfaces.
278 - Requires ONTAP 9.10.1 or later.
279 type: int
280 version_added: 22.1.0
281
282 lambda_config:
283 description:
284 - Configuration parameters for AWS Lambda proxy functionality.
285 - These option and suboptions are only supported with REST.
286 type: dict
287 version_added: 23.3.0
288 suboptions:
289 function_name:
290 description:
291 - The name of the AWS Lambda function to invoke.
292 type: str
293 required: true
294 aws_region:
295 description:
296 - The name of the AWS region.
297 type: str
298 required: true
299 aws_profile:
300 description:
301 - The name of the AWS profile to use for authentication.
302 type: str
303 notes:
304 - REST support requires ONTAP 9.7 or later.
305 - Support check_mode.
306 - Supports AWS Lambda proxy functionality when using REST. See README for example usage.
307 '''
308
309 EXAMPLES = '''
310 - name: Create interface - ZAPI
311 netapp.ontap.na_ontap_interface:
312 state: present
313 interface_name: data2
314 home_port: e0d
315 home_node: laurentn-vsim1
316 role: data
317 protocols:
318 - nfs
319 - cifs
320 admin_status: up
321 failover_policy: local-only
322 firewall_policy: mgmt
323 is_auto_revert: true
324 address: 10.10.10.10
325 netmask: 255.255.255.0
326 force_subnet_association: false
327 dns_domain_name: test.com
328 listen_for_dns_query: true
329 is_dns_update_enabled: true
330 vserver: svm1
331 hostname: "{{ netapp_hostname }}"
332 username: "{{ netapp_username }}"
333 password: "{{ netapp_password }}"
334
335 - name: Create data interface - REST - NAS
336 netapp.ontap.na_ontap_interface:
337 state: present
338 interface_name: data2
339 home_port: e0d
340 home_node: laurentn-vsim1
341 admin_status: up
342 failover_scope: home_node_only
343 service_policy: default-data-files
344 is_auto_revert: true
345 interface_type: ip
346 address: 10.10.10.10
347 netmask: 255.255.255.0
348 vserver: svm1
349 hostname: "{{ netapp_hostname }}"
350 username: "{{ netapp_username }}"
351 password: "{{ netapp_password }}"
352
353 - name: Create cluster interface - ZAPI
354 netapp.ontap.na_ontap_interface:
355 state: present
356 interface_name: cluster_lif
357 home_port: e0a
358 home_node: cluster1-01
359 role: cluster
360 admin_status: up
361 is_auto_revert: true
362 is_ipv4_link_local: true
363 vserver: Cluster
364 hostname: "{{ netapp_hostname }}"
365 username: "{{ netapp_username }}"
366 password: "{{ netapp_password }}"
367
368 - name: Create cluster interface - REST
369 netapp.ontap.na_ontap_interface:
370 state: present
371 interface_name: cluster_lif
372 home_port: e0a
373 home_node: cluster1-01
374 service_policy: default-cluster
375 admin_status: up
376 is_auto_revert: true
377 vserver: Cluster
378 hostname: "{{ netapp_hostname }}"
379 username: "{{ netapp_username }}"
380 password: "{{ netapp_password }}"
381
382 - name: Rename interface
383 netapp.ontap.na_ontap_interface:
384 state: present
385 from_name: ansibleSVM_lif
386 interface_name: ansibleSVM_lif01
387 vserver: ansibleSVM
388 hostname: "{{ netapp_hostname }}"
389 username: "{{ netapp_username }}"
390 password: "{{ netapp_password }}"
391
392 - name: Migrate an interface
393 netapp.ontap.na_ontap_interface:
394 hostname: "{{ netapp_hostname }}"
395 username: "{{ netapp_username }}"
396 password: "{{ netapp_password }}"
397 vserver: ansible
398 https: true
399 validate_certs: false
400 state: present
401 interface_name: carchi_interface3
402 home_port: e0d
403 home_node: ansdev-stor-1
404 current_node: ansdev-stor-2
405 role: data
406 failover_policy: local-only
407 firewall_policy: mgmt
408 is_auto_revert: true
409 address: 10.10.10.12
410 netmask: 255.255.255.0
411 force_subnet_association: false
412 admin_status: up
413
414 - name: Delete interface
415 netapp.ontap.na_ontap_interface:
416 state: absent
417 interface_name: data2
418 vserver: svm1
419 hostname: "{{ netapp_hostname }}"
420 username: "{{ netapp_username }}"
421 password: "{{ netapp_password }}"
422 '''
423
424 RETURN = """
425
426 """
427
428 import time
429 import traceback
430 from ansible.module_utils.basic import AnsibleModule
431 from ansible.module_utils._text import to_native
432 from ansible_collections.netapp.ontap.plugins.module_utils.netapp_module import NetAppModule
433 import ansible_collections.netapp.ontap.plugins.module_utils.netapp as netapp_utils
434 from ansible_collections.netapp.ontap.plugins.module_utils.netapp import OntapRestAPI
435 from ansible_collections.netapp.ontap.plugins.module_utils import rest_generic, netapp_ipaddress
436
437 FAILOVER_POLICIES = ['disabled', 'system-defined', 'local-only', 'sfo-partner-only', 'broadcast-domain-wide']
438 FAILOVER_SCOPES = ['home_port_only', 'default', 'home_node_only', 'sfo_partners_only', 'broadcast_domain_only']
439 REST_UNSUPPORTED_OPTIONS = ['is_ipv4_link_local']
440 REST_IGNORABLE_OPTIONS = ['failover_group', 'force_subnet_association', 'listen_for_dns_query']
441
442
443 class NetAppOntapInterface:
444 ''' object to describe interface info '''
445
446 def __init__(self):
447
448 self.argument_spec = netapp_utils.na_ontap_host_argument_spec()
449 self.argument_spec.update(dict(
450 state=dict(required=False, choices=[
451 'present', 'absent'], default='present'),
452 interface_name=dict(required=True, type='str'),
453 interface_type=dict(type='str', choices=['fc', 'ip']),
454 ipspace=dict(type='str'),
455 broadcast_domain=dict(type='str'),
456 home_node=dict(required=False, type='str', default=None),
457 current_node=dict(required=False, type='str'),
458 home_port=dict(required=False, type='str'),
459 current_port=dict(required=False, type='str'),
460 role=dict(required=False, type='str'),
461 is_ipv4_link_local=dict(required=False, type='bool', default=None),
462 address=dict(required=False, type='str'),
463 netmask=dict(required=False, type='str'),
464 vserver=dict(required=False, type='str'),
465 firewall_policy=dict(required=False, type='str', default=None),
466 failover_policy=dict(required=False, type='str', default=None,
467 choices=['disabled', 'system-defined',
468 'local-only', 'sfo-partner-only', 'broadcast-domain-wide']),
469 failover_scope=dict(required=False, type='str', default=None,
470 choices=['home_port_only', 'default',
471 'home_node_only', 'sfo_partners_only', 'broadcast_domain_only']),
472 failover_group=dict(required=False, type='str'),
473 admin_status=dict(required=False, choices=['up', 'down']),
474 subnet_name=dict(required=False, type='str'),
475 is_auto_revert=dict(required=False, type='bool', default=None),
476 protocols=dict(required=False, type='list', elements='str'),
477 data_protocol=dict(required=False, type='str', choices=['fc_nvme', 'fcp']),
478 force_subnet_association=dict(required=False, type='bool', default=None),
479 dns_domain_name=dict(required=False, type='str'),
480 listen_for_dns_query=dict(required=False, type='bool'),
481 is_dns_update_enabled=dict(required=False, type='bool'),
482 service_policy=dict(required=False, type='str', default=None),
483 from_name=dict(required=False, type='str'),
484 ignore_zapi_options=dict(required=False, type='list', elements='str', default=['force_subnet_association'], choices=REST_IGNORABLE_OPTIONS),
485 probe_port=dict(required=False, type='int'),
486 fail_if_subnet_conflicts=dict(required=False, type='bool'),
487 ))
488 self.argument_spec.update(netapp_utils.na_ontap_lambda_argument_spec())
489
490 self.module = AnsibleModule(
491 argument_spec=self.argument_spec,
492 mutually_exclusive=[
493 ['subnet_name', 'address'],
494 ['subnet_name', 'netmask'],
495 ['is_ipv4_link_local', 'address'],
496 ['is_ipv4_link_local', 'netmask'],
497 ['is_ipv4_link_local', 'subnet_name'],
498 ['failover_policy', 'failover_scope'],
499 ],
500 required_if=[
501 ['use_lambda', True, ('lambda_config',)]
502 ],
503 supports_check_mode=True
504 )
505 self.na_helper = NetAppModule()
506 self.parameters = self.na_helper.set_parameters(self.module.params)
507 self.rest_api = OntapRestAPI(self.module)
508 unsupported_rest_properties = [key for key in REST_IGNORABLE_OPTIONS if key not in self.parameters['ignore_zapi_options']]
509 unsupported_rest_properties.extend(REST_UNSUPPORTED_OPTIONS)
510 if self.na_helper.safe_get(self.parameters, ['address']):
511 self.parameters['address'] = netapp_ipaddress.validate_and_compress_ip_address(self.parameters['address'], self.module)
512 partially_supported_rest_properties = [['dns_domain_name', (9, 9, 0)], ['is_dns_update_enabled', (9, 9, 1)], ['probe_port', (9, 10, 1)],
513 ['subnet_name', (9, 11, 1)], ['fail_if_subnet_conflicts', (9, 11, 1)]]
514 self.use_rest = self.rest_api.is_rest_supported_properties(self.parameters, unsupported_rest_properties, partially_supported_rest_properties)
515 if self.use_rest and not self.rest_api.meets_rest_minimum_version(self.use_rest, 9, 7, 0):
516 msg = 'REST requires ONTAP 9.7 or later for interface APIs.'
517 self.use_rest = self.na_helper.fall_back_to_zapi(self.module, msg, self.parameters)
518
519 if self.use_rest:
520 self.cluster_nodes = None # cached value to limit number of API calls.
521 self.home_node = None # cached value to limit number of API calls.
522 self.map_failover_policy()
523 self.validate_rest_input_parameters()
524 # REST supports both netmask and cidr for ipv4 but cidr only for ipv6.
525 if self.parameters.get('netmask'):
526 self.parameters['netmask'] = str(netapp_ipaddress.netmask_to_netmask_length(self.parameters.get('address'),
527 self.parameters['netmask'], self.module))
528 elif netapp_utils.has_netapp_lib() is False:
529 self.module.fail_json(msg=netapp_utils.netapp_lib_is_required())
530 else:
531 if self.parameters.get('use_lambda'):
532 self.module.fail_json(msg="Error: AWS Lambda proxy for ONTAP APIs is only supported with REST.")
533 for option in ('probe_port', 'fail_if_subnet_conflicts'):
534 if self.parameters.get(option) is not None:
535 self.module.fail_json(msg='Error option %s requires REST.' % option)
536 if 'vserver' not in self.parameters:
537 self.module.fail_json(msg='missing required argument with ZAPI: vserver')
538 self.server = netapp_utils.setup_na_ontap_zapi(module=self.module)
539 # ZAPI supports only netmask.
540 if self.parameters.get('netmask'):
541 self.parameters['netmask'] = netapp_ipaddress.netmask_length_to_netmask(self.parameters.get('address'),
542 self.parameters['netmask'], self.module)
543
544 def map_failover_policy(self):
545 if self.use_rest and 'failover_policy' in self.parameters:
546 mapping = dict(zip(FAILOVER_POLICIES, FAILOVER_SCOPES))
547 self.parameters['failover_scope'] = mapping[self.parameters['failover_policy']]
548
549 def set_interface_type(self, interface_type):
550 if 'interface_type' in self.parameters:
551 if self.parameters['interface_type'] != interface_type:
552 self.module.fail_json(msg="Error: mismatch between configured interface_type: %s and derived interface_type: %s."
553 % (self.parameters['interface_type'], interface_type))
554 else:
555 self.parameters['interface_type'] = interface_type
556
557 def derive_fc_data_protocol(self):
558 protocols = self.parameters.get('protocols')
559 if not protocols:
560 return
561 if len(protocols) > 1:
562 self.module.fail_json(msg="A single protocol entry is expected for FC interface, got %s." % protocols)
563 mapping = {'fc-nvme': 'fc_nvme', 'fc_nvme': 'fc_nvme', 'fcp': 'fcp'}
564 if protocols[0] not in mapping:
565 self.module.fail_json(msg="Unexpected protocol value %s." % protocols[0])
566 data_protocol = mapping[protocols[0]]
567 if 'data_protocol' in self.parameters and self.parameters['data_protocol'] != data_protocol:
568 self.module.fail_json(msg="Error: mismatch between configured data_protocol: %s and data_protocols: %s"
569 % (self.parameters['data_protocol'], protocols))
570 self.parameters['data_protocol'] = data_protocol
571
572 def derive_interface_type(self):
573 protocols = self.parameters.get('protocols')
574 if protocols in (None, ["none"]):
575 if self.parameters.get('role') in ('cluster', 'intercluster') or any(x in self.parameters for x in ('address', 'netmask', 'subnet_name')):
576 self.set_interface_type('ip')
577 return
578 protocol_types = set()
579 unknown_protocols = []
580 for protocol in protocols:
581 if protocol.lower() in ['fc-nvme', 'fcp']:
582 protocol_types.add('fc')
583 elif protocol.lower() in ['nfs', 'cifs', 'iscsi']:
584 protocol_types.add('ip')
585 elif protocol.lower() != 'none':
586 # none is an allowed value with ZAPI
587 unknown_protocols.append(protocol)
588 errors = []
589 if unknown_protocols:
590 errors.append('unexpected value(s) for protocols: %s' % unknown_protocols)
591 if len(protocol_types) > 1:
592 errors.append('incompatible value(s) for protocols: %s' % protocols)
593 if errors:
594 self.module.fail_json(msg='Error: unable to determine interface type, please set interface_type: %s' % (' - '.join(errors)))
595 if protocol_types:
596 self.set_interface_type(protocol_types.pop())
597 return
598
599 def derive_block_file_type(self, protocols):
600 block_p, file_p, fcp = False, False, False
601 if protocols is None:
602 fcp = self.parameters.get('interface_type') == 'fc'
603 return fcp, file_p, fcp
604 block_values, file_values = [], []
605 for protocol in protocols:
606 if protocol.lower() in ['fc-nvme', 'fcp', 'iscsi']:
607 block_p = True
608 block_values.append(protocol)
609 if protocol.lower() in ['fc-nvme', 'fcp']:
610 fcp = True
611 elif protocol.lower() in ['nfs', 'cifs']:
612 file_p = True
613 file_values.append(protocol)
614 if block_p and file_p:
615 self.module.fail_json(msg="Cannot use any of %s with %s" % (block_values, file_values))
616 return block_p, file_p, fcp
617
618 def get_interface_record_rest(self, if_type, query, fields):
619 if 'ipspace' in self.parameters and if_type == 'ip':
620 query['ipspace.name'] = self.parameters['ipspace']
621 return rest_generic.get_one_record(self.rest_api, self.get_net_int_api(if_type), query, fields)
622
623 def get_interface_records_rest(self, if_type, query, fields):
624 if 'ipspace' in self.parameters:
625 if if_type == 'ip':
626 query['ipspace.name'] = self.parameters['ipspace']
627 else:
628 self.module.warn("ipspace is ignored for FC interfaces.")
629 records, error = rest_generic.get_0_or_more_records(self.rest_api, self.get_net_int_api(if_type), query, fields)
630 if error and 'are available in precluster.' in error:
631 # in precluster mode, network APIs are not available!
632 self.module.fail_json(msg="This module cannot use REST in precluster mode, ZAPI can be forced with use_rest: never. Error: %s"
633 % error)
634 return records, error
635
636 def get_net_int_api(self, if_type=None):
637 if if_type is None:
638 if_type = self.parameters.get('interface_type')
639 if if_type is None:
640 self.module.fail_json(msg='Error: missing option "interface_type (or could not be derived)')
641 return 'network/%s/interfaces' % if_type
642
643 def find_interface_record(self, records, home_node, name):
644 full_name = "%s_%s" % (home_node, name) if home_node is not None else name
645 full_name_records = [record for record in records if record['name'] == full_name]
646 if len(full_name_records) > 1:
647 self.module.fail_json(msg='Error: multiple records for: %s - %s' % (full_name, full_name_records))
648 return full_name_records[0] if full_name_records else None
649
650 def find_exact_match(self, records, name):
651 """ with vserver, we expect an exact match
652 but ONTAP transforms cluster interface names by prepending the home_port
653 """
654 if 'vserver' in self.parameters:
655 if len(records) > 1:
656 self.module.fail_json(msg='Error: unexpected records for name: %s, vserver: %s - %s'
657 % (name, self.parameters['vserver'], records))
658 return records[0] if records else None
659 # since our queries included a '*', we expect multiple records
660 # an exact match is <home_node>_<name> or <name>.
661 # is there an exact macth on name only?
662 record = self.find_interface_record(records, None, name)
663 # now matching with home_port as a prefix
664 if 'home_node' in self.parameters and self.parameters['home_node'] != 'localhost':
665 home_record = self.find_interface_record(records, self.parameters['home_node'], name)
666 if record and home_record:
667 self.module.warn('Found both %s, selecting %s' % ([record['name'] for record in (record, home_record)], home_record['name']))
668 else:
669 # look for all known nodes
670 home_node_records = []
671 for home_node in self.get_cluster_node_names_rest():
672 home_record = self.find_interface_record(records, home_node, name)
673 if home_record:
674 home_node_records.append(home_record)
675 if len(home_node_records) > 1:
676 self.module.fail_json(msg='Error: multiple matches for name: %s: %s. Set home_node parameter.'
677 % (name, [record['name'] for record in home_node_records]))
678 home_record = home_node_records[0] if home_node_records else None
679 if record and home_node_records:
680 self.module.fail_json(msg='Error: multiple matches for name: %s: %s. Set home_node parameter.'
681 % (name, [record['name'] for record in (record, home_record)]))
682 if home_record:
683 record = home_record
684 if record and name == self.parameters['interface_name'] and name != record['name']:
685 # fix name, otherwise we'll attempt a rename :(
686 self.parameters['interface_name'] = record['name']
687 self.module.warn('adjusting name from %s to %s' % (name, record['name']))
688 return record
689
690 def get_interface_rest(self, name):
691 """
692 Return details about the interface
693 :param:
694 name : Name of the interface
695
696 :return: Details about the interface. None if not found.
697 :rtype: dict
698 """
699 self.derive_interface_type()
700 if_type = self.parameters.get('interface_type')
701 if 'vserver' in self.parameters:
702 query_ip = {
703 'name': name,
704 'svm.name': self.parameters['vserver']
705 }
706 query_fc = query_ip
707 else:
708 query_ip = {
709 # ONTAP renames cluster interfaces, use a * to find them
710 'name': '*%s' % name,
711 'scope': 'cluster'
712 }
713 query_fc = None
714 fields = 'name,location,uuid,enabled,svm.name'
715 fields_fc = fields + ',data_protocol'
716 fields_ip = fields + ',ip,service_policy'
717 if self.parameters.get('dns_domain_name'):
718 fields_ip += ',dns_zone'
719 if self.parameters.get('probe_port') is not None:
720 fields_ip += ',probe_port'
721 if self.parameters.get('is_dns_update_enabled') is not None:
722 fields_ip += ',ddns_enabled'
723 if self.parameters.get('subnet_name') is not None:
724 fields_ip += ',subnet'
725 records, error, records2, error2 = None, None, None, None
726 if if_type in [None, 'ip']:
727 records, error = self.get_interface_records_rest('ip', query_ip, fields_ip)
728 if if_type in [None, 'fc'] and query_fc:
729 records2, error2 = self.get_interface_records_rest('fc', query_fc, fields_fc)
730 if records and records2:
731 msg = 'Error fetching interface %s - found duplicate entries, please indicate interface_type.' % name
732 msg += ' - ip interfaces: %s' % records
733 msg += ' - fc interfaces: %s' % records2
734 self.module.fail_json(msg=msg)
735 if error is None and error2 is not None and records:
736 # ignore error on fc if ip interface is found
737 error2 = None
738 if error2 is None and error is not None and records2:
739 # ignore error on ip if fc interface is found
740 error = None
741 if error or error2:
742 errors = [to_native(err) for err in (error, error2) if err]
743 self.module.fail_json(msg='Error fetching interface details for %s: %s' % (name, ' - '.join(errors)),
744 exception=traceback.format_exc())
745 if records:
746 self.set_interface_type('ip')
747 if records2:
748 self.set_interface_type('fc')
749 records = records2
750
751 record = self.find_exact_match(records, name) if records else None
752 return self.dict_from_record(record)
753
754 def dict_from_record(self, record):
755 if not record:
756 return None
757 # Note: broadcast_domain is CreateOnly
758 return_value = {
759 'interface_name': record['name'],
760 'interface_type': self.parameters['interface_type'],
761 'uuid': record['uuid'],
762 'admin_status': 'up' if record['enabled'] else 'down',
763 }
764 # home_node/home_port not present for FC on ONTAP 9.7.
765 if self.na_helper.safe_get(record, ['location', 'home_node', 'name']):
766 return_value['home_node'] = record['location']['home_node']['name']
767 if self.na_helper.safe_get(record, ['location', 'home_port', 'name']):
768 return_value['home_port'] = record['location']['home_port']['name']
769 if self.na_helper.safe_get(record, ['svm', 'name']):
770 return_value['vserver'] = record['svm']['name']
771 if 'data_protocol' in record:
772 return_value['data_protocol'] = record['data_protocol']
773 if 'auto_revert' in record['location']:
774 return_value['is_auto_revert'] = record['location']['auto_revert']
775 if 'failover' in record['location']:
776 return_value['failover_scope'] = record['location']['failover']
777 # if interface_attributes.get_child_by_name('failover-group'):
778 # return_value['failover_group'] = interface_attributes['failover-group']
779 if self.na_helper.safe_get(record, ['ip', 'address']):
780 return_value['address'] = netapp_ipaddress.validate_and_compress_ip_address(record['ip']['address'], self.module)
781 if self.na_helper.safe_get(record, ['ip', 'netmask']) is not None:
782 return_value['netmask'] = record['ip']['netmask']
783 if self.na_helper.safe_get(record, ['service_policy', 'name']):
784 return_value['service_policy'] = record['service_policy']['name']
785 if self.na_helper.safe_get(record, ['location', 'node', 'name']):
786 return_value['current_node'] = record['location']['node']['name']
787 if self.na_helper.safe_get(record, ['location', 'port', 'name']):
788 return_value['current_port'] = record['location']['port']['name']
789 if self.na_helper.safe_get(record, ['dns_zone']):
790 return_value['dns_domain_name'] = record['dns_zone']
791 if self.na_helper.safe_get(record, ['probe_port']) is not None:
792 return_value['probe_port'] = record['probe_port']
793 if 'ddns_enabled' in record:
794 return_value['is_dns_update_enabled'] = record['ddns_enabled']
795 if self.na_helper.safe_get(record, ['subnet', 'name']):
796 return_value['subnet_name'] = record['subnet']['name']
797 return return_value
798
799 def get_node_port(self, uuid):
800 record, error = self.get_interface_record_rest(self.parameters['interface_type'], {'uuid': uuid}, 'location')
801 if error or not record:
802 return None, None, error
803 node = self.na_helper.safe_get(record, ['location', 'node', 'name'])
804 port = self.na_helper.safe_get(record, ['location', 'port', 'name'])
805 return node, port, None
806
807 def get_interface(self, name=None):
808 """
809 Return details about the interface
810 :param:
811 name : Name of the interface
812
813 :return: Details about the interface. None if not found.
814 :rtype: dict
815 """
816 if name is None:
817 name = self.parameters['interface_name']
818 if self.use_rest:
819 return self.get_interface_rest(name)
820
821 interface_info = netapp_utils.zapi.NaElement('net-interface-get-iter')
822 interface_attributes = netapp_utils.zapi.NaElement('net-interface-info')
823 interface_attributes.add_new_child('interface-name', name)
824 interface_attributes.add_new_child('vserver', self.parameters['vserver'])
825 query = netapp_utils.zapi.NaElement('query')
826 query.add_child_elem(interface_attributes)
827 interface_info.add_child_elem(query)
828 try:
829 result = self.server.invoke_successfully(interface_info, True)
830 except netapp_utils.zapi.NaApiError as exc:
831 self.module.fail_json(msg='Error fetching interface details for %s: %s' %
832 (name, to_native(exc)),
833 exception=traceback.format_exc())
834 return_value = None
835 if result.get_child_by_name('num-records') and \
836 int(result.get_child_content('num-records')) >= 1:
837
838 interface_attributes = result.get_child_by_name('attributes-list'). \
839 get_child_by_name('net-interface-info')
840 return_value = {
841 'interface_name': name,
842 'admin_status': interface_attributes['administrative-status'],
843 'home_port': interface_attributes['home-port'],
844 'home_node': interface_attributes['home-node'],
845 'failover_policy': interface_attributes['failover-policy'].replace('_', '-'),
846 }
847 if interface_attributes.get_child_by_name('is-auto-revert'):
848 return_value['is_auto_revert'] = (interface_attributes['is-auto-revert'] == 'true')
849 if interface_attributes.get_child_by_name('failover-group'):
850 return_value['failover_group'] = interface_attributes['failover-group']
851 if interface_attributes.get_child_by_name('address'):
852 return_value['address'] = netapp_ipaddress.validate_and_compress_ip_address(interface_attributes['address'], self.module)
853 if interface_attributes.get_child_by_name('netmask'):
854 return_value['netmask'] = interface_attributes['netmask']
855 if interface_attributes.get_child_by_name('firewall-policy'):
856 return_value['firewall_policy'] = interface_attributes['firewall-policy']
857 if interface_attributes.get_child_by_name('dns-domain-name') not in ('none', None):
858 return_value['dns_domain_name'] = interface_attributes['dns-domain-name']
859 else:
860 return_value['dns_domain_name'] = None
861 if interface_attributes.get_child_by_name('listen-for-dns-query'):
862 return_value['listen_for_dns_query'] = self.na_helper.get_value_for_bool(True, interface_attributes[
863 'listen-for-dns-query'])
864 if interface_attributes.get_child_by_name('is-dns-update-enabled'):
865 return_value['is_dns_update_enabled'] = self.na_helper.get_value_for_bool(True, interface_attributes[
866 'is-dns-update-enabled'])
867 if interface_attributes.get_child_by_name('is-ipv4-link-local'):
868 return_value['is_ipv4_link_local'] = self.na_helper.get_value_for_bool(True, interface_attributes[
869 'is-ipv4-link-local'])
870 if interface_attributes.get_child_by_name('service-policy'):
871 return_value['service_policy'] = interface_attributes['service-policy']
872 if interface_attributes.get_child_by_name('current-node'):
873 return_value['current_node'] = interface_attributes['current-node']
874 if interface_attributes.get_child_by_name('current-port'):
875 return_value['current_port'] = interface_attributes['current-port']
876 return return_value
877
878 @staticmethod
879 def set_options(options, parameters):
880 """ set attributes for create or modify """
881 if parameters.get('role') is not None:
882 options['role'] = parameters['role']
883 if parameters.get('home_node') is not None:
884 options['home-node'] = parameters['home_node']
885 if parameters.get('home_port') is not None:
886 options['home-port'] = parameters['home_port']
887 if parameters.get('subnet_name') is not None:
888 options['subnet-name'] = parameters['subnet_name']
889 if parameters.get('address') is not None:
890 options['address'] = parameters['address']
891 if parameters.get('netmask') is not None:
892 options['netmask'] = parameters['netmask']
893 if parameters.get('failover_policy') is not None:
894 options['failover-policy'] = parameters['failover_policy']
895 if parameters.get('failover_group') is not None:
896 options['failover-group'] = parameters['failover_group']
897 if parameters.get('firewall_policy') is not None:
898 options['firewall-policy'] = parameters['firewall_policy']
899 if parameters.get('is_auto_revert') is not None:
900 options['is-auto-revert'] = 'true' if parameters['is_auto_revert'] else 'false'
901 if parameters.get('admin_status') is not None:
902 options['administrative-status'] = parameters['admin_status']
903 if parameters.get('force_subnet_association') is not None:
904 options['force-subnet-association'] = 'true' if parameters['force_subnet_association'] else 'false'
905 if parameters.get('dns_domain_name') is not None:
906 options['dns-domain-name'] = parameters['dns_domain_name']
907 if parameters.get('listen_for_dns_query') is not None:
908 options['listen-for-dns-query'] = 'true' if parameters['listen_for_dns_query'] else 'false'
909 if parameters.get('is_dns_update_enabled') is not None:
910 options['is-dns-update-enabled'] = 'true' if parameters['is_dns_update_enabled'] else 'false'
911 if parameters.get('is_ipv4_link_local') is not None:
912 options['is-ipv4-link-local'] = 'true' if parameters['is_ipv4_link_local'] else 'false'
913 if parameters.get('service_policy') is not None:
914 options['service-policy'] = parameters['service_policy']
915
916 def fix_errors(self, options, errors):
917 '''ignore role and firewall_policy if a service_policy can be safely derived'''
918 block_p, file_p, fcp = self.derive_block_file_type(self.parameters.get('protocols'))
919 if 'role' in errors:
920 fixed = False
921 if errors['role'] == 'data' and errors.get('firewall_policy', 'data') == 'data':
922 if fcp:
923 # service_policy is not supported for FC interfaces
924 fixed = True
925 elif file_p and self.parameters.get('service_policy', 'default-data-files') == 'default-data-files':
926 options['service_policy'] = 'default-data-files'
927 fixed = True
928 elif block_p and self.parameters.get('service_policy', 'default-data-blocks') == 'default-data-blocks':
929 options['service_policy'] = 'default-data-blocks'
930 fixed = True
931 if errors['role'] == 'data' and errors.get('firewall_policy') == 'mgmt':
932 options['service_policy'] = 'default-management'
933 fixed = True
934 if errors['role'] == 'intercluster' and errors.get('firewall_policy') in [None, 'intercluster']:
935 options['service_policy'] = 'default-intercluster'
936 fixed = True
937 if errors['role'] == 'cluster' and errors.get('firewall_policy') in [None, 'mgmt']:
938 options['service_policy'] = 'default-cluster'
939 fixed = True
940 if errors['role'] == 'data' and fcp and errors.get('firewall_policy') is None:
941 # ignore role for FC interface
942 fixed = True
943 if fixed:
944 errors.pop('role')
945 errors.pop('firewall_policy', None)
946
947 def set_options_rest(self, parameters):
948 """ set attributes for create or modify """
949 def add_ip(options, key, value):
950 if 'ip' not in options:
951 options['ip'] = {}
952 options['ip'][key] = value
953
954 def add_location(options, key, value, node=None):
955 if 'location' not in options:
956 options['location'] = {}
957 # Note: broadcast_domain is CreateOnly
958 if key in ['home_node', 'home_port', 'node', 'port', 'broadcast_domain']:
959 options['location'][key] = {'name': value}
960 else:
961 options['location'][key] = value
962 if key in ['home_port', 'port']:
963 options['location'][key]['node'] = {'name': node}
964
965 def get_node_for_port(parameters, pkey):
966 if pkey == 'current_port':
967 return parameters.get('current_node') or self.parameters.get('home_node') or self.get_home_node_for_cluster()
968 elif pkey == 'home_port':
969 return self.parameters.get('home_node') or self.get_home_node_for_cluster()
970 else:
971 return None
972
973 options, migrate_options, errors = {}, {}, {}
974
975 # We normally create using home_port, and migrate to current.
976 # But for FC, home_port is not supported on 9.7 or earlier!
977 create_with_current = False
978 if parameters is None:
979 parameters = self.parameters
980 if self.parameters['interface_type'] == 'fc' and 'home_port' not in self.parameters:
981 create_with_current = True
982
983 mapping_params_to_rest = {
984 'admin_status': 'enabled',
985 'interface_name': 'name',
986 'vserver': 'svm.name',
987 # LOCATION
988 'current_port': 'port',
989 'home_port': 'home_port'
990 }
991 if self.parameters['interface_type'] == 'ip':
992 mapping_params_to_rest.update({
993 'ipspace': 'ipspace.name',
994 'service_policy': 'service_policy',
995 'dns_domain_name': 'dns_zone',
996 'is_dns_update_enabled': 'ddns_enabled',
997 'probe_port': 'probe_port',
998 'subnet_name': 'subnet.name',
999 'fail_if_subnet_conflicts': 'fail_if_subnet_conflicts',
1000 # IP
1001 'address': 'address',
1002 'netmask': 'netmask',
1003 # LOCATION
1004 'broadcast_domain': 'broadcast_domain',
1005 'failover_scope': 'failover',
1006 'is_auto_revert': 'auto_revert',
1007 # home_node/current_node supported only in ip interfaces.
1008 'home_node': 'home_node',
1009 'current_node': 'node'
1010 })
1011 if self.parameters['interface_type'] == 'fc':
1012 mapping_params_to_rest['data_protocol'] = 'data_protocol'
1013 ip_keys = ('address', 'netmask')
1014 location_keys = ('home_port', 'home_node', 'current_port', 'current_node', 'failover_scope', 'is_auto_revert', 'broadcast_domain')
1015
1016 # don't add node location when port structure is already present
1017 has_home_port, has_current_port = False, False
1018 if 'home_port' in parameters:
1019 has_home_port = True
1020 if 'current_port' in parameters:
1021 has_current_port = True
1022
1023 for pkey, rkey in mapping_params_to_rest.items():
1024 if pkey in parameters:
1025 if pkey == 'admin_status':
1026 options[rkey] = parameters[pkey] == 'up'
1027 elif pkey in ip_keys:
1028 add_ip(options, rkey, parameters[pkey])
1029 elif pkey in location_keys:
1030 if has_home_port and pkey == 'home_node':
1031 continue
1032 if has_current_port and pkey == 'current_node':
1033 continue
1034 dest = migrate_options if rkey in ('node', 'port') and not create_with_current else options
1035 add_location(dest, rkey, parameters[pkey], get_node_for_port(parameters, pkey))
1036 else:
1037 options[rkey] = parameters[pkey]
1038
1039 keys_in_error = ('role', 'failover_group', 'firewall_policy', 'force_subnet_association',
1040 'listen_for_dns_query', 'is_ipv4_link_local')
1041 for pkey in keys_in_error:
1042 if pkey in parameters:
1043 errors[pkey] = parameters[pkey]
1044
1045 return options, migrate_options, errors
1046
1047 def set_protocol_option(self, required_keys):
1048 """ set protocols for create """
1049 if self.parameters.get('protocols') is None:
1050 return None
1051 data_protocols_obj = netapp_utils.zapi.NaElement('data-protocols')
1052 for protocol in self.parameters.get('protocols'):
1053 if protocol.lower() in ['fc-nvme', 'fcp']:
1054 if 'address' in required_keys:
1055 required_keys.remove('address')
1056 if 'home_port' in required_keys:
1057 required_keys.remove('home_port')
1058 if 'netmask' in required_keys:
1059 required_keys.remove('netmask')
1060 not_required_params = set(['address', 'netmask', 'firewall_policy'])
1061 if not not_required_params.isdisjoint(set(self.parameters.keys())):
1062 self.module.fail_json(msg='Error: Following parameters for creating interface are not supported'
1063 ' for data-protocol fc-nvme: %s' % ', '.join(not_required_params))
1064 data_protocols_obj.add_new_child('data-protocol', protocol)
1065 return data_protocols_obj
1066
1067 def get_cluster_node_names_rest(self):
1068 ''' get cluster node names, but the cluster may not exist yet
1069 return:
1070 empty list if the cluster cannot be reached
1071 a list of nodes
1072 '''
1073 if self.cluster_nodes is None:
1074 records, error = rest_generic.get_0_or_more_records(self.rest_api, 'cluster/nodes', fields='name,uuid,cluster_interfaces')
1075 if error:
1076 self.module.fail_json(msg='Error fetching cluster node info: %s' % to_native(error),
1077 exception=traceback.format_exc())
1078 self.cluster_nodes = records or []
1079 return [record['name'] for record in self.cluster_nodes]
1080
1081 def get_home_node_for_cluster(self):
1082 ''' get the first node name from this cluster '''
1083 if self.use_rest:
1084 if not self.home_node:
1085 nodes = self.get_cluster_node_names_rest()
1086 if nodes:
1087 self.home_node = nodes[0]
1088 return self.home_node
1089
1090 get_node = netapp_utils.zapi.NaElement('cluster-node-get-iter')
1091 attributes = {
1092 'query': {
1093 'cluster-node-info': {}
1094 }
1095 }
1096 get_node.translate_struct(attributes)
1097 try:
1098 result = self.server.invoke_successfully(get_node, enable_tunneling=True)
1099 except netapp_utils.zapi.NaApiError as exc:
1100 if str(exc.code) == '13003' or exc.message == 'ZAPI is not enabled in pre-cluster mode.':
1101 return None
1102 self.module.fail_json(msg='Error fetching node for interface %s: %s' %
1103 (self.parameters['interface_name'], to_native(exc)),
1104 exception=traceback.format_exc())
1105 if result.get_child_by_name('num-records') and int(result.get_child_content('num-records')) >= 1:
1106 attributes = result.get_child_by_name('attributes-list')
1107 return attributes.get_child_by_name('cluster-node-info').get_child_content('node-name')
1108 return None
1109
1110 def validate_rest_input_parameters(self, action=None):
1111 if 'vserver' in self.parameters and self.parameters.get('role') in ['cluster', 'intercluster', 'node-mgmt', 'cluster-mgmt']:
1112 # REST only supports DATA SVMs
1113 del self.parameters['vserver']
1114 self.module.warn('Ignoring vserver with REST for non data SVM.')
1115 errors = []
1116 if action == 'create':
1117 if 'vserver' not in self.parameters and 'ipspace' not in self.parameters:
1118 errors.append('ipspace name must be provided if scope is cluster, or vserver for svm scope.')
1119 if self.parameters['interface_type'] == 'fc':
1120 unsupported_fc_options = ['broadcast_domain', 'dns_domain_name', 'is_dns_update_enabled', 'probe_port', 'subnet_name',
1121 'fail_if_subnet_conflicts']
1122 used_unsupported_fc_options = [option for option in unsupported_fc_options if option in self.parameters]
1123 if used_unsupported_fc_options:
1124 plural = 's' if len(used_unsupported_fc_options) > 1 else ''
1125 errors.append('%s option%s only supported for IP interfaces: %s, interface_type: %s'
1126 % (', '.join(used_unsupported_fc_options), plural, self.parameters.get('interface_name'), self.parameters['interface_type']))
1127 if self.parameters.get('home_port') and self.parameters.get('broadcast_domain'):
1128 errors.append('home_port and broadcast_domain are mutually exclusive for creating: %s'
1129 % self.parameters.get('interface_name'))
1130 if self.parameters.get('role') == "intercluster" and self.parameters.get('protocols') is not None:
1131 errors.append('Protocol cannot be specified for intercluster role, failed to create interface.')
1132 if errors:
1133 self.module.fail_json(msg='Error: %s' % ' '.join(errors))
1134
1135 ignored_keys = []
1136 for key in self.parameters.get('ignore_zapi_options', []):
1137 if key in self.parameters:
1138 del self.parameters[key]
1139 ignored_keys.append(key)
1140 if ignored_keys:
1141 self.module.warn("Ignoring %s" % ', '.join(ignored_keys))
1142 # if role is intercluster, protocol cannot be specified
1143
1144 def validate_required_parameters(self, keys):
1145 '''
1146 Validate if required parameters for create or modify are present.
1147 Parameter requirement might vary based on given data-protocol.
1148 :return: None
1149 '''
1150 home_node = self.parameters.get('home_node') or self.get_home_node_for_cluster()
1151 # validate if mandatory parameters are present for create or modify
1152 errors = []
1153 if self.use_rest and home_node is None and self.parameters.get('home_port') is not None:
1154 errors.append('Cannot guess home_node, home_node is required when home_port is present with REST.')
1155 if 'broadcast_domain_home_port_or_home_node' in keys:
1156 if all(x not in self.parameters for x in ['broadcast_domain', 'home_port', 'home_node']):
1157 errors.append("At least one of 'broadcast_domain', 'home_port', 'home_node' is required to create an IP interface.")
1158 keys.remove('broadcast_domain_home_port_or_home_node')
1159 if not keys.issubset(set(self.parameters.keys())):
1160 errors.append('Missing one or more required parameters for creating interface: %s.' % ', '.join(keys))
1161 if 'interface_type' in keys and 'interface_type' in self.parameters:
1162 if self.parameters['interface_type'] not in ['fc', 'ip']:
1163 errors.append('unexpected value for interface_type: %s.' % self.parameters['interface_type'])
1164 elif self.parameters['interface_type'] == 'fc':
1165 if not self.rest_api.meets_rest_minimum_version(self.use_rest, 9, 8, 0):
1166 if 'home_port' in self.parameters:
1167 errors.append("'home_port' is not supported for FC interfaces with 9.7, use 'current_port', avoid home_node.")
1168 if 'home_node' in self.parameters:
1169 self.module.warn("Avoid 'home_node' with FC interfaces with 9.7, use 'current_node'.")
1170 if 'vserver' not in self.parameters:
1171 errors.append("A data 'vserver' is required for FC interfaces.")
1172 if 'service_policy' in self.parameters:
1173 errors.append("'service_policy' is not supported for FC interfaces.")
1174 if 'role' in self.parameters and self.parameters.get('role') != 'data':
1175 errors.append("'role' is deprecated, and 'data' is the only value supported for FC interfaces: found %s." % self.parameters.get('role'))
1176 if 'probe_port' in self.parameters:
1177 errors.append("'probe_port' is not supported for FC interfaces.")
1178 if errors:
1179 self.module.fail_json(msg='Error: %s' % ' '.join(errors))
1180
1181 def validate_modify_parameters(self, body):
1182 """ Only the following keys can be modified:
1183 enabled, ip, location, name, service_policy
1184 """
1185 bad_keys = [key for key in body if key not in ['enabled', 'ip', 'location', 'name', 'service_policy', 'dns_zone', 'ddns_enabled', 'subnet.name',
1186 'fail_if_subnet_conflicts']]
1187 if bad_keys:
1188 plural = 's' if len(bad_keys) > 1 else ''
1189 self.module.fail_json(msg='The following option%s cannot be modified: %s' % (plural, ', '.join(bad_keys)))
1190
1191 def build_rest_body(self, modify=None):
1192 required_keys = set(['interface_type']) # python 2.6 syntax
1193 # running validation twice, as interface_type dictates the second set of requirements
1194 self.validate_required_parameters(required_keys)
1195 self.validate_rest_input_parameters(action='modify' if modify else 'create')
1196 if modify:
1197 # force the value of fail_if_subnet_conflicts as it is writeOnly
1198 if self.parameters.get('fail_if_subnet_conflicts') is not None:
1199 modify['fail_if_subnet_conflicts'] = self.parameters['fail_if_subnet_conflicts']
1200 else:
1201 required_keys = set()
1202 required_keys.add('interface_name')
1203 if self.parameters['interface_type'] == 'fc':
1204 self.derive_fc_data_protocol()
1205 required_keys.add('data_protocol')
1206 if 'home_port' not in self.parameters:
1207 # home_port is not supported with 9.7
1208 if self.rest_api.meets_rest_minimum_version(self.use_rest, 9, 8, 0):
1209 required_keys.add('home_port')
1210 else:
1211 required_keys.add('current_port')
1212 if self.parameters['interface_type'] == 'ip':
1213 if 'subnet_name' not in self.parameters:
1214 required_keys.add('address')
1215 required_keys.add('netmask')
1216 required_keys.add('broadcast_domain_home_port_or_home_node')
1217 self.validate_required_parameters(required_keys)
1218 body, migrate_body, errors = self.set_options_rest(modify)
1219 self.fix_errors(body, errors)
1220 if errors:
1221 self.module.fail_json(msg='Error %s interface, unsupported options: %s'
1222 % ('modifying' if modify else 'creating', str(errors)))
1223 if modify:
1224 self.validate_modify_parameters(body)
1225 return body, migrate_body
1226
1227 def create_interface_rest(self, body):
1228 ''' calling REST to create interface '''
1229 query = {'return_records': 'true'}
1230 records, error = rest_generic.post_async(self.rest_api, self.get_net_int_api(), body, query)
1231 if error:
1232 self.module.fail_json(msg='Error creating interface %s: %s' % (self.parameters['interface_name'], to_native(error)),
1233 exception=traceback.format_exc())
1234 return records
1235
1236 def create_interface(self, body):
1237 ''' calling zapi to create interface '''
1238 if self.use_rest:
1239 return self.create_interface_rest(body)
1240
1241 required_keys = set(['role', 'home_port'])
1242 if self.parameters.get('subnet_name') is None and self.parameters.get('is_ipv4_link_local') is None:
1243 required_keys.add('address')
1244 required_keys.add('netmask')
1245 if self.parameters.get('service_policy') is not None:
1246 required_keys.remove('role')
1247 data_protocols_obj = self.set_protocol_option(required_keys)
1248 self.validate_required_parameters(required_keys)
1249
1250 options = {'interface-name': self.parameters['interface_name'],
1251 'vserver': self.parameters['vserver']}
1252 NetAppOntapInterface.set_options(options, self.parameters)
1253 interface_create = netapp_utils.zapi.NaElement.create_node_with_children('net-interface-create', **options)
1254 if data_protocols_obj is not None:
1255 interface_create.add_child_elem(data_protocols_obj)
1256 try:
1257 self.server.invoke_successfully(interface_create, enable_tunneling=True)
1258 except netapp_utils.zapi.NaApiError as exc:
1259 # msg: "Error Creating interface ansible_interface: NetApp API failed. Reason - 17:A LIF with the same name already exists"
1260 if to_native(exc.code) == "17":
1261 self.na_helper.changed = False
1262 else:
1263 self.module.fail_json(msg='Error Creating interface %s: %s' %
1264 (self.parameters['interface_name'], to_native(exc)),
1265 exception=traceback.format_exc())
1266
1267 def delete_interface_rest(self, uuid):
1268 ''' calling zapi to delete interface '''
1269
1270 dummy, error = rest_generic.delete_async(self.rest_api, self.get_net_int_api(), uuid)
1271 if error:
1272 self.module.fail_json(msg='Error deleting interface %s: %s' % (self.parameters['interface_name'], to_native(error)),
1273 exception=traceback.format_exc())
1274
1275 def delete_interface(self, current_status, current_interface, uuid):
1276 ''' calling zapi to delete interface '''
1277 if current_status == 'up':
1278 self.parameters['admin_status'] = 'down'
1279 if self.use_rest:
1280 # only for fc interfaces disable is required before delete.
1281 if current_interface == 'fc':
1282 self.modify_interface_rest(uuid, {'enabled': False})
1283 else:
1284 self.modify_interface({'admin_status': 'down'})
1285
1286 if self.use_rest:
1287 return self.delete_interface_rest(uuid)
1288
1289 interface_delete = netapp_utils.zapi.NaElement.create_node_with_children(
1290 'net-interface-delete', **{'interface-name': self.parameters['interface_name'],
1291 'vserver': self.parameters['vserver']})
1292 try:
1293 self.server.invoke_successfully(interface_delete, enable_tunneling=True)
1294 except netapp_utils.zapi.NaApiError as exc:
1295 self.module.fail_json(msg='Error deleting interface %s: %s' %
1296 (self.parameters['interface_name'], to_native(exc)),
1297 exception=traceback.format_exc())
1298
1299 def modify_interface_rest(self, uuid, body):
1300 ''' calling REST to modify interface '''
1301 if not body:
1302 return
1303 dummy, error = rest_generic.patch_async(self.rest_api, self.get_net_int_api(), uuid, body)
1304 if error:
1305 self.module.fail_json(msg='Error modifying interface %s: %s' % (self.parameters['interface_name'], to_native(error)),
1306 exception=traceback.format_exc())
1307
1308 def migrate_interface_rest(self, uuid, body):
1309 # curiously, we sometimes need to send the request twice (well, always in my experience)
1310 errors = []
1311 desired_node = self.na_helper.safe_get(body, ['location', 'node', 'name'])
1312 desired_port = self.na_helper.safe_get(body, ['location', 'port', 'name'])
1313 for __ in range(12):
1314 self.modify_interface_rest(uuid, body)
1315 time.sleep(10)
1316 node, port, error = self.get_node_port(uuid)
1317 if error is None and desired_node in [None, node] and desired_port in [None, port]:
1318 return
1319 if errors or error is not None:
1320 errors.append(str(error))
1321 if errors:
1322 self.module.fail_json(msg='Errors waiting for migration to complete: %s' % ' - '.join(errors))
1323 else:
1324 self.module.warn('Failed to confirm interface is migrated after 120 seconds')
1325
1326 def modify_interface(self, modify, uuid=None, body=None):
1327 """
1328 Modify the interface.
1329 """
1330 if self.use_rest:
1331 return self.modify_interface_rest(uuid, body)
1332
1333 # Current_node and current_port don't exist in modify only migrate, so we need to remove them from the list
1334 migrate = {}
1335 modify_options = dict(modify)
1336 if modify_options.get('current_node') is not None:
1337 migrate['current_node'] = modify_options.pop('current_node')
1338 if modify_options.get('current_port') is not None:
1339 migrate['current_port'] = modify_options.pop('current_port')
1340 if modify_options:
1341 options = {'interface-name': self.parameters['interface_name'],
1342 'vserver': self.parameters['vserver']
1343 }
1344 NetAppOntapInterface.set_options(options, modify_options)
1345 interface_modify = netapp_utils.zapi.NaElement.create_node_with_children('net-interface-modify', **options)
1346 try:
1347 self.server.invoke_successfully(interface_modify, enable_tunneling=True)
1348 except netapp_utils.zapi.NaApiError as err:
1349 self.module.fail_json(msg='Error modifying interface %s: %s' %
1350 (self.parameters['interface_name'], to_native(err)),
1351 exception=traceback.format_exc())
1352 # if home node has been changed we need to migrate the interface
1353 if migrate:
1354 self.migrate_interface()
1355
1356 def migrate_interface(self):
1357 # ZAPI
1358 interface_migrate = netapp_utils.zapi.NaElement('net-interface-migrate')
1359 if self.parameters.get('current_node') is None:
1360 self.module.fail_json(msg='current_node must be set to migrate')
1361 interface_migrate.add_new_child('destination-node', self.parameters['current_node'])
1362 if self.parameters.get('current_port') is not None:
1363 interface_migrate.add_new_child('destination-port', self.parameters['current_port'])
1364 interface_migrate.add_new_child('lif', self.parameters['interface_name'])
1365 interface_migrate.add_new_child('vserver', self.parameters['vserver'])
1366 try:
1367 self.server.invoke_successfully(interface_migrate, enable_tunneling=True)
1368 except netapp_utils.zapi.NaApiError as error:
1369 self.module.fail_json(msg='Error migrating %s: %s'
1370 % (self.parameters['current_node'], to_native(error)),
1371 exception=traceback.format_exc())
1372 # like with REST, the migration may not be completed on the first try!
1373 # just blindly do it twice.
1374 try:
1375 self.server.invoke_successfully(interface_migrate, enable_tunneling=True)
1376 except netapp_utils.zapi.NaApiError as error:
1377 self.module.fail_json(msg='Error migrating %s: %s'
1378 % (self.parameters['current_node'], to_native(error)),
1379 exception=traceback.format_exc())
1380
1381 def rename_interface(self):
1382 options = {
1383 'interface-name': self.parameters['from_name'],
1384 'new-name': self.parameters['interface_name'],
1385 'vserver': self.parameters['vserver']
1386 }
1387 interface_rename = netapp_utils.zapi.NaElement.create_node_with_children('net-interface-rename', **options)
1388 try:
1389 self.server.invoke_successfully(interface_rename, enable_tunneling=True)
1390 except netapp_utils.zapi.NaApiError as error:
1391 self.module.fail_json(msg='Error renaming %s to %s: %s'
1392 % (self.parameters['from_name'], self.parameters['interface_name'], to_native(error)),
1393 exception=traceback.format_exc())
1394
1395 def get_action(self):
1396 modify, rename, new_name = None, None, None
1397 current = self.get_interface()
1398 cd_action = self.na_helper.get_cd_action(current, self.parameters)
1399 if cd_action == 'create' and self.parameters.get('from_name'):
1400 # create by renaming existing interface
1401 # self.parameters['interface_name'] may be overriden in self.get_interface so save a copy
1402 new_name = self.parameters['interface_name']
1403 old_interface = self.get_interface(self.parameters['from_name'])
1404 rename = self.na_helper.is_rename_action(old_interface, current)
1405 if rename is None:
1406 self.module.fail_json(msg='Error renaming interface %s: no interface with from_name %s.'
1407 % (self.parameters['interface_name'], self.parameters['from_name']))
1408 if rename:
1409 current = old_interface
1410 cd_action = None
1411 if cd_action is None:
1412 modify = self.na_helper.get_modified_attributes(current, self.parameters)
1413 if rename and self.use_rest:
1414 rename = False
1415 if 'interface_name' not in modify:
1416 modify['interface_name'] = new_name
1417 if modify and modify.get('home_node') == 'localhost':
1418 modify.pop('home_node')
1419 if not modify:
1420 self.na_helper.changed = False
1421
1422 return cd_action, modify, rename, current
1423
1424 def build_rest_payloads(self, cd_action, modify, current):
1425 body, migrate_body = None, None
1426 uuid = current.get('uuid') if current else None
1427 if self.use_rest:
1428 if cd_action == 'create':
1429 body, migrate_body = self.build_rest_body()
1430 elif modify:
1431 # fc interface supports only home_port and port in POST/PATCH.
1432 # add home_port and current_port in modify for home_node and current_node respectively to form home_port/port.
1433 if modify.get('home_node') and not modify.get('home_port') and self.parameters['interface_type'] == 'fc':
1434 modify['home_port'] = current['home_port']
1435 # above will modify home_node of fc interface, after modify if requires to update current_node, it will error out for fc interface.
1436 # migrate not supported for fc interface.
1437 if modify.get('current_node') and not modify.get('current_port') and self.parameters['interface_type'] == 'fc':
1438 modify['current_port'] = current['current_port']
1439 body, migrate_body = self.build_rest_body(modify)
1440 if (modify or cd_action == 'delete') and uuid is None:
1441 self.module.fail_json(msg='Error, expecting uuid in existing record')
1442 desired_home_port = self.na_helper.safe_get(body, ['location', 'home_port'])
1443 desired_current_port = self.na_helper.safe_get(migrate_body, ['location', 'port'])
1444 # if try to modify both home_port and current_port in FC interface and if its equal, make migrate_body None
1445 if self.parameters.get('interface_type') == 'fc' and desired_home_port and desired_current_port and desired_home_port == desired_current_port:
1446 migrate_body = None
1447 return uuid, body, migrate_body
1448
1449 def apply(self):
1450 ''' calling all interface features '''
1451 cd_action, modify, rename, current = self.get_action()
1452 # build the payloads even in check_mode, to perform validations
1453 uuid, body, migrate_body = self.build_rest_payloads(cd_action, modify, current)
1454 if self.na_helper.changed and not self.module.check_mode:
1455 if rename and not self.use_rest:
1456 self.rename_interface()
1457 modify.pop('interface_name')
1458 if cd_action == 'create':
1459 records = self.create_interface(body)
1460 if records:
1461 # needed for migrate after creation
1462 uuid = records['records'][0]['uuid']
1463 elif cd_action == 'delete':
1464 # interface type returned in REST but not in ZAPI.
1465 interface_type = current['interface_type'] if self.use_rest else None
1466 self.delete_interface(current['admin_status'], interface_type, uuid)
1467 elif modify:
1468 self.modify_interface(modify, uuid, body)
1469 if migrate_body:
1470 # for 9.7 or earlier, allow modify current node/port for fc interface.
1471 if self.parameters.get('interface_type') == 'fc' and self.use_rest and self.rest_api.meets_rest_minimum_version(self.use_rest, 9, 8, 0):
1472 self.module.fail_json(msg="Error: cannot migrate FC interface")
1473 self.migrate_interface_rest(uuid, migrate_body)
1474
1475 result = netapp_utils.generate_result(self.na_helper.changed, cd_action, modify)
1476 self.module.exit_json(**result)
1477
1478
1479 def main():
1480 interface = NetAppOntapInterface()
1481 interface.apply()
1482
1483
1484 if __name__ == '__main__':
1485 main()