Mass update of docs and tests (credentials/session tokens) (#1921)

Mass update of docs and tests (credentials/session tokens)

SUMMARY
We had a cleanup of credentials/session parameters which included a batch of deprecations and renames.
Ensure that all of our tests and docs are using the 'canonical' names
ISSUE TYPE

Docs Pull Request

COMPONENT NAME
plugins/modules/batch_compute_environment.py
plugins/modules/cloudformation_exports_info.py
plugins/modules/ec2_vpc_vpn.py
plugins/modules/elasticache.py
plugins/modules/elasticache_parameter_group.py
plugins/modules/elasticache_snapshot.py
plugins/modules/ses_rule_set.py
plugins/modules/sts_assume_role.py
plugins/modules/sts_session_token.py
tests/integration
ADDITIONAL INFORMATION
See also

ansible-collections/amazon.aws#1172
ansible-collections/amazon.aws#1714

Reviewed-by: Alina Buzachis

changelogs/fragments/botocore_params-cleanup.yml

@@ -0,0 +1,2 @@
+trivial:
+- update docs and tests to use canonical parameter names for credentials.

plugins/modules/batch_compute_environment.py

@@ -165,15 +165,15 @@
     changed: false
     invocation:
       module_args:
-        aws_access_key: ~
-        aws_secret_key: ~
+        access_key: ~
+        secret_key: ~
         bid_percentage: ~
         compute_environment_name: <name>
         compute_environment_state: ENABLED
         compute_resource_type: EC2
         desiredv_cpus: 0
         ec2_key_pair: ~
-        ec2_url: ~
+        endpoint_url: ~
         image_id: ~
         instance_role: "arn:aws:iam::..."
         instance_types:

plugins/modules/cloudformation_exports_info.py

@@ -19,10 +19,9 @@
 """
 
 EXAMPLES = r"""
+# Note: These examples do not set authentication details, see the AWS Guide for details.
 - name: Get Exports
-  community.aws.cloudformation_exports_info:
-    profile: 'my_aws_profile'
-    region: 'my_region'
+  community.aws.cloudformation_exports_info: {}
   register: cf_exports
 - ansible.builtin.debug:
     msg: "{{ cf_exports }}"

plugins/modules/ec2_vpc_vpn.py

@@ -143,8 +143,7 @@
 """
 
 EXAMPLES = r"""
-# Note: None of these examples set aws_access_key, aws_secret_key, or region.
-# It is assumed that their matching environment variables are set.
+# Note: These examples do not set authentication details, see the AWS Guide for details.
 
 - name: create a VPN connection with vpn_gateway_id
   community.aws.ec2_vpc_vpn:

plugins/modules/elasticache.py

@@ -103,8 +103,7 @@
 RETURN = r""" # """
 
 EXAMPLES = r"""
-# Note: None of these examples set aws_access_key, aws_secret_key, or region.
-# It is assumed that their matching environment variables are set.
+# Note: These examples do not set authentication details, see the AWS Guide for details.
 
 - name: Basic example
   community.aws.elasticache:

plugins/modules/elasticache_parameter_group.py

@@ -50,9 +50,8 @@
 """
 
 EXAMPLES = r"""
-# Note: None of these examples set aws_access_key, aws_secret_key, or region.
-# It is assumed that their matching environment variables are set.
----
+# Note: These examples do not set authentication details, see the AWS Guide for details.
+
 - hosts: localhost
   connection: local
   tasks:

plugins/modules/elasticache_snapshot.py

@@ -49,8 +49,7 @@
 """
 
 EXAMPLES = r"""
-# Note: None of these examples set aws_access_key, aws_secret_key, or region.
-# It is assumed that their matching environment variables are set.
+# Note: These examples do not set authentication details, see the AWS Guide for details.
 
 - name: 'Create a snapshot'
   community.aws.elasticache_snapshot:

plugins/modules/ses_rule_set.py

@@ -50,9 +50,8 @@
 """
 
 EXAMPLES = r"""
-# Note: None of these examples set aws_access_key, aws_secret_key, or region.
-# It is assumed that their matching environment variables are set.
----
+# Note: These examples do not set authentication details, see the AWS Guide for details.
+
 - name: Create default rule set and activate it if not already
   community.aws.ses_rule_set:
     name: default-rule-set

plugins/modules/sts_assume_role.py

@@ -49,7 +49,8 @@
       - The value provided by the MFA device, if the trust policy of the role being assumed requires MFA.
     type: str
 notes:
-  - In order to use the assumed role in a following playbook task you must pass the access_key, access_secret and access_token.
+  - In order to use the assumed role in a following playbook task you must pass the I(access_key),
+    I(secret_key) and I(session_token) parameters to modules that should use the assumed credentials.
 extends_documentation_fragment:
   - amazon.aws.common.modules
   - amazon.aws.region.modules
@@ -80,19 +81,19 @@
 """
 
 EXAMPLES = r"""
-# Note: These examples do not set authentication details, see the AWS Guide for details.
-
 # Assume an existing role (more details: https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)
 - community.aws.sts_assume_role:
+    access_key: AKIA1EXAMPLE1EXAMPLE
+    secret_key: 123456789abcdefghijklmnopqrstuvwxyzABCDE
     role_arn: "arn:aws:iam::123456789012:role/someRole"
     role_session_name: "someRoleSession"
   register: assumed_role
 
 # Use the assumed role above to tag an instance in account 123456789012
 - amazon.aws.ec2_tag:
-    aws_access_key: "{{ assumed_role.sts_creds.access_key }}"
-    aws_secret_key: "{{ assumed_role.sts_creds.secret_key }}"
-    security_token: "{{ assumed_role.sts_creds.session_token }}"
+    access_key: "{{ assumed_role.sts_creds.access_key }}"
+    secret_key: "{{ assumed_role.sts_creds.secret_key }}"
+    session_token: "{{ assumed_role.sts_creds.session_token }}"
     resource: i-xyzxyz01
     state: present
     tags:

plugins/modules/sts_session_token.py

@@ -8,7 +8,7 @@
 ---
 module: sts_session_token
 version_added: 1.0.0
-short_description: Obtain a session token from the AWS Security Token Service
+short_description: obtain a session token from the AWS Security Token Service
 description:
   - Obtain a session token from the AWS Security Token Service.
 author:
@@ -29,7 +29,8 @@
       - The value provided by the MFA device, if the trust policy of the user requires MFA.
     type: str
 notes:
-  - In order to use the session token in a following playbook task you must pass the I(access_key), I(access_secret) and I(access_token).
+  - In order to use the session token in a following playbook task you must pass the I(access_key),
+    I(secret_key) and I(session_token) parameters to modules that should use the session credentials.
 extends_documentation_fragment:
   - amazon.aws.common.modules
   - amazon.aws.region.modules
@@ -42,7 +43,7 @@
     returned: always
     type: list
     sample:
-      access_key: ASXXXXXXXXXXXXXXXXXX
+      access_key: ASIAXXXXXXXXXXXXXXXX
       expiration: "2016-04-08T11:59:47+00:00"
       secret_key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
       session_token: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
@@ -59,14 +60,16 @@
 # (more details: https://docs.aws.amazon.com/STS/latest/APIReference/API_GetSessionToken.html)
 - name: Get a session token
   community.aws.sts_session_token:
+    access_key: AKIA1EXAMPLE1EXAMPLE
+    secret_key: 123456789abcdefghijklmnopqrstuvwxyzABCDE
     duration_seconds: 3600
   register: session_credentials
 
 - name: Use the session token obtained above to tag an instance in account 123456789012
   amazon.aws.ec2_tag:
-    aws_access_key: "{{ session_credentials.sts_creds.access_key }}"
-    aws_secret_key: "{{ session_credentials.sts_creds.secret_key }}"
-    security_token: "{{ session_credentials.sts_creds.session_token }}"
+    access_key: "{{ session_credentials.sts_creds.access_key }}"
+    secret_key: "{{ session_credentials.sts_creds.secret_key }}"
+    session_token: "{{ session_credentials.sts_creds.session_token }}"
     resource: i-xyzxyz01
     state: present
     tags:

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

@@ -1,10 +1,10 @@
 ---
 - module_defaults:
     group/aws:
-      aws_access_key: '{{ aws_access_key | default(omit) }}'
-      aws_secret_key: '{{ aws_secret_key | default(omit) }}'
-      security_token: '{{ security_token | default(omit) }}'
-      region: '{{ aws_region | default(omit) }}'
+      access_key: '{{ aws_access_key }}'
+      secret_key: '{{ aws_secret_key }}'
+      session_token: '{{ security_token | default(omit) }}'
+      region: '{{ aws_region }}'
 
   block:
     - name: get ARN of calling user

tests/integration/targets/acm_certificate/tasks/full_acm_test.yml

@@ -2,9 +2,9 @@
   module_defaults:
     group/aws:
       aws_region: '{{ aws_region }}'
-      aws_access_key: '{{ aws_access_key }}'
-      aws_secret_key: '{{ aws_secret_key }}'
-      security_token: '{{ security_token | default(omit) }}'
+      access_key: '{{ aws_access_key }}'
+      secret_key: '{{ aws_secret_key }}'
+      session_token: '{{ security_token | default(omit) }}'
   block:
   - name: list certs
     aws_acm_info: null

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

@@ -2,9 +2,9 @@
   module_defaults:
     group/aws:
       aws_region: '{{ aws_region }}'
-      aws_access_key: '{{ aws_access_key }}'
-      aws_secret_key: '{{ aws_secret_key }}'
-      security_token: '{{ security_token | default(omit) }}'
+      access_key: '{{ aws_access_key }}'
+      secret_key: '{{ aws_secret_key }}'
+      session_token: '{{ security_token | default(omit) }}'
   block:
   # The CI runs many of these tests in parallel
   # Use this random ID to differentiate which resources

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

@@ -1,9 +1,9 @@
 - name: Wrap API Gateway tests with credentials by default
   module_defaults:
     group/aws:
-      aws_access_key: '{{ aws_access_key }}'
-      aws_secret_key: '{{ aws_secret_key }}'
-      security_token: '{{ security_token | default(omit) }}'
+      access_key: '{{ aws_access_key }}'
+      secret_key: '{{ aws_secret_key }}'
+      session_token: '{{ security_token | default(omit) }}'
       region: '{{ aws_region }}'
 
   block:

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

@@ -4,9 +4,9 @@
 - name: Run aws_api_gateway_domain module integration tests
   module_defaults:
     group/aws:
-      aws_access_key: "{{ aws_access_key }}"
-      aws_secret_key: "{{ aws_secret_key }}"
-      security_token: "{{ security_token | default(omit) }}"
+      access_key: "{{ aws_access_key }}"
+      secret_key: "{{ aws_secret_key }}"
+      session_token: "{{ security_token | default(omit) }}"
       region: "{{ aws_region }}"
 
   # NOTE: To make tests work set TLS ARN in defaults/main.yml to an existing and

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

@@ -2,9 +2,9 @@
 - name: "Wrap up all tests and setup AWS credentials"
   module_defaults:
     group/aws:
-      aws_access_key: "{{ aws_access_key }}"
-      aws_secret_key: "{{ aws_secret_key }}"
-      security_token: "{{ security_token | default(omit) }}"
+      access_key: "{{ aws_access_key }}"
+      secret_key: "{{ aws_secret_key }}"
+      session_token: "{{ security_token | default(omit) }}"
       region: "{{ aws_region }}"
   collections:
     - community.aws

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

@@ -2,9 +2,9 @@
 - name: setup credentials and region
   module_defaults:
     group/aws:
-      aws_access_key: "{{ aws_access_key }}"
-      aws_secret_key: "{{ aws_secret_key }}"
-      security_token: "{{ security_token | default(omit) }}"
+      access_key: "{{ aws_access_key }}"
+      secret_key: "{{ aws_secret_key }}"
+      session_token: "{{ security_token | default(omit) }}"
       region: "{{ aws_region }}"
 
   collections:

tests/integration/targets/autoscaling_instance_refresh/tasks/refresh_and_cancel_three_times.yml

@@ -10,8 +10,8 @@
   ec2_asg_instance_refresh:
     name: "{{ asg_name }}"
     state: "started"
-    aws_access_key: "{{ aws_access_key }}"
-    aws_secret_key: "{{ aws_secret_key }}"
+    access_key: "{{ aws_access_key }}"
+    secret_key: "{{ aws_secret_key }}"
     region: "{{ aws_region }}"
   ignore_errors: no
   retries: 10
@@ -23,7 +23,7 @@
   ec2_asg_instance_refresh:
     name: "{{ asg_name }}"
     state: "cancelled"
-    aws_access_key: "{{ aws_access_key }}"
-    aws_secret_key: "{{ aws_secret_key }}"
+    access_key: "{{ aws_access_key }}"
+    secret_key: "{{ aws_secret_key }}"
     region: "{{ aws_region }}"
   ignore_errors: yes

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

@@ -1,9 +1,9 @@
 - name: run ec2_lc tests
   module_defaults:
     group/aws:
-      aws_access_key: "{{ aws_access_key }}"
-      aws_secret_key: "{{ aws_secret_key }}"
-      security_token: "{{ security_token | default(omit) }}"
+      access_key: "{{ aws_access_key }}"
+      secret_key: "{{ aws_secret_key }}"
+      session_token: "{{ security_token | default(omit) }}"
       region: "{{ aws_region }}"
   collections:
     - amazon.aws

tests/integration/targets/autoscaling_lifecycle_hook/main.yml

@@ -10,9 +10,9 @@
   tasks:
   - module_defaults:
       group/aws:
-        aws_access_key: "{{ aws_access_key }}"
-        aws_secret_key: "{{ aws_secret_key }}"
-        security_token: "{{ security_token | default(omit) }}"
+        access_key: "{{ aws_access_key }}"
+        secret_key: "{{ aws_secret_key }}"
+        session_token: "{{ security_token | default(omit) }}"
         region: "{{ aws_region }}"
     vars:
       # We can't just use "run_once" because the facts don't propagate when

tests/integration/targets/autoscaling_lifecycle_hook/roles/ec2_asg_lifecycle_hook/tasks/main.yml

@@ -6,9 +6,9 @@
 - name: "Wrap up all tests and setup AWS credentials"
   module_defaults:
     group/aws:
-      aws_access_key: "{{ aws_access_key }}"
-      aws_secret_key: "{{ aws_secret_key }}"
-      security_token: "{{ security_token | default(omit) }}"
+      access_key: "{{ aws_access_key }}"
+      secret_key: "{{ aws_secret_key }}"
+      session_token: "{{ security_token | default(omit) }}"
       region: "{{ aws_region }}"
       aws_config:
         retries:

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

@@ -12,9 +12,9 @@
 - module_defaults:
     group/aws:
         region: "{{ aws_region }}"
-        aws_access_key: "{{ aws_access_key }}"
-        aws_secret_key: "{{ aws_secret_key }}"
-        security_token: "{{ security_token | default(omit) }}"
+        access_key: "{{ aws_access_key }}"
+        secret_key: "{{ aws_secret_key }}"
+        session_token: "{{ security_token | default(omit) }}"
   collections:
     - amazon.aws
   block:

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

@@ -5,9 +5,9 @@
     - community.aws
   module_defaults:
     group/aws:
-      aws_access_key: "{{ aws_access_key }}"
-      aws_secret_key: "{{ aws_secret_key }}"
-      security_token: "{{ security_token | default(omit) }}"
+      access_key: "{{ aws_access_key }}"
+      secret_key: "{{ aws_secret_key }}"
+      session_token: "{{ security_token | default(omit) }}"
       region: "{{ aws_region }}"
   block:
     ## Set up the testing dependencies: VPC, subnet, security group, and launch configuration

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

@@ -1,10 +1,10 @@
 ---
 - module_defaults:
     group/aws:
-      aws_access_key: '{{ aws_access_key | default(omit) }}'
-      aws_secret_key: '{{ aws_secret_key | default(omit) }}'
-      security_token: '{{ security_token | default(omit) }}'
-      region: '{{ aws_region | default(omit) }}'
+      access_key: '{{ aws_access_key }}'
+      secret_key: '{{ aws_secret_key }}'
+      session_token: '{{ security_token | default(omit) }}'
+      region: '{{ aws_region }}'
 
   block:
   - name: 'List available Regions'

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

@@ -1,9 +1,9 @@
 - name: set connection information for aws modules and run tasks
   module_defaults:
     group/aws:
-      aws_access_key: "{{ aws_access_key }}"
-      aws_secret_key: "{{ aws_secret_key }}"
-      security_token: "{{ security_token | default(omit) }}"
+      access_key: "{{ aws_access_key }}"
+      secret_key: "{{ aws_secret_key }}"
+      session_token: "{{ security_token | default(omit) }}"
       region: "{{ aws_region }}"
   collections:
     - amazon.aws

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

@@ -5,14 +5,14 @@
 - name: set up aws connection info
   set_fact:
     aws_connection_info: &aws_connection_info
-      aws_access_key: "{{ aws_access_key }}"
-      aws_secret_key: "{{ aws_secret_key }}"
-      security_token: "{{ security_token }}"
+      access_key: "{{ aws_access_key }}"
+      secret_key: "{{ aws_secret_key }}"
+      session_token: "{{ security_token | default(omit) }}"
       region: "{{ aws_region }}"
     aws_secondary_connection_info: &aws_secondary_connection_info
-      aws_access_key: "{{ secondary_aws_access_key }}"
-      aws_secret_key: "{{ secondary_aws_secret_key }}"
-      security_token: "{{ secondary_security_token }}"
+      access_key: "{{ secondary_aws_access_key }}"
+      secret_key: "{{ secondary_aws_secret_key }}"
+      session_token: "{{ secondary_security_token | default(omit) }}"
       region: "{{ aws_region }}"
   no_log: true