Refactored project{,_info} modules

Change-Id: I863d08c42b4c708444b74e3d47f0ca70a8ff94fd

ci/roles/compute_flavor_access/tasks/main.yml

@@ -21,8 +21,8 @@
 - name: Verify demo project
   assert:
     that:
-      - projects.openstack_projects|length == 1
+      - projects.projects|length == 1
-      - projects.openstack_projects.0.name == "demo"
+      - projects.projects.0.name == "demo"
 
 - name: Grant access to flavor
   openstack.cloud.compute_flavor_access:
@@ -47,7 +47,7 @@
   assert:
     that:
       - (flavor_show.stdout | from_json).name == 'ansible_flavor'
-      - projects.openstack_projects.0.id in (flavor_show.stdout | from_json).access_project_ids
+      - projects.projects.0.id in (flavor_show.stdout | from_json).access_project_ids
 
 - name: Grant access to flavor again
   openstack.cloud.compute_flavor_access:

ci/roles/image/tasks/main.yml

@@ -239,8 +239,8 @@
      state: present
      name: image_owner_project
      description: Project owning test image
-     domain_id: default
+     domain: default
-     enabled: True
+     is_enabled: True
   register: owner_project
 
 - name: Create raw image (owner by project name)
@@ -309,7 +309,7 @@
      cloud: "{{ cloud }}"
      state: absent
      name: image_owner_project
-     domain_id: default
+     domain: default
 
 - name: Delete test image file
   file:

ci/roles/neutron_rbac_policy/tasks/main.yml

@@ -5,8 +5,8 @@
      state: present
      name: ansible_source_project
      description: Source project for network RBAC test
-     domain_id: default
+     domain: default
-     enabled: True
+     is_enabled: True
   register: source_project
 
 - name: Create network

ci/roles/project/defaults/main.yml

@@ -1,4 +1,4 @@
-project_fields:
+expected_fields:
   - description
   - domain_id
   - id

ci/roles/project/tasks/main.yml

@@ -1,155 +1,181 @@
 ---
-- name: Ensure project doesn't exist before tests
+- name: Create project
   openstack.cloud.project:
     cloud: "{{ cloud }}"
-    state: absent
+    state: present
     name: ansible_project
+    description: dummy description
+    domain: default
+    is_enabled: True
+  register: project
 
-- block:
+- name: Assert return values of project module
-  - name: Create project
+  assert:
-    openstack.cloud.project:
+    that:
-      cloud: "{{ cloud }}"
+      - project is changed
-      state: present
+      # allow new fields to be introduced but prevent fields from being removed
-      name: ansible_project
+      - expected_fields|difference(project.project.keys())|length == 0
-      description: dummy description
-      domain: default
-      enabled: True
-    register: project
 
-  - name: Assert project changed
+- name: Fetch project
-    assert:
+  openstack.cloud.project_info:
-       that: project is changed
+     cloud: "{{ cloud }}"
+     name: ansible_project
+  register: project
 
-  - name: Assert project fields
+- name: Assert project
-    assert:
+  assert:
-      that: item in project['project']
+    that:
-    loop: "{{ project_fields }}"
+      - project.projects | length == 1
+      - project.projects.0.name == 'ansible_project'
+      - project.projects.0.description == 'dummy description'
 
-  - name: Get project
+- name: Create project again
-    openstack.cloud.project_info:
+  openstack.cloud.project:
-       cloud: "{{ cloud }}"
+    cloud: "{{ cloud }}"
-       name: ansible_project
+    state: present
-    register: project_info
+    name: ansible_project
+    description: dummy description
+    domain: default
+    is_enabled: True
+  register: project
 
-  - name: Assert project
+- name: Assert return values of project module
-    assert:
+  assert:
-      that:
+    that:
-        - project_info.openstack_projects | length == 1
+      - project is not changed
-        - project_info.openstack_projects[0]['name'] == 'ansible_project'
+      # allow new fields to be introduced but prevent fields from being removed
-        - project_info.openstack_projects[0]['description'] == 'dummy description'
+      - expected_fields|difference(project.project.keys())|length == 0
 
