Fixup iam_group integration tests and return value documentation (#61243)

* iam_group: (integration tests) migrate tests to module_defaults

* iam_group: (integration tests) migrate to using temporary user and group with {{ resource_prefix }}

* iam_group: (integration tests) fix test, checking the return values

* iam_group: (integration tests) Add some more tests around the behaviour of 'changed'

* iam_group: (docs) Update documentation of iam_group return value

* Update AWS testing policies to enable group/user management

hacking/aws_config/testing_policies/security-policy.json

@@ -139,6 +139,19 @@
                 "iam:UpdateAccountPasswordPolicy"
             ],
             "Resource": "*"
+        },
+        {
+            "Sid": "AllowAccessToManageUsersAndGroups",
+            "Effect": "Allow",
+            "Action": [
+                "iam:*Group",
+                "iam:*User",
+                "iam:ListAttachedGroupPolicies"
+            ],
+            "Resource": [
+                "arn:aws:iam::{{ aws_account }}:user/ansible-test*",
+                "arn:aws:iam::{{ aws_account }}:group/ansible-test*"
+            ]
         }
     ]
 }

lib/ansible/modules/cloud/amazon/iam_group.py

@@ -111,56 +111,61 @@ EXAMPLES = '''
 
 '''
 RETURN = '''
-group:
-    description: dictionary containing all the group information
+iam_group:
+    description: dictionary containing all the group information including group membership
     returned: success
     type: complex
     contains:
-        arn:
-            description: the Amazon Resource Name (ARN) specifying the group
-            type: str
-            sample: "arn:aws:iam::1234567890:group/testgroup1"
-        create_date:
-            description: the date and time, in ISO 8601 date-time format, when the group was created
-            type: str
-            sample: "2017-02-08T04:36:28+00:00"
-        group_id:
-            description: the stable and unique string identifying the group
-            type: str
-            sample: AGPAIDBWE12NSFINE55TM
-        group_name:
-            description: the friendly name that identifies the group
-            type: str
-            sample: testgroup1
-        path:
-            description: the path to the group
-            type: str
-            sample: /
-users:
-    description: list containing all the group members
-    returned: success
-    type: complex
-    contains:
-        arn:
-            description: the Amazon Resource Name (ARN) specifying the user
-            type: str
-            sample: "arn:aws:iam::1234567890:user/test_user1"
-        create_date:
-            description: the date and time, in ISO 8601 date-time format, when the user was created
-            type: str
-            sample: "2017-02-08T04:36:28+00:00"
-        user_id:
-            description: the stable and unique string identifying the user
-            type: str
-            sample: AIDAIZTPY123YQRS22YU2
-        user_name:
-            description: the friendly name that identifies the user
-            type: str
-            sample: testgroup1
-        path:
-            description: the path to the user
-            type: str
-            sample: /
+        group:
+            description: dictionary containing all the group information
+            returned: success
+            type: complex
+            contains:
+                arn:
+                    description: the Amazon Resource Name (ARN) specifying the group
+                    type: str
+                    sample: "arn:aws:iam::1234567890:group/testgroup1"
+                create_date:
+                    description: the date and time, in ISO 8601 date-time format, when the group was created
+                    type: str
+                    sample: "2017-02-08T04:36:28+00:00"
+                group_id:
+                    description: the stable and unique string identifying the group
+                    type: str
+                    sample: AGPAIDBWE12NSFINE55TM
+                group_name:
+                    description: the friendly name that identifies the group
+                    type: str
+                    sample: testgroup1
+                path:
+                    description: the path to the group
+                    type: str
+                    sample: /
+        users:
+            description: list containing all the group members
+            returned: success
+            type: complex
+            contains:
+                arn:
+                    description: the Amazon Resource Name (ARN) specifying the user
+                    type: str
+                    sample: "arn:aws:iam::1234567890:user/test_user1"
+                create_date:
+                    description: the date and time, in ISO 8601 date-time format, when the user was created
+                    type: str
+                    sample: "2017-02-08T04:36:28+00:00"
+                user_id:
+                    description: the stable and unique string identifying the user
+                    type: str
+                    sample: AIDAIZTPY123YQRS22YU2
+                user_name:
+                    description: the friendly name that identifies the user
+                    type: str
+                    sample: testgroup1
+                path:
+                    description: the path to the user
+                    type: str
+                    sample: /
 '''
 
 from ansible.module_utils.aws.core import AnsibleAWSModule

test/integration/targets/iam_group/defaults/main.yml

@@ -0,0 +1,3 @@
+---
+test_user:  '{{ resource_prefix }}-user'
+test_group: '{{ resource_prefix }}-group'

