Debian Codegraph @

ansible_collections/netapp/storagegrid/plugins/modules/na_sg_org_container.py

raw
1 #!/usr/bin/python
2
3 # (c) 2020-2025, NetApp Inc
4 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
5
6 """NetApp StorageGRID - Manage Buckets"""
7
8 from __future__ import absolute_import, division, print_function
9
10 __metaclass__ = type
11
12
13 ANSIBLE_METADATA = {
14 "metadata_version": "1.1",
15 "status": ["preview"],
16 "supported_by": "community",
17 }
18
19
20 DOCUMENTATION = """
21 module: na_sg_org_container
22 short_description: Manage buckets on StorageGRID.
23 extends_documentation_fragment:
24 - netapp.storagegrid.netapp.sg
25 version_added: '20.6.0'
26 author: NetApp Ansible Team (@joshedmonds) <[email protected]>
27 description:
28 - Create S3 buckets on NetApp StorageGRID.
29 options:
30 state:
31 description:
32 - Whether the specified bucket should exist or not.
33 type: str
34 choices: ['present', 'absent']
35 default: present
36 name:
37 description:
38 - Name of the bucket.
39 required: true
40 type: str
41 region:
42 description:
43 - Set a region for the bucket.
44 type: str
45 compliance:
46 description:
47 - Configure compliance settings for an S3 bucket.
48 - Cannot be specified along with I(s3_object_lock_enabled).
49 type: dict
50 suboptions:
51 auto_delete:
52 description:
53 - If enabled, objects will be deleted automatically when its retention period expires, unless the bucket is under a legal hold.
54 type: bool
55 legal_hold:
56 description:
57 - If enabled, objects in this bucket cannot be deleted, even if their retention period has expired.
58 type: bool
59 retention_period_minutes:
60 description:
61 - specify the length of the retention period for objects added to this bucket, in minutes.
62 type: int
63 capacity_limit:
64 description:
65 - The maximum number of GB available for this buckets's objects.
66 - Represents a logical amount (object size), not a physical amount (size on disk).
67 - Requires storageGRID 11.9 or later.
68 type: float
69 version_added: '21.16.0'
70 s3_object_lock_enabled:
71 description:
72 - Enable S3 Object Lock on the bucket.
73 - S3 Object Lock requires StorageGRID 11.5 or greater.
74 type: bool
75 version_added: '21.9.0'
76 bucket_versioning_enabled:
77 description:
78 - Enable versioning on the bucket.
79 - This API requires StorageGRID 11.6 or greater.
80 type: bool
81 version_added: '21.11.0'
82 consistency:
83 description:
84 - The consistency control affects the availability of objects for client requests.
85 required: false
86 type: str
87 choices: ['all', 'strong-global', 'strong-site', 'read-after-new-write', 'available']
88 version_added: '21.15.0'
89 policy:
90 description:
91 - Configure bucket policy.
92 type: dict
93 version_added: '21.16.0'
94 """
95
96 EXAMPLES = """
97 - name: create a s3 bucket
98 netapp.storagegrid.na_sg_org_container:
99 api_url: "https://<storagegrid-endpoint-url>"
100 auth_token: "storagegrid-auth-token"
101 validate_certs: false
102 state: present
103 name: ansiblebucket1
104
105 - name: delete a s3 bucket
106 netapp.storagegrid.na_sg_org_container:
107 api_url: "https://<storagegrid-endpoint-url>"
108 auth_token: "storagegrid-auth-token"
109 validate_certs: false
110 state: absent
111 name: ansiblebucket1
112
113 - name: create a s3 bucket with Object Lock
114 netapp.storagegrid.na_sg_org_container:
115 api_url: "https://<storagegrid-endpoint-url>"
116 auth_token: "storagegrid-auth-token"
117 validate_certs: false
118 state: present
119 name: objectlock-bucket1
120 s3_object_lock_enabled: true
121
122 - name: create a s3 bucket with versioning enabled
123 netapp.storagegrid.na_sg_org_container:
124 api_url: "https://<storagegrid-endpoint-url>"
125 auth_token: "storagegrid-auth-token"
126 validate_certs: false
127 state: present
128 name: ansiblebucket1
129 bucket_versioning_enabled: true
130
131 - name: create a s3 bucket with capacity_limit
132 netapp.storagegrid.na_sg_org_container:
133 api_url: "https://<storagegrid-endpoint-url>"
134 auth_token: "storagegrid-auth-token"
135 validate_certs: false
136 state: present
137 name: ansiblebucket1
138 capacity_limit: 1.5
139
140 - name: create a s3 bucket with policy
141 netapp.storagegrid.na_sg_org_container:
142 api_url: "https://<storagegrid-endpoint-url>"
143 auth_token: "storagegrid-auth-token"
144 validate_certs: false
145 state: present
146 name: ansiblebucket1
147 policy:
148 Statement:
149 - Sid: "string"
150 Effect: "Allow"
151 Action": "s3:GetObject"
152 Resource:
153 - "arn:aws:s3:::mybucket/myobject"
154 - "arn:aws:s3:::mybucket/myobject"
155 Principal: "*"
156 """
157
158 RETURN = """
159 resp:
160 description: Returns information about the StorageGRID bucket.
161 returned: always
162 type: dict
163 sample: {
164 "name": "example-bucket",
165 "creationTime": "2021-01-01T00:00:00.000Z",
166 "region": "us-east-1",
167 "compliance": {
168 "autoDelete": false,
169 "legalHold": false,
170 "retentionPeriodMinutes": 2629800
171 },
172 "s3ObjectLock": {
173 "enabled": false
174 },
175 "quotaObjectBytes": 1000000000,
176 "policy": {
177 "Statement": [
178 {
179 "Sid": "string",
180 "Effect": "Allow",
181 "Action": "s3:GetObject",
182 "Resource": [
183 "arn:aws:s3:::mybucket/myobject",
184 "arn:aws:s3:::mybucket/myobject"
185 ],
186 "Principal": "*"
187 }
188 ]
189 }
190 }
191 """
192
193 import ansible_collections.netapp.storagegrid.plugins.module_utils.netapp as netapp_utils
194 from ansible.module_utils.basic import AnsibleModule
195 from ansible_collections.netapp.storagegrid.plugins.module_utils.netapp_module import NetAppModule
196 from ansible_collections.netapp.storagegrid.plugins.module_utils.netapp import SGRestAPI
197
198
199 class SgOrgContainer(object):
200 """
201 Create, modify and delete StorageGRID Tenant Account
202 """
203
204 def __init__(self):
205 """
206 Parse arguments, setup state variables,
207 check parameters and ensure request module is installed
208 """
209 self.argument_spec = netapp_utils.na_storagegrid_host_argument_spec()
210 self.argument_spec.update(
211 dict(
212 state=dict(required=False, type="str", choices=["present", "absent"], default="present"),
213 name=dict(required=True, type="str"),
214 region=dict(required=False, type="str"),
215 compliance=dict(
216 required=False,
217 type="dict",
218 options=dict(
219 auto_delete=dict(required=False, type="bool"),
220 legal_hold=dict(required=False, type="bool"),
221 retention_period_minutes=dict(required=False, type="int"),
222 ),
223 ),
224 capacity_limit=dict(required=False, type="float"),
225 s3_object_lock_enabled=dict(required=False, type="bool"),
226 bucket_versioning_enabled=dict(required=False, type="bool"),
227 consistency=dict(required=False, type="str", choices=["all", "strong-global", "strong-site", "read-after-new-write", "available"]),
228 policy=dict(required=False, type="dict"),
229 )
230 )
231 parameter_map = {
232 "auto_delete": "autoDelete",
233 "legal_hold": "legalHold",
234 "retention_period_minutes": "retentionPeriodMinutes",
235 }
236 self.module = AnsibleModule(
237 argument_spec=self.argument_spec,
238 mutually_exclusive=[("compliance", "s3_object_lock_enabled")],
239 supports_check_mode=True,
240 )
241
242 self.na_helper = NetAppModule()
243
244 # set up state variables
245 self.parameters = self.na_helper.set_parameters(self.module.params)
246 # Calling generic SG rest_api class
247 self.rest_api = SGRestAPI(self.module)
248 # Get API version
249 self.rest_api.get_sg_product_version(api_root="org")
250 self.api_version = self.rest_api.get_api_version()
251
252 # Checking for the parameters passed and create new parameters list.
253
254 self.data_versioning = {}
255 self.data_versioning["versioningSuspended"] = True
256
257 self.consistency_setting = {}
258 self.bucket_policy = {}
259 self.quota_object_bytes = {}
260
261 self.data = {}
262 self.data["name"] = self.parameters["name"]
263 self.data["region"] = self.parameters.get("region")
264 if self.parameters.get("compliance"):
265 self.data["compliance"] = dict(
266 (parameter_map[k], v) for (k, v) in self.parameters["compliance"].items() if v is not None
267 )
268
269 if self.parameters.get("s3_object_lock_enabled") is not None:
270 self.rest_api.fail_if_not_sg_minimum_version("S3 Object Lock", 11, 5)
271 self.data["s3ObjectLock"] = dict(enabled=self.parameters["s3_object_lock_enabled"])
272
273 if self.parameters.get("bucket_versioning_enabled") is not None:
274 self.rest_api.fail_if_not_sg_minimum_version("Bucket versioning configuration", 11, 6)
275 self.data_versioning["versioningEnabled"] = self.parameters["bucket_versioning_enabled"]
276 if self.data_versioning["versioningEnabled"]:
277 self.data_versioning["versioningSuspended"] = False
278
279 if self.parameters.get("consistency") is not None:
280 self.rest_api.fail_if_not_sg_minimum_version("consistency setting", 11, 6)
281 self.consistency_setting["consistency"] = self.parameters["consistency"]
282
283 if self.parameters.get("capacity_limit"):
284 self.rest_api.fail_if_not_sg_minimum_version("Bucket capacity limit", 11, 9)
285 self.quota_object_bytes["quotaObjectBytes"] = int(self.parameters["capacity_limit"] * 1024 ** 3)
286
287 if self.parameters.get("policy") is not None:
288 self.rest_api.fail_if_not_sg_minimum_version("bucket policy", 11, 9)
289 self.bucket_policy = {"policy": self.parameters.get("policy")}
290
291 def get_org_container(self):
292 ''' Get org container details '''
293 params = {"include": "compliance,region"}
294 if self.rest_api.meets_sg_minimum_version(11, 9):
295 params["include"] += ",quotaObjectBytes"
296 response, error = self.rest_api.get("api/%s/org/containers" % self.api_version, params=params)
297
298 if error:
299 self.module.fail_json(msg=error)
300
301 for container in response["data"]:
302 if container["name"] == self.parameters["name"]:
303 return container
304
305 return None
306
307 def create_org_container(self):
308 ''' Create org container '''
309 api = "api/%s/org/containers" % self.api_version
310
311 response, error = self.rest_api.post(api, self.data)
312
313 if error:
314 self.module.fail_json(msg=error)
315
316 return response["data"]
317
318 def get_org_container_versioning(self):
319 ''' Get org container versioning details '''
320 api = "api/%s/org/containers/%s/versioning" % (self.api_version, self.parameters["name"])
321 response, error = self.rest_api.get(api)
322
323 if error:
324 self.module.fail_json(msg=error)
325
326 return response["data"]
327
328 def update_org_container_versioning(self):
329 ''' Update org container versioning '''
330 api = "api/%s/org/containers/%s/versioning" % (self.api_version, self.parameters["name"])
331
332 response, error = self.rest_api.put(api, self.data_versioning)
333 if error:
334 self.module.fail_json(msg=error)
335
336 return response["data"]
337
338 def fail_if_global_object_lock_disabled(self):
339 ''' Fail if global object lock is disabled '''
340 api = "api/%s/org/compliance-global" % self.api_version
341
342 response, error = self.rest_api.get(api)
343 if error:
344 self.module.fail_json(msg=error)
345
346 if not response["data"]["complianceEnabled"]:
347 self.module.fail_json(msg="Error: Global S3 Object Lock setting is not enabled.")
348
349 def update_org_container_compliance(self):
350 ''' Update org container compliance '''
351 api = "api/%s/org/containers/%s/compliance" % (self.api_version, self.parameters["name"])
352
353 response, error = self.rest_api.put(api, self.data["compliance"])
354 if error:
355 self.module.fail_json(msg=error)
356
357 return response["data"]
358
359 def update_org_container_quota_object_bytes(self):
360 ''' Update org container quota object bytes '''
361 api = "api/%s/org/containers/%s/quota-object-bytes" % (self.api_version, self.parameters["name"])
362
363 response, error = self.rest_api.put(api, self.quota_object_bytes)
364 if error:
365 self.module.fail_json(msg=error)
366
367 return response["data"]
368
369 def delete_org_container(self):
370 ''' Delete org container '''
371 api = "api/%s/org/containers/%s" % (self.api_version, self.parameters["name"])
372
373 response, error = self.rest_api.delete(api, None)
374 if error:
375 self.module.fail_json(msg=error)
376
377 def get_org_container_consistency(self):
378 api = "api/%s/org/containers/%s/consistency" % (self.api_version, self.parameters["name"])
379 response, error = self.rest_api.get(api)
380
381 if error:
382 self.module.fail_json(msg=error)
383
384 return response["data"]
385
386 def update_org_container_consistency(self):
387 api = "api/%s/org/containers/%s/consistency" % (self.api_version, self.parameters["name"])
388
389 response, error = self.rest_api.put(api, self.consistency_setting)
390 if error:
391 self.module.fail_json(msg=error)
392
393 return response["data"]
394
395 def get_org_container_policy(self):
396 api = "api/v3/org/containers/%s/policy" % self.parameters["name"]
397 response, error = self.rest_api.get(api)
398
399 if error:
400 self.module.fail_json(msg=error)
401
402 return response["data"]
403
404 def update_org_container_policy(self):
405 api = "api/v3/org/containers/%s/policy" % self.parameters["name"]
406
407 response, error = self.rest_api.put(api, self.bucket_policy)
408 if error:
409 self.module.fail_json(msg=error)
410
411 return response["data"]
412
413 def apply(self):
414 """
415 Perform pre-checks, call functions and exit
416 """
417 versioning_config = None
418 update_versioning = False
419 consistency_setting = None
420 update_consistency = False
421 get_policy = None
422
423 org_container = self.get_org_container()
424
425 if org_container and self.parameters.get("bucket_versioning_enabled") is not None:
426 versioning_config = self.get_org_container_versioning()
427 if org_container and self.parameters.get("consistency") is not None:
428 consistency_setting = self.get_org_container_consistency()
429 if org_container:
430 get_policy = self.get_org_container_policy()
431
432 cd_action = self.na_helper.get_cd_action(org_container, self.parameters)
433
434 if cd_action is None and self.parameters["state"] == "present":
435 # let's see if we need to update parameters
436 update_compliance = False
437 update_quota_object_bytes = False
438 update_policy = False
439
440 if self.parameters.get("compliance") and org_container.get("compliance") != self.data["compliance"]:
441 update_compliance = True
442 self.na_helper.changed = True
443
444 if self.parameters.get("capacity_limit") and org_container.get("quotaObjectBytes") != self.quota_object_bytes["quotaObjectBytes"]:
445 update_quota_object_bytes = True
446 self.na_helper.changed = True
447
448 if (
449 versioning_config
450 and versioning_config["versioningEnabled"] != self.data_versioning["versioningEnabled"]
451 ):
452 update_versioning = True
453 self.na_helper.changed = True
454
455 if (
456 consistency_setting
457 and consistency_setting["consistency"] != self.consistency_setting["consistency"]
458 ):
459 update_consistency = True
460 self.na_helper.changed = True
461
462 desired_policy = self.bucket_policy.get("policy") if self.bucket_policy else None
463 current_policy = get_policy.get("policy") if get_policy else None
464
465 # Treating None and {} as equivalent for comparison
466 if not desired_policy:
467 desired_policy = {}
468 if not current_policy:
469 current_policy = {}
470
471 if desired_policy != current_policy:
472 update_policy = True
473 self.na_helper.changed = True
474
475 result_message = ""
476 resp_data = org_container
477 if self.na_helper.changed:
478 if self.module.check_mode:
479 pass
480 else:
481 if cd_action == "delete":
482 self.delete_org_container()
483 resp_data = None
484 result_message = "Org Container deleted"
485
486 elif cd_action == "create":
487 if self.parameters.get("s3_object_lock_enabled"): # if it is set and true
488 self.fail_if_global_object_lock_disabled()
489
490 resp_data = self.create_org_container()
491
492 if self.parameters.get("bucket_versioning_enabled") is not None:
493 self.update_org_container_versioning()
494 if self.parameters.get("consistency") is not None:
495 self.update_org_container_consistency()
496
497 if self.parameters.get("capacity_limit"):
498 resp_data.update(self.update_org_container_quota_object_bytes())
499 if self.parameters.get("policy"):
500 resp_data.update(self.update_org_container_policy())
501 result_message = "Org Container created"
502
503 else:
504 if update_compliance:
505 resp_data = self.update_org_container_compliance()
506 if update_versioning:
507 self.update_org_container_versioning()
508 if update_consistency:
509 self.update_org_container_consistency()
510 if update_quota_object_bytes:
511 resp_data = self.update_org_container_quota_object_bytes()
512 if update_policy:
513 resp_data = self.update_org_container_policy()
514 result_message = "Org Container updated"
515
516 self.module.exit_json(changed=self.na_helper.changed, msg=result_message, resp=resp_data)
517
518
519 def main():
520 """
521 Main function
522 """
523 na_sg_org_container = SgOrgContainer()
524 na_sg_org_container.apply()
525
526
527 if __name__ == "__main__":
528 main()