-- block:
+- name: Update project
-  - name: Create identical project
+  openstack.cloud.project:
-    openstack.cloud.project:
+    cloud: "{{ cloud }}"
-      cloud: "{{ cloud }}"
+    state: present
-      state: present
+    name: ansible_project
-      name: ansible_project
+    description: new description
-      description: dummy description
+    extra_specs:
-      domain: default
+      tags:
-      enabled: True
+        - example_tag
-    register: project
+  register: project
 
-  - name: Assert project not changed
+- name: Assert project changed
-    assert:
+  assert:
-       that: project is not changed
+     that:
+       - project is changed
+       - project.project.description == 'new description'
 
-  - name: Assert project fields
+- name: Fetch all projects
-    assert:
+  openstack.cloud.project_info:
-      that: item in project['project']
+    cloud: "{{ cloud }}"
-    loop: "{{ project_fields }}"
+  register: projects
 
+- name: Assert return values of project_info module
+  assert:
+    that:
+      - projects.projects | length > 0
+      # allow new fields to be introduced but prevent fields from being removed
+      - expected_fields|difference(projects.projects.0.keys())|length == 0
 
-- block:
+- name: Fetch project by name
-  - name: Update project
+  openstack.cloud.project_info:
-    openstack.cloud.project:
+    cloud: "{{ cloud }}"
-      cloud: "{{ cloud }}"
+    name: 'ansible_project'
-      state: present
+  register: projects
-      name: ansible_project
-      description: new description
-      properties:
-        tags:
-          - example_tag
-    register: project
 
-  - name: Assert project changed
+- name: Assert return values of project_info module
-    assert:
+  assert:
-       that: project is changed
+    that:
+      - projects.projects | length == 1
+      - projects.projects.0.name == 'ansible_project'
 
-  - name: Assert project fields
+- name: Fetch projects with filter
-    assert:
+  openstack.cloud.project_info:
-      that: item in project['project']
+    cloud: "{{ cloud }}"
-    loop: "{{ project_fields }}"
+    filters:
+      name: 'ansible_project'
+  register: projects
 
-  - name: Get project
+- name: Assert return values of project_info module
-    openstack.cloud.project_info:
+  assert:
-       cloud: "{{ cloud }}"
+    that:
-       name: ansible_project
+      - projects.projects | length == 1
-    register: project_info
+      - projects.projects.0.name == 'ansible_project'
 
-  - name: Assert project
+- name: Fetch project by name and domain
-    assert:
+  openstack.cloud.project_info:
-      that:
+    cloud: "{{ cloud }}"
-        - project_info.openstack_projects | length == 1
+    name: 'ansible_project'
-        - project_info.openstack_projects[0]['description'] == 'new description'
+    domain: 'default'
+  register: projects
 
-- block:
+- name: Assert return values of project_info module
-  - name: Delete project
+  assert:
-    openstack.cloud.project:
+    that:
-       cloud: "{{ cloud }}"
+      - projects.projects | length == 1
-       state: absent
+      - projects.projects.0.name == 'ansible_project'
-       name: ansible_project
-    register: project
 
-  - name: Assert project changed
+- name: Delete project
-    assert:
+  openstack.cloud.project:
-       that: project is changed
+     cloud: "{{ cloud }}"
+     state: absent
+     name: ansible_project
+  register: project
 
-  - name: Get project
+- name: Assert project changed
-    openstack.cloud.project_info:
+  assert:
-       cloud: "{{ cloud }}"
+     that: project is changed
-       name: ansible_project
-    register: project_info
 
