Refactored identity_group{,_info} modules

Change-Id: I72dce1278a7623d4f68cabcceafcdfefda900195

plugins/modules/identity_group.py

@@ -4,94 +4,94 @@
 # Copyright (c) 2016 IBM
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-DOCUMENTATION = '''
+DOCUMENTATION = r'''
 ---
 module: identity_group
-short_description: Manage OpenStack Identity Groups
+short_description: Manage a OpenStack identity (Keystone) group
 author: OpenStack Ansible SIG
 description:
-    - Manage OpenStack Identity Groups. Groups can be created, deleted or
-      updated. Only the I(description) value can be updated.
+  - Create, update or delete an OpenStack identity (Keystone) group.
 options:
-   description:
-     description:
-        - Group description
-     type: str
-   domain_id:
-     description:
-        - Domain id to create the group in if the cloud supports domains.
-     type: str
-   name:
-     description:
-        - Group name
-     required: true
-     type: str
-   state:
-     description:
-       - Should the resource be present or absent.
-     choices: [present, absent]
-     default: present
-     type: str
+  description:
+    description:
+      - Group description.
+    type: str
+  domain_id:
+    description:
+      - Domain id to create the group in.
+    type: str
+  name:
+    description:
+      - Group name
+    required: true
+    type: str
+  state:
+    description:
+      - Should the resource be present or absent.
+    choices: ['present', 'absent']
+    default: present
+    type: str
 extends_documentation_fragment:
-- openstack.cloud.openstack
+  - openstack.cloud.openstack
 '''
 
-EXAMPLES = '''
-# Create a group named "demo"
-- openstack.cloud.identity_group:
+EXAMPLES = r'''
+- name: Create a group named "demo"
+  openstack.cloud.identity_group:
     cloud: mycloud
     state: present
     name: demo
     description: "Demo Group"
     domain_id: demoid
 
-# Update the description on existing "demo" group
-- openstack.cloud.identity_group:
+- name: Update the description on existing demo group
+  openstack.cloud.identity_group:
     cloud: mycloud
     state: present
     name: demo
     description: "Something else"
     domain_id: demoid
 
-# Delete group named "demo"
-- openstack.cloud.identity_group:
+- name: Delete group named demo
+  openstack.cloud.identity_group:
     cloud: mycloud
     state: absent
     name: demo
 '''
 
-RETURN = '''
+RETURN = r'''
 group:
