Debian Codegraph @

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

raw
1 #!/usr/bin/python
2
3 # (c) 2018-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_job_schedule
8 '''
9
10 from __future__ import absolute_import, division, print_function
11 __metaclass__ = type
12
13
14 DOCUMENTATION = '''
15 module: na_ontap_job_schedule
16 short_description: NetApp ONTAP Job Schedule
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 - Create/Delete/Modify job-schedules on ONTAP
23 options:
24 state:
25 description:
26 - Whether the specified job schedule should exist or not.
27 choices: ['present', 'absent']
28 type: str
29 default: present
30 name:
31 description:
32 - The name of the job-schedule to manage.
33 required: true
34 type: str
35 job_minutes:
36 description:
37 - The minute(s) of each hour when the job should be run.
38 Job Manager cron scheduling minute.
39 - C(-1) represents all minutes.
40 Range is [-1..59]
41 - Required for create.
42 type: list
43 elements: int
44 job_hours:
45 version_added: 2.8.0
46 description:
47 - The hour(s) of the day when the job should be run.
48 Job Manager cron scheduling hour.
49 - C(-1) represents all hours.
50 Range is [-1..23]
51 type: list
52 elements: int
53 job_months:
54 version_added: 2.8.0
55 description:
56 - The month(s) when the job should be run.
57 Job Manager cron scheduling month.
58 - C(-1) represents all months.
59 Range is [-1..12], 0 and 12 may or may not be supported, see C(month_offset)
60 type: list
61 elements: int
62 job_days_of_month:
63 version_added: 2.8.0
64 description:
65 - The day(s) of the month when the job should be run.
66 Job Manager cron scheduling day of month.
67 - C(-1) represents all days of a month from 1 to 31.
68 Range is [-1..31]
69 type: list
70 elements: int
71 job_days_of_week:
72 version_added: 2.8.0
73 description:
74 - The day(s) in the week when the job should be run.
75 Job Manager cron scheduling day of week.
76 - Zero represents Sunday. C(-1) represents all days of a week.
77 Range is [-1..6]
78 type: list
79 elements: int
80 month_offset:
81 description:
82 - whether January starts at 0 or 1. By default, ZAPI is using a 0..11 range, while REST is using 1..12.
83 - default to 0 when using ZAPI, and to 1 when using REST.
84 - when set to 0, a value of 12 or higher is rejected.
85 - when set to 1, a value of 0 or of 13 or higher is rejected.
86 type: int
87 choices: [0, 1]
88 version_added: 21.9.0
89 cluster:
90 description:
91 - Defaults to local cluster.
92 - In a MetroCluster configuration, user-created schedules owned by the local cluster are replicated to the partner cluster.
93 Likewise, user-created schedules owned by the partner cluster are replicated to the local cluster.
94 - Normally, only schedules owned by the local cluster can be created, modified, and deleted on the local cluster.
95 However, when a MetroCluster configuration is in switchover, the cluster in switchover state can
96 create, modify, and delete schedules owned by the partner cluster.
97 type: str
98 version_added: 21.22.0
99 vserver:
100 description:
101 - name of the vserver.
102 type: str
103 version_added: 23.2.0
104 interval:
105 description:
106 - The interval at which the job should be run.
107 - This is specified in an ISO-8601 duration formatted string.
108 - This parameter does not work with cron jobs.
109 type: str
110 version_added: 23.2.0
111 lambda_config:
112 description:
113 - Configuration parameters for AWS Lambda proxy functionality.
114 - These option and suboptions are only supported with REST.
115 type: dict
116 version_added: 23.5.0
117 suboptions:
118 function_name:
119 description:
120 - The name of the AWS Lambda function to invoke.
121 type: str
122 required: true
123 aws_region:
124 description:
125 - The name of the AWS region.
126 type: str
127 required: true
128 aws_profile:
129 description:
130 - The name of the AWS profile to use for authentication.
131 type: str
132
133 notes:
134 - Supports AWS Lambda proxy functionality when using REST. See README for example usage.
135 '''
136
137 EXAMPLES = """
138 - name: Create Job for 11.30PM at 10th of every month
139 netapp.ontap.na_ontap_job_schedule:
140 state: present
141 name: jobName
142 job_minutes: 30
143 job_hours: 23
144 job_days_of_month: 10
145 job_months: -1
146 hostname: "{{ netapp_hostname }}"
147 username: "{{ netapp_username }}"
148 password: "{{ netapp_password }}"
149
150 - name: Create Job for 11.30PM at 10th of January, April, July, October for ZAPI and REST
151 netapp.ontap.na_ontap_job_schedule:
152 state: present
153 name: jobName
154 job_minutes: 30
155 job_hours: 23
156 job_days_of_month: 10
157 job_months: 1,4,7,10
158 month_offset: 1
159 hostname: "{{ netapp_hostname }}"
160 username: "{{ netapp_username }}"
161 password: "{{ netapp_password }}"
162
163 - name: Create Job for 11.30PM at 10th of January, April, July, October for ZAPI and REST
164 netapp.ontap.na_ontap_job_schedule:
165 state: present
166 name: jobName
167 job_minutes: 30
168 job_hours: 23
169 job_days_of_month: 10
170 job_months: 0,3,6,9
171 month_offset: 0
172 hostname: "{{ netapp_hostname }}"
173 username: "{{ netapp_username }}"
174 password: "{{ netapp_password }}"
175
176 - name: Create Job for 11.30PM at 10th of January when using REST and February when using ZAPI !!!
177 netapp.ontap.na_ontap_job_schedule:
178 state: present
179 name: jobName
180 job_minutes: 30
181 job_hours: 23
182 job_days_of_month: 10
183 job_months: 1
184 hostname: "{{ netapp_hostname }}"
185 username: "{{ netapp_username }}"
186 password: "{{ netapp_password }}"
187
188 - name: Create Interval Job using REST
189 netapp.ontap.na_ontap_job_schedule:
190 state: present
191 name: jobName
192 interval: P1DT2H3M4S
193 hostname: "{{ netapp_hostname }}"
194 username: "{{ netapp_username }}"
195 password: "{{ netapp_password }}"
196
197 - name: Delete Job
198 netapp.ontap.na_ontap_job_schedule:
199 state: absent
200 name: jobName
201 hostname: "{{ netapp_hostname }}"
202 username: "{{ netapp_username }}"
203 password: "{{ netapp_password }}"
204 """
205
206 RETURN = """
207
208 """
209
210
211 import traceback
212 from ansible.module_utils.basic import AnsibleModule
213 from ansible.module_utils._text import to_native
214 import ansible_collections.netapp.ontap.plugins.module_utils.netapp as netapp_utils
215 from ansible_collections.netapp.ontap.plugins.module_utils.netapp_module import NetAppModule
216 from ansible_collections.netapp.ontap.plugins.module_utils import rest_generic
217
218
219 class NetAppONTAPJob:
220 '''Class with job schedule cron methods'''
221
222 def __init__(self):
223
224 self.use_rest = False
225 self.argument_spec = netapp_utils.na_ontap_host_argument_spec()
226 self.argument_spec.update(dict(
227 state=dict(required=False, type='str', choices=['present', 'absent'], default='present'),
228 name=dict(required=True, type='str'),
229 job_minutes=dict(required=False, type='list', elements='int'),
230 job_months=dict(required=False, type='list', elements='int'),
231 job_hours=dict(required=False, type='list', elements='int'),
232 job_days_of_month=dict(required=False, type='list', elements='int'),
233 job_days_of_week=dict(required=False, type='list', elements='int'),
234 month_offset=dict(required=False, type='int', choices=[0, 1]),
235 cluster=dict(required=False, type='str'),
236 vserver=dict(required=False, type='str'),
237 interval=dict(required=False, type='str')
238 ))
239 self.argument_spec.update(netapp_utils.na_ontap_lambda_argument_spec())
240
241 self.uuid = None
242 self.module = AnsibleModule(
243 argument_spec=self.argument_spec,
244 required_if=[
245 ('use_lambda', True, ['lambda_config']),
246 ],
247 supports_check_mode=True
248 )
249
250 self.na_helper = NetAppModule()
251 self.parameters = self.na_helper.set_parameters(self.module.params)
252
253 self.rest_api = netapp_utils.OntapRestAPI(self.module)
254 self.use_rest = self.rest_api.is_rest()
255 if not self.use_rest:
256 if self.parameters.get('use_lambda'):
257 self.module.fail_json(msg="Error: AWS Lambda proxy for ONTAP APIs is only supported with REST.")
258
259 self.month_offset = self.parameters.get('month_offset')
260 if self.month_offset is None:
261 # maintain backward compatibility
262 self.month_offset = 1 if self.use_rest else 0
263 if self.month_offset == 1 and self.parameters.get('job_months') and 0 in self.parameters['job_months']:
264 # we explictly test for 0 as it would be converted to -1, which has a special meaning (all).
265 # other value errors will be reported by the API.
266 self.module.fail_json(msg='Error: 0 is not a valid value in months if month_offset is set to 1: %s' % self.parameters['job_months'])
267
268 if self.use_rest:
269 self.set_playbook_api_key_map()
270 elif not netapp_utils.has_netapp_lib():
271 self.module.fail_json(msg=netapp_utils.netapp_lib_is_required())
272 else:
273 self.server = netapp_utils.setup_na_ontap_zapi(module=self.module)
274 self.set_playbook_zapi_key_map()
275
276 def set_playbook_zapi_key_map(self):
277 self.na_helper.zapi_string_keys = {
278 'name': 'job-schedule-name',
279 'cluster': 'job-schedule-cluster'
280 }
281 self.na_helper.zapi_list_keys = {
282 'job_minutes': ('job-schedule-cron-minute', 'cron-minute'),
283 'job_months': ('job-schedule-cron-month', 'cron-month'),
284 'job_hours': ('job-schedule-cron-hour', 'cron-hour'),
285 'job_days_of_month': ('job-schedule-cron-day', 'cron-day-of-month'),
286 'job_days_of_week': ('job-schedule-cron-day-of-week', 'cron-day-of-week')
287 }
288
289 def set_playbook_api_key_map(self):
290 self.na_helper.params_to_rest_api_keys = {
291 'job_minutes': 'minutes',
292 'job_months': 'months',
293 'job_hours': 'hours',
294 'job_days_of_month': 'days',
295 'job_days_of_week': 'weekdays'
296 }
297
298 def get_job_schedule_rest(self):
299 """
300 Return details about the job
301 :param:
302 name : Job name
303 :return: Details about the Job. None if not found.
304 :rtype: dict
305 """
306 query = {'name': self.parameters['name']}
307 if self.parameters.get('cluster'):
308 query['cluster'] = self.parameters['cluster']
309 if self.parameters.get('vserver'):
310 query['svm'] = self.parameters['vserver']
311 record, error = rest_generic.get_one_record(self.rest_api, 'cluster/schedules', query, 'uuid,cron,interval,type')
312 if error is not None:
313 self.module.fail_json(msg="Error fetching job schedule: %s" % error)
314 if record:
315 self.uuid = record['uuid']
316 job_details = {'name': record['name'], 'type': record['type']}
317 if 'svm' in record:
318 job_details['vserver'] = record['svm']['name']
319 if record['type'] == 'cron':
320 for param_key, rest_key in self.na_helper.params_to_rest_api_keys.items():
321 if rest_key in record['cron']:
322 job_details[param_key] = record['cron'][rest_key]
323 else:
324 # if any of the job_hours, job_minutes, job_months, job_days are empty:
325 # it means the value is -1 using ZAPI convention
326 job_details[param_key] = [-1]
327 # adjust offsets if necessary
328 if 'job_months' in job_details and self.month_offset == 0:
329 job_details['job_months'] = [x - 1 if x > 0 else x for x in job_details['job_months']]
330 # adjust minutes if necessary, -1 means all in ZAPI and for our user facing parameters
331 # while REST returns all values
332 if 'job_minutes' in job_details and len(job_details['job_minutes']) == 60:
333 job_details['job_minutes'] = [-1]
334 else:
335 job_details['interval'] = record['interval']
336
337 return job_details
338 return None
339
340 def get_job_schedule(self):
341 """
342 Return details about the job
343 :param:
344 name : Job name
345 :return: Details about the Job. None if not found.
346 :rtype: dict
347 """
348 if self.use_rest:
349 return self.get_job_schedule_rest()
350
351 job_get_iter = netapp_utils.zapi.NaElement('job-schedule-cron-get-iter')
352 query = {'job-schedule-cron-info': {'job-schedule-name': self.parameters['name']}}
353 if self.parameters.get('cluster'):
354 query['job-schedule-cron-info']['job-schedule-cluster'] = self.parameters['cluster']
355 job_get_iter.translate_struct({'query': query})
356 try:
357 result = self.server.invoke_successfully(job_get_iter, True)
358 except netapp_utils.zapi.NaApiError as error:
359 self.module.fail_json(msg='Error fetching job schedule %s: %s'
360 % (self.parameters['name'], to_native(error)),
361 exception=traceback.format_exc())
362 job_details = None
363 # check if job exists
364 if result.get_child_by_name('num-records') and int(result['num-records']) >= 1:
365 job_info = result['attributes-list']['job-schedule-cron-info']
366 job_details = {}
367 for item_key, zapi_key in self.na_helper.zapi_string_keys.items():
368 job_details[item_key] = job_info[zapi_key]
369 for item_key, zapi_key in self.na_helper.zapi_list_keys.items():
370 parent, dummy = zapi_key
371 job_details[item_key] = self.na_helper.get_value_for_list(from_zapi=True,
372 zapi_parent=job_info.get_child_by_name(parent)
373 )
374 if item_key == 'job_months' and self.month_offset == 1:
375 job_details[item_key] = [int(x) + 1 if int(x) >= 0 else int(x) for x in job_details[item_key]]
376 elif item_key == 'job_minutes' and len(job_details[item_key]) == 60:
377 job_details[item_key] = [-1]
378 else:
379 job_details[item_key] = [int(x) for x in job_details[item_key]]
380 # if any of the job_hours, job_minutes, job_months, job_days are empty:
381 # it means the value is -1 for ZAPI
382 if not job_details[item_key]:
383 job_details[item_key] = [-1]
384 return job_details
385
386 def add_job_details(self, na_element_object, values):
387 """
388 Add children node for create or modify NaElement object
389 :param na_element_object: modify or create NaElement object
390 :param values: dictionary of cron values to be added
391 :return: None
392 """
393 for item_key, item_value in values.items():
394 if item_key in self.na_helper.zapi_string_keys:
395 zapi_key = self.na_helper.zapi_string_keys.get(item_key)
396 na_element_object[zapi_key] = item_value
397 elif item_key in self.na_helper.zapi_list_keys:
398 parent_key, child_key = self.na_helper.zapi_list_keys.get(item_key)
399 data = item_value
400 if data:
401 if item_key == 'job_months' and self.month_offset == 1:
402 # -1 is a special value
403 data = [str(x - 1) if x > 0 else str(x) for x in data]
404 else:
405 data = [str(x) for x in data]
406 na_element_object.add_child_elem(self.na_helper.get_value_for_list(from_zapi=False,
407 zapi_parent=parent_key,
408 zapi_child=child_key,
409 data=data))
410
411 def create_job_schedule(self):
412 """
413 Creates a job schedule
414 """
415 if self.use_rest:
416 cron = {}
417 for param_key, rest_key in self.na_helper.params_to_rest_api_keys.items():
418 # -1 means all in zapi, while empty means all in api.
419 if self.parameters.get(param_key):
420 if len(self.parameters[param_key]) == 1 and self.parameters[param_key][0] == -1:
421 # need to set empty value for minutes as this is a required parameter
422 if rest_key == 'minutes':
423 cron[rest_key] = []
424 elif param_key == 'job_months' and self.month_offset == 0:
425 cron[rest_key] = [x + 1 if x >= 0 else x for x in self.parameters[param_key]]
426 else:
427 cron[rest_key] = self.parameters[param_key]
428
429 params = {
430 'name': self.parameters['name'],
431 'cron': cron
432 }
433 if self.parameters.get('cluster'):
434 params['cluster'] = self.parameters['cluster']
435 if self.parameters.get('vserver'):
436 params['svm'] = self.parameters['vserver']
437 if self.parameters.get('interval'):
438 params['interval'] = self.parameters['interval']
439 api = 'cluster/schedules'
440 dummy, error = self.rest_api.post(api, params)
441 if error is not None:
442 self.module.fail_json(msg="Error creating job schedule: %s" % error)
443
444 else:
445 job_schedule_create = netapp_utils.zapi.NaElement('job-schedule-cron-create')
446 self.add_job_details(job_schedule_create, self.parameters)
447 try:
448 self.server.invoke_successfully(job_schedule_create,
449 enable_tunneling=True)
450 except netapp_utils.zapi.NaApiError as error:
451 self.module.fail_json(msg='Error creating job schedule %s: %s'
452 % (self.parameters['name'], to_native(error)),
453 exception=traceback.format_exc())
454
455 def delete_job_schedule(self):
456 """
457 Delete a job schedule
458 """
459 if self.use_rest:
460 api = 'cluster/schedules/' + self.uuid
461 dummy, error = self.rest_api.delete(api)
462 if error is not None:
463 self.module.fail_json(msg="Error deleting job schedule: %s" % error)
464 else:
465 job_schedule_delete = netapp_utils.zapi.NaElement('job-schedule-cron-destroy')
466 self.add_job_details(job_schedule_delete, self.parameters)
467 try:
468 self.server.invoke_successfully(job_schedule_delete,
469 enable_tunneling=True)
470 except netapp_utils.zapi.NaApiError as error:
471 self.module.fail_json(msg='Error deleting job schedule %s: %s'
472 % (self.parameters['name'], to_native(error)),
473 exception=traceback.format_exc())
474
475 def modify_job_schedule(self, modify, current):
476 """
477 modify a job schedule
478 """
479
480 def set_cron(param_key, rest_key, params, cron):
481 # -1 means all in zapi, while empty means all in api.
482 if params[param_key] == [-1]:
483 cron[rest_key] = []
484 elif param_key == 'job_months' and self.month_offset == 0:
485 cron[rest_key] = [x + 1 for x in params[param_key]]
486 else:
487 cron[rest_key] = params[param_key]
488
489 if self.use_rest:
490 cron = {}
491 for param_key, rest_key in self.na_helper.params_to_rest_api_keys.items():
492 if modify.get(param_key):
493 set_cron(param_key, rest_key, modify, cron)
494 elif current.get(param_key):
495 # Usually only include modify attributes, but omitting an attribute means all in api.
496 # Need to add the current attributes in params.
497 set_cron(param_key, rest_key, current, cron)
498 params = {
499 'cron': cron
500 }
501 if modify.get('interval'):
502 params['interval'] = modify['interval']
503 api = 'cluster/schedules/' + self.uuid
504 dummy, error = self.rest_api.patch(api, params)
505 if error is not None:
506 self.module.fail_json(msg="Error modifying job schedule: %s" % error)
507 else:
508 job_schedule_modify = netapp_utils.zapi.NaElement.create_node_with_children(
509 'job-schedule-cron-modify', **{'job-schedule-name': self.parameters['name']})
510 self.add_job_details(job_schedule_modify, modify)
511 try:
512 self.server.invoke_successfully(job_schedule_modify, enable_tunneling=True)
513 except netapp_utils.zapi.NaApiError as error:
514 self.module.fail_json(msg='Error modifying job schedule %s: %s'
515 % (self.parameters['name'], to_native(error)),
516 exception=traceback.format_exc())
517
518 def apply(self):
519 """
520 Apply action to job-schedule
521 """
522 modify = None
523 current = self.get_job_schedule()
524 action = self.na_helper.get_cd_action(current, self.parameters)
525 if action is None and self.parameters['state'] == 'present':
526 modify = self.na_helper.get_modified_attributes(current, self.parameters)
527
528 if self.na_helper.changed and not self.module.check_mode:
529 if action == 'create':
530 self.create_job_schedule()
531 elif action == 'delete':
532 self.delete_job_schedule()
533 elif modify:
534 self.modify_job_schedule(modify, current)
535 result = netapp_utils.generate_result(self.na_helper.changed, action, modify)
536 self.module.exit_json(**result)
537
538
539 def main():
540 '''Execute action'''
541 job_obj = NetAppONTAPJob()
542 job_obj.apply()
543
544
545 if __name__ == '__main__':
546 main()