-  - name: Assert project deleted
+- name: Get project
-    assert:
+  openstack.cloud.project_info:
-      that:
+     cloud: "{{ cloud }}"
-        - project_info.openstack_projects | length == 0
+     name: ansible_project
+  register: project_info
 
+- name: Assert project deleted
+  assert:
+    that:
+      - project_info.projects | length == 0
 
-- block:
+- name: Delete project again
-  - name: Delete non existant project
+  openstack.cloud.project:
-    openstack.cloud.project:
+     cloud: "{{ cloud }}"
-       cloud: "{{ cloud }}"
+     state: absent
-       state: absent
+     name: ansible_project
-       name: ansible_project
+  register: project
-    register: project
 
-  - name: Assert project not changed
+- name: Assert project not changed
-    assert:
+  assert:
-       that: project is not changed
+     that: project is not changed
 
-- block:
+- name: Create project with extra_specs
-  - name: Create project with properties
+  openstack.cloud.project:
-    openstack.cloud.project:
+    cloud: "{{ cloud }}"
-      cloud: "{{ cloud }}"
+    state: present
-      state: present
+    name: ansible_project
-      name: ansible_project
+    extra_specs:
-      description: dummy description
+      is_enabled: False
-      domain: default
+  register: project
-      enabled: True
-      properties:
-        dummy_key: dummy_value
-    register: project
 
-- block:
+- name: Assert return values of project module
-  - name: Update project with properties
+  assert:
-    openstack.cloud.project:
+    that:
-      cloud: "{{ cloud }}"
+      - project.project.is_enabled == False
-      state: present
+
-      name: ansible_project
+- name: Update project with extra_specs
-      description: dummy description
+  openstack.cloud.project:
-      domain: default
+    cloud: "{{ cloud }}"
-      enabled: True
+    state: present
-      properties:
+    name: ansible_project
-        dummy_key: other_dummy_value
+    extra_specs:
-    register: project
+      is_enabled: True
+  register: project
+
+- name: Assert return values of project module
+  assert:
+    that:
+      - project.project.is_enabled == True
+
+- name: Delete project
+  openstack.cloud.project:
+     cloud: "{{ cloud }}"
+     state: absent
+     name: ansible_project

ci/roles/project_info/tasks/main.yml

@@ -1,46 +0,0 @@
----
-- name: List admin project
-  openstack.cloud.project_info:
-    cloud: "{{ cloud }}"
-    name: 'admin'
-  register: project_admin
-
-- name: List admin project with filter
-  openstack.cloud.project_info:
-    cloud: "{{ cloud }}"
-    filters:
-      name: 'admin'
-
-- name: Check output of list admin project
-  assert:
-    that:
-      - project_admin.openstack_projects | length == 1
-
-- name: List all projects
-  openstack.cloud.project_info:
-    cloud: "{{ cloud }}"
-  register: all_projects
-
-- name: Check output of list all projects
-  assert:
-    that:
-      - all_projects.openstack_projects | length > 0
-
-- name: List admin project with domain
-  openstack.cloud.project_info:
-    cloud: "{{ cloud }}"
-    name: 'admin'
-    domain: 'default'
-  register: project_domain
-
-- name: Check output of list admin project with admin domain
-  assert:
-    that:
-      - project_domain.openstack_projects | length == 1
-
-- name: Assert fields on SDK 1.*
-  assert:
-    that:
-      - '["description", "domain_id", "is_domain", "is_enabled", "options",
-          "parent_id", "id", "name", "tags"] |
-          difference(project_admin.openstack_projects.0.keys()) | length == 0'

ci/roles/role_assignment/tasks/main.yml

@@ -5,9 +5,8 @@
      state: present
      name: ansible_project
      description: dummy description
-     domain_id: default
+     domain: default
-     enabled: True
+     is_enabled: True
-  register: project
 
 - name: Grant an admin role on the user admin in the project ansible_project
   openstack.cloud.role_assignment:

ci/roles/router/tasks/shared_network.yml

