Debian Codegraph @

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

raw
1 #!/usr/bin/python
2
3 # (c) 2019-2026, 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_efficiency_policy
8 '''
9 from __future__ import absolute_import, division, print_function
10 __metaclass__ = type
11
12
13 DOCUMENTATION = '''
14 module: na_ontap_efficiency_policy
15 short_description: NetApp ONTAP manage efficiency policies (sis policies)
16 extends_documentation_fragment:
17 - netapp.ontap.netapp.na_ontap
18 version_added: 2.9.0
19 author: NetApp Ansible Team (@carchi8py) <[email protected]>
20 description:
21 - Create/Modify/Delete efficiency policies (sis policies)
22 options:
23 state:
24 description:
25 - Whether the specified efficiency policy should exist or not.
26 choices: ['present', 'absent']
27 default: 'present'
28 type: str
29
30 policy_name:
31 description:
32 - the name of the efficiency policy
33 required: true
34 type: str
35
36 comment:
37 description:
38 - A brief description of the policy.
39 type: str
40
41 duration:
42 description:
43 - The duration in hours for which the scheduled efficiency operation should run.
44 After this time expires, the efficiency operation will be stopped even if the operation is incomplete.
45 If '-' is specified as the duration, the efficiency operation will run till it completes. Otherwise, the duration has to be an integer greater than 0.
46 By default, the operation runs till it completes.
47 type: str
48
49 enabled:
50 description:
51 - If the value is true, the efficiency policy is active in this cluster.
52 If the value is false this policy will not be activated by the schedulers and hence will be inactive.
53 type: bool
54
55 policy_type:
56 description:
57 - The policy type reflects the reason a volume using this policy will start processing a changelog.
58 - (Changelog processing is identifying and eliminating duplicate blocks which were written since the changelog was last processed.)
59 - threshold Changelog processing occurs once the changelog reaches a certain percent full.
60 - scheduled Changelog processing will be triggered by time.
61 choices: ['threshold', 'scheduled']
62 type: str
63
64 qos_policy:
65 description:
66 - QoS policy for the efficiency operation.
67 - background efficiency operation will run in background with minimal or no impact on data serving client operations,
68 - best-effort efficiency operations may have some impact on data serving client operations.
69 choices: ['background', 'best_effort']
70 type: str
71
72 schedule:
73 description:
74 - Cron type job schedule name. When the associated policy is set on a volume, the efficiency operation will be triggered for the volume on this schedule.
75 - These schedules can be created using the na_ontap_job_schedule module
76 type: str
77
78 vserver:
79 description:
80 - Name of the vserver to use.
81 required: true
82 type: str
83
84 changelog_threshold_percent:
85 description:
86 - Specifies the percentage at which the changelog will be processed for a threshold type of policy, tested once each hour.
87 type: int
88 version_added: '19.11.0'
89
90 lambda_config:
91 description:
92 - Configuration parameters for AWS Lambda proxy functionality.
93 - These option and suboptions are only supported with REST.
94 type: dict
95 version_added: 23.5.0
96 suboptions:
97 function_name:
98 description:
99 - The name of the AWS Lambda function to invoke.
100 type: str
101 required: true
102 aws_region:
103 description:
104 - The name of the AWS region.
105 type: str
106 required: true
107 aws_profile:
108 description:
109 - The name of the AWS profile to use for authentication.
110 type: str
111
112 notes:
113 - Supports AWS Lambda proxy functionality when using REST. See the README file for examples.
114 '''
115
116 EXAMPLES = """
117 - name: Create threshold efficiency policy
118 netapp.ontap.na_ontap_efficiency_policy:
119 username: "{{ netapp_username }}"
120 password: "{{ netapp_password }}"
121 hostname: "{{ netapp_hostname }}"
122 vserver: ansible
123 state: present
124 policy_name: test
125 comment: This policy is for x and y
126 enabled: true
127 policy_type: threshold
128 qos_policy: background
129 changelog_threshold_percent: 20
130
131 - name: Create Scheduled efficiency Policy
132 netapp.ontap.na_ontap_efficiency_policy:
133 username: "{{ netapp_username }}"
134 password: "{{ netapp_password }}"
135 hostname: "{{ netapp_hostname }}"
136 vserver: ansible
137 state: present
138 policy_name: test2
139 comment: This policy is for x and y
140 enabled: true
141 schedule: new_job_schedule
142 duration: 1
143 policy_type: scheduled
144 qos_policy: background
145 """
146
147 RETURN = """
148 """
149
150 import traceback
151 import ansible_collections.netapp.ontap.plugins.module_utils.netapp as netapp_utils
152 from ansible_collections.netapp.ontap.plugins.module_utils.netapp_module import NetAppModule
153 from ansible.module_utils.basic import AnsibleModule
154 from ansible.module_utils._text import to_native
155 from ansible_collections.netapp.ontap.plugins.module_utils.netapp import OntapRestAPI
156 from ansible_collections.netapp.ontap.plugins.module_utils import rest_generic
157
158
159 class NetAppOntapEfficiencyPolicy(object):
160 """
161 Create, delete and modify efficiency policy
162 """
163 def __init__(self):
164 self.argument_spec = netapp_utils.na_ontap_host_argument_spec()
165 self.argument_spec.update(dict(
166 state=dict(required=False, choices=['present', 'absent'], default='present'),
167 policy_name=dict(required=True, type='str'),
168 comment=dict(required=False, type='str'),
169 duration=dict(required=False, type='str'),
170 enabled=dict(required=False, type='bool'),
171 policy_type=dict(required=False, choices=['threshold', 'scheduled']),
172 qos_policy=dict(required=False, choices=['background', 'best_effort']),
173 schedule=dict(required=False, type='str'),
174 vserver=dict(required=True, type='str'),
175 changelog_threshold_percent=dict(required=False, type='int')
176 ))
177 self.argument_spec.update(netapp_utils.na_ontap_lambda_argument_spec())
178 self.module = AnsibleModule(
179 argument_spec=self.argument_spec,
180 supports_check_mode=True,
181 mutually_exclusive=[('changelog_threshold_percent', 'duration'), ('changelog_threshold_percent', 'schedule')],
182 required_if=[('use_lambda', True, ('lambda_config',))],
183 )
184 self.na_helper = NetAppModule()
185 self.parameters = self.na_helper.set_parameters(self.module.params)
186
187 # Set up Rest API
188 self.rest_api = OntapRestAPI(self.module)
189 self.use_rest = self.rest_api.is_rest()
190 self.uuid = None
191
192 if self.use_rest and not self.rest_api.meets_rest_minimum_version(self.use_rest, 9, 8, 0):
193 msg = 'REST requires ONTAP 9.8 or later for efficiency_policy APIs.'
194 self.use_rest = self.na_helper.fall_back_to_zapi(self.module, msg, self.parameters)
195
196 if self.parameters.get('policy_type') and self.parameters['state'] == 'present':
197 if self.parameters['policy_type'] == 'threshold':
198 if self.parameters.get('duration'):
199 self.module.fail_json(msg="duration cannot be set if policy_type is threshold")
200 if self.parameters.get('schedule'):
201 self.module.fail_json(msg='schedule cannot be set if policy_type is threshold')
202 # if policy_type is 'scheduled'
203 else:
204 if self.parameters.get('changelog_threshold_percent'):
205 self.module.fail_json(msg='changelog_threshold_percent cannot be set if policy_type is scheduled')
206
207 # if duration not set for a policy, ZAPI returns "-", whereas REST returns 0.
208 # "-" is an invalid value in REST, set to 0 if REST.
209 if self.parameters.get('duration') == "-" and self.use_rest:
210 self.parameters['duration'] = '0'
211
212 if not self.use_rest:
213 if self.parameters.get('use_lambda'):
214 self.module.fail_json(msg="Error: AWS Lambda proxy for ONTAP APIs is only supported with REST.")
215 if not netapp_utils.has_netapp_lib():
216 self.module.fail_json(msg=netapp_utils.netapp_lib_is_required())
217 self.server = netapp_utils.setup_na_ontap_zapi(module=self.module, vserver=self.parameters['vserver'])
218 self.set_playbook_zapi_key_map()
219
220 def set_playbook_zapi_key_map(self):
221
222 self.na_helper.zapi_int_keys = {
223 'changelog_threshold_percent': 'changelog-threshold-percent'
224 }
225 self.na_helper.zapi_str_keys = {
226 'policy_name': 'policy-name',
227 'comment': 'comment',
228 'policy_type': 'policy-type',
229 'qos_policy': 'qos-policy',
230 'schedule': 'schedule',
231 'duration': 'duration'
232 }
233 self.na_helper.zapi_bool_keys = {
234 'enabled': 'enabled'
235 }
236
237 def get_efficiency_policy(self):
238 """
239 Get a efficiency policy
240 :return: a efficiency-policy info
241 """
242 if self.use_rest:
243 return self.get_efficiency_policy_rest()
244 sis_policy_obj = netapp_utils.zapi.NaElement("sis-policy-get-iter")
245 query = netapp_utils.zapi.NaElement("query")
246 sis_policy_info = netapp_utils.zapi.NaElement("sis-policy-info")
247 sis_policy_info.add_new_child("policy-name", self.parameters['policy_name'])
248 sis_policy_info.add_new_child("vserver", self.parameters['vserver'])
249 query.add_child_elem(sis_policy_info)
250 sis_policy_obj.add_child_elem(query)
251 try:
252 results = self.server.invoke_successfully(sis_policy_obj, True)
253 except netapp_utils.zapi.NaApiError as error:
254 self.module.fail_json(msg="Error searching for efficiency policy %s: %s" % (self.parameters['policy_name'], to_native(error)),
255 exception=traceback.format_exc())
256 return_value = {}
257 if results.get_child_by_name('num-records') and int(results.get_child_content('num-records')) == 1:
258 attributes_list = results.get_child_by_name('attributes-list')
259 sis_info = attributes_list.get_child_by_name('sis-policy-info')
260 for option, zapi_key in self.na_helper.zapi_int_keys.items():
261 return_value[option] = self.na_helper.get_value_for_int(from_zapi=True, value=sis_info.get_child_content(zapi_key))
262 for option, zapi_key in self.na_helper.zapi_bool_keys.items():
263 return_value[option] = self.na_helper.get_value_for_bool(from_zapi=True, value=sis_info.get_child_content(zapi_key))
264 for option, zapi_key in self.na_helper.zapi_str_keys.items():
265 return_value[option] = sis_info.get_child_content(zapi_key)
266 return return_value
267 return None
268
269 def get_efficiency_policy_rest(self):
270 api = 'storage/volume-efficiency-policies'
271 query = {'name': self.parameters['policy_name'], 'svm.name': self.parameters['vserver']}
272 fields = 'name,type,start_threshold_percent,qos_policy,schedule,comment,duration,enabled'
273 record, error = rest_generic.get_one_record(self.rest_api, api, query, fields)
274 if error:
275 self.module.fail_json(msg="Error searching for efficiency policy %s: %s" % (self.parameters['policy_name'], error))
276 if record:
277 self.uuid = record['uuid']
278 current = {
279 'policy_name': record['name'],
280 'policy_type': record['type'],
281 'qos_policy': record['qos_policy'],
282 'schedule': record['schedule']['name'] if 'schedule' in record else None,
283 'enabled': record['enabled'],
284 'duration': str(record['duration']) if 'duration' in record else None,
285 'changelog_threshold_percent': record['start_threshold_percent'] if 'start_threshold_percent' in record else None,
286 'comment': record['comment']
287 }
288 return current
289 return None
290
291 def create_efficiency_policy(self):
292 """
293 Creates a efficiency policy
294 :return: None
295 """
296 if self.use_rest:
297 return self.create_efficiency_policy_rest()
298 sis_policy_obj = netapp_utils.zapi.NaElement("sis-policy-create")
299 for option, zapi_key in self.na_helper.zapi_int_keys.items():
300 if self.parameters.get(option):
301 sis_policy_obj.add_new_child(zapi_key,
302 self.na_helper.get_value_for_int(from_zapi=False,
303 value=self.parameters[option]))
304 for option, zapi_key in self.na_helper.zapi_bool_keys.items():
305 if self.parameters.get(option):
306 sis_policy_obj.add_new_child(zapi_key,
307 self.na_helper.get_value_for_bool(from_zapi=False,
308 value=self.parameters[option]))
309 for option, zapi_key in self.na_helper.zapi_str_keys.items():
310 if self.parameters.get(option):
311 sis_policy_obj.add_new_child(zapi_key, str(self.parameters[option]))
312 try:
313 self.server.invoke_successfully(sis_policy_obj, True)
314 except netapp_utils.zapi.NaApiError as error:
315 self.module.fail_json(msg="Error creating efficiency policy %s: %s" % (self.parameters["policy_name"], to_native(error)),
316 exception=traceback.format_exc())
317
318 def create_efficiency_policy_rest(self):
319 api = 'storage/volume-efficiency-policies'
320 body = {
321 'svm.name': self.parameters['vserver'],
322 'name': self.parameters['policy_name']
323 }
324 create_or_modify_body = self.form_create_or_modify_body(self.parameters)
325 if create_or_modify_body:
326 body.update(create_or_modify_body)
327 dummy, error = rest_generic.post_async(self.rest_api, api, body)
328 if error:
329 self.module.fail_json(msg="Error creating efficiency policy %s: %s" % (self.parameters["policy_name"], error))
330
331 def form_create_or_modify_body(self, create_or_modify):
332 """
333 Form body contents for create or modify efficiency policy.
334 :return: create or modify body.
335 """
336 body = {}
337 if 'comment' in create_or_modify:
338 body['comment'] = create_or_modify['comment']
339 if 'duration' in create_or_modify:
340 body['duration'] = create_or_modify['duration']
341 if 'enabled' in create_or_modify:
342 body['enabled'] = create_or_modify['enabled']
343 if 'qos_policy' in create_or_modify:
344 body['qos_policy'] = create_or_modify['qos_policy']
345 if 'schedule' in create_or_modify:
346 body['schedule'] = {'name': create_or_modify['schedule']}
347 if 'changelog_threshold_percent' in create_or_modify:
348 body['start_threshold_percent'] = create_or_modify['changelog_threshold_percent']
349 if 'policy_type' in create_or_modify:
350 body['type'] = create_or_modify['policy_type']
351 return body
352
353 def delete_efficiency_policy(self):
354 """
355 Delete a efficiency Policy
356 :return: None
357 """
358 if self.use_rest:
359 return self.delete_efficiency_policy_rest()
360 sis_policy_obj = netapp_utils.zapi.NaElement("sis-policy-delete")
361 sis_policy_obj.add_new_child("policy-name", self.parameters['policy_name'])
362 try:
363 self.server.invoke_successfully(sis_policy_obj, True)
364 except netapp_utils.zapi.NaApiError as error:
365 self.module.fail_json(msg="Error deleting efficiency policy %s: %s" % (self.parameters["policy_name"], to_native(error)),
366 exception=traceback.format_exc())
367
368 def delete_efficiency_policy_rest(self):
369 api = 'storage/volume-efficiency-policies'
370 dummy, error = rest_generic.delete_async(self.rest_api, api, self.uuid)
371 if error:
372 self.module.fail_json(msg="Error deleting efficiency policy %s: %s" % (self.parameters["policy_name"], error))
373
374 def modify_efficiency_policy(self, modify):
375 """
376 Modify a efficiency policy
377 :return: None
378 """
379 if self.use_rest:
380 return self.modify_efficiency_policy_rest(modify)
381 sis_policy_obj = netapp_utils.zapi.NaElement("sis-policy-modify")
382 sis_policy_obj.add_new_child("policy-name", self.parameters['policy_name'])
383 for attribute in modify:
384 sis_policy_obj.add_new_child(self.attribute_to_name(attribute), str(self.parameters[attribute]))
385 try:
386 self.server.invoke_successfully(sis_policy_obj, True)
387 except netapp_utils.zapi.NaApiError as error:
388 self.module.fail_json(msg="Error modifying efficiency policy %s: %s" % (self.parameters["policy_name"], to_native(error)),
389 exception=traceback.format_exc())
390
391 @staticmethod
392 def attribute_to_name(attribute):
393 return str.replace(attribute, '_', '-')
394
395 def validate_modify(self, current, modify):
396 """
397 sis-policy-create zapi pre-checks the options and fails if it's not supported.
398 is-policy-modify pre-checks one of the options, but tries to modify the others even it's not supported. And it will mess up the vsim.
399 Do the checks before sending to the zapi.
400 This checks applicable for REST modify too.
401 """
402 if current['policy_type'] == 'scheduled' and self.parameters.get('policy_type') != 'threshold':
403 if modify.get('changelog_threshold_percent'):
404 self.module.fail_json(msg="changelog_threshold_percent cannot be set if policy_type is scheduled")
405 elif current['policy_type'] == 'threshold' and self.parameters.get('policy_type') != 'scheduled':
406 if modify.get('duration'):
407 self.module.fail_json(msg="duration cannot be set if policy_type is threshold")
408 elif modify.get('schedule'):
409 self.module.fail_json(msg="schedule cannot be set if policy_type is threshold")
410
411 def modify_efficiency_policy_rest(self, modify):
412 api = 'storage/volume-efficiency-policies'
413 body = self.form_create_or_modify_body(modify)
414 dummy, error = rest_generic.patch_async(self.rest_api, api, self.uuid, body)
415 if error:
416 self.module.fail_json(msg="Error modifying efficiency policy %s: %s" % (self.parameters["policy_name"], error))
417
418 def apply(self):
419 current = self.get_efficiency_policy()
420 modify = None
421 cd_action = self.na_helper.get_cd_action(current, self.parameters)
422 if cd_action is None and self.parameters['state'] == 'present':
423 modify = self.na_helper.get_modified_attributes(current, self.parameters)
424 if modify:
425 self.validate_modify(current, modify)
426 if self.na_helper.changed and not self.module.check_mode:
427 if cd_action == 'create':
428 self.create_efficiency_policy()
429 elif cd_action == 'delete':
430 self.delete_efficiency_policy()
431 elif modify:
432 self.modify_efficiency_policy(modify)
433 result = netapp_utils.generate_result(self.na_helper.changed, cd_action, modify)
434 self.module.exit_json(**result)
435
436
437 def main():
438 obj = NetAppOntapEfficiencyPolicy()
439 obj.apply()
440
441
442 if __name__ == '__main__':
443 main()