Debian Codegraph @

ansible_collections/netapp/ontap/plugins/modules/na_ontap_volume_clone.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 from __future__ import absolute_import, division, print_function
6
7 __metaclass__ = type
8
9 DOCUMENTATION = '''
10 module: na_ontap_volume_clone
11 short_description: NetApp ONTAP manage volume clones.
12 extends_documentation_fragment:
13 - netapp.ontap.netapp.na_ontap
14 version_added: 2.6.0
15 author: NetApp Ansible Team (@carchi8py) <[email protected]>
16 description:
17 - Create NetApp ONTAP volume clones.
18 - A FlexClone License is required to use this module
19 options:
20 state:
21 description:
22 - Whether volume clone should be created.
23 choices: ['present']
24 type: str
25 default: 'present'
26 parent_volume:
27 description:
28 - The parent volume of the volume clone being created.
29 required: true
30 type: str
31 name:
32 description:
33 - The name of the volume clone being created.
34 required: true
35 type: str
36 aliases:
37 - volume
38 vserver:
39 description:
40 - Vserver in which the volume clone should be created.
41 required: true
42 type: str
43 parent_snapshot:
44 description:
45 - Parent snapshot in which volume clone is created off.
46 type: str
47 parent_vserver:
48 description:
49 - Vserver of parent volume in which clone is created off.
50 type: str
51 qos_policy_group_name:
52 description:
53 - The qos-policy-group-name which should be set for volume clone.
54 type: str
55 space_reserve:
56 description:
57 - The space_reserve setting which should be used for the volume clone.
58 choices: ['volume', 'none']
59 type: str
60 volume_type:
61 description:
62 - The volume-type setting which should be used for the volume clone.
63 choices: ['rw', 'dp']
64 type: str
65 junction_path:
66 version_added: 2.8.0
67 description:
68 - Junction path of the volume.
69 type: str
70 uid:
71 version_added: 2.9.0
72 description:
73 - The UNIX user ID for the clone volume.
74 type: int
75 gid:
76 version_added: 2.9.0
77 description:
78 - The UNIX group ID for the clone volume.
79 type: int
80 split:
81 version_added: '20.2.0'
82 description:
83 - Split clone volume from parent volume.
84 type: bool
85 time_out:
86 version_added: 23.2.0
87 description:
88 - With C(wait_for_completion) set, specifies time to wait for clone/split operation in seconds.
89 - Only supported with REST.
90 type: int
91 default: 180
92
93 wait_for_completion:
94 version_added: 23.2.0
95 description:
96 - Set this parameter to 'true' for synchronous execution.
97 - For asynchronous, execution exits as soon as the request is sent, and the operation continues in the background.
98 - Only supported with REST.
99 type: bool
100 default: true
101
102 lambda_config:
103 description:
104 - Configuration parameters for AWS Lambda proxy functionality.
105 - These option and suboptions are only supported with REST.
106 type: dict
107 version_added: 23.4.0
108 suboptions:
109 function_name:
110 description:
111 - The name of the AWS Lambda function to invoke.
112 type: str
113 required: true
114 aws_region:
115 description:
116 - The name of the AWS region.
117 type: str
118 required: true
119 aws_profile:
120 description:
121 - The name of the AWS profile to use for authentication.
122 type: str
123
124 notes:
125 - Supports AWS Lambda proxy functionality when using REST. See the README file for examples.
126 '''
127
128 EXAMPLES = """
129 - name: Create volume clone - ZAPI
130 netapp.ontap.na_ontap_volume_clone:
131 state: present
132 vserver: ansibleSVM
133 parent_volume: source_volume
134 name: cloned_volume
135 space_reserve: none
136 parent_snapshot: backup1
137 junction_path: /cloned_volume
138 uid: 1
139 gid: 1
140 hostname: "{{ netapp_hostname }}"
141 username: "{{ netapp_username }}"
142 password: "{{ netapp_password }}"
143 https: true
144 validate_certs: "{{ validate_certs }}"
145 use_rest: never
146
147 - name: Split an existing volume clone - REST
148 netapp.ontap.na_ontap_volume_clone:
149 state: present
150 vserver: ansibleSVM
151 parent_volume: source_volume
152 name: cloned_volume
153 split: true
154 wait_for_completion: true
155 time_out: 90
156 hostname: "{{ netapp_hostname }}"
157 username: "{{ netapp_username }}"
158 password: "{{ netapp_password }}"
159 https: true
160 validate_certs: "{{ validate_certs }}"
161 use_rest: always
162 """
163
164 RETURN = """
165 """
166
167 from ansible.module_utils.basic import AnsibleModule
168 from ansible.module_utils._text import to_native
169 import ansible_collections.netapp.ontap.plugins.module_utils.netapp as netapp_utils
170 from ansible_collections.netapp.ontap.plugins.module_utils.netapp_module import NetAppModule
171 from ansible_collections.netapp.ontap.plugins.module_utils.netapp import OntapRestAPI
172 from ansible_collections.netapp.ontap.plugins.module_utils import rest_generic
173
174
175 class NetAppONTAPVolumeClone:
176 """
177 Creates a volume clone
178 """
179
180 def __init__(self):
181 """
182 Initialize the NetAppOntapVolumeClone class
183 """
184 self.argument_spec = netapp_utils.na_ontap_host_argument_spec()
185 self.argument_spec.update(dict(
186 state=dict(required=False, type='str', choices=['present'], default='present'),
187 parent_volume=dict(required=True, type='str'),
188 name=dict(required=True, type='str', aliases=["volume"]),
189 vserver=dict(required=True, type='str'),
190 parent_snapshot=dict(required=False, type='str', default=None),
191 parent_vserver=dict(required=False, type='str', default=None),
192 qos_policy_group_name=dict(required=False, type='str', default=None),
193 space_reserve=dict(required=False, type='str', choices=['volume', 'none'], default=None),
194 volume_type=dict(required=False, type='str', choices=['rw', 'dp']),
195 junction_path=dict(required=False, type='str', default=None),
196 uid=dict(required=False, type='int'),
197 gid=dict(required=False, type='int'),
198 split=dict(required=False, type='bool', default=None),
199 time_out=dict(required=False, type='int', default=180),
200 wait_for_completion=dict(required=False, type='bool', default=True),
201 ))
202
203 self.argument_spec.update(netapp_utils.na_ontap_lambda_argument_spec())
204
205 self.module = AnsibleModule(
206 argument_spec=self.argument_spec,
207 supports_check_mode=True,
208 required_together=[
209 ['uid', 'gid']
210 ],
211 mutually_exclusive=[
212 ('junction_path', 'parent_vserver'),
213 ('uid', 'parent_vserver'),
214 ('gid', 'parent_vserver')
215 ],
216 required_if=[['use_lambda', True, ('lambda_config',)]],
217 )
218
219 self.uuid = None # UUID if the FlexClone if it exists, or after creation
220 self.na_helper = NetAppModule()
221 self.parameters = self.na_helper.set_parameters(self.module.params)
222 self.rest_api = OntapRestAPI(self.module)
223 unsupported_rest_properties = ['space_reserve']
224 self.use_rest = self.rest_api.is_rest_supported_properties(self.parameters, unsupported_rest_properties)
225 if not self.use_rest:
226 if self.parameters.get('use_lambda'):
227 self.module.fail_json(msg="Error: AWS Lambda proxy for ONTAP APIs is only supported with REST.")
228 if not netapp_utils.has_netapp_lib():
229 self.module.fail_json(msg=netapp_utils.netapp_lib_is_required())
230 if self.parameters.get('parent_vserver'):
231 # use cluster ZAPI, as vserver ZAPI does not support parent-vserser for create
232 self.create_server = netapp_utils.setup_na_ontap_zapi(module=self.module)
233 # keep vserver for ems log and clone-get
234 self.vserver = netapp_utils.setup_na_ontap_zapi(module=self.module, vserver=self.parameters['vserver'])
235 else:
236 self.vserver = netapp_utils.setup_na_ontap_zapi(module=self.module, vserver=self.parameters['vserver'])
237 self.create_server = self.vserver
238 if 'wait_for_completion' in self.parameters or 'time_out' in self.parameters:
239 self.module.warn("'wait_for_completion' and 'time_out' parameters are only supported when using REST.")
240
241 def create_volume_clone(self):
242 """
243 Creates a new volume clone
244 """
245 if self.use_rest:
246 return self.create_volume_clone_rest()
247 clone_obj = netapp_utils.zapi.NaElement('volume-clone-create')
248 clone_obj.add_new_child("parent-volume", self.parameters['parent_volume'])
249 clone_obj.add_new_child("volume", self.parameters['name'])
250 if self.parameters.get('qos_policy_group_name'):
251 clone_obj.add_new_child("qos-policy-group-name", self.parameters['qos_policy_group_name'])
252 if self.parameters.get('space_reserve'):
253 clone_obj.add_new_child("space-reserve", self.parameters['space_reserve'])
254 if self.parameters.get('parent_snapshot'):
255 clone_obj.add_new_child("parent-snapshot", self.parameters['parent_snapshot'])
256 if self.parameters.get('parent_vserver'):
257 clone_obj.add_new_child("parent-vserver", self.parameters['parent_vserver'])
258 clone_obj.add_new_child("vserver", self.parameters['vserver'])
259 if self.parameters.get('volume_type'):
260 clone_obj.add_new_child("volume-type", self.parameters['volume_type'])
261 if self.parameters.get('junction_path'):
262 clone_obj.add_new_child("junction-path", self.parameters['junction_path'])
263 if self.parameters.get('uid'):
264 clone_obj.add_new_child("uid", str(self.parameters['uid']))
265 clone_obj.add_new_child("gid", str(self.parameters['gid']))
266 try:
267 self.create_server.invoke_successfully(clone_obj, True)
268 except netapp_utils.zapi.NaApiError as exc:
269 self.module.fail_json(msg='Error creating volume clone: %s: %s' % (self.parameters['name'], to_native(exc)))
270
271 def modify_volume_clone(self):
272 """
273 Modify an existing volume clone
274 """
275 if 'split' in self.parameters and self.parameters['split']:
276 self.start_volume_clone_split()
277
278 def start_volume_clone_split(self):
279 """
280 Starts a volume clone split
281 """
282 if self.use_rest:
283 return self.start_volume_clone_split_rest()
284 clone_obj = netapp_utils.zapi.NaElement('volume-clone-split-start')
285 clone_obj.add_new_child("volume", self.parameters['name'])
286 try:
287 self.vserver.invoke_successfully(clone_obj, True)
288 except netapp_utils.zapi.NaApiError as exc:
289 self.module.fail_json(msg='Error starting volume clone split: %s: %s' % (self.parameters['name'], to_native(exc)))
290
291 def get_volume_clone(self):
292 if self.use_rest:
293 return self.get_volume_clone_rest()
294 clone_obj = netapp_utils.zapi.NaElement('volume-clone-get')
295 clone_obj.add_new_child("volume", self.parameters['name'])
296 try:
297 results = self.vserver.invoke_successfully(clone_obj, True)
298 except netapp_utils.zapi.NaApiError as error:
299 # Error 15661 denotes a volume clone not being found.
300 if to_native(error.code) == "15661":
301 return None
302 self.module.fail_json(msg='Error fetching volume clone information %s: %s' % (self.parameters['name'], to_native(error)))
303 current = None
304 if results.get_child_by_name('attributes'):
305 attributes = results.get_child_by_name('attributes')
306 info = attributes.get_child_by_name('volume-clone-info')
307 # Check if clone is currently splitting. Whilst a split is in
308 # progress, these attributes are present in 'volume-clone-info':
309 # block-percentage-complete, blocks-scanned & blocks-updated.
310 current = {
311 'split': bool(
312 info.get_child_by_name('block-percentage-complete')
313 or info.get_child_by_name('blocks-scanned')
314 or info.get_child_by_name('blocks-updated')
315 )
316 }
317 return current
318
319 def get_volume_clone_rest(self):
320 api = 'storage/volumes'
321 params = {'name': self.parameters['name'],
322 'svm.name': self.parameters['vserver'],
323 'fields': 'clone.is_flexclone,uuid'}
324 record, error = rest_generic.get_one_record(self.rest_api, api, params)
325 if error:
326 self.module.fail_json(msg='Error getting volume clone %s: %s' % (self.parameters['name'], to_native(error)))
327 if record:
328 return self.format_get_volume_clone_rest(record)
329 return record
330
331 def format_get_volume_clone_rest(self, record):
332 return {
333 'name': record.get('name', None),
334 'uuid': record.get('uuid', None),
335 'is_clone': self.na_helper.safe_get(record, ['clone', 'is_flexclone']),
336 # if it is a FlexClone, it is not split.
337 # if it is not a FlexClone, it can be either the result of a split, or a plain volume. We mark it as split,
338 # as it cannot be split again.
339 'split': self.na_helper.safe_get(record, ['clone', 'is_flexclone']) is not True
340 }
341
342 def create_volume_clone_rest(self):
343 api = 'storage/volumes'
344 query = {'return_records': 'true'} # in order to capture UUID
345 if not self.parameters.get('wait_for_completion'):
346 query['return_timeout'] = 0
347 timeout = 0 if not self.parameters.get('wait_for_completion') else self.parameters['time_out']
348 body = {'name': self.parameters['name'],
349 'clone.parent_volume.name': self.parameters['parent_volume'],
350 "clone.is_flexclone": True,
351 "svm.name": self.parameters['vserver']}
352 if self.parameters.get('qos_policy_group_name'):
353 body['qos.policy.name'] = self.parameters['qos_policy_group_name']
354 if self.parameters.get('parent_snapshot'):
355 body['clone.parent_snapshot.name'] = self.parameters['parent_snapshot']
356 if self.parameters.get('parent_vserver'):
357 body['clone.parent_svm.name'] = self.parameters['parent_vserver']
358 if self.parameters.get('volume_type'):
359 body['type'] = self.parameters['volume_type']
360 if self.parameters.get('junction_path'):
361 body['nas.path'] = self.parameters['junction_path']
362 if self.parameters.get('uid'):
363 body['nas.uid'] = self.parameters['uid']
364 if self.parameters.get('gid'):
365 body['nas.gid'] = self.parameters['gid']
366
367 response, error = rest_generic.post_async(self.rest_api, api, body, query, job_timeout=timeout)
368 if error:
369 if 'job reported error:' in error and 'Timeout error: Process still running' in error:
370 if not self.parameters.get('wait_for_completion'):
371 warning = "Volume cloning process is still running in the background, "\
372 "exiting with no further waiting as 'wait_for_completion' is set to false."
373 else:
374 warning = ('Volume cloning is still in progress after %d seconds.' % self.parameters['time_out'])
375 self.module.warn(warning)
376 else:
377 self.module.fail_json(msg='Error creating volume clone %s: %s' % (self.parameters['name'],
378 to_native(error)))
379 if response:
380 if 'records' in response and response.get('records') != []:
381 self.uuid = response['records'][0].get('uuid', None)
382 return
383 if self.uuid is None:
384 error = 'UUID key not present in response: %s' % response.get('records', [])
385 else:
386 self.module.fail_json(msg='Error: failed to parse create clone response: %s' % to_native(response))
387
388 def start_volume_clone_split_rest(self):
389 if self.uuid is None:
390 self.module.fail_json(msg='Error starting volume clone split %s: %s' % (self.parameters['name'],
391 'clone UUID is not set'))
392 api = 'storage/volumes'
393 query = {'return_timeout': 0} if not self.parameters.get('wait_for_completion') else None
394 timeout = 0 if not self.parameters.get('wait_for_completion') else self.parameters['time_out']
395 body = {'clone.split_initiated': True}
396 dummy, error = rest_generic.patch_async(self.rest_api, api, self.uuid, body, query, job_timeout=timeout)
397 if error:
398 if "entry doesn't exist" in error:
399 msg = "Volume clone not found; "\
400 "it is advisable to use 'wait_for_completion' to ensure clone creation is complete before splitting."
401 self.module.fail_json(msg=msg)
402 elif 'job reported error:' in error and 'Timeout error: Process still running' in error:
403 if not self.parameters.get('wait_for_completion'):
404 warning = "Volume clone splitting is still running in the background, "\
405 "exiting with no further waiting as 'wait_for_completion' is set to false."
406 else:
407 warning = ('Volume clone split is still in progress after %d seconds.' % self.parameters['time_out'])
408 self.module.warn(warning)
409 else:
410 self.module.fail_json(msg='Error starting volume clone split %s: %s' % (self.parameters['name'],
411 to_native(error)))
412
413 def apply(self):
414 """
415 Run Module based on playbook
416 """
417 current = self.get_volume_clone()
418 if self.use_rest and current:
419 self.uuid = current['uuid']
420 if self.use_rest and current and not current['is_clone'] and not self.parameters.get('split'):
421 self.module.fail_json(
422 msg="Error: a volume %s which is not a FlexClone already exists, and split not requested." % self.parameters['name'])
423 modify = None
424 cd_action = self.na_helper.get_cd_action(current, self.parameters)
425 if cd_action is None and self.parameters['state'] == 'present':
426 # the only thing that is supported is split
427 current_split = {'split': current.get('split')} if current else None
428 modify = self.na_helper.get_modified_attributes(current_split, self.parameters)
429 if self.na_helper.changed and not self.module.check_mode:
430 if cd_action == 'create':
431 self.create_volume_clone()
432 if self.parameters.get('split'):
433 self.modify_volume_clone()
434 if modify:
435 self.modify_volume_clone()
436 result = netapp_utils.generate_result(self.na_helper.changed, cd_action, modify)
437 self.module.exit_json(**result)
438
439
440 def main():
441 """
442 Creates the NetApp Ontap Volume Clone object and runs the correct play task
443 """
444 obj = NetAppONTAPVolumeClone()
445 obj.apply()
446
447
448 if __name__ == '__main__':
449 main()