@@ -5,8 +5,8 @@
     state: present
     name: "shared_net_test_1"
     description: "Project that contains the subnet to be shared"
-    domain_id: default
+    domain: default
-    enabled: True
+    is_enabled: True
   register: project_1
 
 - name: Create the network to be shared
@@ -37,8 +37,8 @@
     state: present
     name: "shared_net_test_2"
     description: "Project that contains the subnet to be shared"
-    domain_id: default
+    domain: default
-    enabled: True
+    is_enabled: True
   register: project_2
 
 - name: Share the network with the second project

ci/roles/volume_type_access/tasks/main.yml

@@ -23,8 +23,8 @@
 - name: Verify demo project
   assert:
     that:
-      - projects.openstack_projects|length == 1
+      - projects.projects|length == 1
-      - projects.openstack_projects.0.name == "demo"
+      - projects.projects.0.name == "demo"
 
 - name: Grant access to volume type
   openstack.cloud.volume_type_access:
@@ -49,7 +49,7 @@
   assert:
     that:
       - (volume_type.stdout | from_json).name == 'ansible_volume_type'
-      - projects.openstack_projects.0.id in (volume_type.stdout | from_json).access_project_ids
+      - projects.projects.0.id in (volume_type.stdout | from_json).access_project_ids
 
 - name: Grant access to volume type again
   openstack.cloud.volume_type_access:

ci/run-collection.yml

@@ -42,7 +42,6 @@
     - { role: object_container, tags: object_container }
     - { role: port, tags: port }
     - { role: project, tags: project }
-    - { role: project_info, tags: project_info }
     - { role: recordset, tags: recordset }
     - { role: role_assignment, tags: role_assignment }
     - { role: router, tags: router }

plugins/modules/project.py

@@ -4,44 +4,40 @@
 # Copyright (c) 2015 IBM Corporation
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-DOCUMENTATION = '''
+DOCUMENTATION = r'''
 ---
 module: project
-short_description: Manage OpenStack Projects
+short_description: Manage OpenStack Identity (Keystone) projects
 author: OpenStack Ansible SIG
 description:
-    - Manage OpenStack Projects. Projects can be created,
+  - Create, update or delete a OpenStack Identity (Keystone) project.
-      updated or deleted using this module. A project will be updated
-      if I(name) matches an existing project and I(state) is present.
-      The value for I(name) cannot be updated without deleting and
-      re-creating the project.
 options:
   name:
     description:
-      - Name for the project
+      - Name for the project.
+      - This attribute cannot be updated.
     required: true
     type: str
   description:
     description:
-      - Description for the project
+      - Description for the project.
     type: str
   domain:
     description:
-       - Domain name or id to create the project in if the cloud supports
+      - Domain name or id to create the project in if the cloud supports
-         domains.
+        domains.
     aliases: ['domain_id']
     type: str
-  is_enabled:
+  extra_specs:
-    description:
-      - Is the project enabled
-    aliases: ['enabled']
-    type: bool
-    default: 'yes'
-  properties:
     description:
       - Additional properties to be associated with this project.
     type: dict
-    required: false
+    aliases: ['properties']
+  is_enabled:
+    description:
+      - Whether this project is enabled or not.
+    aliases: ['enabled']
+    type: bool
   state:
     description:
       - Should the resource be present or absent.
@@ -49,73 +45,70 @@ options:
     default: present
     type: str
 requirements:
-    - "python >= 3.6"
+  - "python >= 3.6"
-    - "openstacksdk"
+  - "openstacksdk"
-
 extends_documentation_fragment:
