Debian Codegraph @

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

raw
1 #!/usr/bin/python
2
3 # (c) 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_bucket
22 short_description: Manage buckets on StorageGRID.
23 extends_documentation_fragment:
24 - netapp.storagegrid.netapp.sg
25 version_added: '21.15.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 bucket_versioning_enabled:
76 description:
77 - Enable versioning on the bucket.
78 - This API requires StorageGRID 11.6 or greater.
79 type: bool
80 """
81
82 EXAMPLES = """
83 - name: create a s3 bucket
84 netapp.storagegrid.na_sg_org_bucket:
85 api_url: "https://<storagegrid-endpoint-url>"
86 auth_token: "storagegrid-auth-token"
87 validate_certs: false
88 state: present
89 name: ansiblebucket1
90
91 - name: delete a s3 bucket
92 netapp.storagegrid.na_sg_org_bucket:
93 api_url: "https://<storagegrid-endpoint-url>"
94 auth_token: "storagegrid-auth-token"
95 validate_certs: false
96 state: absent
97 name: ansiblebucket1
98
99 - name: create a s3 bucket with Object Lock
100 netapp.storagegrid.na_sg_org_bucket:
101 api_url: "https://<storagegrid-endpoint-url>"
102 auth_token: "storagegrid-auth-token"
103 validate_certs: false
104 state: present
105 name: objectlock-bucket1
106 s3_object_lock_enabled: true
107
108 - name: create a s3 bucket with versioning enabled
109 netapp.storagegrid.na_sg_org_bucket:
110 api_url: "https://<storagegrid-endpoint-url>"
111 auth_token: "storagegrid-auth-token"
112 validate_certs: false
113 state: present
114 name: ansiblebucket1
115 bucket_versioning_enabled: true
116
117 - name: create a s3 bucket with capacity_limit
118 netapp.storagegrid.na_sg_org_bucket:
119 api_url: "https://<storagegrid-endpoint-url>"
120 auth_token: "storagegrid-auth-token"
121 validate_certs: false
122 state: present
123 name: ansiblebucket1
124 capacity_limit: 1.5
125 """
126
127 RETURN = """
128 resp:
129 description: Returns information about the StorageGRID bucket.
130 returned: always
131 type: dict
132 sample: {
133 "name": "example-bucket",
134 "creationTime": "2021-01-01T00:00:00.000Z",
135 "region": "us-east-1",
136 "compliance": {
137 "autoDelete": false,
138 "legalHold": false,
139 "retentionPeriodMinutes": 2629800
140 },
141 "s3ObjectLock": {
142 "enabled": false
143 },
144 "quotaObjectBytes": 1000000000
145 }
146 """
147
148 import ansible_collections.netapp.storagegrid.plugins.module_utils.netapp as netapp_utils
149 from ansible.module_utils.basic import AnsibleModule
150 from ansible_collections.netapp.storagegrid.plugins.module_utils.netapp_module import NetAppModule
151 from ansible_collections.netapp.storagegrid.plugins.module_utils.netapp import SGRestAPI
152
153
154 class SgOrgBucket(object):
155 """
156 Create, modify and delete StorageGRID Buckets
157 """
158
159 def __init__(self):
160 """
161 Parse arguments, setup state variables,
162 check parameters and ensure request module is installed
163 """
164 self.argument_spec = netapp_utils.na_storagegrid_host_argument_spec()
165 self.argument_spec.update(
166 dict(
167 state=dict(required=False, type="str", choices=["present", "absent"], default="present"),
168 name=dict(required=True, type="str"),
169 region=dict(required=False, type="str"),
170 compliance=dict(
171 required=False,
172 type="dict",
173 options=dict(
174 auto_delete=dict(required=False, type="bool"),
175 legal_hold=dict(required=False, type="bool"),
176 retention_period_minutes=dict(required=False, type="int"),
177 ),
178 ),
179 capacity_limit=dict(required=False, type="float"),
180 s3_object_lock_enabled=dict(required=False, type="bool"),
181 bucket_versioning_enabled=dict(required=False, type="bool"),
182 )
183 )
184 parameter_map = {
185 "auto_delete": "autoDelete",
186 "legal_hold": "legalHold",
187 "retention_period_minutes": "retentionPeriodMinutes",
188 }
189 self.module = AnsibleModule(
190 argument_spec=self.argument_spec,
191 mutually_exclusive=[("compliance", "s3_object_lock_enabled")],
192 supports_check_mode=True,
193 )
194
195 self.na_helper = NetAppModule()
196
197 # set up state variables
198 self.parameters = self.na_helper.set_parameters(self.module.params)
199 # Calling generic SG rest_api class
200 self.rest_api = SGRestAPI(self.module)
201 # Get API version
202 self.rest_api.get_sg_product_version(api_root="org")
203 self.api_version = self.rest_api.get_api_version()
204
205 # Checking for the parameters passed and create new parameters list
206
207 self.data_versioning = {}
208 self.data_versioning["versioningSuspended"] = True
209
210 self.quota_object_bytes = {}
211
212 self.data = {}
213 self.data["name"] = self.parameters["name"]
214 self.data["region"] = self.parameters.get("region")
215 if self.parameters.get("compliance"):
216 self.data["compliance"] = dict(
217 (parameter_map[k], v) for (k, v) in self.parameters["compliance"].items() if v is not None
218 )
219
220 if self.parameters.get("s3_object_lock_enabled") is not None:
221 self.rest_api.fail_if_not_sg_minimum_version("S3 Object Lock", 11, 5)
222 self.data["s3ObjectLock"] = dict(enabled=self.parameters["s3_object_lock_enabled"])
223
224 if self.parameters.get("bucket_versioning_enabled") is not None:
225 self.rest_api.fail_if_not_sg_minimum_version("Bucket versioning configuration", 11, 6)
226 self.data_versioning["versioningEnabled"] = self.parameters["bucket_versioning_enabled"]
227 if self.data_versioning["versioningEnabled"]:
228 self.data_versioning["versioningSuspended"] = False
229
230 if self.parameters.get("capacity_limit"):
231 self.rest_api.fail_if_not_sg_minimum_version("Bucket capacity limit", 11, 9)
232 self.quota_object_bytes["quotaObjectBytes"] = int(self.parameters["capacity_limit"] * 1024 ** 3)
233
234 def get_org_container(self):
235 ''' Get org container details '''
236 params = {"include": "compliance,region"}
237 if self.rest_api.meets_sg_minimum_version(11, 9):
238 params["include"] += ",quotaObjectBytes"
239 response, error = self.rest_api.get("api/%s/org/containers" % self.api_version, params=params)
240
241 if error:
242 self.module.fail_json(msg=error)
243
244 for container in response["data"]:
245 if container["name"] == self.parameters["name"]:
246 return container
247
248 return None
249
250 def create_org_container(self):
251 ''' Create org container '''
252 api = "api/%s/org/containers" % self.api_version
253
254 response, error = self.rest_api.post(api, self.data)
255
256 if error:
257 self.module.fail_json(msg=error)
258
259 return response["data"]
260
261 def get_org_container_versioning(self):
262 ''' Get org container versioning details '''
263 api = "api/%s/org/containers/%s/versioning" % (self.api_version, self.parameters["name"])
264 response, error = self.rest_api.get(api)
265
266 if error:
267 self.module.fail_json(msg=error)
268
269 return response["data"]
270
271 def update_org_container_versioning(self):
272 ''' Update org container versioning '''
273 api = "api/%s/org/containers/%s/versioning" % (self.api_version, self.parameters["name"])
274
275 response, error = self.rest_api.put(api, self.data_versioning)
276 if error:
277 self.module.fail_json(msg=error)
278
279 return response["data"]
280
281 def fail_if_global_object_lock_disabled(self):
282 ''' Fail if global object lock is disabled '''
283 api = "api/%s/org/compliance-global" % self.api_version
284
285 response, error = self.rest_api.get(api)
286 if error:
287 self.module.fail_json(msg=error)
288
289 if not response["data"]["complianceEnabled"]:
290 self.module.fail_json(msg="Error: Global S3 Object Lock setting is not enabled.")
291
292 def update_org_container_compliance(self):
293 ''' Update org container compliance '''
294 api = "api/%s/org/containers/%s/compliance" % (self.api_version, self.parameters["name"])
295
296 response, error = self.rest_api.put(api, self.data["compliance"])
297 if error:
298 self.module.fail_json(msg=error)
299
300 return response["data"]
301
302 def update_org_container_quota_object_bytes(self):
303 ''' Update org container quota object bytes '''
304 api = "api/%s/org/containers/%s/quota-object-bytes" % (self.api_version, self.parameters["name"])
305
306 response, error = self.rest_api.put(api, self.quota_object_bytes)
307 if error:
308 self.module.fail_json(msg=error)
309
310 return response["data"]
311
312 def delete_org_container(self):
313 ''' Delete org container '''
314 api = "api/%s/org/containers/%s" % (self.api_version, self.parameters["name"])
315
316 response, error = self.rest_api.delete(api, None)
317 if error:
318 self.module.fail_json(msg=error)
319
320 def apply(self):
321 """
322 Perform pre-checks, call functions and exit
323 """
324 versioning_config = None
325 update_versioning = False
326
327 org_container = self.get_org_container()
328
329 if org_container and self.parameters.get("bucket_versioning_enabled") is not None:
330 versioning_config = self.get_org_container_versioning()
331
332 cd_action = self.na_helper.get_cd_action(org_container, self.parameters)
333
334 if cd_action is None and self.parameters["state"] == "present":
335 # let's see if we need to update parameters
336 update_compliance = False
337 update_quota_object_bytes = False
338
339 if self.parameters.get("compliance") and org_container.get("compliance") != self.data["compliance"]:
340 update_compliance = True
341 self.na_helper.changed = True
342
343 if self.parameters.get("capacity_limit") and org_container.get("quotaObjectBytes") != self.quota_object_bytes["quotaObjectBytes"]:
344 update_quota_object_bytes = True
345 self.na_helper.changed = True
346
347 if (
348 versioning_config
349 and versioning_config["versioningEnabled"] != self.data_versioning["versioningEnabled"]
350 ):
351 update_versioning = True
352 self.na_helper.changed = True
353
354 result_message = ""
355 resp_data = org_container
356 if self.na_helper.changed:
357 if self.module.check_mode:
358 pass
359 else:
360 if cd_action == "delete":
361 self.delete_org_container()
362 resp_data = None
363 result_message = "Org Container deleted"
364
365 elif cd_action == "create":
366 if self.parameters.get("s3_object_lock_enabled"): # if it is set and true
367 self.fail_if_global_object_lock_disabled()
368
369 resp_data = self.create_org_container()
370
371 if self.parameters.get("bucket_versioning_enabled") is not None:
372 self.update_org_container_versioning()
373
374 if self.parameters.get("capacity_limit"):
375 resp_data.update(self.update_org_container_quota_object_bytes())
376 result_message = "Org Container created"
377
378 else:
379 if update_compliance:
380 resp_data = self.update_org_container_compliance()
381 if update_versioning:
382 self.update_org_container_versioning()
383 if update_quota_object_bytes:
384 resp_data = self.update_org_container_quota_object_bytes()
385 result_message = "Org Container updated"
386
387 self.module.exit_json(changed=self.na_helper.changed, msg=result_message, resp=resp_data)
388
389
390 def main():
391 """
392 Main function
393 """
394 na_sg_org_bucket = SgOrgBucket()
395 na_sg_org_bucket.apply()
396
397
398 if __name__ == "__main__":
399 main()