AWS modules: _facts -> _info (#57613)

* Rename aws_acm_facts -> aws_acm_info.

* Rename aws_az_facts -> aws_az_info.

* Rename aws_caller_facts -> aws_caller_info.

* Rename aws_kms_facts -> aws_kms_info.

* Rename aws_region_facts -> aws_region_info.

* Rename aws_sgw_facts -> aws_sgw_info.

* Rename aws_waf_facts -> aws_waf_info.

* Adjust docs.

* Add changelog and update porting guide.

changelogs/fragments/57613-aws-facts-info.yaml

@@ -0,0 +1,8 @@
+minor_changes:
+- The ``aws_acm_facts`` module has been renamed to ``aws_acm_info``.
+- The ``aws_az_facts`` module has been renamed to ``aws_az_info``.
+- The ``aws_caller_facts`` module has been renamed to ``aws_caller_info``.
+- The ``aws_kms_facts`` module has been renamed to ``aws_kms_info``.
+- The ``aws_region_facts`` module has been renamed to ``aws_region_info``.
+- The ``aws_sgw_facts`` module has been renamed to ``aws_sgw_info``.
+- The ``aws_waf_facts`` module has been renamed to ``aws_waf_info``.

docs/docsite/rst/porting_guides/porting_guide_2.9.rst

@@ -95,6 +95,13 @@ Noteworthy module changes
 * The ``digital_ocean_snapshot_facts`` module was renamed to :ref:`digital_ocean_snapshot_info <digital_ocean_snapshot_info_module>`.
 * The ``digital_ocean_tag_facts`` module was renamed to :ref:`digital_ocean_tag_info <digital_ocean_tag_info_module>`.
 * The ``digital_ocean_volume_facts`` module was renamed to :ref:`digital_ocean_volume_info <digital_ocean_volume_info_module>`.
+* The ``aws_acm_facts`` module was renamed to :ref:`aws_acm_info <aws_acm_info_module>`.
+* The ``aws_az_facts`` module was renamed to :ref:`aws_az_info <aws_az_info_module>`.
+* The ``aws_caller_facts`` module was renamed to :ref:`aws_caller_info <aws_caller_info_module>`.
+* The ``aws_kms_facts`` module was renamed to :ref:`aws_kms_info <aws_kms_info_module>`.
+* The ``aws_region_facts`` module was renamed to :ref:`aws_region_info <aws_region_info_module>`.
+* The ``aws_sgw_facts`` module was renamed to :ref:`aws_sgw_info <aws_sgw_info_module>`.
+* The ``aws_waf_facts`` module was renamed to :ref:`aws_waf_info <aws_waf_info_module>`.
 
 
 Plugins

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

@@ -0,0 +1 @@
+aws_acm_info.py

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

@@ -0,0 +1 @@
+aws_az_info.py

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

@@ -0,0 +1 @@
+aws_caller_info.py

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

@@ -0,0 +1 @@
+aws_kms_info.py

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

@@ -0,0 +1 @@
+aws_region_info.py

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

@@ -0,0 +1 @@
+aws_sgw_info.py

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

@@ -0,0 +1 @@
+aws_waf_info.py

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

@@ -7,10 +7,11 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'supported_by': 'community'}
 
 DOCUMENTATION = '''
-module: aws_acm_facts
+module: aws_acm_info
-short_description: Retrieve certificate facts from AWS Certificate Manager service
+short_description: Retrieve certificate information from AWS Certificate Manager service
 description:
-  - Retrieve facts for ACM certificates
+  - Retrieve information for ACM certificates
+  - This module was called C(aws_acm_facts) before Ansible 2.9. The usage did not change.
 version_added: "2.5"
 options:
   domain_name:
@@ -33,14 +34,14 @@ extends_documentation_fragment:
 
 EXAMPLES = '''
 - name: obtain all ACM certificates
-  aws_acm_facts:
+  aws_acm_info:
 
-- name: obtain all facts for a single ACM certificate
+- name: obtain all information for a single ACM certificate
-  aws_acm_facts:
+  aws_acm_info:
     domain_name: "*.example_com"
 
 - name: obtain all certificates pending validiation
-  aws_acm_facts:
+  aws_acm_info:
     statuses:
     - PENDING_VALIDATION
 '''
@@ -314,6 +315,8 @@ def main():
         )
     )
     module = AnsibleModule(argument_spec=argument_spec, supports_check_mode=True)
+    if module._name == 'aws_acm_facts':
+        module.deprecate("The 'aws_acm_facts' module has been renamed to 'aws_acm_info'", version='2.13')
 
     if not HAS_BOTO3:
         module.fail_json(msg='boto3 and botocore are required by this module')

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

@@ -9,10 +9,11 @@ ANSIBLE_METADATA = {
 }
 
 DOCUMENTATION = '''