-- openstack.cloud.openstack
+  - openstack.cloud.openstack
 '''
 
-EXAMPLES = '''
+EXAMPLES = r'''
-# Create a project
+- name: Create a project
-- openstack.cloud.project:
+  openstack.cloud.project:
     cloud: mycloud
-    endpoint_type: admin
-    state: present
-    name: demoproject
     description: demodescription
     domain: demoid
     is_enabled: True
-    properties:
+    name: demoproject
+    extra_specs:
       internal_alias: demo_project
+    state: present
 
-# Delete a project
+- name: Delete a project
-- openstack.cloud.project:
+  openstack.cloud.project:
     cloud: mycloud
     endpoint_type: admin
-    state: absent
     name: demoproject
+    state: absent
 '''
 
-
+RETURN = r'''
-RETURN = '''
 project:
-    description: Dictionary describing the project.
+  description: Dictionary describing the project.
-    returned: On success when I(state) is 'present'
+  returned: On success when I(state) is C(present).
-    type: dict
+  type: dict
-    contains:
+  contains:
-        description:
+    description:
-            description: Project description
+      description: Project description
-            type: str
+      type: str
-            sample: "demodescription"
+      sample: "demodescription"
-        domain_id:
+    domain_id:
-            description: domain to which the project belongs
+      description: Domain ID to which the project belongs
-            type: str
+      type: str
-            sample: "default"
+      sample: "default"
-        id:
+    id:
-            description: Project ID
+      description: Project ID
-            type: str
+      type: str
-            sample: "f59382db809c43139982ca4189404650"
+      sample: "f59382db809c43139982ca4189404650"
-        is_domain:
+    is_domain:
-            description: Indicates whether the project also acts as a domain.
+      description: Indicates whether the project also acts as a domain.
-            type: bool
+      type: bool
-        is_enabled:
+    is_enabled:
-            description: Indicates whether the project is enabled
+      description: Indicates whether the project is enabled
-            type: bool
+      type: bool
-        name:
+    name:
-            description: Project name
+      description: Project name
-            type: str
+      type: str
-            sample: "demoproject"
+      sample: "demoproject"
-        options:
+    options:
-            description: The resource options for the project
+      description: The resource options for the project
-            type: dict
+      type: dict
-        parent_id:
+    parent_id:
-            description: The ID of the parent of the project
+      description: The ID of the parent of the project
-            type: str
+      type: str
-        tags:
+    tags:
-            description: A list of associated tags
+      description: A list of associated tags
-            type: list
+      type: list
-            elements: str
+      elements: str
 '''
 
 from ansible_collections.openstack.cloud.plugins.module_utils.openstack import OpenStackModule
@@ -123,98 +116,137 @@ from ansible_collections.openstack.cloud.plugins.module_utils.openstack import O
 
 class IdentityProjectModule(OpenStackModule):
     argument_spec = dict(
-        name=dict(required=True),
         description=dict(),
         domain=dict(aliases=['domain_id']),
-        is_enabled=dict(default=True, type='bool', aliases=['enabled']),
+        extra_specs=dict(type='dict', aliases=['properties']),
-        properties=dict(type='dict', min_ver='0.45.1'),
+        is_enabled=dict(type='bool', aliases=['enabled']),
+        name=dict(required=True),
         state=dict(default='present', choices=['absent', 'present'])
     )
     module_kwargs = dict(
         supports_check_mode=True
     )
 
-    def _needs_update(self, project, update, extra):
-        # We cannot update a project name because name find projects by name so
-        # only a project with an already matching name will be considered for
-        # updates
-        keys = ('description', 'is_enabled')
-        if any((k in update and update[k] != project[k]) for k in keys):
-            return True
-
-        # Additional keys passed by user will be checked completely
-        if extra and any(k not in project or extra[k] != project[k]
-                         for k in extra.keys()):
-            return True
-
-        return False
-
-    def _get_domain_id(self, domain):
-        dom_obj = self.conn.identity.find_domain(domain)
-        if dom_obj is None:
-            # Ok, let's hope the user is non-admin and passing a sane id
-            return domain
-        return dom_obj.id
-
-    def _system_state_change(self, state, project, attrs, extra_attrs):
-        if state == 'present':
-            if project is None:
-                return True
-            return self._needs_update(project, attrs, extra_attrs)
-        # Else state is absent
-        return project is not None
-
     def run(self):
-        name = self.params['name']
-        domain = self.params['domain']
         state = self.params['state']
-        properties = self.params['properties']
-        enabled = self.params['is_enabled']
-        description = self.params['description']
 
-        find_project_kwargs = {}
+        project = self._find()
-        domain_id = None
-        if domain:
-            domain_id = self._get_domain_id(domain)
-            find_project_kwargs['domain_id'] = domain_id
 
-        project = None
+        if self.ansible.check_mode:
-        if name is not None:
+            self.exit_json(changed=self._will_change(state, project))
-            project = self.conn.identity.find_project(
-                name, **find_project_kwargs)
 
-        project_attrs = {
+        if state == 'present' and not project:
-            'name': name,
+            # Create project
-            'description': description,
+            project = self._create()
-            'is_enabled': enabled,
+            self.exit_json(changed=True,
-            'domain_id': domain_id,
-        }
-        project_attrs = {k: v for k, v in project_attrs.items()
-                         if v is not None}
-        # Add in arbitrary properties
-        if properties:
-            project_attrs.update(properties)
-
-        if self.check_mode:
-            self.exit_json(changed=self._system_state_change(state, project,
-                                                             project_attrs,
-                                                             properties))
-
-        changed = False
-        if state == 'present':
-            if project is None:
-                project = self.conn.identity.create_project(**project_attrs)
-                changed = True
-            elif self._needs_update(project, project_attrs, properties):
-                project = self.conn.identity.update_project(
-                    project, **project_attrs)
-                changed = True
-            self.exit_json(changed=changed,
                            project=project.to_dict(computed=False))
-        elif state == 'absent' and project is not None:
+
-            self.conn.identity.delete_project(project['id'])
+        elif state == 'present' and project:
-            changed = True
+            # Update project
-        self.exit_json(changed=changed)
+            update = self._build_update(project)
+            if update:
+                project = self._update(project, update)
+
+            self.exit_json(changed=bool(update),
+                           project=project.to_dict(computed=False))
+
+        elif state == 'absent' and project:
+            # Delete project
+            self._delete(project)
+            self.exit_json(changed=True)
+
+        elif state == 'absent' and not project:
+            # Do nothing
+            self.exit_json(changed=False)
+
+    def _build_update(self, project):
+        update = {}
+
+        # Params name and domain are being used to find this project.
+
+        non_updateable_keys = [k for k in []
+                               if self.params[k] is not None
+                               and self.params[k] != project[k]]
+
+        if non_updateable_keys:
+            self.fail_json(msg='Cannot update parameters {0}'
+                               .format(non_updateable_keys))
+
+        attributes = dict((k, self.params[k])
+                          for k in ['description', 'is_enabled']
+                          if self.params[k] is not None
+                          and self.params[k] != project[k])
+
+        extra_specs = self.params['extra_specs']
+        if extra_specs:
+            duplicate_keys = set(attributes.keys()) & set(extra_specs.keys())
+            if duplicate_keys:
+                raise ValueError('Duplicate key(s) in extra_specs: {0}'
+                                 .format(', '.join(list(duplicate_keys))))
+            for k, v in extra_specs.items():
+                if v != project[k]:
+                    attributes[k] = v
+
+        if attributes:
+            update['attributes'] = attributes
+
+        return update
+
+    def _create(self):
+        kwargs = dict((k, self.params[k])
+                      for k in ['description', 'is_enabled', 'name']
+                      if self.params[k] is not None)
+
+        domain_name_or_id = self.params['domain']
+        if domain_name_or_id is not None:
+            domain = self.conn.identity.find_domain(domain_name_or_id,
+                                                    ignore_missing=False)
+            kwargs['domain_id'] = domain.id
+
+        extra_specs = self.params['extra_specs']
+        if extra_specs:
+            duplicate_keys = set(kwargs.keys()) & set(extra_specs.keys())
+            if duplicate_keys:
+                raise ValueError('Duplicate key(s) in extra_specs: {0}'
+                                 .format(', '.join(list(duplicate_keys))))
+            kwargs = dict(kwargs, **extra_specs)
+
+        return self.conn.identity.create_project(**kwargs)
+
+    def _delete(self, project):
+        self.conn.identity.delete_project(project.id)
+
+    def _find(self):
+        name = self.params['name']
+        kwargs = {}
+
+        domain_name_or_id = self.params['domain']
+        if domain_name_or_id is not None:
+            domain = self.conn.identity.find_domain(domain_name_or_id,
+                                                    ignore_missing=False)
+            kwargs['domain_id'] = domain.id
+
+        return self.conn.identity.find_project(name_or_id=name,
+                                               **kwargs)
+
+    def _update(self, project, update):
+        attributes = update.get('attributes')
+        if attributes:
+            project = self.conn.identity.update_project(project.id,
+                                                        **attributes)
+
+        return project
+
+    def _will_change(self, state, project):
+        if state == 'present' and not project:
+            return True
+        elif state == 'present' and project:
+            return bool(self._build_update(project))
+        elif state == 'absent' and project:
+            return True
+        else:
+            # state == 'absent' and not project:
+            return False
 
 
 def main():

plugins/modules/project_info.py

@@ -4,117 +4,97 @@
 # Copyright (c) 2016 Hewlett-Packard Enterprise Corporation
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
-DOCUMENTATION = '''
+DOCUMENTATION = r'''
 ---
 module: project_info
 short_description: Retrieve information about one or more OpenStack projects
 author: OpenStack Ansible SIG
 description:
-    - Retrieve information about a one or more OpenStack projects
+  - Retrieve information about a one or more OpenStack projects
 options:
-   name:
+  name:
-     description:
+    description:
-        - Name or ID of the project
+      - Name or ID of the project.
-     type: str
+    type: str
-   domain:
+  domain:
-     description:
+    description:
-        - Name or ID of the domain containing the project if the cloud supports domains
+      - Name or ID of the domain containing the project.
-     type: str
+    type: str
-   filters:
+  filters:
-     description:
+    description:
-        - A dictionary of meta data to use for filtering projects. Elements of
+      - A dictionary of meta data to use for filtering projects.
-          this dictionary are parsed as queries for openstack identity api in
+      - Elements of I(filters) are passed as query parameters to
-          the new openstacksdk.
+        OpenStack Identity API.
-     type: dict
+    type: dict
 requirements:
-    - "python >= 3.6"
+  - "python >= 3.6"
-    - "openstacksdk"
+  - "openstacksdk"
-
 extends_documentation_fragment:
-- openstack.cloud.openstack
+  - openstack.cloud.openstack
 '''
 
