Debian Codegraph @

ansible_collections/netapp/storagegrid/plugins/modules/na_sg_org_group.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 tenant Groups"""
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_group
22 short_description: NetApp StorageGRID manage groups within a tenancy.
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, Update, Delete Groups within NetApp StorageGRID tenant.
29 options:
30 state:
31 description:
32 - Whether the specified group should exist or not.
33 type: str
34 choices: ['present', 'absent']
35 default: present
36 unique_name:
37 description:
38 - Unique Name for the group. Must begin with C(group/) or C(federated-group/).
39 - Required for create, modify or delete operation.
40 type: str
41 required: true
42 display_name:
43 description:
44 - Name of the group.
45 - Required for create operation.
46 type: str
47 read_only:
48 description:
49 - Users can view settings and features but cannot make changes or perform operations.
50 type: bool
51 version_added: '21.14.0'
52 management_policy:
53 description:
54 - Management access controls granted to the group within the tenancy.
55 type: dict
56 suboptions:
57 manage_all_containers:
58 description:
59 - Allows users to manage the settings for all S3 buckets in the tenant account, regardless of S3 bucket or group policies.
60 type: bool
61 manage_endpoints:
62 description:
63 - Allows users to use the Tenant Manager or the Tenant Management API to create or edit endpoints.
64 - Endpoints are used as the destination for StorageGRID platform services.
65 type: bool
66 manage_own_s3_credentials:
67 description:
68 - Allows users to create and remove their own S3 access keys.
69 - Users who do not have this permission do not see the S3 > My Credentials menu option.
70 type: bool
71 root_access:
72 description:
73 - Provides full access to the Tenant Manager and the Tenant Management API.
74 type: bool
75 s3_console:
76 description:
77 - Allows use of S3 Console to view and manage bucket objects (supported from SG 11.8 or later).
78 - It was experimental in earlier SG versions.
79 type: bool
80 version_added: '21.16.0'
81 view_all_containers:
82 description:
83 - Allows users to view all S3 buckets in the tenant account.
84 - Requires storageGRID 11.8 or later.
85 type: bool
86 version_added: '21.16.0'
87 s3_policy:
88 description:
89 - StorageGRID S3 Group Policy.
90 type: json
91 """
92
93 EXAMPLES = """
94 - name: create a group
95 netapp.storagegrid.na_sg_org_group:
96 api_url: "https://<storagegrid-endpoint-url>"
97 auth_token: "storagegrid-auth-token"
98 validate_certs: false
99 state: present
100 display_name: ansiblegroup1
101 unique_name: group/ansiblegroup1
102 management_policy:
103 manage_all_containers: true
104 manage_endpoints: true
105 manage_own_s3_credentials: false
106 root_access: false
107 s3_console: true
108 view_all_containers: true
109 s3_policy: {"Statement":[{"Effect":"Deny", "Action":"s3:*", "Resource":"arn:aws:s3:::*"}]}
110 """
111
112 RETURN = """
113 resp:
114 description: Returns information about the StorageGRID tenant group attributes.
115 returned: success
116 type: dict
117 sample: {
118 "displayName": "Example Group",
119 "policies": {
120 "management": {
121 "manageAllContainers": true,
122 "manageEndpoints": true,
123 "manageOwnS3Credentials": true,
124 "rootAccess": true,
125 "manageOwnContainerObjects": true,
126 "viewAllContainers": true
127 },
128 "s3": {...},
129 "swift": {...}
130 },
131 "uniqueName": "group/examplegroup",
132 "accountId": "12345678901234567890",
133 "id": "00000000-0000-0000-0000-000000000000",
134 "federated": false,
135 "groupURN": "urn:sgws:identity::12345678901234567890:group/examplegroup"
136 }
137 """
138
139 import json
140 import re
141
142 import ansible_collections.netapp.storagegrid.plugins.module_utils.netapp as netapp_utils
143 from ansible.module_utils.basic import AnsibleModule
144 from ansible_collections.netapp.storagegrid.plugins.module_utils.netapp_module import NetAppModule
145 from ansible_collections.netapp.storagegrid.plugins.module_utils.netapp import SGRestAPI
146
147
148 class SgOrgGroup(object):
149 """
150 Create, modify and delete StorageGRID Tenant Account
151 """
152
153 def __init__(self):
154 """
155 Parse arguments, setup state variables,
156 check parameters and ensure request module is installed
157 """
158 self.argument_spec = netapp_utils.na_storagegrid_host_argument_spec()
159 self.argument_spec.update(
160 dict(
161 state=dict(required=False, type="str", choices=["present", "absent"], default="present"),
162 display_name=dict(required=False, type="str"),
163 unique_name=dict(required=True, type="str"),
164 read_only=dict(required=False, type="bool"),
165 management_policy=dict(
166 required=False,
167 type="dict",
168 options=dict(
169 manage_all_containers=dict(required=False, type="bool"),
170 manage_endpoints=dict(required=False, type="bool"),
171 manage_own_s3_credentials=dict(required=False, type="bool"),
172 root_access=dict(required=False, type="bool"),
173 s3_console=dict(required=False, type="bool"),
174 view_all_containers=dict(required=False, type="bool"),
175 ),
176 ),
177 s3_policy=dict(required=False, type="json"),
178 )
179 )
180 parameter_map = {
181 "manage_all_containers": "manageAllContainers",
182 "manage_endpoints": "manageEndpoints",
183 "manage_own_s3_credentials": "manageOwnS3Credentials",
184 "root_access": "rootAccess",
185 "s3_console": "manageOwnContainerObjects",
186 "view_all_containers": "viewAllContainers",
187 }
188 self.module = AnsibleModule(
189 argument_spec=self.argument_spec,
190 # required_if=[("state", "present", ["display_name"])],
191 supports_check_mode=True,
192 )
193
194 self.na_helper = NetAppModule()
195
196 # set up state variables
197 self.parameters = self.na_helper.set_parameters(self.module.params)
198 # Calling generic SG rest_api class
199 self.rest_api = SGRestAPI(self.module)
200 # Get API version
201 self.rest_api.get_sg_product_version(api_root="org")
202 self.api_version = self.rest_api.get_api_version()
203
204 # Checking for the parameters passed and create new parameters list
205 self.data = {}
206 self.data["displayName"] = self.parameters.get("display_name")
207 self.data["uniqueName"] = self.parameters["unique_name"]
208 if self.parameters.get("read_only"):
209 self.data["managementReadOnly"] = self.parameters["read_only"]
210 # Only add the parameter if value is True, as JSON response does not include non-true objects
211 self.data["policies"] = {}
212
213 if self.parameters.get("management_policy"):
214 if self.parameters["management_policy"]["view_all_containers"]:
215 self.rest_api.fail_if_not_sg_minimum_version("view_all_containers", 11, 8)
216 self.data["policies"] = {
217 "management": dict(
218 (parameter_map[k], v) for (k, v) in self.parameters["management_policy"].items() if v
219 )
220 }
221 if not self.data["policies"].get("management"):
222 self.data["policies"]["management"] = None
223
224 if self.parameters.get("s3_policy"):
225 try:
226 self.data["policies"]["s3"] = json.loads(self.parameters["s3_policy"])
227 except ValueError:
228 self.module.fail_json(msg="Failed to decode s3_policy. Invalid JSON.")
229
230 self.re_local_group = re.compile("^group/")
231 self.re_fed_group = re.compile("^federated-group/")
232
233 if (
234 self.re_local_group.match(self.parameters["unique_name"]) is None
235 and self.re_fed_group.match(self.parameters["unique_name"]) is None
236 ):
237 self.module.fail_json(msg="unique_name must begin with 'group/' or 'federated-group/'")
238
239 def get_org_group(self, unique_name):
240 # Use the unique name to check if the group exists
241 api = "api/%s/org/groups/%s" % (self.api_version, unique_name)
242 response, error = self.rest_api.get(api)
243
244 if error:
245 if response["code"] != 404:
246 self.module.fail_json(msg=error)
247 else:
248 return response["data"]
249 return None
250
251 def create_org_group(self):
252 api = "api/%s/org/groups" % 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 delete_org_group(self, group_id):
262 api = "api/%s/org/groups/%s" % (self.api_version, group_id)
263
264 self.data = None
265 response, error = self.rest_api.delete(api, self.data)
266 if error:
267 self.module.fail_json(msg=error)
268
269 def update_org_group(self, group_id):
270 api = "api/%s/org/groups/%s" % (self.api_version, group_id)
271
272 response, error = self.rest_api.put(api, self.data)
273 if error:
274 self.module.fail_json(msg=error)
275
276 return response["data"]
277
278 def apply(self):
279 """
280 Perform pre-checks, call functions and exit
281 """
282 org_group = self.get_org_group(self.parameters["unique_name"])
283
284 cd_action = self.na_helper.get_cd_action(org_group, self.parameters)
285
286 if cd_action is None and self.parameters["state"] == "present":
287 # let's see if we need to update parameters
288
289 if self.parameters.get("management_policy"):
290 if org_group.get("policies") is None or org_group.get("policies", {}).get("management") != self.data["policies"]["management"]:
291 self.na_helper.changed = True
292 if self.parameters.get("s3_policy"):
293 if org_group.get("policies") is None or org_group.get("policies", {}).get("s3") != self.data["policies"]["s3"]:
294 self.na_helper.changed = True
295 if self.parameters.get("read_only") is not None and self.parameters.get("read_only") != org_group["managementReadOnly"]:
296 self.na_helper.changed = True
297
298 result_message = ""
299 resp_data = org_group
300 if self.na_helper.changed:
301 if self.module.check_mode:
302 pass
303 else:
304 if cd_action == "delete":
305 self.delete_org_group(org_group["id"])
306 result_message = "Org Group deleted"
307
308 elif cd_action == "create":
309 resp_data = self.create_org_group()
310 result_message = "Org Group created"
311
312 else:
313 # for a federated group, the displayName parameter needs to be specified
314 # and must match the existing displayName
315 if self.re_fed_group.match(self.parameters["unique_name"]):
316 self.data["displayName"] = org_group["displayName"]
317
318 resp_data = self.update_org_group(org_group["id"])
319 result_message = "Org Group updated"
320
321 self.module.exit_json(changed=self.na_helper.changed, msg=result_message, resp=resp_data)
322
323
324 def main():
325 """
326 Main function
327 """
328 na_sg_org_group = SgOrgGroup()
329 na_sg_org_group.apply()
330
331
332 if __name__ == "__main__":
333 main()