-    description: Dictionary describing the group.
-    returned: On success when I(state) is 'present'.
-    type: dict
-    contains:
-        description:
-            description: Group description
-            type: str
-            sample: "Demo Group"
-        domain_id:
-            description: Domain for the group
-            type: str
-            sample: "default"
-        id:
-            description: Unique group ID
-            type: str
-            sample: "ee6156ff04c645f481a6738311aea0b0"
-        name:
-            description: Group name
-            type: str
-            sample: "demo"
+  description: Dictionary describing the identity group.
+  returned: On success when I(state) is C(present).
+  type: dict
+  contains:
+    description:
+      description: Group description
+      type: str
+      sample: "Demo Group"
+    domain_id:
+      description: Domain for the group
+      type: str
+      sample: "default"
+    id:
+      description: Unique group ID
+      type: str
+      sample: "ee6156ff04c645f481a6738311aea0b0"
+    name:
+      description: Group name
+      type: str
+      sample: "demo"
 '''
 
 from ansible_collections.openstack.cloud.plugins.module_utils.openstack import OpenStackModule
+from ansible_collections.openstack.cloud.plugins.module_utils.resource import StateMachine
 
 
 class IdentityGroupModule(OpenStackModule):
     argument_spec = dict(
-        name=dict(required=True),
         description=dict(),
         domain_id=dict(),
+        name=dict(required=True),
         state=dict(default='present', choices=['absent', 'present']),
     )
 
@@ -99,57 +99,40 @@ class IdentityGroupModule(OpenStackModule):
         supports_check_mode=True
     )
 
-    def _system_state_change(self, state, group):
-        if state == 'present' and not group:
-            return True
-        if state == 'present' and self._build_update(group):
-            return True
-        if state == 'absent' and group:
-            return True
-        return False
+    class _StateMachine(StateMachine):
+        def _find(self, attributes, **kwargs):
+            kwargs = dict((k, attributes[k])
+                          for k in ['domain_id']
+                          if k in attributes and attributes[k] is not None)
 
-    def _build_update(self, group):
-        update = {}
-        desc = self.params['description']
-        if desc is not None and desc != group.description:
-            update['description'] = desc
-        return update
+            return self.find_function(attributes['name'], **kwargs)
 
     def run(self):
-        name = self.params['name']
-        description = self.params['description']
-        state = self.params['state']
-        domain_id = self.params['domain_id']
+        sm = self._StateMachine(connection=self.conn,
+                                service_name='identity',
+                                type_name='group',
+                                sdk=self.sdk)
 
-        group_filters = {}
-        if domain_id is not None:
-            group_filters['domain_id'] = domain_id
+        kwargs = dict((k, self.params[k])
+                      for k in ['state', 'timeout']
+                      if self.params[k] is not None)
 
-        group = self.conn.identity.find_group(name, **group_filters)
+        kwargs['attributes'] = \
+            dict((k, self.params[k])
+                 for k in ['description', 'domain_id', 'name']
+                 if self.params[k] is not None)
 
-        if self.ansible.check_mode:
-            self.exit_json(changed=self._system_state_change(state, group))
+        group, is_changed = sm(check_mode=self.ansible.check_mode,
+                               updateable_attributes=None,
+                               non_updateable_attributes=['domain_id'],
+                               wait=False,
+                               **kwargs)
 
-        changed = False
-        if state == 'present':
-            if group is None:
-                kwargs = dict(description=description, domain_id=domain_id)
-                kwargs = {k: v for k, v in kwargs.items() if v is not None}
-                group = self.conn.identity.create_group(
-                    name=name, **kwargs)
-                changed = True
-            else:
-                update = self._build_update(group)
-                if update:
-                    group = self.conn.identity.update_group(group, **update)
-                    changed = True
-            group = group.to_dict(computed=False)
-            self.exit_json(changed=changed, group=group)
-
-        elif state == 'absent' and group is not None:
-            self.conn.identity.delete_group(group)
-            changed = True
-        self.exit_json(changed=changed)
+        if group is None:
+            self.exit_json(changed=is_changed)
+        else:
+            self.exit_json(changed=is_changed,
+                           group=group.to_dict(computed=False))
 
 
 def main():

plugins/modules/identity_group_info.py

@@ -4,108 +4,74 @@
 # Copyright (c) 2019, Phillipe Smith <phillipelnx@gmail.com>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-DOCUMENTATION = '''
+DOCUMENTATION = r'''
 ---
 module: identity_group_info
-short_description: Retrieve info about one or more OpenStack groups
+short_description: Fetch OpenStack identity (Keystone) groups
 author: OpenStack Ansible SIG
 description:
-    - Retrieve info about a one or more OpenStack groups.
+  - Fetch OpenStack identity (Keystone) groups.
 options:
-   name:
-     description:
-        - Name or ID of the group.
-     type: str
-   domain:
-     description:
-        - Name or ID of the domain containing the group if the cloud supports domains
-     type: str
-   filters:
-     description:
-        - A dictionary of meta data to use for further filtering.  Elements of
-          this dictionary may be additional dictionaries.
-     type: dict
+  domain:
+    description:
+      - Name or ID of the domain containing the group.
+    type: str
+  filters:
+    description:
+      - A dictionary of meta data to use for further filtering. Elements of
+        this dictionary may be additional dictionaries.
+    type: dict
+  name:
+    description:
+      - Name or ID of the group.
+    type: str
 extends_documentation_fragment:
-- openstack.cloud.openstack
+  - openstack.cloud.openstack
 '''
 
-EXAMPLES = '''
-# Gather info about previously created groups
-- name: gather info
-  hosts: localhost
-  tasks:
-    - name: Gather info about previously created groups
-      openstack.cloud.identity_group_info:
-        cloud: awesomecloud
-      register: openstack_groups
-    - debug:
-        var: openstack_groups
+EXAMPLES = r'''
+- name: Gather previously created groups
+  openstack.cloud.identity_group_info:
+    cloud: awesomecloud
 
