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,7 +111,12 @@ EXAMPLES = '''
 
 '''
 RETURN = '''
-group:
+iam_group:
+    description: dictionary containing all the group information including group membership
+    returned: success
+    type: complex
+    contains:
+        group:
             description: dictionary containing all the group information
             returned: success
             type: complex
@@ -136,7 +141,7 @@ group:
                     description: the path to the group
                     type: str
                     sample: /
-users:
+        users:
             description: list containing all the group members
             returned: success
             type: complex

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:
+  module_defaults:
-    aws_connection_info: &aws_connection_info
+    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
+  block:
-
+  - name: ensure ansible user exists
-- name: ensure ansible user exists
     iam_user:
-    name: AnsibleTestUser
+      name: '{{ test_user }}'
       state: present
-    <<: *aws_connection_info
 
-- name: ensure group exists
+  - name: ensure group exists
     iam_group:
-    name: ansible_test
+      name: '{{ test_group }}'
       users:
-      - AnsibleTestUser
+        - '{{ test_user }}'
       state: present
-    <<: *aws_connection_info
     register: iam_group
 
-- assert:
+  - assert:
       that:
-      - iam_group.users
+        - iam_group.iam_group.users
+        - iam_group is changed
 
-- name: add non existent user to group
+  - name: add non existent user to group
     iam_group:
-    name: ansible_test
+      name: '{{ test_group }}'
       users:
-      - AnsibleTestUser
+        - '{{ test_user }}'
         - 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
+  - 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")
+        - 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: remove a user
+  - name: re-remove a user (no change)
     iam_group:
-    name: ansible_test
+      name: '{{ test_group }}'
       purge_users: True
       users: []
       state: present
-    <<: *aws_connection_info
     register: iam_group
 
-- assert:
+  - 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.changed
+        - iam_group is not changed
-      - not iam_group.users
 
-- name: remove group
+  always:
+  - name: remove group
     iam_group:
-    name: ansible_test
+      name: '{{ test_group }}'
       state: absent
-    <<: *aws_connection_info
 
-- name: remove ansible user
+  - name: remove ansible user
     iam_user:
-    name: AnsibleTestUser
+      name: '{{ test_user }}'
       state: absent
-    <<: *aws_connection_info