-EXAMPLES = '''
+EXAMPLES = r'''
-# Gather information about previously created projects
+- name: Fetch all Identity (Keystone) projects
-- openstack.cloud.project_info:
+  openstack.cloud.project_info:
     cloud: awesomecloud
-  register: result
-- debug:
-    msg: "{{ result.openstack_projects }}"
 
-# Gather information about a previously created project by name
+- name: Fetch all projects with a name
-- openstack.cloud.project_info:
+  openstack.cloud.project_info:
     cloud: awesomecloud
     name: demoproject
-  register: result
-- debug:
-    msg: "{{ result.openstack_projects }}"
 
-# Gather information about a previously created project in a specific domain
+- name: Fetch all projects with a name in a domain
-- openstack.cloud.project_info:
+  openstack.cloud.project_info:
     cloud: awesomecloud
     name: demoproject
     domain: admindomain
-  register: result
-- debug:
-    msg: "{{ result.openstack_projects }}"
 
-# Gather information about a previously created project in a specific domain with filter
+- name: Fetch all disabled projects
-- openstack.cloud.project_info:
+  openstack.cloud.project_info:
     cloud: awesomecloud
-    name: demoproject
-    domain: admindomain
     filters:
-      is_enabled: False
+      is_enabled: false
-  register: result
-- debug:
-    msg: "{{ result.openstack_projects }}"
 '''
 
-
+RETURN = r'''
-RETURN = '''
+projects:
-openstack_projects:
+  description: List of dictionaries describing Identity (Keystone) projects.
-    description: has all the OpenStack information about projects
+  elements: dict
-    elements: dict
+  returned: always, but can be empty
-    returned: always, but can be empty
+  type: list
-    type: list
+  contains:
-    contains:
+    description:
-        id:
+      description: Project description
-            description: Unique UUID.
+      type: str
-            returned: success
+      sample: "demodescription"
-            type: str
+    domain_id:
-        name:
+      description: Domain ID to which the project belongs
-            description: Name given to the project.
+      type: str
-            returned: success
+      sample: "default"
-            type: str
+    id:
-        description:
+      description: Project ID
-            description: Description of the project
+      type: str
-            returned: success
+      sample: "f59382db809c43139982ca4189404650"
-            type: str
+    is_domain:
-        is_enabled:
+      description: Indicates whether the project also acts as a domain.
-            description: Flag to indicate if the project is enabled
+      type: bool
-            returned: success
+    is_enabled:
-            type: bool
+      description: Indicates whether the project is enabled
-        domain_id:
+      type: bool
-            description: Domain ID containing the project (keystone v3 clouds only)
+    name:
-            returned: success
+      description: Project name
-            type: bool
+      type: str
-        tags:
+      sample: "demoproject"
-            description: A list of simple strings assigned to a project
+    options:
-            returned: success
+      description: The resource options for the project
-            type: list
+      type: dict
-        parent_id:
+    parent_id:
-            description: The ID of the parent for the project
+      description: The ID of the parent of the project
-            returned: success
+      type: str
-            type: str
+    tags:
-        is_domain:
+      description: A list of associated tags
-            description: Indicates whether the project also acts as a domain.
+      type: list
-            returned: success
+      elements: str
-            type: bool
-        options:
-            description: Set of options for the project
-            returned: success
-            type: dict
 '''
 
 from ansible_collections.openstack.cloud.plugins.module_utils.openstack import OpenStackModule