-# Gather info about a previously created group by name
-- name: gather info
-  hosts: localhost
-  tasks:
-    - name: Gather info about a previously created group by name
-      openstack.cloud.identity_group_info:
-        cloud: awesomecloud
-        name: demogroup
-      register: openstack_groups
-    - debug:
-        var: openstack_groups
+- name: Gather previously created groups by name
+  openstack.cloud.identity_group_info:
+    cloud: awesomecloud
+    name: demogroup
 
-# Gather info about a previously created group in a specific domain
-- name: gather info
-  hosts: localhost
-  tasks:
-    - name: Gather info about a previously created group in a specific domain
-      openstack.cloud.identity_group_info:
-        cloud: awesomecloud
-        name: demogroup
-        domain: admindomain
-      register: openstack_groups
-    - debug:
-        var: openstack_groups
+- name: Gather previously created groups in a specific domain
+  openstack.cloud.identity_group_info:
+    cloud: awesomecloud
+    domain: admindomain
 
-# Gather info about a previously created group in a specific domain with filter
-- name: gather info
-  hosts: localhost
-  tasks:
-    - name: Gather info about a previously created group in a specific domain with filter
-      openstack.cloud.identity_group_info:
-        cloud: awesomecloud
-        name: demogroup
-        domain: admindomain
-        filters:
-          enabled: False
-      register: openstack_groups
-    - debug:
-        var: openstack_groups
+- name: Gather and filter previously created groups
+  openstack.cloud.identity_group_info:
+    cloud: awesomecloud
+    name: demogroup
+    domain: admindomain
+    filters:
+      is_enabled: False
 '''
 
-
-RETURN = '''
+RETURN = r'''
 groups:
-    description: Dictionary describing all the matching groups.
-    returned: always, but can be an empty list
-    type: list
-    elements: dict
-    contains:
-        name:
-            description: Name given to the group.
-            returned: success
-            type: str
-        description:
-            description: Description of the group.
-            returned: success
-            type: str
-        id:
-            description: Unique UUID.
-            returned: success
-            type: str
-        domain_id:
-            description: Domain ID containing the group (keystone v3 clouds only)
-            returned: success
-            type: bool
+  description: Dictionary describing all matching identity groups.
+  returned: always
+  type: list
+  elements: dict
+  contains:
+    name:
+      description: Name given to the group.
+      type: str
+    description:
+      description: Description of the group.
+      type: str
+    id:
+      description: Unique UUID.
+      type: str
+    domain_id:
+      description: Domain ID containing the group (keystone v3 clouds only)
+      type: bool
 '''
 
 from ansible_collections.openstack.cloud.plugins.module_utils.openstack import OpenStackModule
@@ -113,9 +79,9 @@ from ansible_collections.openstack.cloud.plugins.module_utils.openstack import O
 
 class IdentityGroupInfoModule(OpenStackModule):
     argument_spec = dict(
-        name=dict(),
         domain=dict(),
         filters=dict(type='dict'),
+        name=dict(),
     )
     module_kwargs = dict(
         supports_check_mode=True
@@ -123,20 +89,19 @@ class IdentityGroupInfoModule(OpenStackModule):
 
     def run(self):
         name = self.params['name']
-        domain = self.params['domain']
         filters = self.params['filters'] or {}
 
-        args = {}
-        if domain:
-            dom = self.conn.identity.find_domain(domain)
-            if dom:
-                args['domain_id'] = dom['id']
-            else:
-                self.fail_json(msg='Domain name or ID does not exist')
+        kwargs = {}
+        domain_name_or_id = self.params['domain']
+        if domain_name_or_id:
+            domain = self.conn.identity.find_domain(domain_name_or_id)
+            if domain is None:
+                self.exit_json(changed=False, groups=[])
+            kwargs['domain_id'] = domain['id']
 
-        groups = self.conn.search_groups(name, filters, **args)
-        groups = [g.to_dict(computed=False) for g in groups]
-        self.exit_json(changed=False, groups=groups)
+        groups = self.conn.search_groups(name, filters, **kwargs)
+        self.exit_json(changed=False,
+                       groups=[g.to_dict(computed=False) for g in groups])
 
 
 def main():