Update ec2_vpc_subnet_facts to use Boto3 (#25374)

* update ec2_vpc_subnet_facts module to use boto3 and support gathering updated fact items from AWS API

add version_added to new parameter

added return docs and other requested changes

removed errant extra blank line

updates per review

* update per review: fix AWSRetry backoff implementation and fix example that was not correct

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

@@ -26,13 +26,18 @@ description:
     - Gather facts about ec2 VPC subnets in AWS
 version_added: "2.1"
 author: "Rob White (@wimnat)"
+requirements:
+  - boto3
+  - botocore
 options:
+  subnet_ids:
+    description:
+      - A list of subnet IDs to gather facts for.
+    version_added: "2.5"
   filters:
     description:
       - A dict of filters to apply. Each dict item consists of a filter key and a filter value.
         See U(http://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeSubnets.html) for possible filters.
-    required: false
-    default: null
 extends_documentation_fragment:
     - aws
     - ec2
@@ -46,8 +51,7 @@ EXAMPLES = '''
 
 # Gather facts about a particular VPC subnet using ID
 - ec2_vpc_subnet_facts:
-    filters:
+    subnet_ids: subnet-00112233
-      subnet-id: subnet-00112233
 
 # Gather facts about any VPC subnet with a tag key Name and value Example
 - ec2_vpc_subnet_facts:
@@ -74,76 +78,169 @@ EXAMPLES = '''
   register: subnet_facts
 
 - set_fact:
-    subnet_ids: "{{ subnet_facts.results|map(attribute='subnets.0.id')|list }}"
+    subnet_ids: "{{ subnet_facts.subnets|map(attribute='id')|list }}"
 '''
 
-try:
+RETURN = '''
-    import boto.vpc
+subnets:
-    from boto.exception import BotoServerError
+    description: Returns an array of complex objects as described below.
-    HAS_BOTO = True
+    returned: success
-except ImportError:
+    type: complex
-    HAS_BOTO = False
+    contains:
+        subnet_id:
+            description: The ID of the Subnet.
+            returned: always
+            type: string
+        id:
+            description: The ID of the Subnet (for backwards compatibility).
+            returned: always
+            type: string
+        vpc_id:
+            description: The ID of the VPC .
+            returned: always
+            type: string
+        state:
+            description: The state of the subnet.
+            returned: always
+            type: string
+        tags:
+            description: A dict of tags associated with the Subnet.
+            returned: always
+            type: dict
+        map_public_ip_on_launch:
+            description: True/False depending on attribute setting for public IP mapping.
+            returned: always
+            type: boolean
+        default_for_az:
+            description: True if this is the default subnet for AZ.
+            returned: always
+            type: boolean
+        cidr_block:
+            description: The IPv4 CIDR block assigned to the subnet.
+            returned: always
+            type: string
+        available_ip_address_count:
+            description: Count of available IPs in subnet.
+            returned: always
+            type: string
+        availability_zone:
+            description: The availability zone where the subnet exists.
+            returned: always
+            type: string
+        assign_ipv6_address_on_creation:
+            description: True/False depending on attribute setting for IPv6 address assignment.
+            returned: always
+            type: boolean
+        ipv6_cidr_block_association_set:
+            description: An array of IPv6 cidr block association set information.
+            returned: always
+            type: complex
+            contains:
+                association_id:
+                    description: The association ID
+                    returned: always
+                    type: string
+                ipv6_cidr_block:
+                    description: The IPv6 CIDR block that is associated with the subnet.
+                    returned: always
+                    type: string
+                ipv6_cidr_block_state:
+                    description: A hash/dict that contains a single item. The state of the cidr block association.
+                    returned: always
+                    type: dict
+                    contains:
+                        state:
+                            description: The CIDR block association state.
+                            returned: always
+                            type: string
+'''
 
+import traceback
 from ansible.module_utils.basic import AnsibleModule
-from ansible.module_utils.ec2 import AnsibleAWSError, connect_to_aws, ec2_argument_spec, get_aws_connection_info
+from ansible.module_utils.ec2 import (
+    boto3_conn,
+    ec2_argument_spec,
+    get_aws_connection_info,
+    AWSRetry,
+    HAS_BOTO3,
+    boto3_tag_list_to_ansible_dict,
+    camel_dict_to_snake_dict,
+    ansible_dict_to_boto3_filter_list
+)
+
+try:
+    import botocore
+except ImportError:
+    pass  # caught by imported HAS_BOTO3
 
 
-def get_subnet_info(subnet):
+@AWSRetry.exponential_backoff()
+def describe_subnets_with_backoff(connection, subnet_ids, filters):
+    """
+    Describe Subnets with AWSRetry backoff throttling support.
 
-    subnet_info = {'id': subnet.id,
+    connection  : boto3 client connection object
-                   'availability_zone': subnet.availability_zone,
+    subnet_ids  : list of subnet ids for which to gather facts
-                   'available_ip_address_count': subnet.available_ip_address_count,
+    filters     : additional filters to apply to request
-                   'cidr_block': subnet.cidr_block,
+    """
-                   'default_for_az': subnet.defaultForAz,
+    return connection.describe_subnets(SubnetIds=subnet_ids, Filters=filters)
-                   'map_public_ip_on_launch': subnet.mapPublicIpOnLaunch,
-                   'state': subnet.state,
-                   'tags': subnet.tags,
-                   'vpc_id': subnet.vpc_id}
-
-    return subnet_info
 
 
-def list_ec2_vpc_subnets(connection, module):
+def describe_subnets(connection, module):
+    """
+    Describe Subnets.
 
-    filters = module.params.get("filters")
+    module  : AnsibleModule object
-    subnet_dict_array = []
+    connection  : boto3 client connection object
+    """
+    # collect parameters
+    filters = ansible_dict_to_boto3_filter_list(module.params.get('filters'))
+    subnet_ids = module.params.get('subnet_ids')
 
+    if subnet_ids is None:
+        # Set subnet_ids to empty list if it is None
+        subnet_ids = []
+
+    # init empty list for return vars
+    subnet_info = list()
+
+    # Get the basic VPC info
     try:
-        all_subnets = connection.get_all_subnets(filters=filters)
+        response = describe_subnets_with_backoff(connection, subnet_ids, filters)
-    except BotoServerError as e:
+    except botocore.exceptions.ClientError as e:
-        module.fail_json(msg=e.message)
+        module.fail_json(msg=e.message, exception=traceback.format_exc(), **camel_dict_to_snake_dict(e.response))
 
-    for subnet in all_subnets:
+    for subnet in response['Subnets']:
-        subnet_dict_array.append(get_subnet_info(subnet))
+        # for backwards compatibility
+        subnet['id'] = subnet['SubnetId']
+        subnet_info.append(camel_dict_to_snake_dict(subnet))
+        # convert tag list to ansible dict
+        subnet_info[-1]['tags'] = boto3_tag_list_to_ansible_dict(subnet['Tags'])
 
-    module.exit_json(subnets=subnet_dict_array)
+    module.exit_json(subnets=subnet_info)
 
 
 def main():
     argument_spec = ec2_argument_spec()
-    argument_spec.update(
+    argument_spec.update(dict(
-        dict(
+        subnet_ids=dict(type='list', default=[]),
-            filters=dict(default=None, type='dict')
+        filters=dict(type='dict', default={})
-        )
+    ))
-    )
 
     module = AnsibleModule(argument_spec=argument_spec,
                            supports_check_mode=True)
 
-    if not HAS_BOTO:
+    if not HAS_BOTO3:
-        module.fail_json(msg='boto required for this module')
+        module.fail_json(msg='boto3 is required for this module')
 
-    region, ec2_url, aws_connect_params = get_aws_connection_info(module)
+    region, ec2_url, aws_connect_params = get_aws_connection_info(module, boto3=True)
 
-    if region:
     try:
-            connection = connect_to_aws(boto.vpc, region, **aws_connect_params)
+        connection = boto3_conn(module, conn_type='client', resource='ec2', **aws_connect_params)
-        except (boto.exception.NoAuthHandlerFound, AnsibleAWSError) as e:
+    except (botocore.exceptions.NoCredentialsError, botocore.exceptions.ProfileNotFound) as e:
-            module.fail_json(msg=str(e))
+        module.fail_json(msg=e.message, exception=traceback.format_exc(), **camel_dict_to_snake_dict(e.response))
-    else:
-        module.fail_json(msg="region must be specified")
 
-    list_ec2_vpc_subnets(connection, module)
+    describe_subnets(connection, module)
 
 
 if __name__ == '__main__':