Debian Codegraph @

ansible_collections/netapp/ontap/plugins/modules/na_ontap_flexcache.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_flexcache
8 """
9
10 from __future__ import absolute_import, division, print_function
11 __metaclass__ = type
12
13 DOCUMENTATION = '''
14 short_description: NetApp ONTAP FlexCache - create/delete relationship
15 author: NetApp Ansible Team (@carchi8py) <[email protected]>
16 description:
17 - Create/Modify/Delete FlexCache volume relationships.
18 - This module does not modify an existing FlexCache volume when using ZAPI.
19 - When using REST, a prepopulate can be started on an exising FlexCache volume.
20 - When using REST, the volume can be mounted or unmounted. Set path to '' to unmount it.
21 - It is required the volume is mounted to prepopulate it.
22 - Some actions are also available through the na_ontap_volume.
23 - Cache volume can not be deleted in ZAPI.
24 extends_documentation_fragment:
25 - netapp.ontap.netapp.na_ontap
26 module: na_ontap_flexcache
27 version_added: 2.8.0
28 options:
29 state:
30 choices: ['present', 'absent']
31 description:
32 - Whether the specified relationship should exist or not.
33 default: present
34 type: str
35 origin_volume:
36 description:
37 - Name of the origin volume for the FlexCache.
38 - Required for creation.
39 type: str
40 origin_vserver:
41 description:
42 - Name of the origin vserver for the FlexCache.
43 - Required for creation.
44 type: str
45 origin_cluster:
46 description:
47 - Name of the origin cluster for the FlexCache.
48 - Defaults to cluster associated with target vserver if absent.
49 - Not used for creation.
50 type: str
51 name:
52 description:
53 - Name of the target volume for the FlexCache.
54 required: true
55 type: str
56 aliases: ['volume']
57 version_added: 21.3.0
58 junction_path:
59 description:
60 - Junction path of the cache volume.
61 type: str
62 aliases: ['path']
63 auto_provision_as:
64 description:
65 - Use this parameter to automatically select existing aggregates for volume provisioning. Eg flexgroup
66 - Note that the fastest aggregate type with at least one aggregate on each node of the cluster will be selected.
67 - Ignored when using REST - omit aggr_list for automatic selection.
68 type: str
69 size:
70 description:
71 - Size of cache volume.
72 type: int
73 size_unit:
74 description:
75 - The unit used to interpret the size parameter.
76 choices: ['bytes', 'b', 'kb', 'mb', 'gb', 'tb', 'pb', 'eb', 'zb', 'yb']
77 type: str
78 default: gb
79 vserver:
80 description:
81 - Name of the target vserver for the FlexCache.
82 - Note that hostname, username, password are intended for the target vserver.
83 required: true
84 type: str
85 aggr_list:
86 description:
87 - List of aggregates to host target FlexCache volume.
88 type: list
89 elements: str
90 aliases: ['aggregates']
91 aggr_list_multiplier:
92 description:
93 - Aggregate list repeat count.
94 - REST - Number of FlexCache constituents per aggregate when the C(aggregates) field is mentioned.
95 type: int
96 aliases: ['constituents_per_aggregate']
97 force_unmount:
98 description:
99 - Unmount FlexCache volume. Delete the junction path at which the volume is mounted before deleting the FlexCache relationship.
100 type: bool
101 default: false
102 force_offline:
103 description:
104 - Offline FlexCache volume before deleting the FlexCache relationship.
105 - The volume will be destroyed and data can be lost.
106 type: bool
107 default: false
108 time_out:
109 description:
110 - time to wait for flexcache creation or deletion in seconds
111 - if 0, the request is asynchronous
112 - default is set to 3 minutes
113 type: int
114 default: 180
115 writeback:
116 version_added: 22.13.0
117 description:
118 - FlexCache Writeback.
119 - Requires ONTAP 9.12 or later and only supported with REST.
120 type: dict
121 suboptions:
122 enabled:
123 description:
124 - Indicates whether or not writeback is enabled for the FlexCache volume.
125 - Writeback is a storage method where data is first written to the FlexCache volume and then written to the origin of a FlexCache volume.
126 type: bool
127 default: no
128 prepopulate:
129 version_added: 21.3.0
130 description:
131 - prepopulate FlexCache with data from origin volume.
132 - requires ONTAP 9.8 or later, and REST support.
133 - dir_paths must be set for this option to be effective.
134 type: dict
135 suboptions:
136 dir_paths:
137 description:
138 - List of directory paths in the owning SVM's namespace at which the FlexCache volume is mounted.
139 - Path must begin with '/'.
140 type: list
141 elements: str
142 required: true
143 exclude_dir_paths:
144 description:
145 - Directory path which needs to be excluded from prepopulation.
146 - Path must begin with '/'.
147 - Requires ONTAP 9.9 or later.
148 type: list
149 elements: str
150 recurse:
151 description:
152 - Specifies whether or not the prepopulate action should search through the directory-path recursively.
153 - If not set, the default value 'true' is used.
154 type: bool
155 force_prepopulate_if_already_created:
156 description:
157 - by default, this module will start a prepopulate task each time it is called, and is not idempotent.
158 - if set to false, the prepopulate task is not started if the FlexCache already exists.
159 type: bool
160 default: true
161 relative_size:
162 version_added: 22.14.0
163 description:
164 - Only supported with REST and requires ONTAP 9.13.1 or later.
165 type: dict
166 suboptions:
167 enabled:
168 description:
169 - Specifies whether the relative sizing is enabled for the FlexCache volume.
170 type: bool
171 percentage:
172 description:
173 - Specifies the percent size the FlexCache volume should have relative to the total size of the origin volume.
174 type: int
175 override_encryption:
176 version_added: 22.14.0
177 description:
178 - If set to true, a plaintext FlexCache volume for an encrypted origin volume is created.
179 - Only supported with REST and requires ONTAP 9.14.1 or later.
180 type: bool
181 atime_scrub:
182 version_added: 22.14.0
183 description:
184 - Only supported with REST and requires ONTAP 9.14.1 or later.
185 type: dict
186 suboptions:
187 enabled:
188 description:
189 - Specifies whether scrubbing of inactive files based on atime is enabled for the FlexCache volume.
190 type: bool
191 period:
192 description:
193 - Specifies the atime duration in days after which a cached file is considered inactive.
194 type: int
195 cifs_change_notify_enabled:
196 version_added: 22.14.0
197 description:
198 - Specifies whether a CIFS change notification is enabled for the FlexCache volume.
199 - Only supported with REST and requires ONTAP 9.15.1 or later.
200 type: bool
201 global_file_locking_enabled:
202 version_added: 22.14.0
203 description:
204 - Specifies whether or not a FlexCache volume has global file locking mode enabled.
205 - When global file locking mode is enabled, the 'is_disconnected_mode_off_for_locks' flag is always set to 'true'.
206 - Only supported with REST and requires ONTAP 9.9 or later.
207 type: bool
208 guarantee_type:
209 version_added: 22.14.0
210 description:
211 - Specifies The type of space guarantee of this volume in the aggregate.
212 - A value of 'volume' reserves space on the aggregates for the entire volume.
213 - A value of 'none' reserves no space on the aggregates, meaning that writes can fail if an aggregate runs out of space.
214 - Only supported with REST and requires ONTAP 9.7 or later.
215 choices: ['volume', 'none']
216 type: str
217 dr_cache:
218 version_added: 22.14.0
219 description:
220 - If set to true, a DR cache is created.
221 - Only supported with REST and requires ONTAP 9.9 or later.
222 type: bool
223 lambda_config:
224 description:
225 - Configuration parameters for AWS Lambda proxy functionality.
226 - These option and suboptions are only supported with REST.
227 type: dict
228 version_added: 23.5.0
229 suboptions:
230 function_name:
231 description:
232 - The name of the AWS Lambda function to invoke.
233 type: str
234 required: true
235 aws_region:
236 description:
237 - The name of the AWS region.
238 type: str
239 required: true
240 aws_profile:
241 description:
242 - The name of the AWS profile to use for authentication.
243 type: str
244
245 notes:
246 - Supports AWS Lambda proxy functionality when using REST. See README for example usage.
247 '''
248
249 EXAMPLES = """
250 - name: Create FlexCache
251 netapp.ontap.na_ontap_flexcache:
252 state: present
253 origin_volume: test_src
254 name: test_dest
255 origin_vserver: ansible_src
256 vserver: ansible_dest
257 hostname: "{{ netapp_hostname }}"
258 username: "{{ netapp_username }}"
259 password: "{{ netapp_password }}"
260
261 - name: Delete FlexCache
262 netapp.ontap.na_ontap_flexcache:
263 state: absent
264 name: test_dest
265 vserver: ansible_dest
266 hostname: "{{ netapp_hostname }}"
267 username: "{{ netapp_username }}"
268 password: "{{ netapp_password }}"
269 """
270
271 RETURN = """
272
273 """
274
275 import time
276 import traceback
277 from ansible.module_utils.basic import AnsibleModule
278 from ansible.module_utils._text import to_native
279 import ansible_collections.netapp.ontap.plugins.module_utils.netapp as netapp_utils
280 from ansible_collections.netapp.ontap.plugins.module_utils.netapp_module import NetAppModule
281 from ansible_collections.netapp.ontap.plugins.module_utils import rest_generic, rest_volume
282
283
284 class NetAppONTAPFlexCache:
285 """
286 Class with FlexCache methods
287 """
288
289 def __init__(self):
290
291 self.argument_spec = netapp_utils.na_ontap_host_argument_spec()
292 self.argument_spec.update(dict(
293 state=dict(required=False, type='str', choices=['present', 'absent'],
294 default='present'),
295 origin_volume=dict(required=False, type='str'), # origins[0]
296 origin_vserver=dict(required=False, type='str'), # origins[0]
297 origin_cluster=dict(required=False, type='str'), # origins[0]
298 auto_provision_as=dict(required=False, type='str'), # ignored with REST
299 name=dict(required=True, type='str', aliases=['volume']),
300 junction_path=dict(required=False, type='str', aliases=['path']),
301 size=dict(required=False, type='int'),
302 size_unit=dict(default='gb',
303 choices=['bytes', 'b', 'kb', 'mb', 'gb', 'tb',
304 'pb', 'eb', 'zb', 'yb'], type='str'),
305 vserver=dict(required=True, type='str'),
306 aggr_list=dict(required=False, type='list', elements='str', aliases=['aggregates']),
307 aggr_list_multiplier=dict(required=False, type='int', aliases=['constituents_per_aggregate']),
308 force_offline=dict(required=False, type='bool', default=False),
309 force_unmount=dict(required=False, type='bool', default=False),
310 time_out=dict(required=False, type='int', default=180),
311 prepopulate=dict(required=False, type='dict', options=dict(
312 dir_paths=dict(required=True, type='list', elements='str'),
313 exclude_dir_paths=dict(required=False, type='list', elements='str'),
314 recurse=dict(required=False, type='bool'),
315 force_prepopulate_if_already_created=dict(required=False, type='bool', default=True),
316 )),
317 writeback=dict(required=False, type='dict', options=dict(
318 enabled=dict(required=False, type='bool', default=False)
319 )),
320 relative_size=dict(required=False, type='dict', options=dict(
321 enabled=dict(required=False, type='bool'),
322 percentage=dict(required=False, type='int'),
323 )),
324 override_encryption=dict(required=False, type='bool'),
325 atime_scrub=dict(required=False, type='dict', options=dict(
326 enabled=dict(required=False, type='bool'),
327 period=dict(required=False, type='int'),
328 )),
329 cifs_change_notify_enabled=dict(required=False, type='bool'),
330 global_file_locking_enabled=dict(required=False, type='bool'),
331 guarantee_type=dict(required=False, type='str', choices=['volume', 'none']),
332 dr_cache=dict(required=False, type='bool')
333 ))
334 self.argument_spec.update(netapp_utils.na_ontap_lambda_argument_spec())
335
336 self.module = AnsibleModule(
337 argument_spec=self.argument_spec,
338 mutually_exclusive=[
339 ('aggr_list', 'auto_provision_as'),
340 ],
341 required_if=[
342 ('use_lambda', True, ['lambda_config']),
343 ],
344 supports_check_mode=True
345 )
346
347 self.na_helper = NetAppModule(self.module)
348 self.parameters = self.na_helper.set_parameters(self.module.params)
349 if self.parameters.get('size'):
350 self.parameters['size'] = self.parameters['size'] * netapp_utils.POW2_BYTE_MAP[self.parameters['size_unit']]
351 # setup later if required
352 self.origin_server = None
353
354 self.rest_api = netapp_utils.OntapRestAPI(self.module)
355 partially_supported_rest_properties = [['guarantee_type', (9, 7)], ['prepopulate', (9, 8)],
356 ['global_file_locking_enabled', (9, 9)], ['dr_cache', (9, 9)],
357 ['writeback', (9, 12)], ['relative_size', (9, 13, 1)],
358 ['override_encryption', (9, 14, 1)], ['atime_scrub', (9, 14, 1)],
359 ['cifs_change_notify_enabled', (9, 15, 1)]]
360 self.use_rest = self.rest_api.is_rest_supported_properties(self.parameters, None, partially_supported_rest_properties)
361 if not self.use_rest:
362 if self.parameters.get('use_lambda'):
363 self.module.fail_json(msg="Error: AWS Lambda proxy for ONTAP APIs is only supported with REST.")
364 if not netapp_utils.has_netapp_lib():
365 self.module.fail_json(msg=netapp_utils.netapp_lib_is_required())
366 self.server = netapp_utils.setup_na_ontap_zapi(module=self.module, vserver=self.parameters['vserver'])
367 else:
368 self.rest_errors()
369
370 def rest_errors(self):
371 if 'prepopulate' in self.parameters:
372 # sanitize the dictionary, as Ansible fills everything with None values
373 self.parameters['prepopulate'] = self.na_helper.filter_out_none_entries(self.parameters['prepopulate'])
374 ontap_99_options = ['exclude_dir_paths']
375 if not self.rest_api.meets_rest_minimum_version(self.use_rest, 9, 9) and any(x in self.parameters['prepopulate'] for x in ontap_99_options):
376 options = ['prepopulate: ' + x for x in ontap_99_options]
377 self.module.fail_json(msg='Error: %s' % self.rest_api.options_require_ontap_version(options, version='9.9'))
378
379 def add_parameter_to_dict(self, adict, name, key, tostr=False):
380 """
381 add defined parameter (not None) to a dict using key
382 """
383 value = self.parameters.get(name)
384 if value is not None:
385 adict[key] = str(value) if tostr else value
386
387 def get_job(self, jobid, server):
388 """
389 Get job details by id
390 """
391 job_get = netapp_utils.zapi.NaElement('job-get')
392 job_get.add_new_child('job-id', jobid)
393 try:
394 result = server.invoke_successfully(job_get, enable_tunneling=True)
395 except netapp_utils.zapi.NaApiError as error:
396 if to_native(error.code) == "15661":
397 # Not found
398 return None
399 self.module.fail_json(msg='Error fetching job info: %s' % to_native(error),
400 exception=traceback.format_exc())
401 job_info = result.get_child_by_name('attributes').get_child_by_name('job-info')
402 return {
403 'job-progress': job_info['job-progress'],
404 'job-state': job_info['job-state'],
405 'job-completion': job_info['job-completion'] if job_info.get_child_by_name('job-completion') is not None else None
406 }
407
408 def check_job_status(self, jobid):
409 """
410 Loop until job is complete
411 """
412 server = self.server
413 sleep_time = 5
414 time_out = self.parameters['time_out']
415 while time_out > 0:
416 results = self.get_job(jobid, server)
417 # If running as cluster admin, the job is owned by cluster vserver
418 # rather than the target vserver.
419 if results is None and server == self.server:
420 results = netapp_utils.get_cserver(self.server)
421 server = netapp_utils.setup_na_ontap_zapi(module=self.module, vserver=results)
422 continue
423 if results is None:
424 error = 'cannot locate job with id: %s' % jobid
425 break
426 if results['job-state'] in ('queued', 'running'):
427 time.sleep(sleep_time)
428 time_out -= sleep_time
429 continue
430 if results['job-state'] in ('success', 'failure'):
431 break
432 else:
433 self.module.fail_json(msg='Unexpected job status in: %s' % repr(results))
434
435 if results is not None:
436 if results['job-state'] == 'success':
437 error = None
438 elif results['job-state'] in ('queued', 'running'):
439 error = 'job completion exceeded expected timer of: %s seconds' % self.parameters['time_out']
440 elif results['job-completion'] is not None:
441 error = results['job-completion']
442 else:
443 error = results['job-progress']
444 return error
445
446 def flexcache_get_iter(self):
447 """
448 Compose NaElement object to query current FlexCache relation
449 """
450 options = {'volume': self.parameters['name']}
451 self.add_parameter_to_dict(options, 'origin_volume', 'origin-volume')
452 self.add_parameter_to_dict(options, 'origin_vserver', 'origin-vserver')
453 self.add_parameter_to_dict(options, 'origin_cluster', 'origin-cluster')
454 flexcache_info = netapp_utils.zapi.NaElement.create_node_with_children(
455 'flexcache-info', **options)
456 query = netapp_utils.zapi.NaElement('query')
457 query.add_child_elem(flexcache_info)
458 flexcache_get_iter = netapp_utils.zapi.NaElement('flexcache-get-iter')
459 flexcache_get_iter.add_child_elem(query)
460 return flexcache_get_iter
461
462 def flexcache_get(self):
463 """
464 Get current FlexCache relations
465 :return: Dictionary of current FlexCache details if query successful, else None
466 """
467 if self.use_rest:
468 api = 'storage/flexcache/flexcaches'
469 query = {
470 'name': self.parameters['name'],
471 'svm.name': self.parameters['vserver']
472 }
473 if 'origin_cluster' in self.parameters:
474 query['origins.cluster.name'] = self.parameters['origin_cluster']
475 fields = 'svm,name,uuid,path,'
476 if 'guarantee_type' in self.parameters:
477 fields += 'guarantee.type,'
478 if 'global_file_locking_enabled' in self.parameters:
479 fields += 'global_file_locking_enabled,'
480 if 'dr_cache' in self.parameters:
481 fields += 'dr_cache,'
482 if 'writeback' in self.parameters:
483 fields += 'writeback,'
484 if 'relative_size' in self.parameters:
485 fields += 'relative_size,'
486 if 'override_encryption' in self.parameters:
487 fields += 'override_encryption,'
488 if 'atime_scrub' in self.parameters:
489 fields += 'atime_scrub,'
490 if 'cifs_change_notify_enabled' in self.parameters:
491 fields += 'cifs_change_notify.enabled,'
492
493 flexcache, error = rest_generic.get_one_record(self.rest_api, api, query, fields)
494 self.na_helper.fail_on_error(error)
495 if flexcache is None:
496 return None
497 flexcache_info = dict(
498 vserver=flexcache['svm']['name'],
499 name=flexcache['name'],
500 uuid=flexcache['uuid'],
501 junction_path=flexcache.get('path'),
502 writeback=flexcache.get('writeback'),
503 relative_size=flexcache.get('relative_size'),
504 atime_scrub=flexcache.get('atime_scrub'),
505 cifs_change_notify_enabled=self.na_helper.safe_get(flexcache, ['cifs_change_notify', 'enabled'])
506 )
507 return flexcache_info
508
509 flexcache_get_iter = self.flexcache_get_iter()
510 flex_info = {}
511 try:
512 result = self.server.invoke_successfully(flexcache_get_iter, enable_tunneling=True)
513 except netapp_utils.zapi.NaApiError as error:
514 self.module.fail_json(msg='Error fetching FlexCache info: %s' % to_native(error),
515 exception=traceback.format_exc())
516 if result.get_child_by_name('num-records') and \
517 int(result.get_child_content('num-records')) == 1:
518 flexcache_info = result.get_child_by_name('attributes-list') \
519 .get_child_by_name('flexcache-info')
520 flex_info['origin_cluster'] = flexcache_info.get_child_content('origin-cluster')
521 flex_info['origin_volume'] = flexcache_info.get_child_content('origin-volume')
522 flex_info['origin_vserver'] = flexcache_info.get_child_content('origin-vserver')
523 flex_info['size'] = flexcache_info.get_child_content('size')
524 flex_info['name'] = flexcache_info.get_child_content('volume')
525 flex_info['vserver'] = flexcache_info.get_child_content('vserver')
526
527 return flex_info
528 if result.get_child_by_name('num-records') and \
529 int(result.get_child_content('num-records')) > 1:
530 msg = 'Multiple records found for %s:' % self.parameters['name']
531 self.module.fail_json(msg='Error fetching FlexCache info: %s' % msg)
532 return None
533
534 def flexcache_rest_create_body(self, mappings, params=None):
535 """
536 maps self.parameters to REST API body attributes, using mappings to identify fields to add
537 """
538 body = {}
539 params = self.parameters if params is None else params
540 for key, value in mappings.items():
541 if key in params:
542 if key == 'aggr_list':
543 body[value] = [dict(name=aggr) for aggr in params[key]]
544 else:
545 body[value] = params[key]
546 elif key == 'origins':
547 # this is an artificial key, to match the REST list of dict structure
548 origin = dict(
549 volume=dict(name=params['origin_volume']),
550 svm=dict(name=params['origin_vserver'])
551 )
552 body[value] = [origin]
553 return body
554
555 def flexcache_rest_create(self):
556 ''' use POST to create a FlexCache '''
557 mappings = dict(
558 name='name',
559 vserver='svm.name',
560 junction_path='path',
561 size='size',
562 aggr_list='aggregates',
563 aggr_list_multiplier='constituents_per_aggregate',
564 origins='origins',
565 prepopulate='prepopulate',
566 writeback='writeback',
567 guarantee_type='guarantee.type',
568 global_file_locking_enabled='global_file_locking_enabled',
569 dr_cache='dr_cache',
570 relative_size='relative_size',
571 override_encryption='override_encryption',
572 atime_scrub='atime_scrub',
573 cifs_change_notify_enabled='cifs_change_notify.enabled'
574 )
575 body = self.flexcache_rest_create_body(mappings)
576 api = 'storage/flexcache/flexcaches'
577 response, error = rest_generic.post_async(self.rest_api, api, body, job_timeout=self.parameters['time_out'])
578 self.na_helper.fail_on_error(error)
579 return response
580
581 def flexcache_rest_modify(self, uuid, modify):
582 """
583 use PATCH to start prepopulating a FlexCache or modify other properties
584 """
585 mappings = dict( # name cannot be set, though swagger example shows it
586 prepopulate='prepopulate',
587 writeback='writeback',
588 relative_size='relative_size',
589 atime_scrub='atime_scrub',
590 cifs_change_notify_enabled='cifs_change_notify.enabled'
591 )
592 body = self.flexcache_rest_create_body(mappings, modify)
593 api = 'storage/flexcache/flexcaches'
594 response, error = rest_generic.patch_async(self.rest_api, api, uuid, body, job_timeout=self.parameters['time_out'])
595 self.na_helper.fail_on_error(error)
596 return response
597
598 def flexcache_create_async(self):
599 """
600 Create a FlexCache relationship
601 """
602 options = {'origin-volume': self.parameters['origin_volume'],
603 'origin-vserver': self.parameters['origin_vserver'],
604 'volume': self.parameters['name']}
605 self.add_parameter_to_dict(options, 'junction_path', 'junction-path')
606 self.add_parameter_to_dict(options, 'auto_provision_as', 'auto-provision-as')
607 self.add_parameter_to_dict(options, 'size', 'size', tostr=True)
608 if self.parameters.get('aggr_list') and self.parameters.get('aggr_list_multiplier'):
609 self.add_parameter_to_dict(options, 'aggr_list_multiplier', 'aggr-list-multiplier', tostr=True)
610 flexcache_create = netapp_utils.zapi.NaElement.create_node_with_children('flexcache-create-async', **options)
611 if self.parameters.get('aggr_list'):
612 aggregates = netapp_utils.zapi.NaElement('aggr-list')
613 for aggregate in self.parameters['aggr_list']:
614 aggregates.add_new_child('aggr-name', aggregate)
615 flexcache_create.add_child_elem(aggregates)
616 try:
617 result = self.server.invoke_successfully(flexcache_create, enable_tunneling=True)
618 except netapp_utils.zapi.NaApiError as error:
619 self.module.fail_json(msg='Error creating FlexCache: %s' % to_native(error),
620 exception=traceback.format_exc())
621 results = {}
622 for key in ('result-status', 'result-jobid'):
623 if result.get_child_by_name(key):
624 results[key] = result[key]
625 return results
626
627 def flexcache_create(self):
628 """
629 Create a FlexCache relationship
630 Check job status
631 """
632 if self.use_rest:
633 return self.flexcache_rest_create()
634
635 results = self.flexcache_create_async()
636 status = results.get('result-status')
637 if status == 'in_progress' and 'result-jobid' in results:
638 if self.parameters['time_out'] == 0:
639 # asynchronous call, assuming success!
640 return
641 error = self.check_job_status(results['result-jobid'])
642 if error is None:
643 return
644 else:
645 self.module.fail_json(msg='Error when creating flexcache: %s' % error)
646 self.module.fail_json(msg='Unexpected error when creating flexcache: results is: %s' % repr(results))
647
648 def flexcache_delete_async(self):
649 """
650 Delete FlexCache relationship at destination cluster
651 """
652 options = {'volume': self.parameters['name']}
653 flexcache_delete = netapp_utils.zapi.NaElement.create_node_with_children('flexcache-destroy-async', **options)
654 try:
655 result = self.server.invoke_successfully(flexcache_delete, enable_tunneling=True)
656 except netapp_utils.zapi.NaApiError as error:
657 self.module.fail_json(msg='Error deleting FlexCache: %s' % (to_native(error)),
658 exception=traceback.format_exc())
659 results = {}
660 for key in ('result-status', 'result-jobid'):
661 if result.get_child_by_name(key):
662 results[key] = result[key]
663 return results
664
665 def rest_offline_volume(self, current):
666 """
667 Make the volume offline using REST PATCH method.
668 """
669 uuid = current.get('uuid')
670 if uuid is None:
671 error = 'Error, no uuid in current: %s' % str(current)
672 self.na_helper.fail_on_error(error)
673 body = dict(state='offline')
674 return self.patch_volume_rest(uuid, body)
675
676 def volume_offline(self, current):
677 """
678 Make the FlexCache volume offline at destination cluster
679 """
680 if self.use_rest:
681 self.rest_offline_volume(current)
682 else:
683 options = {'name': self.parameters['name']}
684 xml = netapp_utils.zapi.NaElement.create_node_with_children(
685 'volume-offline', **options)
686 try:
687 self.server.invoke_successfully(xml, enable_tunneling=True)
688 except netapp_utils.zapi.NaApiError as error:
689 self.module.fail_json(msg='Error offlining FlexCache volume: %s'
690 % (to_native(error)),
691 exception=traceback.format_exc())
692
693 def rest_mount_volume(self, current, path):
694 """
695 Mount the volume using REST PATCH method.
696 If path is empty string, unmount the volume.
697 """
698 uuid = current.get('uuid')
699 if uuid is None:
700 error = 'Error, no uuid in current: %s' % str(current)
701 self.na_helper.fail_on_error(error)
702 body = dict(nas=dict(path=path))
703 return self.patch_volume_rest(uuid, body)
704
705 def rest_unmount_volume(self, current):
706 """
707 Unmount the volume using REST PATCH method.
708 """
709 self.rest_mount_volume(current, '') if current.get('junction_path') else None
710
711 def volume_unmount(self, current):
712 """
713 Unmount FlexCache volume at destination cluster
714 """
715 if self.use_rest:
716 self.rest_unmount_volume(current)
717 else:
718 options = {'volume-name': self.parameters['name']}
719 xml = netapp_utils.zapi.NaElement.create_node_with_children(
720 'volume-unmount', **options)
721 try:
722 self.server.invoke_successfully(xml, enable_tunneling=True)
723 except netapp_utils.zapi.NaApiError as error:
724 self.module.fail_json(msg='Error unmounting FlexCache volume: %s'
725 % (to_native(error)),
726 exception=traceback.format_exc())
727
728 def patch_volume_rest(self, uuid, body):
729 response, error = rest_volume.patch_volume(self.rest_api, uuid, body)
730 self.na_helper.fail_on_error(error)
731 return response
732
733 def flexcache_rest_delete(self, current):
734 """
735 Delete the flexcache using REST DELETE method.
736 """
737 response = None
738 uuid = current.get('uuid')
739 if uuid is None:
740 error = 'Error, no uuid in current: %s' % str(current)
741 self.na_helper.fail_on_error(error)
742 api = 'storage/flexcache/flexcaches'
743 # There may be a bug in ONTAP. If return_timeout is >= 15, the call fails with uuid not found!
744 # With 5, a job is queued, and completes with success. With a big enough value, no job is
745 # queued, and the API returns in around 15 seconds with a not found error.
746 rto = netapp_utils.get_feature(self.module, 'flexcache_delete_return_timeout')
747 response, error = rest_generic.delete_async(self.rest_api, api, uuid, timeout=rto, job_timeout=self.parameters['time_out'])
748 self.na_helper.fail_on_error(error)
749 return response
750
751 def flexcache_delete(self, current):
752 """
753 Delete FlexCache relationship at destination cluster
754 Check job status
755 """
756 self.module.warn('Cache volume can not be deleted in ZAPI. '
757 'Flexcache relationship was ended.')
758 if self.parameters['force_unmount']:
759 self.volume_unmount(current)
760 if self.parameters['force_offline']:
761 self.volume_offline(current)
762 if self.use_rest:
763 return self.flexcache_rest_delete(current)
764 results = self.flexcache_delete_async()
765 status = results.get('result-status')
766 if status == 'in_progress' and 'result-jobid' in results:
767 if self.parameters['time_out'] == 0:
768 # asynchronous call, assuming success!
769 return None
770 error = self.check_job_status(results['result-jobid'])
771 if error is not None:
772 self.module.fail_json(msg='Error when deleting flexcache: %s' % error)
773 return None
774 self.module.fail_json(msg='Unexpected error when deleting flexcache: results is: %s' % repr(results))
775
776 def check_parameters(self, cd_action):
777 """
778 Validate parameters and fail if one or more required params are missing
779 """
780 if cd_action != 'create':
781 return
782 if self.parameters['state'] == 'present':
783 expected = 'origin_volume', 'origin_vserver'
784 missings = [param for param in expected if not self.parameters.get(param)]
785 if missings:
786 plural = 's' if len(missings) > 1 else ''
787 msg = 'Missing parameter%s: %s' % (plural, ', '.join(missings))
788 self.module.fail_json(msg=msg)
789
790 def apply(self):
791 """
792 Apply action to FlexCache
793 """
794 current = self.flexcache_get()
795 cd_action = self.na_helper.get_cd_action(current, self.parameters)
796 modify, mount_unmount = None, None
797 prepopulate_if_already_created = None
798
799 if self.parameters['state'] == 'present' and 'prepopulate' in self.parameters:
800 prepopulate_if_already_created = self.parameters['prepopulate'].pop('force_prepopulate_if_already_created')
801
802 if cd_action is None:
803 modify = self.na_helper.get_modified_attributes(current, self.parameters)
804 if modify:
805 if self.use_rest:
806 modify.pop('name', None)
807 if not modify:
808 # ignore modify operation if the only key to modify is 'name'
809 self.na_helper.changed = False
810 mount_unmount = modify.pop('junction_path', None)
811 else:
812 self.module.fail_json(msg='FlexCache properties cannot be modified by this module when using ZAPI. modify: %s' % str(modify))
813 if current and prepopulate_if_already_created:
814 # force a prepopulate action
815 modify.update(dict(prepopulate=self.parameters['prepopulate']))
816 self.na_helper.changed = True
817 self.module.warn('na_ontap_flexcache is not idempotent when prepopulate is present and force_prepopulate_if_already_created=true')
818 if mount_unmount == '' or current['junction_path'] == '':
819 self.module.warn('prepopulate requires the FlexCache volume to be mounted')
820 self.check_parameters(cd_action)
821 response = None
822 if self.na_helper.changed and not self.module.check_mode:
823 if cd_action == 'create':
824 response = self.flexcache_create()
825 elif cd_action == 'delete':
826 response = self.flexcache_delete(current)
827 else:
828 if mount_unmount is not None:
829 # mount first, as this is required for prepopulate to succeed (or fail for unmount)
830 self.rest_mount_volume(current, mount_unmount)
831 if modify:
832 response = self.flexcache_rest_modify(current['uuid'], modify)
833 result = netapp_utils.generate_result(self.na_helper.changed, cd_action, modify, response)
834 self.module.exit_json(**result)
835
836
837 def main():
838 """Execute action"""
839 my_obj = NetAppONTAPFlexCache()
840 my_obj.apply()
841
842
843 if __name__ == '__main__':
844 main()