Debian Codegraph @

ansible_collections/netapp/storagegrid/plugins/modules/na_sg_grid_ilm_rule.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 ILM policies"""
7
8 from __future__ import absolute_import, division, print_function
9
10 __metaclass__ = type
11
12
13 ANSIBLE_METADATA = {
14 "metadata_version": "1.0",
15 "status": ["preview"],
16 "supported_by": "community",
17 }
18
19
20 DOCUMENTATION = """
21 module: na_sg_grid_ilm_rule
22 short_description: Manage ILM rules on StorageGRID.
23 extends_documentation_fragment:
24 - netapp.storagegrid.netapp.sg
25 version_added: '21.14.0'
26 author: Denis Magel (@dmagel-netapp) <[email protected]>
27 description:
28 - Interact with ILM rules on NetApp StorageGRID.
29 options:
30 bucket_filter:
31 description:
32 - S3 or Swift bucket(s) to which the ILM rule applies.
33 - If omitted, matches all objects in any specified tenant accounts
34 required: false
35 type: dict
36 suboptions:
37 operator:
38 description:
39 - Operator used to match bucket(s) with the value
40 required: true
41 type: str
42 choices: ['contains', 'endsWith', 'equals', 'startsWith']
43 value:
44 description:
45 - str value used to match bucket(s) with the specified operator
46 required: true
47 type: str
48 description:
49 description:
50 - A short description of the ILM rule to indicate its purpose
51 required: false
52 type: str
53 filters:
54 description:
55 - Filtering criteria used to determine if the ILM rule shall be applied to the evaluated object.
56 - An ILM rule without filters applies to all objects
57 required: false
58 type: list
59 elements: dict
60 default: []
61 suboptions:
62 logicalOperator:
63 description:
64 - Logical operator connecting filtering criteria when more than one criterion provided
65 required: false
66 type: str
67 criteria:
68 description:
69 - A group of logical conditions based on object metadata
70 required: false
71 type: list
72 elements: dict
73 suboptions:
74 operator:
75 description:
76 - Used to compare the "metadataName" with the "value" str
77 required: true
78 type: str
79 choices: ['contains', 'notContains', 'equals', 'notEquals', 'startsWith', 'notStartsWith', 'endsWith', 'notEndsWith', 'exists', 'notExists',
80 'lessThan', 'lessThanOrEquals', 'greaterThan', 'greaterThanOrEquals']
81 metadataName:
82 description:
83 - System metadata identifier, user metadata name, or tag name
84 required: true
85 type: str
86 metadataType:
87 description:
88 - Indicates the type of filtered metadata
89 required: false
90 type: str
91 value:
92 description:
93 - Entry against which the metadata values specified by metadataName should be compared
94 required: false
95 type: str
96 ingest_behavior:
97 description:
98 - How objects matching this rule are stored on ingest.
99 - dual-commit creates interim copies and applies the rule later.
100 - strict and balanced immediately create the copies specified in the rule's day 0 instructions.
101 - balanced uses dual-commit if following the rule instructions is not possible.
102 required: false
103 type: str
104 choices: ['strict', 'balanced', 'dual-commit']
105 default: balanced
106 name:
107 description:
108 - Displayed name of the ILM rule.
109 - A representative and unique name for the ILM rule.
110 - Immutable once the ILM rule is created
111 required: true
112 type: str
113 placements:
114 description:
115 - Specifies where and how object data that matches the ILM rule is stored
116 required: false
117 type: list
118 elements: dict
119 suboptions:
120 retention:
121 description:
122 - Specifies where and how object data that matches the ILM rule is stored over time
123 required: true
124 type: dict
125 suboptions:
126 after:
127 description:
128 - Day when object storage starts
129 required: true
130 type: int
131 duration:
132 description:
133 - Number of days object data to be stored at the specified locations. Objects stored forever if null
134 required: false
135 type: int
136 replicated:
137 description:
138 - Creates replicated copies of object data; otherwise, must be omitted
139 required: false
140 type: list
141 elements: dict
142 suboptions:
143 poolId:
144 description:
145 - One or more storage pools where object data is saved, specified as comma-separated values. Either poolId or cloudStoragePoolId is required.
146 required: false
147 type: str
148 temporaryPoolId:
149 description:
150 - Temporary locations are deprecated and should not be used for new ILM rules.
151 - If you select the Strict ingest behavior, the temporary location is ignored.
152 required: false
153 type: str
154 cloudStoragePoolId:
155 description:
156 - Cloud Storage Pool where object data is saved. Cloud Storage Pools cannot be used in the same placement as a storage pool.
157 - Either poolId or cloudStoragePoolId is required.
158 required: false
159 type: str
160 copies:
161 description:
162 - Number of replicated copies
163 required: true
164 type: int
165 erasureCoded:
166 description:
167 - Creates erasure coded copies of object data; otherwise, must be omitted
168 required: false
169 type: list
170 elements: dict
171 suboptions:
172 poolId:
173 description:
174 - Storage pool where object data is stored
175 required: true
176 type: str
177 profileId:
178 description:
179 - Erasure coding profile used. Erasure coded object data only
180 required: true
181 type: str
182 reference_time:
183 description:
184 - Indicates the time from which the ILM rule is applied
185 required: false
186 type: str
187 choices: ['ingestTime', 'lastAccessTime', 'noncurrentTime', 'userDefinedCreationTime']
188 default: ingestTime
189 state:
190 description:
191 - Whether the specified rule should exist.
192 required: false
193 type: str
194 choices: ['present', 'absent']
195 default: present
196 tenant_account_id:
197 description:
198 - One or more S3 or Swift tenant account IDs to which the ILM rule applies
199 - If omitted, applies to all objects
200 required: false
201 type: str
202 validate_certs:
203 description:
204 - Should https certificates be validated?
205 required: false
206 type: bool
207 default: true
208 """
209
210 EXAMPLES = """
211 - name: Create ILM rule with existing EC pool
212 na_sg_grid_ilm_rule:
213 api_url: "https://<storagegrid-endpoint-url>"
214 auth_token: "storagegrid-auth-token"
215 name: "1 Copy Per Site"
216 state: present
217 reference_time: "ingestTime"
218 ingest_behavior: "balanced"
219 filters: []
220 placements:
221 - retention:
222 after: 0
223 erasureCoded:
224 - profileId: "1"
225 poolId: "p10771105546308032398"
226
227 - name: Delete existing ILM rule
228 na_sg_grid_ilm_rule:
229 api_url: "https://<storagegrid-endpoint-url>"
230 auth_token: "storagegrid-auth-token"
231 name: "1 Copy Per Site"
232 state: absent
233 """
234
235 RETURN = """
236 resp:
237 description: Returns information about the StorageGRID ILM rule.
238 returned: If state is 'present'.
239 type: dict
240 sample: {
241 "active": false,
242 "api": "s3OrSwift",
243 "displayName": "1 Copy Per Site",
244 "filters": [],
245 "id": "r14896911895584977919",
246 "ingestBehavior": "balanced",
247 "permissions": [
248 "delete",
249 "edit"
250 ],
251 "placements": [
252 {
253 "erasureCoded": [
254 {
255 "poolId": "p10771105546308032398",
256 "profileld": "1"
257 }
258 ],
259 "retention": {
260 "after": 0
261 }
262 }
263 ],
264 "proposed": false,
265 "referenceTime": "ingestTime",
266 "schemaVersion": "1.0",
267 "version": "1.0"
268 }
269 """
270
271 from datetime import datetime
272
273 import ansible_collections.netapp.storagegrid.plugins.module_utils.netapp as netapp_utils
274 from ansible.module_utils.basic import AnsibleModule
275 from ansible_collections.netapp.storagegrid.plugins.module_utils.netapp_module import NetAppModule
276 from ansible_collections.netapp.storagegrid.plugins.module_utils.netapp import SGRestAPI
277 from ansible_collections.netapp.storagegrid.plugins.module_utils.tools import first_inside_second_dict_or_list
278
279 __LOGGING__ = []
280
281
282 class ILM_rule(object):
283 """
284 Create, modify and delete StorageGRID ILM rule
285 """
286
287 def __init__(self):
288 """
289 Parse arguments, setup state variables,
290 check parameters and ensure request module is installed
291 """
292 self.argument_spec = netapp_utils.na_storagegrid_host_argument_spec()
293 self.argument_spec.update(
294 dict(
295 state=dict(required=False, type="str", choices=["present", "absent"], default="present"),
296 name=dict(required=True, type="str"),
297 bucket_filter=dict(
298 required=False,
299 type="dict",
300 options=dict(
301 operator=dict(required=True, type="str", choices=["contains", "endsWith", "equals", "startsWith"]),
302 value=dict(required=True, type="str"),
303 ),
304 ),
305 description=dict(required=False, type="str"),
306 filters=dict(
307 required=False,
308 type="list",
309 elements="dict",
310 default=[],
311 options=dict(
312 logicalOperator=dict(required=False, type="str"),
313 criteria=dict(
314 required=False,
315 type="list",
316 elements="dict",
317 options=dict(
318 operator=dict(
319 required=True,
320 type="str",
321 choices=[
322 "contains",
323 "notContains",
324 "equals",
325 "notEquals",
326 "startsWith",
327 "notStartsWith",
328 "endsWith",
329 "notEndsWith",
330 "exists",
331 "notExists",
332 "lessThan",
333 "lessThanOrEquals",
334 "greaterThan",
335 "greaterThanOrEquals",
336 ],
337 ),
338 metadataName=dict(required=True, type="str"),
339 metadataType=dict(required=False, type="str"),
340 value=dict(
341 required=False,
342 type="str",
343 ),
344 ),
345 ),
346 ),
347 ),
348 ingest_behavior=dict(required=False, type="str", choices=["strict", "balanced", "dual-commit"], default="balanced"),
349 placements=dict(
350 required=False,
351 type="list",
352 elements="dict",
353 options=dict(
354 retention=dict(
355 required=True,
356 type="dict",
357 options=dict(
358 after=dict(type="int", required=True),
359 duration=dict(type="int", required=False),
360 ),
361 ),
362 replicated=dict(
363 required=False,
364 type="list",
365 elements="dict",
366 options=dict(
367 poolId=dict(required=False, type="str"),
368 temporaryPoolId=dict(required=False, type="str"),
369 cloudStoragePoolId=dict(required=False, type="str"),
370 copies=dict(required=True, type="int"),
371 ),
372 ),
373 erasureCoded=dict(
374 required=False,
375 type="list",
376 elements="dict",
377 options=dict(profileId=dict(required=True, type="str"), poolId=dict(required=True, type="str")),
378 ),
379 ),
380 ),
381 reference_time=dict(
382 required=False, type="str", choices=["ingestTime", "lastAccessTime", "noncurrentTime", "userDefinedCreationTime"], default="ingestTime"
383 ),
384 tenant_account_id=dict(required=False, type="str"),
385 )
386 )
387 self.module = AnsibleModule(
388 argument_spec=self.argument_spec,
389 required_if=[("state", "present", ["placements"])],
390 supports_check_mode=True,
391 )
392 self.na_helper = NetAppModule()
393
394 # set up state variables
395 self.parameters = self.na_helper.set_parameters(self.module.params)
396 __LOGGING__.append("params: %s" % (self.module.params))
397 # Calling generic SG rest_api class
398 self.rest_api = SGRestAPI(self.module)
399 # Get API version
400 self.rest_api.get_sg_product_version()
401 self.api_version = self.rest_api.get_api_version()
402
403 # Create body for creation request (POST with state present)
404 self.data = {}
405 self.data["displayName"] = self.parameters["name"]
406 self.data["filters"] = self.parameters["filters"]
407 # optional parameters
408 if self.parameters.get("bucket_filter"):
409 self.data["bucketFilter"] = self.parameters.get("bucket_filter")
410 self.data["api"] = "s3OrSwift" # this deprecated parameter is required for PUT operations, in case "bucketFilter" is set. Dont ask me.
411 if self.parameters.get("description"):
412 self.data["description"] = self.parameters.get("description")
413 if self.parameters.get("ingest_behavior"):
414 self.data["ingestBehavior"] = self.parameters.get("ingest_behavior")
415 if self.parameters.get("placements"):
416 self.data["placements"] = self.parameters.get("placements")
417 if self.parameters.get("reference_time"):
418 self.data["referenceTime"] = self.parameters.get("reference_time")
419 if self.parameters.get("tenant_account_id"):
420 self.data["tenantAccountId"] = self.parameters.get("tenant_account_id")
421 __LOGGING__.append("data: %s" % (self.data))
422
423 def module_logging_handler(self, log_msg):
424 """Module logging handler"""
425 # Create timestamp for logs
426 date_now = datetime.now()
427 timestamp = date_now.strftime("%Y/%m/%d-%H:%M:%S")
428 # Log events
429 self.module.log(log_msg)
430 __LOGGING__.append("%s: %s" % (timestamp, log_msg))
431
432 def get_ilm_rule(self):
433 # Check if rule exists
434 # Return info if found, or None
435 api = "api/%s/grid/ilm-rules" % self.api_version
436 response, error = self.rest_api.get(api)
437
438 if error:
439 self.module.fail_json(msg=error, log=__LOGGING__)
440 self.module_logging_handler("all ILM rules: %s" % (response["data"]))
441 # if rule with 'name' exists, return it, else none
442 for rule in response["data"]:
443 if rule["displayName"] == self.parameters["name"]:
444 self.id = rule["id"]
445 return rule
446
447 return None
448
449 def create_ilm_rule(self):
450 __LOGGING__.append("creating ILM rule with payload: %s" % (self.data))
451 api = "api/%s/grid/ilm-rules" % self.api_version
452 response, error = self.rest_api.post(api, self.data)
453
454 if error:
455 self.module.fail_json(msg=error, log=__LOGGING__)
456
457 return response["data"]
458
459 def delete_ilm_rule(self):
460 __LOGGING__.append("deleting ILM rule")
461 api = "api/%s/grid/ilm-rules/%s" % (self.api_version, self.id)
462
463 response, error = self.rest_api.delete(api, None)
464 if error:
465 self.module.fail_json(msg=error, log=__LOGGING__)
466
467 def update_ilm_rule(self):
468 __LOGGING__.append("updating ILM rule with payload: %s" % (self.data))
469 api = "api/%s/grid/ilm-rules/%s" % (self.api_version, self.id)
470 response, error = self.rest_api.put(api, self.data)
471
472 if error:
473 self.module.fail_json(msg=error, log=__LOGGING__)
474
475 return response["data"]
476
477 def apply(self):
478 """
479 Perform pre-checks, call functions and exit
480 """
481
482 ilm_rule = self.get_ilm_rule()
483 self.module_logging_handler("got matching ILM rules: %s" % (ilm_rule))
484
485 cd_action = self.na_helper.get_cd_action(ilm_rule, self.parameters)
486
487 if cd_action is None and self.parameters["state"] == "present":
488 # let's see if we need to update parameters
489 if self.data.get("bucketFilter") and self.data.get("bucketFilter") != ilm_rule.get("bucketFilter"):
490 self.na_helper.changed = True
491 if self.data.get("description") and self.data.get("description") != ilm_rule.get("description"):
492 self.na_helper.changed = True
493 if self.data.get("filters") and not first_inside_second_dict_or_list(self.data.get("filters"), ilm_rule.get("filters")):
494 self.na_helper.changed = True
495 if self.data.get("ingestBehavior") and ilm_rule.get("ingestBehavior") != self.data.get("ingestBehavior"):
496 self.na_helper.changed = True
497 if self.data.get("placements") and not first_inside_second_dict_or_list(self.data.get("placements"), ilm_rule.get("placements")):
498 self.na_helper.changed = True
499 if self.data.get("referenceTime") and ilm_rule.get("referenceTime") != self.data.get("referenceTime"):
500 self.na_helper.changed = True
501 if self.data.get("tenantAccountId") and set(ilm_rule.get("tenantAccountId")) != set(self.data.get("tenantAccountId")):
502 self.na_helper.changed = True
503
504 result_message = ""
505 resp_data = ilm_rule
506 if self.na_helper.changed:
507 if self.module.check_mode:
508 pass
509 else:
510 if cd_action == "delete":
511 self.delete_ilm_rule()
512 resp_data = None
513 result_message = "ILM rule deleted"
514 __LOGGING__.append("ILM rule deleted")
515
516 elif cd_action == "create":
517 resp_data = self.create_ilm_rule()
518 result_message = "ILM rule created"
519 __LOGGING__.append("ILM rule created")
520
521 else:
522 resp_data = self.update_ilm_rule()
523 result_message = "ILM rule updated"
524 __LOGGING__.append("ILM rule updated")
525
526 self.module.exit_json(changed=self.na_helper.changed, msg=result_message, resp=resp_data, log=__LOGGING__)
527
528
529 def main():
530 """
531 Main function
532 """
533 na_sg_ilm_rule = ILM_rule()
534 na_sg_ilm_rule.apply()
535
536
537 if __name__ == "__main__":
538 main()