@@ -122,8 +102,8 @@ from ansible_collections.openstack.cloud.plugins.module_utils.openstack import O
 
 class IdentityProjectInfoModule(OpenStackModule):
     argument_spec = dict(
-        name=dict(),
         domain=dict(),
+        name=dict(),
         filters=dict(type='dict'),
     )
     module_kwargs = dict(
@@ -131,18 +111,22 @@ class IdentityProjectInfoModule(OpenStackModule):
     )
 
     def run(self):
-        name = self.params['name']
-        domain = self.params['domain']
         filters = self.params['filters'] or {}
 
-        if domain:
+        domain_name_or_id = self.params['domain']
-            filters['domain_id'] = self.conn.identity.find_domain(
+        if domain_name_or_id is not None:
-                domain, ignore_missing=False).id
+            domain = self.conn.identity.find_domain(domain_name_or_id)
 
-        projects = self.conn.search_projects(name, filters=filters)
+            if not domain:
-        projects = [p.to_dict(computed=False) for p in projects]
+                self.exit_json(changed=False, projects=[])
 
-        self.exit_json(changed=False, openstack_projects=projects)
+            filters['domain_id'] = domain.id
+
+        projects = self.conn.search_projects(name_or_id=self.params['name'],
+                                             filters=filters)
+
+        self.exit_json(changed=False,
+                       projects=[p.to_dict(computed=False) for p in projects])
 
 
 def main():