Debian Codegraph @

ansible_collections/netapp/ontap/plugins/modules/na_ontap_unix_group.py

raw
1 #!/usr/bin/python
2 """
3 na_ontap_unix_group
4 """
5
6 # (c) 2019-2025, NetApp, Inc
7 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
8 from __future__ import absolute_import, division, print_function
9 __metaclass__ = type
10
11
12 DOCUMENTATION = """
13 author: NetApp Ansible Team (@carchi8py) <[email protected]>
14 description:
15 - "Create/Delete Unix user group"
16 extends_documentation_fragment:
17 - netapp.ontap.netapp.na_ontap
18 module: na_ontap_unix_group
19 options:
20 state:
21 description:
22 - Whether the specified group should exist or not.
23 choices: ['present', 'absent']
24 type: str
25 default: 'present'
26
27 name:
28 description:
29 - Specifies UNIX group's name, unique for each group.
30 - Non-modifiable.
31 required: true
32 type: str
33
34 id:
35 description:
36 - Specifies an identification number for the UNIX group.
37 - Group ID is unique for each UNIX group.
38 - Required for create, modifiable.
39 type: int
40
41 vserver:
42 description:
43 - Specifies the Vserver for the UNIX group.
44 - Non-modifiable.
45 required: true
46 type: str
47
48 skip_name_validation:
49 description:
50 - Specifies if group name validation is skipped.
51 type: bool
52
53 users:
54 description:
55 - Specifies the users associated with this group. Should be comma separated.
56 - It represents the expected state of a list of users at any time.
57 - Add a user into group if it is specified in expected state but not in current state.
58 - Delete a user from group if it is specified in current state but not in expected state.
59 - To delete all current users, use '' as value.
60 type: list
61 elements: str
62 version_added: 2.9.0
63
64 short_description: NetApp ONTAP UNIX Group
65 version_added: 2.8.0
66
67 """
68
69 EXAMPLES = """
70 - name: Create UNIX group
71 netapp.ontap.na_ontap_unix_group:
72 state: present
73 name: SampleGroup
74 vserver: ansibleVServer
75 id: 2
76 users: user1,user2
77 hostname: "{{ netapp_hostname }}"
78 username: "{{ netapp_username }}"
79 password: "{{ netapp_password }}"
80
81 - name: Delete all users in UNIX group
82 netapp.ontap.na_ontap_unix_group:
83 state: present
84 name: SampleGroup
85 vserver: ansibleVServer
86 users: ''
87 hostname: "{{ netapp_hostname }}"
88 username: "{{ netapp_username }}"
89 password: "{{ netapp_password }}"
90
91 - name: Delete UNIX group
92 netapp.ontap.na_ontap_unix_group:
93 state: absent
94 name: SampleGroup
95 vserver: ansibleVServer
96 hostname: "{{ netapp_hostname }}"
97 username: "{{ netapp_username }}"
98 password: "{{ netapp_password }}"
99 """
100
101 RETURN = """
102 """
103 import traceback
104
105 from ansible.module_utils.basic import AnsibleModule
106 from ansible.module_utils._text import to_native
107 import ansible_collections.netapp.ontap.plugins.module_utils.netapp as netapp_utils
108 from ansible_collections.netapp.ontap.plugins.module_utils.netapp_module import NetAppModule
109 from ansible_collections.netapp.ontap.plugins.module_utils.netapp import OntapRestAPI
110 from ansible_collections.netapp.ontap.plugins.module_utils import rest_generic
111
112
113 class NetAppOntapUnixGroup:
114 """
115 Common operations to manage UNIX groups
116 """
117
118 def __init__(self):
119 self.argument_spec = netapp_utils.na_ontap_host_argument_spec()
120 self.argument_spec.update(dict(
121 state=dict(required=False, type='str', choices=['present', 'absent'], default='present'),
122 name=dict(required=True, type='str'),
123 id=dict(required=False, type='int'),
124 skip_name_validation=dict(required=False, type='bool'),
125 vserver=dict(required=True, type='str'),
126 users=dict(required=False, type='list', elements='str')
127 ))
128
129 self.module = AnsibleModule(
130 argument_spec=self.argument_spec,
131 supports_check_mode=True
132 )
133
134 self.na_helper = NetAppModule()
135 self.parameters = self.na_helper.set_parameters(self.module.params)
136 # Set up Rest API
137 self.rest_api = OntapRestAPI(self.module)
138 self.use_rest = self.rest_api.is_rest()
139 if self.use_rest:
140 self.parameters['users'] = self.safe_strip(self.parameters.get('users')) if self.parameters.get('users') is not None else None
141
142 if self.use_rest and not self.rest_api.meets_rest_minimum_version(self.use_rest, 9, 9, 1):
143 msg = 'REST requires ONTAP 9.9.1 or later for UNIX group APIs.'
144 self.use_rest = self.na_helper.fall_back_to_zapi(self.module, msg, self.parameters)
145
146 if not self.use_rest:
147 if netapp_utils.has_netapp_lib() is False:
148 self.module.fail_json(msg=netapp_utils.netapp_lib_is_required())
149 self.set_playbook_zapi_key_map()
150 self.server = netapp_utils.setup_na_ontap_zapi(module=self.module, vserver=self.parameters['vserver'])
151
152 def safe_strip(self, users):
153 """ strip the given user """
154 return [user.strip() for user in users if len(user.strip())]
155
156 def set_playbook_zapi_key_map(self):
157 self.na_helper.zapi_string_keys = {
158 'name': 'group-name'
159 }
160 self.na_helper.zapi_int_keys = {
161 'id': 'group-id'
162 }
163 self.na_helper.zapi_bool_keys = {
164 'skip_name_validation': 'skip-name-validation'
165 }
166
167 def get_unix_group(self):
168 """
169 Checks if the UNIX group exists.
170
171 :return:
172 dict() if group found
173 None if group is not found
174 """
175
176 get_unix_group = netapp_utils.zapi.NaElement('name-mapping-unix-group-get-iter')
177 attributes = {
178 'query': {
179 'unix-group-info': {
180 'group-name': self.parameters['name'],
181 'vserver': self.parameters['vserver'],
182 }
183 }
184 }
185 get_unix_group.translate_struct(attributes)
186 try:
187 result = self.server.invoke_successfully(get_unix_group, enable_tunneling=True)
188 if result.get_child_by_name('num-records') and int(result.get_child_content('num-records')) >= 1:
189 group_info = result['attributes-list']['unix-group-info']
190 group_details = dict()
191 else:
192 return None
193 except netapp_utils.zapi.NaApiError as error:
194 self.module.fail_json(msg='Error getting UNIX group %s: %s' % (self.parameters['name'], to_native(error)),
195 exception=traceback.format_exc())
196 for item_key, zapi_key in self.na_helper.zapi_string_keys.items():
197 group_details[item_key] = group_info[zapi_key]
198 for item_key, zapi_key in self.na_helper.zapi_int_keys.items():
199 group_details[item_key] = self.na_helper.get_value_for_int(from_zapi=True,
200 value=group_info[zapi_key])
201 if group_info.get_child_by_name('users') is not None:
202 group_details['users'] = [user.get_child_content('user-name')
203 for user in group_info.get_child_by_name('users').get_children()]
204 else:
205 group_details['users'] = None
206 return group_details
207
208 def create_unix_group(self):
209 """
210 Creates an UNIX group in the specified Vserver
211
212 :return: None
213 """
214 if self.parameters.get('id') is None:
215 self.module.fail_json(msg='Error: Missing a required parameter for create: (id)')
216
217 group_create = netapp_utils.zapi.NaElement('name-mapping-unix-group-create')
218 group_details = {}
219 for item in self.parameters:
220 if item in self.na_helper.zapi_string_keys:
221 zapi_key = self.na_helper.zapi_string_keys.get(item)
222 group_details[zapi_key] = self.parameters[item]
223 elif item in self.na_helper.zapi_bool_keys:
224 zapi_key = self.na_helper.zapi_bool_keys.get(item)
225 group_details[zapi_key] = self.na_helper.get_value_for_bool(from_zapi=False,
226 value=self.parameters[item])
227 elif item in self.na_helper.zapi_int_keys:
228 zapi_key = self.na_helper.zapi_int_keys.get(item)
229 group_details[zapi_key] = self.na_helper.get_value_for_int(from_zapi=True,
230 value=self.parameters[item])
231 group_create.translate_struct(group_details)
232 try:
233 self.server.invoke_successfully(group_create, enable_tunneling=True)
234 except netapp_utils.zapi.NaApiError as error:
235 self.module.fail_json(msg='Error creating UNIX group %s: %s' % (self.parameters['name'], to_native(error)),
236 exception=traceback.format_exc())
237 if self.parameters.get('users') is not None:
238 self.modify_users_in_group()
239
240 def delete_unix_group(self):
241 """
242 Deletes an UNIX group from a vserver
243
244 :return: None
245 """
246 group_delete = netapp_utils.zapi.NaElement.create_node_with_children(
247 'name-mapping-unix-group-destroy', **{'group-name': self.parameters['name']})
248
249 try:
250 self.server.invoke_successfully(group_delete, enable_tunneling=True)
251 except netapp_utils.zapi.NaApiError as error:
252 self.module.fail_json(msg='Error removing UNIX group %s: %s' % (self.parameters['name'], to_native(error)),
253 exception=traceback.format_exc())
254
255 def modify_unix_group(self, params):
256 """
257 Modify an UNIX group from a vserver
258 :param params: modify parameters
259 :return: None
260 """
261 # modify users requires separate zapi.
262 if 'users' in params:
263 self.modify_users_in_group()
264 if len(params) == 1:
265 return
266
267 group_modify = netapp_utils.zapi.NaElement('name-mapping-unix-group-modify')
268 group_details = {'group-name': self.parameters['name']}
269 for key in params:
270 if key in self.na_helper.zapi_int_keys:
271 zapi_key = self.na_helper.zapi_int_keys.get(key)
272 group_details[zapi_key] = self.na_helper.get_value_for_int(from_zapi=True,
273 value=params[key])
274 group_modify.translate_struct(group_details)
275
276 try:
277 self.server.invoke_successfully(group_modify, enable_tunneling=True)
278 except netapp_utils.zapi.NaApiError as error:
279 self.module.fail_json(msg='Error modifying UNIX group %s: %s' % (self.parameters['name'], to_native(error)),
280 exception=traceback.format_exc())
281
282 def modify_users_in_group(self):
283 """
284 Add/delete one or many users in a UNIX group
285
286 :return: None
287 """
288 current_users = self.get_unix_group().get('users')
289 expect_users = self.parameters.get('users')
290
291 if current_users is None:
292 current_users = []
293 if expect_users[0] == '' and len(expect_users) == 1:
294 expect_users = []
295 users_to_remove = list(set(current_users) - set(expect_users))
296 users_to_add = list(set(expect_users) - set(current_users))
297 if len(users_to_add) > 0:
298 for user in users_to_add:
299 add_user = netapp_utils.zapi.NaElement('name-mapping-unix-group-add-user')
300 group_details = {'group-name': self.parameters['name'], 'user-name': user}
301 add_user.translate_struct(group_details)
302 try:
303 self.server.invoke_successfully(add_user, enable_tunneling=True)
304 except netapp_utils.zapi.NaApiError as error:
305 self.module.fail_json(
306 msg='Error adding user %s to UNIX group %s: %s' % (user, self.parameters['name'], to_native(error)),
307 exception=traceback.format_exc())
308
309 if len(users_to_remove) > 0:
310 for user in users_to_remove:
311 delete_user = netapp_utils.zapi.NaElement('name-mapping-unix-group-delete-user')
312 group_details = {'group-name': self.parameters['name'], 'user-name': user}
313 delete_user.translate_struct(group_details)
314 try:
315 self.server.invoke_successfully(delete_user, enable_tunneling=True)
316 except netapp_utils.zapi.NaApiError as error:
317 self.module.fail_json(
318 msg='Error deleting user %s from UNIX group %s: %s' % (user, self.parameters['name'], to_native(error)),
319 exception=traceback.format_exc())
320
321 def get_unix_group_rest(self):
322 """
323 Retrieves the UNIX groups for all of the SVMs.
324 UNIX users who are the members of the group are also displayed.
325 """
326 if not self.use_rest:
327 return self.get_unix_group()
328 query = {'svm.name': self.parameters.get('vserver'),
329 'name': self.parameters.get('name')}
330 api = 'name-services/unix-groups'
331 fields = 'svm.uuid,id,name,users.name'
332 record, error = rest_generic.get_one_record(self.rest_api, api, query, fields)
333 if error:
334 self.module.fail_json(msg="Error getting UNIX group: %s" % error)
335 if record:
336 if 'users' in record:
337 record['users'] = [user['name'] for user in record['users']]
338 return {
339 'svm': {'uuid': self.na_helper.safe_get(record, ['svm', 'uuid'])},
340 'name': self.na_helper.safe_get(record, ['name']),
341 'id': self.na_helper.safe_get(record, ['id']),
342 'users': self.na_helper.safe_get(record, ['users'])
343 }
344 return None
345
346 def create_unix_group_rest(self):
347 """
348 Creates the local UNIX group configuration for the specified SVM.
349 Group name and group ID are mandatory parameters.
350 """
351 if not self.use_rest:
352 return self.create_unix_group()
353
354 body = {'svm.name': self.parameters.get('vserver')}
355 if 'name' in self.parameters:
356 body['name'] = self.parameters['name']
357 if 'id' in self.parameters:
358 body['id'] = self.parameters['id']
359 if 'skip_name_validation' in self.parameters:
360 body['skip_name_validation'] = self.parameters['skip_name_validation']
361 api = 'name-services/unix-groups'
362 dummy, error = rest_generic.post_async(self.rest_api, api, body)
363 if error is not None:
364 self.module.fail_json(msg="Error creating UNIX group: %s" % error)
365 if self.parameters.get('users') is not None:
366 self.modify_users_in_group_rest()
367
368 def modify_users_in_group_rest(self, current=None):
369 """
370 Add/delete one or many users in a UNIX group
371 """
372 body = {'records': []}
373 # current is to add user when creating a group
374 if not current:
375 current = self.get_unix_group_rest()
376 current_users = current['users'] or []
377 expect_users = self.parameters.get('users')
378 users_to_remove = list(set(current_users) - set(expect_users))
379 users_to_add = list(set(expect_users) - set(current_users))
380 if len(users_to_add) > 0:
381 body['records'] = [{'name': user} for user in users_to_add]
382 if 'skip_name_validation' in self.parameters:
383 body['skip_name_validation'] = self.parameters['skip_name_validation']
384 api = 'name-services/unix-groups/%s/%s/users' % (current['svm']['uuid'], current['name'])
385 dummy, error = rest_generic.post_async(self.rest_api, api, body)
386 if error is not None:
387 self.module.fail_json(msg="Error Adding user to UNIX group: %s" % error)
388
389 if len(users_to_remove) > 0:
390 for user in users_to_remove:
391 api = 'name-services/unix-groups/%s/%s/users' % (current['svm']['uuid'], current['name'])
392 dummy, error = rest_generic.delete_async(self.rest_api, api, user, body=None)
393 if error is not None:
394 self.module.fail_json(msg="Error removing user from UNIX group: %s" % error)
395
396 def delete_unix_group_rest(self, current):
397 """
398 Deletes a UNIX user configuration for the specified SVM with rest API.
399 """
400 if not self.use_rest:
401 return self.delete_unix_group()
402
403 api = 'name-services/unix-groups/%s' % current['svm']['uuid']
404 dummy, error = rest_generic.delete_async(self.rest_api, api, self.parameters['name'])
405 if error is not None:
406 self.module.fail_json(msg="Error deleting UNIX group: %s" % error)
407
408 def modify_unix_group_rest(self, modify, current=None):
409 """
410 Updates UNIX group information for the specified user and SVM with rest API.
411 """
412 if not self.use_rest:
413 return self.modify_unix_group(modify)
414
415 if 'users' in modify:
416 self.modify_users_in_group_rest(current)
417 if len(modify) == 1:
418 return
419
420 api = 'name-services/unix-groups/%s' % current['svm']['uuid']
421 body = {}
422 if 'id' in modify:
423 body['id'] = modify['id']
424 if body:
425 dummy, error = rest_generic.patch_async(self.rest_api, api, self.parameters['name'], body)
426 if error is not None:
427 self.module.fail_json(msg="Error on modifying UNIX group: %s" % error)
428
429 def apply(self):
430 """
431 Invoke appropriate action based on playbook parameters
432
433 :return: None
434 """
435 cd_action = None
436 current = self.get_unix_group_rest()
437 if current and current['users'] is None:
438 current['users'] = []
439 cd_action = self.na_helper.get_cd_action(current, self.parameters)
440 modify = self.na_helper.get_modified_attributes(current, self.parameters) if cd_action is None else None
441 if self.na_helper.changed and not self.module.check_mode:
442 if cd_action == 'create':
443 self.create_unix_group_rest()
444 elif cd_action == 'delete':
445 self.delete_unix_group_rest(current)
446 else:
447 self.modify_unix_group_rest(modify, current)
448 result = netapp_utils.generate_result(self.na_helper.changed, cd_action, modify)
449 self.module.exit_json(**result)
450
451
452 def main():
453 obj = NetAppOntapUnixGroup()
454 obj.apply()
455
456
457 if __name__ == '__main__':
458 main()