-module: aws_az_facts
+module: aws_az_info
-short_description: Gather facts about availability zones in AWS.
+short_description: Gather information about availability zones in AWS.
 description:
-    - Gather facts about availability zones in AWS.
+    - Gather information about availability zones in AWS.
+    - This module was called C(aws_az_facts) before Ansible 2.9. The usage did not change.
 version_added: '2.5'
 author: 'Henrique Rodrigues (@Sodki)'
 options:
@@ -33,11 +34,11 @@ requirements: [botocore, boto3]
 EXAMPLES = '''
 # Note: These examples do not set authentication details, see the AWS Guide for details.
 
-# Gather facts about all availability zones
+# Gather information about all availability zones
-- aws_az_facts:
+- aws_az_info:
 
-# Gather facts about a single availability zone
+# Gather information about a single availability zone
-- aws_az_facts:
+- aws_az_info:
     filters:
       zone-name: eu-west-1a
 '''
@@ -87,6 +88,8 @@ def main():
     )
 
     module = AnsibleModule(argument_spec=argument_spec)
+    if module._name == 'aws_acm_facts':
+        module.deprecate("The 'aws_az_facts' module has been renamed to 'aws_az_info'", version='2.13')
 
     if not HAS_BOTO3:
         module.fail_json(msg='boto3 required for this module')

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

@@ -10,11 +10,12 @@ ANSIBLE_METADATA = {
 
 DOCUMENTATION = '''
 ---
-module: aws_caller_facts
+module: aws_caller_info
-short_description: Get facts about the user and account being used to make AWS calls.
+short_description: Get information about the user and account being used to make AWS calls.
 description:
     - This module returns information about the account and user / role from which the AWS access tokens originate.
     - The primary use of this is to get the account id for templating into ARNs or similar to avoid needing to specify this information in inventory.
+    - This module was called C(aws_caller_facts) before Ansible 2.9. The usage did not change.
 version_added: "2.6"
 
 author:
@@ -30,9 +31,9 @@ extends_documentation_fragment:
 EXAMPLES = '''
 # Note: These examples do not set authentication details, see the AWS Guide for details.
 
-- name: Get the current caller identity facts
+- name: Get the current caller identity information
-  aws_caller_facts:
+  aws_caller_info:
-  register: caller_facts
+  register: caller_info
 '''
 
 RETURN = '''
@@ -74,12 +75,14 @@ def main():
         argument_spec={},
         supports_check_mode=True,
     )
+    if module._name == 'aws_caller_facts':
+        module.deprecate("The 'aws_caller_facts' module has been renamed to 'aws_caller_info'", version='2.13')
 
     client = module.client('sts')
 
     try:
-        caller_facts = client.get_caller_identity()
+        caller_info = client.get_caller_identity()
-        caller_facts.pop('ResponseMetadata', None)
+        caller_info.pop('ResponseMetadata', None)
     except (BotoCoreError, ClientError) as e:
         module.fail_json_aws(e, msg='Failed to retrieve caller identity')
 
@@ -91,9 +94,9 @@ def main():
         # see https://docs.aws.amazon.com/cli/latest/reference/iam/list-account-aliases.html#output
         response = iam_client.list_account_aliases()
         if response and response['AccountAliases']:
-            caller_facts['account_alias'] = response['AccountAliases'][0]
+            caller_info['account_alias'] = response['AccountAliases'][0]
         else:
-            caller_facts['account_alias'] = ''
+            caller_info['account_alias'] = ''
     except (BotoCoreError, ClientError) as e:
         # The iam:ListAccountAliases permission is required for this operation to succeed.
         # Lacking this permission is handled gracefully by not returning the account_alias.
@@ -101,7 +104,7 @@ def main():
 
     module.exit_json(
         changed=False,
-        **camel_dict_to_snake_dict(caller_facts))
+        **camel_dict_to_snake_dict(caller_info))
 
 
 if __name__ == '__main__':

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

