Debian Codegraph @

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

raw
1 #!/usr/bin/python
2
3 # (c) 2022-2025, NetApp, Inc. GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
4
5 from __future__ import absolute_import, division, print_function
6 __metaclass__ = type
7
8 DOCUMENTATION = """
9 module: na_ontap_security_ipsec_policy
10 short_description: NetApp ONTAP module to create, modify or delete security IPsec policy.
11 extends_documentation_fragment:
12 - netapp.ontap.netapp.na_ontap_rest
13 version_added: '22.1.0'
14 author: NetApp Ansible Team (@carchi8py) <[email protected]>
15 description:
16 - Create, modify or delete security IPsec policy.
17 options:
18 state:
19 description:
20 - Create or delete security IPsec policy.
21 choices: ['present', 'absent']
22 type: str
23 default: present
24 name:
25 description:
26 - Name of the security IPsec policy
27 type: str
28 required: true
29 action:
30 description:
31 - Action for the IPsec policy.
32 - Cannot modify after create.
33 type: str
34 choices: ['bypass', 'discard', 'esp_transport', 'esp_udp']
35 authentication_method:
36 description:
37 - Authentication method for the IPsec policy.
38 - Supported from 9.10.1 or later.
39 - Cannot modify after create.
40 type: str
41 choices: ['none', 'psk', 'pki']
42 certificate:
43 description:
44 - Certificate for the IPsec policy.
45 - Supported from 9.10.1 or later.
46 - Required when C(authentication_method) is 'pki' in create.
47 type: str
48 enabled:
49 description:
50 - Indicates whether or not the policy is enabled.
51 type: bool
52 ipspace:
53 description:
54 - IPspace name where C(svm) exist.
55 type: str
56 local_endpoint:
57 description:
58 - Local endpoint for the IPsec policy.
59 type: dict
60 suboptions:
61 address:
62 description:
63 - IPv4 or IPv6 address.
64 type: str
65 required: true
66 netmask:
67 description:
68 - Input as netmask length (16) or IPv4 mask (255.255.0.0).
69 - For IPv6, the default value is 64 with a valid range of 1 to 127.
70 type: str
71 required: true
72 port:
73 description:
74 - Application port to be covered by the IPsec policy, example 23.
75 type: str
76 remote_endpoint:
77 description:
78 - remote endpoint for the IPsec policy.
79 type: dict
80 suboptions:
81 address:
82 description:
83 - IPv4 or IPv6 address.
84 type: str
85 required: true
86 netmask:
87 description:
88 - Input as netmask length (16) or IPv4 mask (255.255.0.0).
89 - For IPv6, the default value is 64 with a valid range of 1 to 127.
90 type: str
91 required: true
92 port:
93 description:
94 - Application port to be covered by the IPsec policy, example 23 or 23-23.
95 type: str
96 local_identity:
97 description:
98 - local IKE endpoint's identity for authentication purpose.
99 type: str
100 remote_identity:
101 description:
102 - remote IKE endpoint's identity for authentication purpose.
103 type: str
104 protocol:
105 description:
106 - protocol to be protected by by this policy.
107 - example 'any' or '0', 'tcp', 'udp' or protocol number.
108 type: str
109 secret_key:
110 description:
111 - Pre-shared key for IKE negotiation.
112 - Required when C(authentication_method) is 'psk' in create.
113 - Cannot modify after create.
114 type: str
115 svm:
116 description:
117 - The name of the SVM.
118 - Required when creating security IPsec policy.
119 type: str
120
121 notes:
122 - Supports check_mode.
123 - Only supported with REST and requires ONTAP 9.8 or later.
124 """
125
126 EXAMPLES = """
127 - name: Create security IPsec policy with pre-shared Keys.
128 netapp.ontap.na_ontap_security_ipsec_policy:
129 name: ipsec_policy_psk
130 ipspace: Default
131 svm: ansibleSVM
132 authentication_method: psk
133 secret_key: "{{ secret_key }}"
134 action: esp_transport
135 local_endpoint:
136 address: 10.23.43.23
137 netmask: 24
138 port: 201
139 remote_endpoint:
140 address: 10.23.43.30
141 netmask: 24
142 port: 205
143 protocol: tcp
144 enabled: true
145 hostname: "{{ netapp_hostname }}"
146 username: "{{ netapp_username }}"
147 password: "{{ netapp_password }}"
148 https: true
149 validate_certs: "{{ validate_certs }}"
150
151 - name: Create security IPsec policy with certificates.
152 netapp.ontap.na_ontap_security_ipsec_policy:
153 name: ipsec_policy_pki
154 ipspace: Default
155 svm: ansibleSVM
156 authentication_method: pki
157 certificate: "{{ cert_name }}"
158 action: esp_transport
159 local_endpoint:
160 address: 10.23.43.23
161 netmask: 24
162 port: 201
163 remote_endpoint:
164 address: 10.23.43.30
165 netmask: 24
166 port: 205
167 protocol: tcp
168 enabled: true
169 hostname: "{{ netapp_hostname }}"
170 username: "{{ netapp_username }}"
171 password: "{{ netapp_password }}"
172 https: true
173 validate_certs: "{{ validate_certs }}"
174
175 - name: Create security IPsec policy without psk or certificates.
176 netapp.ontap.na_ontap_security_ipsec_policy:
177 name: ipsec_policy_none
178 ipspace: Default
179 svm: ansibleSVM
180 action: bypass
181 local_endpoint:
182 address: 10.23.43.23
183 netmask: 24
184 port: 201
185 remote_endpoint:
186 address: 10.23.43.30
187 netmask: 24
188 port: 205
189 protocol: tcp
190 hostname: "{{ netapp_hostname }}"
191 username: "{{ netapp_username }}"
192 password: "{{ netapp_password }}"
193 https: true
194 validate_certs: "{{ validate_certs }}"
195
196 - name: Modify security IPsec policy local, remote end_point.
197 netapp.ontap.na_ontap_security_ipsec_policy:
198 name: ipsec_policy_pki
199 ipspace: Default
200 svm: ansibleSVM
201 authentication_method: pki
202 certificate: "{{ cert_name }}"
203 action: esp_transport
204 local_endpoint:
205 address: 10.23.43.50
206 netmask: 24
207 port: 201
208 remote_endpoint:
209 address: 10.23.43.60
210 netmask: 24
211 port: 205
212 protocol: tcp
213 enabled: true
214 hostname: "{{ netapp_hostname }}"
215 username: "{{ netapp_username }}"
216 password: "{{ netapp_password }}"
217 https: true
218 validate_certs: "{{ validate_certs }}"
219
220 - name: Modify security IPsec protocol, enable options.
221 netapp.ontap.na_ontap_security_ipsec_policy:
222 name: ipsec_policy_pki
223 ipspace: Default
224 svm: ansibleSVM
225 authentication_method: pki
226 certificate: "{{ cert_name }}"
227 action: esp_transport
228 local_endpoint:
229 address: 10.23.43.50
230 netmask: 24
231 port: 201
232 remote_endpoint:
233 address: 10.23.43.60
234 netmask: 24
235 port: 205
236 protocol: udp
237 enabled: false
238 hostname: "{{ netapp_hostname }}"
239 username: "{{ netapp_username }}"
240 password: "{{ netapp_password }}"
241 https: true
242 validate_certs: "{{ validate_certs }}"
243
244 - name: Delete security IPsec policy.
245 netapp.ontap.na_ontap_security_ipsec_policy:
246 name: ipsec_policy_pki
247 svm: ansibleSVM
248 hostname: "{{ netapp_hostname }}"
249 username: "{{ netapp_username }}"
250 password: "{{ netapp_password }}"
251 https: true
252 validate_certs: "{{ validate_certs }}"
253 """
254
255 RETURN = """
256 """
257
258 import traceback
259 from ansible.module_utils.basic import AnsibleModule
260 from ansible.module_utils._text import to_native
261 import ansible_collections.netapp.ontap.plugins.module_utils.netapp as netapp_utils
262 from ansible_collections.netapp.ontap.plugins.module_utils.netapp_module import NetAppModule
263 from ansible_collections.netapp.ontap.plugins.module_utils import rest_generic, netapp_ipaddress
264
265
266 class NetAppOntapSecurityIPsecPolicy:
267 def __init__(self):
268 self.argument_spec = netapp_utils.na_ontap_rest_only_spec()
269 self.argument_spec.update(dict(
270 state=dict(required=False, type='str', choices=['present', 'absent'], default='present'),
271 name=dict(required=True, type='str'),
272 action=dict(required=False, type='str', choices=['bypass', 'discard', 'esp_transport', 'esp_udp']),
273 authentication_method=dict(required=False, type='str', choices=['none', 'psk', 'pki']),
274 certificate=dict(required=False, type='str'),
275 enabled=dict(required=False, type='bool'),
276 ipspace=dict(required=False, type='str'),
277 local_endpoint=dict(required=False, type='dict', options=dict(
278 address=dict(required=True, type='str'),
279 netmask=dict(required=True, type='str'),
280 port=dict(required=False, type='str')
281 )),
282 local_identity=dict(required=False, type='str'),
283 remote_identity=dict(required=False, type='str'),
284 protocol=dict(required=False, type='str'),
285 remote_endpoint=dict(required=False, type='dict', options=dict(
286 address=dict(required=True, type='str'),
287 netmask=dict(required=True, type='str'),
288 port=dict(required=False, type='str')
289 )),
290 secret_key=dict(required=False, type='str', no_log=True),
291 svm=dict(required=False, type='str')
292 ))
293 self.module = AnsibleModule(
294 argument_spec=self.argument_spec,
295 mutually_exclusive=[('secret_key', 'certificate')],
296 required_if=[
297 ('authentication_method', 'psk', ['secret_key']),
298 ('authentication_method', 'pki', ['certificate'])
299 ],
300 supports_check_mode=True
301 )
302 self.uuid = None
303 self.na_helper = NetAppModule(self.module)
304 self.parameters = self.na_helper.check_and_set_parameters(self.module)
305 self.rest_api = netapp_utils.OntapRestAPI(self.module)
306 self.rest_api.fail_if_not_rest_minimum_version('na_ontap_security_ipsec_policy', 9, 8)
307 partially_supported_rest_properties = [['authentication_method', (9, 10, 1)], ['certificate', (9, 10, 1)]]
308 self.rest_api.is_rest_supported_properties(self.parameters, None, partially_supported_rest_properties)
309 self.parameters = self.na_helper.filter_out_none_entries(self.parameters)
310 if self.parameters['state'] == 'present':
311 self.validate_ipsec()
312
313 def validate_ipsec(self):
314 """
315 validate ipsec options.
316 """
317 for end_point in ['local_endpoint', 'remote_endpoint']:
318 if self.parameters.get(end_point):
319 self.parameters[end_point]['address'] = netapp_ipaddress.validate_and_compress_ip_address(self.parameters[end_point]['address'], self.module)
320 self.parameters[end_point]['netmask'] = str(netapp_ipaddress.netmask_to_netmask_length(self.parameters[end_point]['address'],
321 self.parameters[end_point]['netmask'], self.module))
322 # ONTAP returns port in port ranges. 120 set is returned as 120-120
323 if self.parameters[end_point].get('port') and '-' not in self.parameters[end_point]['port']:
324 self.parameters[end_point]['port'] = self.parameters[end_point]['port'] + '-' + self.parameters[end_point]['port']
325 # if action is bypass/discard and auth_method is psk/pki then security_key/certificate will be ignored in REST.
326 # so delete the authentication_method, secret_key and certificate to avoid idempotent issue.
327 if self.parameters.get('action') in ['bypass', 'discard'] and self.parameters.get('authentication_method') != 'none':
328 msg = "The IPsec action is %s, which does not provide packet protection. The authentication_method and " % self.parameters['action']
329 self.parameters.pop('authentication_method', None)
330 if self.parameters.get('secret_key'):
331 del self.parameters['secret_key']
332 self.module.warn(msg + 'secret_key options are ignored')
333 if self.parameters.get('certificate'):
334 del self.parameters['certificate']
335 self.module.warn(msg + 'certificate options are ignored')
336 # mapping protocol number to protocol to avoid idempotency issue.
337 protocols_info = {'6': 'tcp', '17': 'udp', '0': 'any'}
338 if self.parameters.get('protocol') in protocols_info:
339 self.parameters['protocol'] = protocols_info[self.parameters['protocol']]
340
341 def get_security_ipsec_policy(self):
342 """
343 Get security ipsec policy.
344 """
345 api = 'security/ipsec/policies'
346 query = {
347 'name': self.parameters['name'],
348 'fields': 'uuid,enabled,local_endpoint,local_identity,remote_identity,protocol,remote_endpoint,action'
349 }
350 if self.parameters.get('authentication_method'):
351 query['fields'] += ',authentication_method'
352 if self.parameters.get('certificate'):
353 query['fields'] += ',certificate'
354 if self.parameters.get('svm'):
355 query['svm.name'] = self.parameters['svm']
356 else:
357 query['scope'] = 'cluster'
358 # Cannot get current IPsec policy with ipspace - burt1519419
359 # if self.parameters.get('ipspace'):
360 # query['ipspace.name'] = self.parameters['ipspace']
361 record, error = rest_generic.get_one_record(self.rest_api, api, query)
362 if error:
363 self.module.fail_json(msg='Error fetching security ipsec policy %s: %s' % (self.parameters['name'], to_native(error)),
364 exception=traceback.format_exc())
365 if record:
366 self.uuid = record['uuid']
367 return {
368 'action': self.na_helper.safe_get(record, ['action']),
369 'authentication_method': self.na_helper.safe_get(record, ['authentication_method']),
370 'certificate': self.na_helper.safe_get(record, ['certificate', 'name']),
371 'enabled': self.na_helper.safe_get(record, ['enabled']),
372 'local_endpoint': self.na_helper.safe_get(record, ['local_endpoint']),
373 'local_identity': self.na_helper.safe_get(record, ['local_identity']),
374 'protocol': self.na_helper.safe_get(record, ['protocol']),
375 'remote_endpoint': self.na_helper.safe_get(record, ['remote_endpoint']),
376 'remote_identity': self.na_helper.safe_get(record, ['remote_identity'])
377 }
378 return None
379
380 def create_security_ipsec_policy(self):
381 """
382 Create security ipsec policy
383 """
384 api = 'security/ipsec/policies'
385 dummy, error = rest_generic.post_async(self.rest_api, api, self.form_create_modify_body())
386 if error:
387 self.module.fail_json(msg='Error creating security ipsec policy %s: %s.' % (self.parameters['name'], to_native(error)),
388 exception=traceback.format_exc())
389
390 def modify_security_ipsec_policy(self, modify):
391 """
392 Modify security ipsec policy.
393 """
394 api = 'security/ipsec/policies'
395 dummy, error = rest_generic.patch_async(self.rest_api, api, self.uuid, self.form_create_modify_body(modify))
396 if error:
397 self.module.fail_json(msg='Error modifying security ipsec policy %s: %s.' % (self.parameters['name'], to_native(error)),
398 exception=traceback.format_exc())
399
400 def delete_security_ipsec_policy(self):
401 """
402 Delete security ipsec policy.
403 """
404 api = 'security/ipsec/policies'
405 dummy, error = rest_generic.delete_async(self.rest_api, api, self.uuid)
406 if error:
407 self.module.fail_json(msg='Error deleting security ipsec policy %s: %s.' % (self.parameters['name'], to_native(error)),
408 exception=traceback.format_exc())
409
410 def form_create_modify_body(self, params=None):
411 """
412 Returns body for create or modify.
413 """
414 if params is None:
415 params = self.parameters
416 body = {}
417 keys = ['name', 'action', 'authentication_method', 'enabled', 'secret_key',
418 'local_endpoint', 'local_identity', 'remote_identity', 'protocol', 'remote_endpoint']
419 for key in keys:
420 if key in params:
421 body[key] = self.parameters[key]
422 if 'certificate' in params:
423 body['certificate.name'] = self.parameters['certificate']
424 if 'ipspace' in params:
425 body['ipspace.name'] = self.parameters['ipspace']
426 if 'svm' in params:
427 body['svm.name'] = self.parameters['svm']
428 return body
429
430 def apply(self):
431 current = self.get_security_ipsec_policy()
432 cd_action = self.na_helper.get_cd_action(current, self.parameters)
433 if cd_action is None:
434 modify = self.na_helper.get_modified_attributes(current, self.parameters)
435 error_keys = [key for key in modify if key in ['authentication_method', 'action']]
436 if error_keys:
437 plural = 's' if len(error_keys) > 1 else ''
438 self.module.fail_json(msg="Error: cannot modify option%s - %s." % (plural, ", ".join(error_keys)))
439 # Expected ONTAP to throw error but restarts instead, if try to set certificate where auth_method is none.
440 if modify.get('certificate') and current['authentication_method'] == 'none':
441 self.module.fail_json(msg="Error: cannot set certificate for IPsec policy where authentication_method is none")
442 if self.na_helper.changed and not self.module.check_mode:
443 if cd_action == 'create':
444 self.create_security_ipsec_policy()
445 elif cd_action == 'delete':
446 self.delete_security_ipsec_policy()
447 else:
448 self.modify_security_ipsec_policy(modify)
449 self.module.exit_json(changed=self.na_helper.changed)
450
451
452 def main():
453 ipsec_obj = NetAppOntapSecurityIPsecPolicy()
454 ipsec_obj.apply()
455
456
457 if __name__ == '__main__':
458 main()