Debian Codegraph @

ansible_collections/netapp/ontap/plugins/modules/na_ontap_net_routes.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_net_routes
8 '''
9
10 from __future__ import absolute_import, division, print_function
11 __metaclass__ = type
12
13
14 DOCUMENTATION = '''
15 module: na_ontap_net_routes
16 short_description: NetApp ONTAP network routes
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 - Modify ONTAP network routes.
23 options:
24 state:
25 description:
26 - Whether you want to create or delete a network route.
27 choices: ['present', 'absent']
28 type: str
29 default: present
30 vserver:
31 description:
32 - The name of the vserver.
33 - Required when using ZAPI.
34 - When using REST, omit this parameter for cluster scoped routes, or set it to NULL.
35 type: str
36 destination:
37 description:
38 - Specify the route destination.
39 - Example 10.7.125.5/20, fd20:13::/64.
40 required: true
41 type: str
42 gateway:
43 description:
44 - Specify the route gateway.
45 - Example 10.7.125.1, fd20:13::1.
46 required: true
47 type: str
48 metric:
49 description:
50 - Specify the route metric. If this field is not provided, ONTAP will default to 20.
51 - Supported from ONTAP 9.11.0 in REST.
52 - With REST, trying to modify destination or gateway will also reset metric to 20 in ONTAP 9.10.1 or earlier.
53 type: int
54 from_destination:
55 description:
56 - Specify the route destination that should be changed.
57 version_added: 2.8.0
58 type: str
59 from_gateway:
60 description:
61 - Specify the route gateway that should be changed.
62 version_added: 2.8.0
63 type: str
64 from_metric:
65 description:
66 - Specify the route metric that should be changed.
67 - This parameter is ignored, as the value is read from ONTAP.
68 - Not supported with REST, ignored with ZAPI.
69 version_added: 2.8.0
70 type: int
71 '''
72
73 EXAMPLES = """
74 - name: Create route
75 netapp.ontap.na_ontap_net_routes:
76 state: present
77 vserver: "{{ vserver_name }}"
78 username: "{{ netapp_username }}"
79 password: "{{ netapp_password }}"
80 hostname: "{{ netapp_hostname }}"
81 destination: 10.7.125.5/20
82 gateway: 10.7.125.1
83 metric: 30
84
85 - name: Create route - cluster scope, using REST
86 netapp.ontap.na_ontap_net_routes:
87 state: present
88 username: "{{ netapp_username }}"
89 password: "{{ netapp_password }}"
90 hostname: "{{ netapp_hostname }}"
91 destination: 10.7.125.5/20
92 gateway: 10.7.125.1
93
94 - name: Create route - vserver scope, using REST
95 netapp.ontap.na_ontap_net_routes:
96 state: present
97 vserver: "{{ vserver_name }}"
98 username: "{{ netapp_username }}"
99 password: "{{ netapp_password }}"
100 hostname: "{{ netapp_hostname }}"
101 destination: 10.7.125.5/20
102 gateway: 10.7.125.1
103 """
104
105 RETURN = """
106
107 """
108
109 import traceback
110
111 from ansible.module_utils.basic import AnsibleModule
112 from ansible.module_utils._text import to_native
113 import ansible_collections.netapp.ontap.plugins.module_utils.netapp as netapp_utils
114 from ansible_collections.netapp.ontap.plugins.module_utils.netapp_module import NetAppModule
115 from ansible_collections.netapp.ontap.plugins.module_utils import rest_generic
116
117
118 class NetAppOntapNetRoutes:
119 """
120 Create, Modifies and Destroys a Net Route
121 """
122
123 def __init__(self):
124 """
125 Initialize the Ontap Net Route class
126 """
127 self.use_rest = False
128 self.argument_spec = netapp_utils.na_ontap_host_argument_spec()
129 self.argument_spec.update(dict(
130 state=dict(required=False, type='str', choices=['present', 'absent'], default='present'),
131 vserver=dict(required=False, type='str'),
132 destination=dict(required=True, type='str'),
133 gateway=dict(required=True, type='str'),
134 metric=dict(required=False, type='int'),
135 from_destination=dict(required=False, type='str', default=None),
136 from_gateway=dict(required=False, type='str', default=None),
137 from_metric=dict(required=False, type='int', default=None),
138 ))
139
140 self.module = AnsibleModule(
141 argument_spec=self.argument_spec,
142 supports_check_mode=True
143 )
144
145 self.na_helper = NetAppModule()
146 self.parameters = self.na_helper.set_parameters(self.module.params)
147 self.rest_api = netapp_utils.OntapRestAPI(self.module)
148
149 # metric supported from ONTAP 9.11.0 version.
150 self.use_rest = self.rest_api.is_rest_supported_properties(self.parameters, ['from_metric'], [['metric', (9, 11, 0)]])
151 self.validate_options()
152 if not self.use_rest:
153 if not netapp_utils.has_netapp_lib():
154 self.module.fail_json(msg=netapp_utils.netapp_lib_is_required())
155 self.server = netapp_utils.setup_na_ontap_zapi(module=self.module, vserver=self.parameters['vserver'])
156
157 def validate_options(self):
158 errors = []
159 example = ''
160 if not self.use_rest and 'vserver' not in self.parameters:
161 # self.module.fail_json(msg="Error: vserver is a required parameter when using ZAPI")
162 errors.append("vserver is a required parameter when using ZAPI")
163 for attr in ('destination', 'from_destination'):
164 value = self.parameters.get(attr)
165 if value is not None and '/' not in value:
166 errors.append("Expecting '/' in '%s'" % value)
167 example = 'Examples: 10.7.125.5/20, fd20:13::/64'
168 if errors:
169 if example:
170 errors.append(example)
171 self.module.fail_json(msg="Error: %s." % '. '.join(errors))
172
173 @staticmethod
174 def sanitize_exception(action, exc):
175 if action == 'create' and to_native(exc.code) == '13001' and 'already exists' in to_native(exc.message):
176 return None
177 if action == 'get' and to_native(exc.code) == "15661":
178 # Error 15661 denotes a route doesn't exist.
179 return None
180 return to_native(exc)
181
182 def create_net_route(self, current=None, fail=True):
183 """
184 Creates a new Route
185 """
186 if current is None:
187 current = self.parameters
188 if self.use_rest:
189 api = 'network/ip/routes'
190 body = {'gateway': current['gateway']}
191 dest = current['destination']
192 if isinstance(dest, dict):
193 body['destination'] = dest
194 else:
195 dest = current['destination'].split('/')
196 body['destination'] = {'address': dest[0], 'netmask': dest[1]}
197 if current.get('vserver') is not None:
198 body['svm.name'] = current['vserver']
199 if current.get('metric') is not None:
200 body['metric'] = current['metric']
201 __, error = rest_generic.post_async(self.rest_api, api, body)
202 else:
203 route_obj = netapp_utils.zapi.NaElement('net-routes-create')
204 route_obj.add_new_child("destination", current['destination'])
205 route_obj.add_new_child("gateway", current['gateway'])
206 metric = current.get('metric')
207 if metric is not None:
208 route_obj.add_new_child("metric", str(metric))
209 try:
210 self.server.invoke_successfully(route_obj, True)
211 error = None
212 except netapp_utils.zapi.NaApiError as exc:
213 # return if desired route already exists
214 error = self.sanitize_exception('create', exc)
215 if error:
216 error = 'Error creating net route: %s' % error
217 if fail:
218 self.module.fail_json(msg=error)
219 return error
220
221 def delete_net_route(self, current):
222 """
223 Deletes a given Route
224 """
225 if self.use_rest:
226 uuid = current['uuid']
227 api = 'network/ip/routes'
228 dummy, error = rest_generic.delete_async(self.rest_api, api, uuid)
229 if error:
230 self.module.fail_json(msg='Error deleting net route - %s' % error)
231 else:
232 route_obj = netapp_utils.zapi.NaElement('net-routes-destroy')
233 route_obj.add_new_child("destination", current['destination'])
234 route_obj.add_new_child("gateway", current['gateway'])
235 try:
236 self.server.invoke_successfully(route_obj, True)
237 except netapp_utils.zapi.NaApiError as error:
238 self.module.fail_json(msg='Error deleting net route: %s'
239 % (to_native(error)),
240 exception=traceback.format_exc())
241
242 def recreate_net_route(self, current):
243 """
244 Modify a net route
245 Since we cannot modify a route, we are deleting the existing route, and creating a new one.
246 """
247 self.delete_net_route(current)
248 # use existing metric if not specified
249 if current.get('metric') is not None and self.parameters.get('metric') is None:
250 self.parameters['metric'] = current['metric']
251 error = self.create_net_route(fail=False)
252 if error:
253 # restore the old route, create the route with the existing values
254 self.create_net_route(current)
255 # Invalid value specified for any of the attributes
256 self.module.fail_json(msg='Error modifying net route: %s' % error,
257 exception=traceback.format_exc())
258
259 def get_net_route(self, params=None):
260 """
261 Checks to see if a route exist or not
262 :return: NaElement object if a route exists, None otherwise
263 """
264 if params is None:
265 params = self.parameters
266 if self.use_rest:
267 api = "network/ip/routes"
268 fields = 'destination,gateway,svm,scope'
269 if self.parameters.get('metric') is not None:
270 fields += ',metric'
271 query = {'destination.address': params['destination'].split('/')[0],
272 'gateway': params['gateway']}
273 if params.get('vserver') is None:
274 query['scope'] = 'cluster'
275 else:
276 query['scope'] = 'svm'
277 query['svm.name'] = params['vserver']
278 record, error = rest_generic.get_one_record(self.rest_api, api, query, fields)
279 if error:
280 self.module.fail_json(msg='Error fetching net route: %s' % error)
281 # even if metric not set, 20 is set by default.
282 if record and 'metric' not in record:
283 record['metric'] = None
284 return record
285 else:
286 route_obj = netapp_utils.zapi.NaElement('net-routes-get')
287 for attr in ('destination', 'gateway'):
288 route_obj.add_new_child(attr, params[attr])
289 try:
290 result = self.server.invoke_successfully(route_obj, True)
291 except netapp_utils.zapi.NaApiError as exc:
292 # Error 15661 denotes a route doesn't exist.
293 error = self.sanitize_exception('get', exc)
294 if error is None:
295 return None
296 self.module.fail_json(msg='Error fetching net route: %s' % error,
297 exception=traceback.format_exc())
298 if result.get_child_by_name('attributes') is not None:
299 route_info = result.get_child_by_name('attributes').get_child_by_name('net-vs-routes-info')
300 return {
301 'destination': route_info.get_child_content('destination'),
302 'gateway': route_info.get_child_content('gateway'),
303 'metric': int(route_info.get_child_content('metric'))
304 }
305 return None
306
307 def apply(self):
308 """
309 Run Module based on play book
310 """
311 modify, rename = False, False
312 current = self.get_net_route()
313 cd_action = self.na_helper.get_cd_action(current, self.parameters)
314 if cd_action == 'create' and any(self.parameters.get(attr) is not None for attr in ('from_gateway', 'from_destination')):
315 # create by renaming existing route if it exists
316 # destination and gateway combination is unique, and is considered like an id.
317 # So modify destination or gateway is considered a rename action.
318 # If one of 'destination', 'gateway' is not in the from field, use the desired value.
319 from_params = {'gateway': self.parameters.get('from_gateway', self.parameters['gateway']),
320 'destination': self.parameters.get('from_destination', self.parameters['destination'])}
321 if self.parameters.get('vserver'):
322 from_params['vserver'] = self.parameters['vserver']
323 current = self.get_net_route(from_params)
324 if current is None:
325 self.module.fail_json(msg="Error modifying: route %s does not exist" % self.parameters['from_destination'])
326 rename = True
327 cd_action = None
328
329 if cd_action is None and self.parameters.get('metric') is not None and current:
330 modify = self.parameters['metric'] != current['metric']
331 if modify:
332 self.na_helper.changed = True
333
334 if self.na_helper.changed and not self.module.check_mode:
335 if cd_action == 'create':
336 self.create_net_route()
337 elif cd_action == 'delete':
338 self.delete_net_route(current)
339 elif rename or modify:
340 self.recreate_net_route(current)
341 result = netapp_utils.generate_result(self.na_helper.changed, cd_action, modify, extra_responses={'rename': rename})
342 self.module.exit_json(**result)
343
344
345 def main():
346 """
347 Creates the NetApp Ontap Net Route object and runs the correct play task
348 """
349 obj = NetAppOntapNetRoutes()
350 obj.apply()
351
352
353 if __name__ == '__main__':
354 main()