@@ -41,7 +41,7 @@ extends_documentation_fragment:
 
 EXAMPLES = '''
 - name: Get current account ID
-  aws_caller_facts:
+  aws_caller_info:
   register: whoami
 - aws_config_aggregation_authorization:
     state: present

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

@@ -25,7 +25,7 @@ options:
     description: An alias for a key. For safety, even though KMS does not require keys
       to have an alias, this module expects all new keys to be given an alias
       to make them easier to manage. Existing keys without an alias may be
-      referred to by I(key_id). Use M(aws_kms_facts) to find key ids. Required
+      referred to by I(key_id). Use M(aws_kms_info) to find key ids. Required
       if I(key_id) is not given. Note that passing a I(key_id) and I(alias)
       will only cause a new alias to be added, an alias will never be renamed.
       The 'alias/' prefix is optional.

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

@@ -20,10 +20,11 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
 
 DOCUMENTATION = '''
 ---
-module: aws_kms_facts
+module: aws_kms_info
-short_description: Gather facts about AWS KMS keys
+short_description: Gather information about AWS KMS keys
 description:
-    - Gather facts about AWS KMS keys including tags and grants
+    - Gather information about AWS KMS keys including tags and grants
+    - This module was called C(aws_kms_facts) before Ansible 2.9. The usage did not change.
 version_added: "2.5"
 author: "Will Thames (@willthames)"
 options:
@@ -45,16 +46,16 @@ extends_documentation_fragment:
 EXAMPLES = '''
 # Note: These examples do not set authentication details, see the AWS Guide for details.
 
-# Gather facts about all KMS keys
+# Gather information about all KMS keys
-- aws_kms_facts:
+- aws_kms_info:
 
-# Gather facts about all keys with a Name tag
+# Gather information about all keys with a Name tag
-- aws_kms_facts:
+- aws_kms_info:
     filters:
       tag-key: Name
 
-# Gather facts about all keys with a specific name
+# Gather information about all keys with a specific name
-- aws_kms_facts:
+- aws_kms_info:
     filters:
       "tag:Name": Example
 '''
@@ -384,7 +385,7 @@ def get_key_details(connection, module, key_id, tokens=None):
     return result
 
 
-def get_kms_facts(connection, module):
+def get_kms_info(connection, module):
     try:
         keys = get_kms_keys_with_backoff(connection)['Keys']
     except botocore.exceptions.ClientError as e:
@@ -406,6 +407,8 @@ def main():
 
     module = AnsibleModule(argument_spec=argument_spec,
                            supports_check_mode=True)
+    if module._name == 'aws_kms_facts':
+        module.deprecate("The 'aws_kms_facts' module has been renamed to 'aws_kms_info'", version='2.13')
 
     if not HAS_BOTO3:
         module.fail_json(msg='boto3 and botocore are required for this module')
@@ -417,7 +420,7 @@ def main():
     else:
         module.fail_json(msg="region must be specified")
 
-    all_keys = get_kms_facts(connection, module)
+    all_keys = get_kms_info(connection, module)
     module.exit_json(keys=[key for key in all_keys if key_matches_filters(key, module.params['filters'])])
 
 

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

@@ -9,10 +9,11 @@ ANSIBLE_METADATA = {
 }
 
 DOCUMENTATION = '''
-module: aws_region_facts
+module: aws_region_info
-short_description: Gather facts about AWS regions.
+short_description: Gather information about AWS regions.
 description:
-    - Gather facts about AWS regions.
+    - Gather information about AWS regions.
+    - This module was called C(aws_region_facts) before Ansible 2.9. The usage did not change.
 version_added: '2.5'
 author: 'Henrique Rodrigues (@Sodki)'
 options:
@@ -32,11 +33,11 @@ requirements: [botocore, boto3]
 EXAMPLES = '''
 # Note: These examples do not set authentication details, see the AWS Guide for details.
 
-# Gather facts about all regions
+# Gather information about all regions
-- aws_region_facts:
+- aws_region_info:
 
-# Gather facts about a single region
+# Gather information about a single region
-- aws_region_facts:
+- aws_region_info:
     filters:
       region-name: eu-west-1
 '''
@@ -76,6 +77,8 @@ def main():
     )
 
     module = AnsibleModule(argument_spec=argument_spec)
+    if module._name == 'aws_region_facts':
+        module.deprecate("The 'aws_region_facts' module has been renamed to 'aws_region_info'", version='2.13')
 
     if not HAS_BOTO3:
         module.fail_json(msg='boto3 required for this module')

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

@@ -11,10 +11,11 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
 
 DOCUMENTATION = '''
 ---
-module: aws_sgw_facts
+module: aws_sgw_info
-short_description: Fetch AWS Storage Gateway facts
+short_description: Fetch AWS Storage Gateway information
 description:
