Debian Codegraph @

ansible_collections/netapp/ontap/plugins/modules/na_ontap_s3_buckets.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 from __future__ import absolute_import, division, print_function
7
8 __metaclass__ = type
9
10 DOCUMENTATION = '''
11 module: na_ontap_s3_buckets
12 short_description: NetApp ONTAP S3 Buckets
13 extends_documentation_fragment:
14 - netapp.ontap.netapp.na_ontap_rest
15 version_added: 21.19.0
16 author: NetApp Ansible Team (@carchi8py) <[email protected]>
17 description:
18 - Create, delete, or modify S3 buckets on NetApp ONTAP.
19
20 options:
21 state:
22 description:
23 - Whether the specified S3 bucket should exist or not.
24 choices: ['present', 'absent']
25 type: str
26 default: 'present'
27
28 name:
29 description:
30 - The name of the S3 or NAS bucket.
31 type: str
32 required: true
33
34 vserver:
35 description:
36 - Name of the vserver to use.
37 type: str
38 required: true
39
40 aggregates:
41 description:
42 - List of aggregates names to use for the S3 bucket.
43 - This option is not supported when I(type=nas).
44 type: list
45 elements: str
46
47 constituents_per_aggregate:
48 description:
49 - Number of constituents per aggregate.
50 - This option is not supported when I(type=nas).
51 type: int
52
53 size:
54 description:
55 - Size of the S3 bucket in bytes.
56 - This option is not supported when I(type=nas).
57 type: int
58
59 comment:
60 description:
61 - Comment for the S3 bucket.
62 type: str
63
64 type:
65 description:
66 - Specifies the bucket type. Valid values are "s3"and "nas".
67 type: str
68 choices: ['s3', 'nas']
69 version_added: 22.6.0
70
71 nas_path:
72 description:
73 - Specifies the NAS path to which the nas bucket corresponds to.
74 type: str
75 version_added: 22.7.0
76
77 versioning_state:
78 description:
79 - Specifies the versioning state of the bucket.
80 - The versioning state cannot be modified to 'disabled' from any other state.
81 - Requires ONTAP 9.11.1 or later.
82 type: str
83 choices: ['disabled', 'enabled', 'suspended']
84 version_added: 22.13.0
85
86 policy:
87 description:
88 - Access policy uses the Amazon Web Services (AWS) policy language syntax to allow S3 tenants to create access policies to their data
89 type: dict
90 suboptions:
91 statements:
92 description:
93 - Policy statements are built using this structure to specify permissions
94 - Grant <Effect> to allow/deny <Principal> to perform <Action> on <Resource> when <Condition> applies
95 type: list
96 elements: dict
97 suboptions:
98 sid:
99 description: Statement ID
100 type: str
101 resources:
102 description:
103 - The bucket and any object it contains.
104 - The wildcard characters * and ? can be used to form a regular expression for specifying a resource.
105 type: list
106 elements: str
107 actions:
108 description:
109 - You can specify * to mean all actions, or a list of one or more of the following
110 - GetObject
111 - PutObject
112 - DeleteObject
113 - ListBucket
114 - GetBucketAcl
115 - GetObjectAcl
116 - ListBucketMultipartUploads
117 - ListMultipartUploadParts
118 type: list
119 elements: str
120 effect:
121 description: The statement may allow or deny access
122 type: str
123 choices:
124 - allow
125 - deny
126 principals:
127 description: A list of one or more S3 users or groups.
128 type: list
129 elements: str
130 conditions:
131 description: Conditions for when a policy is in effect.
132 type: list
133 elements: dict
134 suboptions:
135 operator:
136 description:
137 - The operator to use for the condition.
138 type: str
139 choices:
140 - ip_address
141 - not_ip_address
142 - string_equals
143 - string_not_equals
144 - string_equals_ignore_case
145 - string_not_equals_ignore_case
146 - string_like
147 - string_not_like
148 - numeric_equals
149 - numeric_not_equals
150 - numeric_greater_than
151 - numeric_greater_than_equals
152 - numeric_less_than
153 - numeric_less_than_equals
154 max_keys:
155 description:
156 - The maximum number of keys that can be returned in a request.
157 type: list
158 elements: str
159 delimiters:
160 description:
161 - The delimiter used to identify a prefix in a list of objects.
162 type: list
163 elements: str
164 source_ips:
165 description:
166 - The source IP address of the request.
167 type: list
168 elements: str
169 prefixes:
170 description:
171 - The prefixes of the objects that you want to list.
172 type: list
173 elements: str
174 usernames:
175 description:
176 - The user names that you want to allow to access the bucket.
177 type: list
178 elements: str
179
180 qos_policy:
181 description:
182 - A policy group defines measurable service level objectives (SLOs) that apply to the storage objects with which the policy group is associated.
183 - If you do not assign a policy group to a bucket, the system wil not monitor and control the traffic to it.
184 - This option is not supported when I(type=nas).
185 type: dict
186 suboptions:
187 max_throughput_iops:
188 description: The maximum throughput in IOPS.
189 type: int
190 max_throughput_mbps:
191 description: The maximum throughput in MBPS.
192 type: int
193 min_throughput_iops:
194 description: The minimum throughput in IOPS.
195 type: int
196 min_throughput_mbps:
197 description: The minimum throughput in MBPS.
198 type: int
199 name:
200 description: The QoS policy group name. This is mutually exclusive with other QoS attributes.
201 type: str
202
203 audit_event_selector:
204 description:
205 - Audit event selector allows you to specify access and permission types to audit.
206 - This option is not supported when I(type=nas).
207 type: dict
208 suboptions:
209 access:
210 description:
211 - specifies the type of event access to be audited, read-only, write-only or all (default is all).
212 type: str
213 choices:
214 - read
215 - write
216 - all
217 permission:
218 description:
219 - specifies the type of event permission to be audited, allow-only, deny-only or all (default is all).
220 type: str
221 choices:
222 - allow
223 - deny
224 - all
225
226 snapshot_policy:
227 description:
228 - Specifies the snapshot policy for the bucket.
229 type: str
230 version_added: 23.1.0
231
232 lambda_config:
233 description:
234 - Configuration parameters for AWS Lambda proxy functionality.
235 - These option and suboptions are only supported with REST.
236 type: dict
237 version_added: 23.4.0
238 suboptions:
239 function_name:
240 description:
241 - The name of the AWS Lambda function to invoke.
242 type: str
243 required: true
244 aws_region:
245 description:
246 - The name of the AWS region.
247 type: str
248 required: true
249 aws_profile:
250 description:
251 - The name of the AWS profile to use for authentication.
252 type: str
253
254 notes:
255 - module will try to set desired C(audit_event_selector) if the bucket is not configured with audit_event_selector options,
256 but may not take effect if there is no audit configuration present in vserver.
257 - Supports AWS Lambda proxy functionality. See README for example usage.
258 '''
259
260 EXAMPLES = """
261 - name: Create S3 bucket
262 netapp.ontap.na_ontap_s3_buckets:
263 state: present
264 name: carchi-test-bucket
265 comment: carchi8py was here
266 size: 838860800
267 vserver: ansibleSVM
268 hostname: "{{ netapp_hostname }}"
269 username: "{{ netapp_username }}"
270 password: "{{ netapp_password }}"
271 https: true
272 validate_certs: false
273 use_rest: always
274
275 - name: Create S3 bucket with a policy
276 netapp.ontap.na_ontap_s3_buckets:
277 state: present
278 name: carchi-test-bucket
279 comment: carchi8py was here
280 size: 838860800
281 policy:
282 statements:
283 - sid: FullAccessToUser1
284 resources:
285 - bucket1
286 - bucket1/*
287 actions:
288 - GetObject
289 - PutObject
290 - DeleteObject
291 - ListBucket
292 effect: allow
293 conditions:
294 - operator: ip_address
295 max_keys:
296 - 1000
297 delimiters:
298 - "/"
299 source_ips:
300 - 1.1.1.1
301 - 1.2.2.0/24
302 prefixes:
303 - prex
304 usernames:
305 - user1
306 principals:
307 - user1
308 - group/grp1
309 vserver: ansibleSVM
310 hostname: "{{ netapp_hostname }}"
311 username: "{{ netapp_username }}"
312 password: "{{ netapp_password }}"
313 https: true
314 validate_certs: false
315 use_rest: always
316
317 - name: Delete S3 bucket
318 netapp.ontap.na_ontap_s3_buckets:
319 state: absent
320 name: carchi-test-bucket
321 vserver: ansibleSVM
322 hostname: "{{ netapp_hostname }}"
323 username: "{{ netapp_username }}"
324 password: "{{ netapp_password }}"
325 https: true
326 validate_certs: false
327 use_rest: always
328 """
329
330 RETURN = """
331 """
332
333 import traceback
334 from ansible.module_utils.basic import AnsibleModule
335 from ansible.module_utils._text import to_native
336 import ansible_collections.netapp.ontap.plugins.module_utils.netapp as netapp_utils
337 from ansible_collections.netapp.ontap.plugins.module_utils.netapp_module import NetAppModule
338 from ansible_collections.netapp.ontap.plugins.module_utils import rest_generic
339
340
341 class NetAppOntapS3Buckets:
342 def __init__(self):
343 self.argument_spec = netapp_utils.na_ontap_rest_only_spec()
344 self.argument_spec.update(dict(
345 state=dict(required=False, type='str', choices=['present', 'absent'], default='present'),
346 name=dict(required=True, type='str'),
347 vserver=dict(required=True, type='str'),
348 aggregates=dict(required=False, type='list', elements='str'),
349 constituents_per_aggregate=dict(required=False, type='int'),
350 size=dict(required=False, type='int'),
351 comment=dict(required=False, type='str'),
352 type=dict(required=False, type='str', choices=['s3', 'nas']),
353 nas_path=dict(required=False, type='str'),
354 versioning_state=dict(required=False, type='str', choices=['disabled', 'enabled', 'suspended']),
355 policy=dict(type='dict', options=dict(
356 statements=dict(type='list', elements='dict', options=dict(
357 sid=dict(required=False, type='str'),
358 resources=dict(required=False, type='list', elements='str'),
359 actions=dict(required=False, type='list', elements='str'),
360 effect=dict(required=False, type='str', choices=['allow', 'deny']),
361 conditions=dict(type='list', elements='dict', options=dict(
362 operator=dict(required=False, type='str', choices=['ip_address',
363 'not_ip_address',
364 'string_equals',
365 'string_not_equals',
366 'string_equals_ignore_case',
367 'string_not_equals_ignore_case',
368 'string_like',
369 'string_not_like',
370 'numeric_equals',
371 'numeric_not_equals',
372 'numeric_greater_than',
373 'numeric_greater_than_equals',
374 'numeric_less_than',
375 'numeric_less_than_equals']),
376 max_keys=dict(required=False, type='list', elements='str', no_log=False),
377 delimiters=dict(required=False, type='list', elements='str'),
378 source_ips=dict(required=False, type='list', elements='str'),
379 prefixes=dict(required=False, type='list', elements='str'),
380 usernames=dict(required=False, type='list', elements='str'))),
381 principals=dict(type='list', elements='str')
382 )))),
383 qos_policy=dict(type='dict', options=dict(
384 max_throughput_iops=dict(type='int'),
385 max_throughput_mbps=dict(type='int'),
386 name=dict(type='str'),
387 min_throughput_iops=dict(type='int'),
388 min_throughput_mbps=dict(type='int'),
389 )),
390 audit_event_selector=dict(type='dict', options=dict(
391 access=dict(type='str', choices=['read', 'write', 'all']),
392 permission=dict(type='str', choices=['allow', 'deny', 'all']))),
393 snapshot_policy=dict(required=False, type='str'),
394 ))
395 self.argument_spec.update(netapp_utils.na_ontap_lambda_argument_spec())
396
397 self.module = AnsibleModule(
398 argument_spec=self.argument_spec,
399 required_if=[
400 ['use_lambda', True, ('lambda_config',)]
401 ],
402 supports_check_mode=True
403 )
404 self.svm_uuid = None
405 self.uuid = None
406 self.volume_uuid = None
407 self.na_helper = NetAppModule(self.module)
408 self.parameters = self.na_helper.check_and_set_parameters(self.module)
409
410 self.rest_api = netapp_utils.OntapRestAPI(self.module)
411 self.rest_api.fail_if_not_rest_minimum_version('na_ontap_s3_buckets', 9, 8)
412 partially_supported_rest_properties = [['audit_event_selector', (9, 10, 1)], ['versioning_state', (9, 11, 1)],
413 ['type', (9, 12, 1)], ['nas_path', (9, 12, 1)], ['snapshot_policy', (9, 16, 1)]]
414 self.use_rest = self.rest_api.is_rest_supported_properties(self.parameters, None, partially_supported_rest_properties)
415 # few keys in policy.statements will be configured with default value if not set in create.
416 # so removing None entries to avoid idempotent issue in next run.
417 if self.parameters.get('policy'):
418 # below keys can be reset with empty list.
419 # - statements.
420 # - conditions.
421 # - actions.
422 # - principals.
423 self.parameters['policy'] = self.na_helper.filter_out_none_entries(self.parameters['policy'], True)
424 for statement in self.parameters['policy'].get('statements', []):
425 if {} in self.parameters['policy']['statements']:
426 self.module.fail_json(msg="Error: cannot set empty dict for policy statements.")
427 if len(statement.get('resources', [])) == 1 and statement['resources'] == ["*"]:
428 statement['resources'] = [self.parameters['name'], self.parameters['name'] + '/*']
429 for condition in statement.get('conditions', []):
430 updated_ips = []
431 for ip in condition.get('source_ips', []):
432 if '/' in ip:
433 updated_ips.append(ip)
434 else:
435 # if cidr notation not set in each ip, append /32.
436 # cidr unset ip address will return with /32 in next run.
437 updated_ips.append(ip + '/32')
438 if updated_ips:
439 condition['source_ips'] = updated_ips
440
441 def get_s3_bucket(self):
442 api = 'protocols/s3/buckets'
443 fields = 'name,svm.name,size,comment,volume.uuid,policy,policy.statements,qos_policy'
444 if self.rest_api.meets_rest_minimum_version(self.use_rest, 9, 10, 1):
445 fields += ',audit_event_selector'
446 if self.rest_api.meets_rest_minimum_version(self.use_rest, 9, 11, 1):
447 fields += ',versioning_state'
448 if self.rest_api.meets_rest_minimum_version(self.use_rest, 9, 12, 1):
449 fields += ',type,nas_path'
450 if self.rest_api.meets_rest_minimum_version(self.use_rest, 9, 16, 1):
451 fields += ',snapshot_policy'
452 params = {'name': self.parameters['name'],
453 'svm.name': self.parameters['vserver'],
454 'fields': fields}
455 record, error = rest_generic.get_one_record(self.rest_api, api, params)
456 if error:
457 self.module.fail_json(msg='Error fetching S3 bucket %s: %s' % (self.parameters['name'], to_native(error)),
458 exception=traceback.format_exc())
459 return self.form_current(record) if record else None
460
461 def form_current(self, record):
462 self.set_uuid(record)
463 body = {
464 'comment': self.na_helper.safe_get(record, ['comment']),
465 'size': self.na_helper.safe_get(record, ['size']),
466 'policy': self.na_helper.safe_get(record, ['policy']),
467 'qos_policy': self.na_helper.safe_get(record, ['qos_policy']),
468 'audit_event_selector': self.na_helper.safe_get(record, ['audit_event_selector']),
469 'type': self.na_helper.safe_get(record, ['type']),
470 'nas_path': self.na_helper.safe_get(record, ['nas_path']),
471 'versioning_state': self.na_helper.safe_get(record, ['versioning_state']),
472 'snapshot_policy': self.na_helper.safe_get(record, ['snapshot_policy', 'name']),
473 }
474 if body['policy']:
475 for policy_statement in body['policy'].get('statements', []):
476 # So we treat SID as a String as it can accept Words, or Numbers.
477 # ONTAP will return it as a String, unless it is just
478 # numbers then it is returned as an INT.
479 policy_statement['sid'] = str(policy_statement['sid'])
480 # setting keys in each condition to None if not present to avoid idempotency issue.
481 if not policy_statement.get('conditions'):
482 policy_statement['conditions'] = []
483 else:
484 for condition in policy_statement['conditions']:
485 condition['delimiters'] = condition.get('delimiters')
486 condition['max_keys'] = condition.get('max_keys')
487 condition['operator'] = condition.get('operator')
488 condition['prefixes'] = condition.get('prefixes')
489 condition['source_ips'] = condition.get('source_ips')
490 condition['usernames'] = condition.get('usernames')
491 # empty [] is used to reset policy statements.
492 # setting policy statements to [] to avoid idempotency issue.
493 else:
494 body['policy'] = {'statements': []}
495 return body
496
497 def set_uuid(self, record):
498 self.uuid = record['uuid']
499 self.svm_uuid = record['svm']['uuid']
500 # volume key is not returned for NAS buckets.
501 self.volume_uuid = self.na_helper.safe_get(record, ['volume', 'uuid'])
502
503 def create_s3_bucket(self):
504 api = 'protocols/s3/buckets'
505 body = {'svm.name': self.parameters['vserver'], 'name': self.parameters['name']}
506 body.update(self.form_create_or_modify_body())
507 dummy, error = rest_generic.post_async(self.rest_api, api, body, job_timeout=120)
508 if error:
509 self.module.fail_json(msg='Error creating S3 bucket %s: %s' % (self.parameters['name'], to_native(error)),
510 exception=traceback.format_exc())
511
512 def delete_s3_bucket(self):
513 api = 'protocols/s3/buckets'
514 uuids = '%s/%s' % (self.svm_uuid, self.uuid)
515 dummy, error = rest_generic.delete_async(self.rest_api, api, uuids, job_timeout=120)
516 if error:
517 self.module.fail_json(msg='Error deleting S3 bucket %s: %s' % (self.parameters['name'], to_native(error)),
518 exception=traceback.format_exc())
519
520 def modify_s3_bucket(self, modify):
521 api = 'protocols/s3/buckets'
522 uuids = '%s/%s' % (self.svm_uuid, self.uuid)
523 body = self.form_create_or_modify_body(modify)
524 dummy, error = rest_generic.patch_async(self.rest_api, api, uuids, body, job_timeout=120)
525 if error:
526 self.module.fail_json(msg='Error modifying S3 bucket %s: %s' % (self.parameters['name'], to_native(error)),
527 exception=traceback.format_exc())
528
529 def form_create_or_modify_body(self, params=None):
530 if params is None:
531 params = self.parameters
532 body = {}
533 options = ['aggregates', 'constituents_per_aggregate', 'size', 'comment', 'type', 'nas_path',
534 'policy', 'versioning_state', 'snapshot_policy']
535 for option in options:
536 if option in params:
537 body[option] = params[option]
538 if 'qos_policy' in params:
539 body['qos_policy'] = self.na_helper.filter_out_none_entries(params['qos_policy'])
540 if 'audit_event_selector' in params:
541 body['audit_event_selector'] = self.na_helper.filter_out_none_entries(params['audit_event_selector'])
542 return body
543
544 def check_volume_aggr(self):
545 api = 'storage/volumes/%s' % self.volume_uuid
546 params = {'fields': 'aggregates.name'}
547 record, error = rest_generic.get_one_record(self.rest_api, api, params)
548 if error:
549 self.module.fail_json(msg=error)
550 aggr_names = [aggr['name'] for aggr in record['aggregates']]
551 if self.parameters.get('aggregates'):
552 if sorted(aggr_names) != sorted(self.parameters['aggregates']):
553 return True
554 return False
555
556 def validate_modify_required(self, modify, current):
557 # if desired statement length different than current, allow modify.
558 if len(modify['policy']['statements']) != len(current['policy']['statements']):
559 return True
560 match_found = []
561 for statement in modify['policy']['statements']:
562 for index, current_statement in enumerate(current['policy']['statements']):
563 # continue to next if the current statement already has a match.
564 if index in match_found:
565 continue
566 statement_modified = self.na_helper.get_modified_attributes(current_statement, statement)
567 # no modify required, match found for the statment.
568 # break the loop and check next desired policy statement has match.
569 if not statement_modified:
570 match_found.append(index)
571 break
572 # match not found, switch to next current statement and continue to find desired statement is present.
573 if len(statement_modified) > 1:
574 continue
575 # 'conditions' key in policy.statements is list type, each element is dict.
576 # if the len of the desired conditions different than current, allow for modify.
577 # check for modify if 'conditions' is the only key present in statement_modified.
578 # check for difference in each modify[policy.statements[index][conditions] with current[policy.statements[index][conditions].
579 if statement_modified.get('conditions'):
580 if not current_statement['conditions']:
581 continue
582 if len(statement_modified.get('conditions')) != len(current_statement['conditions']):
583 continue
584
585 # each condition should be checked for modify based on the operator key.
586 def require_modify(desired, current):
587 for condition in desired:
588 # operator is a required field for condition, if not present, REST will throw error.
589 if condition.get('operator'):
590 for current_condition in current:
591 if condition['operator'] == current_condition['operator']:
592 condition_modified = self.na_helper.get_modified_attributes(current_condition, condition)
593 if condition_modified:
594 return True
595 else:
596 return True
597 if not require_modify(statement_modified['conditions'], current_statement['conditions']):
598 match_found.append(index)
599 break
600 # allow modify
601 # - if not match found
602 # - if only partial policy statements has match found.
603 return not match_found or len(match_found) != len(modify['policy']['statements'])
604
605 def apply(self):
606 current = self.get_s3_bucket()
607 cd_action, modify = None, None
608 cd_action = self.na_helper.get_cd_action(current, self.parameters)
609 if cd_action is None:
610 modify = self.na_helper.get_modified_attributes(current, self.parameters)
611 if modify.get('type'):
612 self.module.fail_json(msg='Error: cannot modify bucket type.')
613 if modify.get('versioning_state') == 'disabled' and\
614 current.get('versioning_state') in ('enabled', 'suspended'):
615 self.module.fail_json(msg='Error: cannot disable bucket versioning once it has been enabled.')
616 if len(modify) == 1 and 'policy' in modify and current.get('policy'):
617 if modify['policy'].get('statements'):
618 self.na_helper.changed = self.validate_modify_required(modify, current)
619 if not self.na_helper.changed:
620 modify = False
621 # volume uuid returned only for s3 buckets.
622 if current and self.volume_uuid and self.check_volume_aggr():
623 self.module.fail_json(msg='Aggregates cannot be modified for S3 bucket %s' % self.parameters['name'])
624 if self.na_helper.changed and not self.module.check_mode:
625 if cd_action == 'create':
626 self.create_s3_bucket()
627 if cd_action == 'delete':
628 self.delete_s3_bucket()
629 if modify:
630 self.modify_s3_bucket(modify)
631 result = netapp_utils.generate_result(self.na_helper.changed, cd_action, modify)
632 self.module.exit_json(**result)
633
634
635 def main():
636 '''Apply volume operations from playbook'''
637 obj = NetAppOntapS3Buckets()
638 obj.apply()
639
640
641 if __name__ == '__main__':
642 main()