test/integration/targets/iam_group/meta/main.yml

@@ -0,0 +1,3 @@
+dependencies:
+  - prepare_tests
+  - setup_ec2

test/integration/targets/iam_group/tasks/main.yml

@@ -1,70 +1,125 @@
+---
 - name: set up aws connection info
-  set_fact:
-    aws_connection_info: &aws_connection_info
+  module_defaults:
+    group/aws:
       aws_access_key: "{{ aws_access_key }}"
       aws_secret_key: "{{ aws_secret_key }}"
-      security_token: "{{ security_token }}"
+      security_token: "{{ security_token | default(omit) }}"
       region: "{{ aws_region }}"
-  no_log: yes
-
-- name: ensure ansible user exists
-  iam_user:
-    name: AnsibleTestUser
-    state: present
-    <<: *aws_connection_info
-
-- name: ensure group exists
-  iam_group:
-    name: ansible_test
-    users:
-      - AnsibleTestUser
-    state: present
-    <<: *aws_connection_info
-  register: iam_group
-
-- assert:
-    that:
-      - iam_group.users
-
-- name: add non existent user to group
-  iam_group:
-    name: ansible_test
-    users:
-      - AnsibleTestUser
-      - NonExistentUser
-    state: present
-    <<: *aws_connection_info
-  ignore_errors: yes
-  register: iam_group
-
-- name: assert that adding non existent user to group fails with helpful message
-  assert:
-    that:
-      - iam_group is failed
-      - iam_group.msg.startswith("Couldn't add user NonExistentUser to group ansible_test")
-
-- name: remove a user
-  iam_group:
-    name: ansible_test
-    purge_users: True
-    users: []
-    state: present
-    <<: *aws_connection_info
-  register: iam_group
-
-- assert:
-    that:
-      - iam_group.changed
-      - not iam_group.users
-
-- name: remove group
-  iam_group:
-    name: ansible_test
-    state: absent
-    <<: *aws_connection_info
-
-- name: remove ansible user
-  iam_user:
-    name: AnsibleTestUser
-    state: absent
-    <<: *aws_connection_info
+  block:
+  - name: ensure ansible user exists
+    iam_user:
+      name: '{{ test_user }}'
+      state: present
+
+  - name: ensure group exists
+    iam_group:
+      name: '{{ test_group }}'
+      users:
+        - '{{ test_user }}'
+      state: present
+    register: iam_group
+
+  - assert:
+      that:
+        - iam_group.iam_group.users
+        - iam_group is changed
+
+  - name: add non existent user to group
+    iam_group:
+      name: '{{ test_group }}'
+      users:
+        - '{{ test_user }}'
+        - NonExistentUser
+      state: present
+    ignore_errors: yes
+    register: iam_group
+
+  - name: assert that adding non existent user to group fails with helpful message
+    assert:
+      that:
+        - iam_group is failed
+        - iam_group.msg.startswith("Couldn't add user NonExistentUser to group {{ test_group }}")
+
+  - name: remove a user
+    iam_group:
+      name: '{{ test_group }}'
+      purge_users: True
+      users: []
+      state: present
+    register: iam_group
+
+  - assert:
+      that:
+        - iam_group is changed
+        - not iam_group.iam_group.users
+
+  - name: re-remove a user (no change)
+    iam_group:
+      name: '{{ test_group }}'
+      purge_users: True
+      users: []
+      state: present
+    register: iam_group
+
+  - assert:
+      that:
+        - iam_group is not changed
+        - not iam_group.iam_group.users
+
+  - name: Add the user again
+    iam_group:
+      name: '{{ test_group }}'
+      users:
+        - '{{ test_user }}'
+      state: present
+    register: iam_group
+
+  - assert:
+      that:
+        - iam_group is changed
+        - iam_group.iam_group.users
+
+  - name: Re-add the user
+    iam_group:
+      name: '{{ test_group }}'
+      users:
+        - '{{ test_user }}'
+      state: present
+    register: iam_group
+
+  - assert:
+      that:
+        - iam_group is not changed
+        - iam_group.iam_group.users
+
+  - name: remove group
+    iam_group:
+      name: '{{ test_group }}'
+      state: absent
+    register: iam_group
+
+  - assert:
+      that:
+        - iam_group is changed
+
+  - name: re-remove group
+    iam_group:
+      name: '{{ test_group }}'
+      state: absent
+    register: iam_group
+
+  - assert:
+      that:
+        - iam_group is not changed
+
+  always:
+  - name: remove group
+    iam_group:
+      name: '{{ test_group }}'
+      state: absent
+
+  - name: remove ansible user
+    iam_user:
+      name: '{{ test_user }}'
+      state: absent