execute_lambda - fix check mode and update RETURN docs (#1115) (#1135)

[PR #1115/f2ad6375 backport][stable-2] execute_lambda - fix check mode and update RETURN docs

This is a backport of PR #1115 as merged into main (f2ad637).
Depends-On: #1116
SUMMARY

check_mode fix
update RETURN docs to match what is actually being returned
require one of name, function_arn

ISSUE TYPE

Bugfix Pull Request

COMPONENT NAME
execute_lambda
ADDITIONAL INFORMATION
I noticed some modules in community.aws will return data directly, and others will return data nested in a dict.
Example: let iam_group be the module, retrieving a key called group_arn, and registering the response as response. Some modules you would need to query result.iam_group.group_arn, meanwhile in others, you can result.group_arn (where iam_group is assumed, since its the name of the module). Do we have a preference for either method? Should we come to some sort of collection-wide consensus on which to use moving forward?

Reviewed-by: Joseph Torcasso <None>

changelogs/fragments/1115-execute_lambda-checkmode-fix-update-return-docs.yml

@@ -0,0 +1,2 @@
+bugfixes:
+  - execute_lambda - fix check mode and update RETURN documentation (https://github.com/ansible-collections/community.aws/pull/1115).

plugins/modules/execute_lambda.py

@@ -108,20 +108,25 @@
 '''
 
 RETURN = '''
-output:
-    description: Function output if wait=true and the function returns a value
+result:
+    description: Resulting data structure from a successful task execution.
     returned: success
     type: dict
-    sample: "{ 'output': 'something' }"
-logs:
-    description: The last 4KB of the function logs. Only provided if I(tail_log) is true
-    type: str
-    returned: if I(tail_log) == true
-status:
-    description: C(StatusCode) of API call exit (200 for synchronous invokes, 202 for async)
-    type: int
-    sample: 200
-    returned: always
+    contains:
+        output:
+            description: Function output if wait=true and the function returns a value
+            returned: success
+            type: dict
+            sample: "{ 'output': 'something' }"
+        logs:
+            description: The last 4KB of the function logs. Only provided if I(tail_log) is C(true)
+            type: str
+            returned: if I(tail_log) == true
+        status:
+            description: C(StatusCode) of API call exit (200 for synchronous invokes, 202 for async)
+            type: int
+            sample: 200
+            returned: always
 '''
 
 import base64
@@ -134,6 +139,7 @@
 
 from ansible_collections.amazon.aws.plugins.module_utils.core import AnsibleAWSModule
 from ansible_collections.amazon.aws.plugins.module_utils.core import is_boto3_error_code
+from ansible_collections.amazon.aws.plugins.module_utils.ec2 import AWSRetry
 
 
 def main():
@@ -151,7 +157,10 @@ def main():
         supports_check_mode=True,
         mutually_exclusive=[
             ['name', 'function_arn'],
-        ]
+        ],
+        required_one_of=[
+            ('name', 'function_arn')
+        ],
     )
 
     name = module.params.get('name')
@@ -162,11 +171,8 @@ def main():
     version_qualifier = module.params.get('version_qualifier')
     payload = module.params.get('payload')
 
-    if not (name or function_arn):
-        module.fail_json(msg="Must provide either a function_arn or a name to invoke.")
-
     try:
-        client = module.client('lambda')
+        client = module.client('lambda', retry_decorator=AWSRetry.jittered_backoff())
     except (botocore.exceptions.ClientError, botocore.exceptions.BotoCoreError) as e:
         module.fail_json_aws(e, msg='Failed to connect to AWS')
 
@@ -202,11 +208,12 @@ def main():
     elif name:
         invoke_params['FunctionName'] = name
 
-    if not module.check_mode:
-        wait_for_lambda(client, module, name)
+    if module.check_mode:
+        module.exit_json(changed=True)
 
     try:
-        response = client.invoke(**invoke_params)
+        wait_for_lambda(client, module, name)
+        response = client.invoke(**invoke_params, aws_retry=True)
     except is_boto3_error_code('ResourceNotFoundException') as nfe:
         module.fail_json_aws(nfe, msg="Could not find Lambda to execute. Make sure "
                              "the ARN is correct and your profile has "

tests/integration/targets/lambda/tasks/main.yml

@@ -70,6 +70,16 @@
       - '"handler" in result.msg'
       - '"role" in result.msg'
 
+  - name: test execute lambda with no function arn or name
+    execute_lambda:
+    register: result
+    ignore_errors: true
+  - name: assert failure when called with no parameters
+    assert:
+      that:
+      - result.failed
+      - "result.msg == 'one of the following is required: name, function_arn'"
+
   - name: test state=present with security group but no vpc
     lambda:
       name: '{{ lambda_function_name }}'
@@ -109,6 +119,19 @@
       - result.configuration.tracing_config.mode == "PassThrough"
 
   # Test basic operation of Uploaded lambda
+  - name: test lambda works (check mode)
+    execute_lambda:
+      name: '{{lambda_function_name}}'
+      payload:
+        name: Mr Ansible Tests
+    register: result
+    check_mode: yes
+  - name: assert check mode works correctly
+    assert:
+      that:
+        - result.changed
+        - "'result' not in result"
+
   - name: test lambda works
     execute_lambda:
       name: '{{lambda_function_name}}'