-    - Fetch AWS Storage Gateway facts
+    - Fetch AWS Storage Gateway information
+    - This module was called C(aws_sgw_facts) before Ansible 2.9. The usage did not change.
 version_added: "2.6"
 requirements: [ boto3 ]
 author: Loic Blot (@nerzhul) <loic.blot@unix-experience.fr>
@@ -164,11 +165,11 @@ gateways:
 EXAMPLES = '''
 # Note: These examples do not set authentication details, see the AWS Guide for details.
 
-- name: "Get AWS storage gateway facts"
+- name: "Get AWS storage gateway information"
-  aws_sgw_facts:
+  aws_sgw_info:
 
-- name: "Get AWS storage gateway facts for region eu-west-3"
+- name: "Get AWS storage gateway information for region eu-west-3"
-  aws_sgw_facts:
+  aws_sgw_info:
     region: eu-west-3
 '''
 
@@ -181,7 +182,7 @@ except ImportError:
     pass  # caught by imported HAS_BOTO3
 
 
-class SGWFactsManager(object):
+class SGWInformationManager(object):
     def __init__(self, client, module):
         self.client = client
         self.module = module
@@ -344,12 +345,14 @@ def main():
     )
 
     module = AnsibleAWSModule(argument_spec=argument_spec)
+    if module._name == 'aws_sgw_facts':
+        module.deprecate("The 'aws_sgw_facts' module has been renamed to 'aws_sgw_info'", version='2.13')
     client = module.client('storagegateway')
 
     if client is None:  # this should never happen
         module.fail_json(msg='Unknown error, failed to create storagegateway client, no information from boto.')
 
-    SGWFactsManager(client, module).fetch()
+    SGWInformationManager(client, module).fetch()
 
 
 if __name__ == '__main__':

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

@@ -7,10 +7,11 @@ ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'supported_by': 'community'}
 
 DOCUMENTATION = '''
-module: aws_waf_facts
+module: aws_waf_info
-short_description: Retrieve facts for WAF ACLs, Rule , Conditions and Filters.
+short_description: Retrieve information for WAF ACLs, Rule , Conditions and Filters.
 description:
-  - Retrieve facts for WAF ACLs, Rule , Conditions and Filters.
+  - Retrieve information for WAF ACLs, Rule , Conditions and Filters.
+  - This module was called C(aws_waf_facts) before Ansible 2.9. The usage did not change.
 version_added: "2.4"
 requirements: [ boto3 ]
 options:
@@ -33,15 +34,15 @@ extends_documentation_fragment:
 '''
 
 EXAMPLES = '''
-- name: obtain all WAF facts
+- name: obtain all WAF information
-  aws_waf_facts:
+  aws_waf_info:
 
-- name: obtain all facts for a single WAF
+- name: obtain all information for a single WAF
-  aws_waf_facts:
+  aws_waf_info:
     name: test_waf
 
-- name: obtain all facts for a single WAF Regional
+- name: obtain all information for a single WAF Regional
-  aws_waf_facts:
+  aws_waf_info:
     name: test_waf
     waf_regional: true
 '''
@@ -128,6 +129,8 @@ def main():
         )
     )
     module = AnsibleAWSModule(argument_spec=argument_spec, supports_check_mode=True)
+    if module._name == 'aws_waf_facts':
+        module.deprecate("The 'aws_waf_facts' module has been renamed to 'aws_waf_info'", version='2.13')
 
     region, ec2_url, aws_connect_kwargs = get_aws_connection_info(module, boto3=True)
     resource = 'waf' if not module.params['waf_regional'] else 'waf-regional'

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

@@ -496,7 +496,7 @@ def main():
     if state == 'present' and not module.params['accounts']:
         module.fail_json(
             msg="Can't create a stack set without choosing at least one account. "
-                "To get the ID of the current account, use the aws_caller_facts module."
+                "To get the ID of the current account, use the aws_caller_info module."
         )
 
     module.params['accounts'] = [to_native(a) for a in module.params['accounts']]

test/integration/targets/aws_caller_info/tasks/main.yaml

@@ -1,5 +1,5 @@
 - name: retrieve caller facts
-  aws_caller_facts:
+  aws_caller_info:
     region: "{{ aws_region }}"
     aws_access_key: "{{ aws_access_key }}"
     aws_secret_key: "{{ aws_secret_key }}"

test/integration/targets/aws_kms/aliases

