Debian Codegraph @

ansible_collections/netapp/ontap/plugins/modules/na_ontap_qtree.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_qtree
8 '''
9
10 from __future__ import absolute_import, division, print_function
11
12 __metaclass__ = type
13
14 DOCUMENTATION = '''
15
16 module: na_ontap_qtree
17
18 short_description: NetApp ONTAP manage qtrees
19 extends_documentation_fragment:
20 - netapp.ontap.netapp.na_ontap
21 version_added: 2.6.0
22 author: NetApp Ansible Team (@carchi8py) <[email protected]>
23
24 description:
25 - Create/Modify/Delete Qtrees.
26
27 options:
28
29 state:
30 description:
31 - Whether the specified qtree should exist or not.
32 choices: ['present', 'absent']
33 type: str
34 default: 'present'
35
36 name:
37 description:
38 - The name of the qtree to manage.
39 - With REST, this can also be a path.
40 required: true
41 type: str
42
43 from_name:
44 description:
45 - Name of the qtree to be renamed.
46 version_added: 2.7.0
47 type: str
48
49 flexvol_name:
50 description:
51 - The name of the FlexVol the qtree should exist on.
52 required: true
53 type: str
54 aliases: ['volume_name']
55
56 vserver:
57 description:
58 - The name of the vserver to use.
59 required: true
60 type: str
61
62 export_policy:
63 description:
64 - The name of the export policy to apply.
65 version_added: 2.9.0
66 type: str
67
68 security_style:
69 description:
70 - The security style for the qtree.
71 choices: ['unix', 'ntfs', 'mixed']
72 type: str
73 version_added: 2.9.0
74
75 oplocks:
76 description:
77 - Whether the oplocks should be enabled or not for the qtree.
78 choices: ['enabled', 'disabled']
79 type: str
80 version_added: 2.9.0
81
82 unix_permissions:
83 description:
84 - File permissions bits of the qtree.
85 - Accepts either octal or string format.
86 - Examples 0777, 777 in octal and ---rwxrwxrwx, sstrwxrwxrwx, rwxrwxrwx in string format.
87 - Optional parameter. Only relevant for Unix and mixed security styles.
88 - Ignored when security_style is set to 'ntfs'.
89 version_added: 2.9.0
90 type: str
91
92 force_delete:
93 description:
94 - Whether the qtree should be deleted even if files still exist.
95 - Note that the default of true reflect the REST API behavior.
96 - a value of false is not supported with REST.
97 type: bool
98 default: true
99 version_added: 20.8.0
100
101 wait_for_completion:
102 description:
103 - Only applicable for REST. When using ZAPI, the deletion is always synchronous.
104 - Deleting a qtree may take time if many files need to be deleted.
105 - Set this parameter to 'true' for synchronous execution during delete.
106 - Set this parameter to 'false' for asynchronous execution.
107 - For asynchronous, execution exits as soon as the request is sent, and the qtree is deleted in background.
108 type: bool
109 default: true
110 version_added: 2.9.0
111
112 time_out:
113 description:
114 - Maximum time to wait for qtree deletion in seconds when wait_for_completion is True.
115 - Error out if task is not completed in defined time.
116 - Default is set to 3 minutes.
117 default: 180
118 type: int
119 version_added: 2.9.0
120
121 unix_user:
122 description:
123 - The user set as owner of the qtree.
124 - Optional parameter. Only relevant for Unix and mixed security styles.
125 - Ignored when security_style is set to 'ntfs'.
126 - Only supported with REST and ONTAP 9.9 or later.
127 type: str
128 version_added: 21.21.0
129
130 unix_group:
131 description:
132 - The group set as owner of the qtree.
133 - Optional parameter. Only relevant for Unix and mixed security styles.
134 - Ignored when security_style is set to 'ntfs'.
135 - Only supported with REST and ONTAP 9.9 or later.
136 type: str
137 version_added: 21.21.0
138
139 lambda_config:
140 description:
141 - Configuration parameters for AWS Lambda proxy functionality.
142 - These option and suboptions are only supported with REST.
143 type: dict
144 version_added: 23.5.0
145 suboptions:
146 function_name:
147 description:
148 - The name of the AWS Lambda function to invoke.
149 type: str
150 required: true
151 aws_region:
152 description:
153 - The name of the AWS region.
154 type: str
155 required: true
156 aws_profile:
157 description:
158 - The name of the AWS profile to use for authentication.
159 type: str
160
161 notes:
162 - Supports AWS Lambda proxy functionality when using REST. See the README file for examples.
163 '''
164
165 EXAMPLES = """
166 - name: Create Qtrees.
167 netapp.ontap.na_ontap_qtree:
168 state: present
169 name: ansibleQTree
170 flexvol_name: ansibleVolume
171 export_policy: policyName
172 security_style: mixed
173 oplocks: disabled
174 unix_permissions: 777
175 vserver: ansibleVServer
176 unix_user: user1
177 unix_group: group1
178 hostname: "{{ netapp_hostname }}"
179 username: "{{ netapp_username }}"
180 password: "{{ netapp_password }}"
181
182 - name: Rename Qtrees.
183 netapp.ontap.na_ontap_qtree:
184 state: present
185 from_name: ansibleQTree
186 name: ansibleQTree_rename
187 volume_name: ansibleVolume
188 vserver: ansibleVServer
189 hostname: "{{ netapp_hostname }}"
190 username: "{{ netapp_username }}"
191 password: "{{ netapp_password }}"
192
193 - name: modify Qtrees unix_permissions using string format.
194 netapp.ontap.na_ontap_qtree:
195 state: present
196 name: ansibleQTree_rename
197 flexvol_name: ansibleVolume
198 vserver: ansibleVServer
199 unix_permissions: sstrwxrwxrwx
200 hostname: "{{ netapp_hostname }}"
201 username: "{{ netapp_username }}"
202 password: "{{ netapp_password }}"
203
204 - name: Create Qtree with NTFS security style.
205 netapp.ontap.na_ontap_qtree:
206 state: present
207 name: ntfsQTree
208 flexvol_name: ansibleVolume
209 security_style: ntfs
210 vserver: ansibleVServer
211 hostname: "{{ netapp_hostname }}"
212 username: "{{ netapp_username }}"
213 password: "{{ netapp_password }}"
214 # Note: unix_user, unix_group, and unix_permissions are not needed for NTFS security style
215
216 - name: delete Qtrees.
217 netapp.ontap.na_ontap_qtree:
218 state: absent
219 name: ansibleQTree_rename
220 vserver: ansibleVServer
221 hostname: "{{ netapp_hostname }}"
222 username: "{{ netapp_username }}"
223 password: "{{ netapp_password }}"
224 """
225
226 RETURN = """
227
228 """
229 import traceback
230 from ansible.module_utils.basic import AnsibleModule
231 from ansible.module_utils._text import to_native
232 import ansible_collections.netapp.ontap.plugins.module_utils.netapp as netapp_utils
233 from ansible_collections.netapp.ontap.plugins.module_utils.netapp_module import NetAppModule
234 from ansible_collections.netapp.ontap.plugins.module_utils.netapp import OntapRestAPI
235 import ansible_collections.netapp.ontap.plugins.module_utils.rest_response_helpers as rrh
236 from ansible_collections.netapp.ontap.plugins.module_utils import rest_generic
237
238
239 class NetAppOntapQTree:
240 '''Class with qtree operations'''
241
242 def __init__(self):
243 self.use_rest = False
244 self.argument_spec = netapp_utils.na_ontap_host_argument_spec()
245 self.argument_spec.update(dict(
246 state=dict(required=False, type='str', choices=['present', 'absent'], default='present'),
247 name=dict(required=True, type='str'),
248 from_name=dict(required=False, type='str'),
249 flexvol_name=dict(required=True, type='str', aliases=['volume_name']),
250 vserver=dict(required=True, type='str'),
251 export_policy=dict(required=False, type='str'),
252 security_style=dict(required=False, type='str', choices=['unix', 'ntfs', 'mixed']),
253 oplocks=dict(required=False, type='str', choices=['enabled', 'disabled']),
254 unix_permissions=dict(required=False, type='str'),
255 force_delete=dict(required=False, type='bool', default=True),
256 wait_for_completion=dict(required=False, type='bool', default=True),
257 time_out=dict(required=False, type='int', default=180),
258 unix_user=dict(required=False, type='str'),
259 unix_group=dict(required=False, type='str')
260 ))
261 self.argument_spec.update(netapp_utils.na_ontap_lambda_argument_spec())
262 self.volume_uuid, self.qid = None, None
263 self.module = AnsibleModule(
264 argument_spec=self.argument_spec,
265 required_if=[
266 ('state', 'present', ['flexvol_name']),
267 ('use_lambda', True, ['lambda_config']),
268 ],
269 supports_check_mode=True
270 )
271 self.na_helper = NetAppModule()
272 self.parameters = self.na_helper.set_parameters(self.module.params)
273
274 self.rest_api = OntapRestAPI(self.module)
275 unsupported_rest_properties = ['oplocks']
276 partially_supported_rest_properties = [['unix_user', (9, 9)], ['unix_group', (9, 9)]]
277 self.use_rest = self.rest_api.is_rest_supported_properties(self.parameters, unsupported_rest_properties, partially_supported_rest_properties)
278 if not self.use_rest:
279 if self.parameters.get('use_lambda'):
280 self.module.fail_json(msg="Error: AWS Lambda proxy for ONTAP APIs is only supported with REST.")
281 if not netapp_utils.has_netapp_lib():
282 self.module.fail_json(msg=netapp_utils.netapp_lib_is_required())
283 self.server = netapp_utils.setup_na_ontap_zapi(module=self.module, vserver=self.parameters['vserver'])
284
285 def get_qtree(self, name=None):
286 """
287 Checks if the qtree exists.
288 :param:
289 name : qtree name
290 :return:
291 Details about the qtree
292 False if qtree is not found
293 :rtype: bool
294 """
295 if name is None:
296 name = self.parameters['name']
297 if self.use_rest:
298 api = "storage/qtrees"
299 query = {'fields': 'export_policy,unix_permissions,security_style,volume',
300 'svm.name': self.parameters['vserver'],
301 'volume': self.parameters['flexvol_name'],
302 'name': '"' + name + '"'}
303 if 'unix_user' in self.parameters:
304 query['fields'] += ',user.name'
305 if 'unix_group' in self.parameters:
306 query['fields'] += ',group.name'
307 record, error = rest_generic.get_one_record(self.rest_api, api, query)
308 if error:
309 msg = "Error fetching qtree: %s" % error
310 self.module.fail_json(msg=msg)
311 if record:
312 self.volume_uuid = record['volume']['uuid']
313 self.qid = str(record['id'])
314 return {
315 'name': record['name'],
316 'export_policy': self.na_helper.safe_get(record, ['export_policy', 'name']),
317 'security_style': self.na_helper.safe_get(record, ['security_style']),
318 'unix_permissions': str(self.na_helper.safe_get(record, ['unix_permissions'])),
319 'unix_user': self.na_helper.safe_get(record, ['user', 'name']),
320 'unix_group': self.na_helper.safe_get(record, ['group', 'name'])
321 }
322 return None
323
324 qtree_list_iter = netapp_utils.zapi.NaElement('qtree-list-iter')
325 query_details = netapp_utils.zapi.NaElement.create_node_with_children(
326 'qtree-info', **{'vserver': self.parameters['vserver'],
327 'volume': self.parameters['flexvol_name'],
328 'qtree': name})
329 query = netapp_utils.zapi.NaElement('query')
330 query.add_child_elem(query_details)
331 qtree_list_iter.add_child_elem(query)
332 try:
333 result = self.server.invoke_successfully(qtree_list_iter, enable_tunneling=True)
334 except netapp_utils.zapi.NaApiError as error:
335 self.module.fail_json(msg='Error fetching qtree: %s' % to_native(error),
336 exception=traceback.format_exc())
337 return_q = None
338 if (result.get_child_by_name('num-records') and int(result.get_child_content('num-records')) >= 1):
339 return_q = {'export_policy': result['attributes-list']['qtree-info']['export-policy'],
340 'oplocks': result['attributes-list']['qtree-info']['oplocks'],
341 'security_style': result['attributes-list']['qtree-info']['security-style']}
342
343 value = self.na_helper.safe_get(result, ['attributes-list', 'qtree-info', 'mode'])
344 return_q['unix_permissions'] = value if value is not None else ''
345
346 return return_q
347
348 def create_qtree(self):
349 """
350 Create a qtree
351 """
352 if self.use_rest:
353 api = "storage/qtrees"
354 body = {'volume': {'name': self.parameters['flexvol_name']},
355 'svm': {'name': self.parameters['vserver']}}
356 body.update(self.form_create_modify_body_rest())
357 query = dict(return_timeout=10)
358 dummy, error = rest_generic.post_async(self.rest_api, api, body, query)
359 if error:
360 if "job reported error:" in error and "entry doesn't exist" in error:
361 # ignore RBAC issue with FSx - BURT1525998
362 self.module.warn('Ignoring job status, assuming success.')
363 return
364 self.module.fail_json(msg='Error creating qtree %s: %s' % (self.parameters['name'], error))
365 else:
366 self.create_or_modify_qtree_zapi('qtree-create', "Error creating qtree %s: %s")
367
368 def delete_qtree(self):
369 """
370 Delete a qtree
371 """
372 if self.use_rest:
373 api = "storage/qtrees/%s" % self.volume_uuid
374 query = {'return_timeout': 120}
375 response, error = rest_generic.delete_async(self.rest_api, api, self.qid, query)
376 if self.parameters['wait_for_completion']:
377 dummy, error = rrh.check_for_error_and_job_results(api, response, error, self.rest_api)
378 if error:
379 if not self.parameters['wait_for_completion'] and \
380 'job reported error:' in error and 'Timeout error: Process still running' in error:
381 self.module.warn("Process is still running in the background, exiting with no further waiting as 'wait_for_completion' is set to false.")
382 return
383 self.module.fail_json(msg='Error deleting qtree %s: %s' % (self.parameters['name'], error))
384
385 else:
386 path = '/vol/%s/%s' % (self.parameters['flexvol_name'], self.parameters['name'])
387 options = {'qtree': path}
388 if self.parameters['force_delete']:
389 options['force'] = "true"
390 qtree_delete = netapp_utils.zapi.NaElement.create_node_with_children(
391 'qtree-delete', **options)
392
393 try:
394 self.server.invoke_successfully(qtree_delete,
395 enable_tunneling=True)
396 except netapp_utils.zapi.NaApiError as error:
397 self.module.fail_json(msg="Error deleting qtree %s: %s" % (path, to_native(error)),
398 exception=traceback.format_exc())
399
400 def rename_qtree(self):
401 """
402 Rename a qtree
403 """
404 if self.use_rest:
405 error = 'Internal error, use modify with REST'
406 self.module.fail_json(msg=error)
407 else:
408 path = '/vol/%s/%s' % (self.parameters['flexvol_name'], self.parameters['from_name'])
409 new_path = '/vol/%s/%s' % (self.parameters['flexvol_name'], self.parameters['name'])
410 qtree_rename = netapp_utils.zapi.NaElement.create_node_with_children(
411 'qtree-rename', **{'qtree': path,
412 'new-qtree-name': new_path})
413
414 try:
415 self.server.invoke_successfully(qtree_rename,
416 enable_tunneling=True)
417 except netapp_utils.zapi.NaApiError as error:
418 self.module.fail_json(msg="Error renaming qtree %s: %s"
419 % (self.parameters['from_name'], to_native(error)),
420 exception=traceback.format_exc())
421
422 def modify_qtree(self):
423 """
424 Modify a qtree
425 """
426 if self.use_rest:
427 body = self.form_create_modify_body_rest()
428 api = "storage/qtrees/%s" % self.volume_uuid
429 query = dict(return_timeout=10)
430 dummy, error = rest_generic.patch_async(self.rest_api, api, self.qid, body, query)
431 if error:
432 self.module.fail_json(msg='Error modifying qtree %s: %s' % (self.parameters['name'], error))
433 else:
434 self.create_or_modify_qtree_zapi('qtree-modify', 'Error modifying qtree %s: %s')
435
436 def create_or_modify_qtree_zapi(self, zapi_request_name, error_message):
437 options = {'qtree': self.parameters['name'], 'volume': self.parameters['flexvol_name']}
438
439 if self.parameters.get('export_policy'):
440 options['export-policy'] = self.parameters['export_policy']
441 if self.parameters.get('security_style'):
442 options['security-style'] = self.parameters['security_style']
443 if self.parameters.get('oplocks'):
444 options['oplocks'] = self.parameters['oplocks']
445 if self.parameters.get('unix_permissions'):
446 options['mode'] = self.parameters['unix_permissions']
447 zapi_request = netapp_utils.zapi.NaElement.create_node_with_children(zapi_request_name, **options)
448
449 try:
450 self.server.invoke_successfully(zapi_request, enable_tunneling=True)
451 except netapp_utils.zapi.NaApiError as error:
452 self.module.fail_json(msg=(error_message % (self.parameters['name'], to_native(error))), exception=traceback.format_exc())
453
454 def form_create_modify_body_rest(self):
455 body = {'name': self.parameters['name']}
456 if self.parameters.get('security_style'):
457 body['security_style'] = self.parameters['security_style']
458 if self.parameters.get('unix_permissions'):
459 body['unix_permissions'] = self.parameters['unix_permissions']
460 if self.parameters.get('export_policy'):
461 body['export_policy'] = {'name': self.parameters['export_policy']}
462 if self.parameters.get('unix_user'):
463 body['user'] = {'name': self.parameters['unix_user']}
464 if self.parameters.get('unix_group'):
465 body['group'] = {'name': self.parameters['unix_group']}
466 return body
467
468 def apply(self):
469 '''Call create/delete/modify/rename operations'''
470 current = self.get_qtree()
471 rename, cd_action, modify = None, None, None
472 cd_action = self.na_helper.get_cd_action(current, self.parameters)
473 if cd_action == 'create' and self.parameters.get('from_name'):
474 current = self.get_qtree(self.parameters['from_name'])
475 if current is None:
476 self.module.fail_json(msg="Error renaming: qtree %s does not exist" % self.parameters['from_name'])
477 cd_action = None
478 if not self.use_rest:
479 # modify can change the name for REST, as UUID is the key.
480 rename = True
481
482 if cd_action is None:
483 octal_value = current.get('unix_permissions') if current else None
484 if self.parameters.get('unix_permissions')\
485 and self.na_helper.compare_chmod_value(octal_value, self.parameters['unix_permissions']):
486 del self.parameters['unix_permissions']
487 modify = self.na_helper.get_modified_attributes(current, self.parameters)
488
489 if self.use_rest and cd_action == 'delete' and not self.parameters['force_delete']:
490 self.module.fail_json(msg='Error: force_delete option is not supported for REST, unless set to true.')
491
492 if self.na_helper.changed and not self.module.check_mode:
493 if cd_action == 'create':
494 self.create_qtree()
495 elif cd_action == 'delete':
496 self.delete_qtree()
497 else:
498 if rename:
499 self.rename_qtree()
500 if modify:
501 self.modify_qtree()
502 result = netapp_utils.generate_result(self.na_helper.changed, cd_action, modify)
503 self.module.exit_json(**result)
504
505
506 def main():
507 '''Apply qtree operations from playbook'''
508 qtree_obj = NetAppOntapQTree()
509 qtree_obj.apply()
510
511
512 if __name__ == '__main__':
513 main()