@@ -1,3 +1,3 @@
 cloud/aws
-aws_kms_facts
+aws_kms_info
 unsupported

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

@@ -2,7 +2,7 @@
 
     # ============================================================
     - name: See whether key exists and its current state
-      aws_kms_facts:
+      aws_kms_info:
         region: "{{ aws_region }}"
         aws_access_key: "{{ aws_access_key }}"
         aws_secret_key: "{{ aws_secret_key }}"
@@ -30,7 +30,7 @@
           - create_kms.tags['Hello'] == 'World'
 
     - name: find facts about the key
-      aws_kms_facts:
+      aws_kms_info:
         region: "{{ aws_region }}"
         aws_access_key: "{{ aws_access_key }}"
         aws_secret_key: "{{ aws_secret_key }}"
@@ -66,7 +66,7 @@
         region: "{{ aws_region }}"
 
     - name: find facts about the key
-      aws_kms_facts:
+      aws_kms_info:
         region: "{{ aws_region }}"
         aws_access_key: "{{ aws_access_key }}"
         aws_secret_key: "{{ aws_secret_key }}"
@@ -86,7 +86,7 @@
         region: "{{ aws_region }}"
 
     - name: find facts about the key
-      aws_kms_facts:
+      aws_kms_info:
         region: "{{ aws_region }}"
         aws_access_key: "{{ aws_access_key }}"
         aws_secret_key: "{{ aws_secret_key }}"

test/integration/targets/aws_secret/tasks/main.yaml

@@ -10,7 +10,7 @@
     no_log: true
 
   - name: retrieve caller facts
-    aws_caller_facts:
+    aws_caller_info:
       <<: *aws_connection_info
     register: test_caller_facts
 

test/integration/targets/aws_waf_web_acl/aliases

@@ -1,5 +1,5 @@
 cloud/aws
-aws_waf_facts
+aws_waf_info
 aws_waf_web_acl
 aws_waf_web_match
 aws_waf_web_rule

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

@@ -18,11 +18,11 @@
 
 - block:
     - name: Get current account ID
-      aws_caller_facts:
+      aws_caller_info:
         <<: *aws_connection_info
       register: whoami
     - name: Get current account ID
-      aws_caller_facts:
+      aws_caller_info:
         <<: *aws_secondary_connection_info
       register: target_acct
 

test/integration/targets/ec2_group/tasks/multi_account.yml

@@ -1,5 +1,5 @@
 - block:
-    - aws_caller_facts:
+    - aws_caller_info:
       register: caller_facts
     - name: create a VPC
       ec2_vpc_net:

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

@@ -127,13 +127,13 @@
       register: lambda_result
 
     - name: get the aws account ID for use in future commands
-      aws_caller_facts:
+      aws_caller_info:
         <<: *aws_connection_info
-      register: aws_caller_facts
+      register: aws_caller_info
 
     - name: register lambda uri for use in template
       set_fact:
-        mini_lambda_uri: "arn:aws:apigateway:{{ aws_region }}:lambda:path/2015-03-31/functions/arn:aws:lambda:{{ aws_region }}:{{ aws_caller_facts.account }}:function:{{ lambda_result.configuration.function_name }}/invocations"
+        mini_lambda_uri: "arn:aws:apigateway:{{ aws_region }}:lambda:path/2015-03-31/functions/arn:aws:lambda:{{ aws_region }}:{{ aws_caller_info.account }}:function:{{ lambda_result.configuration.function_name }}/invocations"
 
     - name: build API file
       template:
@@ -170,7 +170,7 @@
         statement_id: api-gateway-invoke-lambdas
         action: lambda:InvokeFunction
         principal: apigateway.amazonaws.com
-        source_arn: "arn:aws:execute-api:{{ aws_region }}:{{ aws_caller_facts.account }}:*/*"
+        source_arn: "arn:aws:execute-api:{{ aws_region }}:{{ aws_caller_info.account }}:*/*"
         <<: *aws_connection_info
 
     - name: try again but with ARN
@@ -180,7 +180,7 @@
         statement_id: api-gateway-invoke-lambdas
         action: lambda:InvokeFunction
         principal: apigateway.amazonaws.com
-        source_arn: "arn:aws:execute-api:{{ aws_region }}:{{ aws_caller_facts.account }}:*/*"
+        source_arn: "arn:aws:execute-api:{{ aws_region }}:{{ aws_caller_info.account }}:*/*"
         <<: *aws_connection_info
 
     - name: check API works with execute permissions