ec2_vpc_net.py

#!/usr/bin/python
# -*- coding: utf-8 -*-

# Copyright: Ansible Project
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

DOCUMENTATION = r"""
---
module: ec2_vpc_net
version_added: 1.0.0
short_description: Configure AWS Virtual Private Clouds
description:
  - Create, modify, and terminate AWS Virtual Private Clouds (VPCs).
author:
  - Jonathan Davila (@defionscode)
  - Sloane Hertel (@s-hertel)
options:
  name:
    description:
      - The name to give your VPC. This is used in combination with O(cidr_block)
        to determine if a VPC already exists.
      - The value of O(name) overrides any value set for V(Name) in the O(tags)
        parameter.
      - At least one of O(name) and O(vpc_id) must be specified.
      - O(name) must be specified when creating a new VPC.
    type: str
  vpc_id:
    version_added: 4.0.0
    description:
      - The ID of the VPC.
      - At least one of O(name) and O(vpc_id) must be specified.
      - At least one of O(name) and O(cidr_block) must be specified.
    type: str
  cidr_block:
    description:
      - The primary CIDR of the VPC.
      - The first in the list will be used as the primary CIDR
        and is used in conjunction with O(name) to ensure idempotence.
      - Required when O(vpc_id) is not set.
    type: list
    elements: str
  ipv6_cidr:
    description:
      - Request an Amazon-provided IPv6 CIDR block with /56 prefix length. You cannot specify the range of IPv6 addresses,
        or the size of the CIDR block.
      - Default value is V(false) when creating a new VPC.
    type: bool
  purge_cidrs:
    description:
      - Remove CIDRs that are associated with the VPC and are not specified in O(cidr_block).
    default: false
    type: bool
  tenancy:
    description:
      - Whether to be V(default) or V(dedicated) tenancy.
      - This cannot be changed after the VPC has been created.
    default: default
    choices: [ 'default', 'dedicated' ]
    type: str
  dns_support:
    description:
      - Whether to enable AWS DNS support.
      - Default value is V(true) when creating a new VPC.
    type: bool
  dns_hostnames:
    description:
      - Whether to enable AWS hostname support.
      - Default value is V(true) when creating a new VPC.
    type: bool
  dhcp_opts_id:
    description:
      - The id of the DHCP options to use for this VPC.
    type: str
  state:
    description:
      - The state of the VPC. Either absent or present.
    default: present
    choices: [ 'present', 'absent' ]
    type: str
  multi_ok:
    description:
      - By default the module will not create another VPC if there is another VPC with the same name and CIDR block.
        Specify O(multi_ok=true) if you want duplicate VPCs created.
    type: bool
    default: false
extends_documentation_fragment:
  - amazon.aws.common.modules
  - amazon.aws.region.modules
  - amazon.aws.tags
  - amazon.aws.boto3
"""

EXAMPLES = r"""
# Note: These examples do not set authentication details, see the AWS Guide for details.

- name: create a VPC with dedicated tenancy and a couple of tags
  amazon.aws.ec2_vpc_net:
    name: Module_dev2
    cidr_block: 10.10.0.0/16
    region: us-east-1
    tags:
      module: ec2_vpc_net
      this: works
    tenancy: dedicated

- name: create a VPC with dedicated tenancy and request an IPv6 CIDR
  amazon.aws.ec2_vpc_net:
    name: Module_dev2
    cidr_block: 10.10.0.0/16
    ipv6_cidr: true
    region: us-east-1
    tenancy: dedicated

- name: Delete an existing VPC
  amazon.aws.ec2_vpc_net:
    vpc_id: vpc-0123456789abcdef0
    state: absent
"""

RETURN = r"""
vpc:
  description: Info about the VPC that was created or deleted.
  returned: always
  type: complex
  contains:
    cidr_block:
      description: The CIDR of the VPC.
      returned: always
      type: str
      sample: 10.0.0.0/16
    cidr_block_association_set:
      description: IPv4 CIDR blocks associated with the VPC.
      returned: success
      type: list
      sample:
        "cidr_block_association_set": [
            {
                "association_id": "vpc-cidr-assoc-97aeeefd",
                "cidr_block": "10.0.0.0/24",
                "cidr_block_state": {
                    "state": "associated"
                }
            }
        ]
    dhcp_options_id:
      description: The id of the DHCP options associated with this VPC.
      returned: always
      type: str
      sample: dopt-12345678
    id:
      description: VPC resource id.
      returned: always
      type: str
      sample: vpc-12345678
    name:
      description: The Name tag of the VPC.
      returned: When the Name tag has been set on the VPC
      type: str
      sample: MyVPC
      version_added: 4.0.0
    instance_tenancy:
      description: Indicates whether VPC uses default or dedicated tenancy.
      returned: always
      type: str
      sample: default
    ipv6_cidr_block_association_set:
      description: IPv6 CIDR blocks associated with the VPC.
      returned: success
      type: list
      sample:
        "ipv6_cidr_block_association_set": [
            {
                "association_id": "vpc-cidr-assoc-97aeeefd",
                "ipv6_cidr_block": "2001:db8::/56",
                "ipv6_cidr_block_state": {
                    "state": "associated"
                }
            }
        ]
    is_default:
      description: Indicates whether this is the default VPC.
      returned: always
      type: bool
      sample: false
    state:
      description: State of the VPC.
      returned: always
      type: str
      sample: available
    tags:
      description: Tags attached to the VPC, includes name.
      returned: always
      type: complex
      contains:
        Name:
          description: Name tag for the VPC.
          returned: always
          type: str
          sample: pk_vpc4
    owner_id:
      description: The AWS account which owns the VPC.
      returned: always
      type: str
      sample: 123456789012
"""

from time import sleep
from time import time
from typing import Any
from typing import Dict
from typing import List
from typing import Optional

from ansible.module_utils.common.dict_transformations import camel_dict_to_snake_dict
from ansible.module_utils.common.network import to_subnet

from ansible_collections.amazon.aws.plugins.module_utils.ec2 import AnsibleEC2Error
from ansible_collections.amazon.aws.plugins.module_utils.ec2 import associate_dhcp_options
from ansible_collections.amazon.aws.plugins.module_utils.ec2 import associate_vpc_cidr_block
from ansible_collections.amazon.aws.plugins.module_utils.ec2 import create_vpc
from ansible_collections.amazon.aws.plugins.module_utils.ec2 import delete_vpc
from ansible_collections.amazon.aws.plugins.module_utils.ec2 import describe_vpc_attribute
from ansible_collections.amazon.aws.plugins.module_utils.ec2 import describe_vpcs
from ansible_collections.amazon.aws.plugins.module_utils.ec2 import disassociate_vpc_cidr_block
from ansible_collections.amazon.aws.plugins.module_utils.ec2 import ensure_ec2_tags
from ansible_collections.amazon.aws.plugins.module_utils.ec2 import modify_vpc_attribute
from ansible_collections.amazon.aws.plugins.module_utils.modules import AnsibleAWSModule
from ansible_collections.amazon.aws.plugins.module_utils.tagging import ansible_dict_to_boto3_tag_list
from ansible_collections.amazon.aws.plugins.module_utils.tagging import boto3_tag_list_to_ansible_dict
from ansible_collections.amazon.aws.plugins.module_utils.tagging import boto3_tag_specifications
from ansible_collections.amazon.aws.plugins.module_utils.transformation import ansible_dict_to_boto3_filter_list
from ansible_collections.amazon.aws.plugins.module_utils.waiters import wait_for_resource_state


def get_vpc_id(connection, module: AnsibleAWSModule) -> Optional[str]:
    """Returns None or a vpc object depending on the existence of a VPC. When supplied
    with a CIDR, it will check for matching tags to determine if it is a match
    otherwise it will assume the VPC does not exist and thus return None.
    """
    name = module.params.get("name")
    cidr_block = module.params.get("cidr_block")
    multi_ok = module.params.get("multi_ok")
    vpc_filters = ansible_dict_to_boto3_filter_list({"tag:Name": name, "cidr-block": cidr_block})
    matching_vpcs = describe_vpcs(connection, Filters=vpc_filters)
    # If an exact matching using a list of CIDRs isn't found, check for a match with the first CIDR as is documented for C(cidr_block)
    if not matching_vpcs:
        vpc_filters = ansible_dict_to_boto3_filter_list({"tag:Name": name, "cidr-block": [cidr_block[0]]})
        matching_vpcs = describe_vpcs(connection, Filters=vpc_filters)

    vpc_id = None
    if not multi_ok and matching_vpcs:
        if len(matching_vpcs) > 1:
            module.fail_json(
                msg=(
                    f"Currently there are {len(matching_vpcs)} VPCs that have the same name and CIDR block you specified."
                    " If you would like to create the VPC anyway please pass True to the multi_ok param."
                )
            )
        vpc_id = matching_vpcs[0]["VpcId"]
    return vpc_id


def get_vpc(module: AnsibleAWSModule, connection, vpc_id: str) -> Dict[str, Any]:
    wait_for_resource_state(connection, module, "vpc_available", VpcIds=[vpc_id])
    return describe_vpcs(connection, VpcIds=[vpc_id])[0]


def update_vpc_tags(connection, module, vpc_id, tags, name, purge_tags):
    # Name is a tag rather than a direct parameter, we need to inject 'Name'
    # into tags, but since tags isn't explicitly passed we'll treat it not being
    # set as purge_tags == False
    if name:
        if purge_tags and tags is None:
            purge_tags = False
        tags = tags or {}
        tags.update({"Name": name})

    if tags is None:
        return False

    changed = ensure_ec2_tags(connection, module, vpc_id, tags=tags, purge_tags=purge_tags)
    if not changed or module.check_mode:
        return changed

    return True


def update_dhcp_opts(connection, module: AnsibleAWSModule, vpc_obj: Dict[str, Any], dhcp_id: Optional[str]) -> bool:
    if dhcp_id is None:
        return False
    if vpc_obj["DhcpOptionsId"] == dhcp_id:
        return False
    if module.check_mode:
        return True

    return associate_dhcp_options(connection, vpc_id=vpc_obj["VpcId"], dhcp_options_id=dhcp_id)


def create_vpc_net(
    connection,
    module: AnsibleAWSModule,
    cidr_block: List[str],
    tenancy,
    tags: Dict[str, str],
    ipv6_cidr: bool,
    name: Optional[str],
) -> Dict[str, Any]:
    if module.check_mode:
        module.exit_json(changed=True, msg="VPC would be created if not in check mode")

    create_args = dict(
        CidrBlock=cidr_block,
        InstanceTenancy=tenancy,
    )

    if name:
        tags = tags or {}
        tags["Name"] = name
    if tags:
        create_args["TagSpecifications"] = boto3_tag_specifications(tags, "vpc")

    # Defaults to False (including None)
    if ipv6_cidr:
        create_args["AmazonProvidedIpv6CidrBlock"] = True

    vpc_obj = create_vpc(connection, **create_args)

    # Wait up to 30 seconds for vpc to exist and for state 'available'
    for waiter_name in ("vpc_exists", "vpc_available"):
        wait_for_resource_state(connection, module, waiter_name, max_attempts=30, VpcIds=[vpc_obj["VpcId"]])

    return vpc_obj


def wait_for_vpc_attribute(connection, module, vpc_id, attribute, expected_value):
    if expected_value is None:
        return
    if module.check_mode:
        return

    start_time = time()
    updated = False
    while time() < start_time + 300:
        current_value = describe_vpc_attribute(connection, attribute=attribute, vpc_id=vpc_id)[
            f"{attribute[0].upper()}{attribute[1:]}"
        ]["Value"]
        if current_value != expected_value:
            sleep(3)
        else:
            updated = True
            break
    if not updated:
        module.fail_json(msg=f"Failed to wait for {attribute} to be updated")


def wait_for_vpc_ipv6_state(module, connection, vpc_id, ipv6_assoc_state):
    """
    If ipv6_assoc_state is True, wait for VPC to be associated with at least one Amazon-provided IPv6 CIDR block.
    If ipv6_assoc_state is False, wait for VPC to be dissociated from all Amazon-provided IPv6 CIDR blocks.
    """

    if ipv6_assoc_state is None:
        return
    if module.check_mode:
        return

    start_time = time()
    criteria_match = False
    while time() < start_time + 300:
        current_value = get_vpc(module, connection, vpc_id)
        if current_value:
            ipv6_set = current_value.get("Ipv6CidrBlockAssociationSet")
            # "ipv6_cidr": false and no Ipv6CidrBlockAssociationSet
            if not ipv6_set and not ipv6_assoc_state:
                return
            if ipv6_set:
                if ipv6_assoc_state:
                    # At least one 'Amazon' IPv6 CIDR block must be associated.
                    for val in ipv6_set:
                        if (
                            val.get("Ipv6Pool") == "Amazon"
                            and val.get("Ipv6CidrBlockState").get("State") == "associated"
                        ):
                            criteria_match = True
                            break
                    if criteria_match:
                        break
                else:
                    # All 'Amazon' IPv6 CIDR blocks must be disassociated.
                    expected_count = sum([(val.get("Ipv6Pool") == "Amazon") for val in ipv6_set])
                    actual_count = sum(
                        [
                            (
                                val.get("Ipv6Pool") == "Amazon"
                                and val.get("Ipv6CidrBlockState").get("State") == "disassociated"
                            )
                            for val in ipv6_set
                        ]
                    )
                    if actual_count == expected_count:
                        criteria_match = True
                        break
        sleep(3)
    if not criteria_match:
        module.fail_json(msg="Failed to wait for IPv6 CIDR association")


def get_cidr_network_bits(module, cidr_block):
    if cidr_block is None:
        return None

    fixed_cidrs = []
    for cidr in cidr_block:
        split_addr = cidr.split("/")
        if len(split_addr) == 2:
            # this_ip is a IPv4 CIDR that may or may not have host bits set
            # Get the network bits.
            valid_cidr = to_subnet(split_addr[0], split_addr[1])
            if cidr != valid_cidr:
                module.warn(
                    f"One of your CIDR addresses ({cidr}) has host bits set. To get rid of this warning, check the"
                    f" network mask and make sure that only network bits are set: {valid_cidr}."
                )
            fixed_cidrs.append(valid_cidr)
        else:
            # let AWS handle invalid CIDRs
            fixed_cidrs.append(cidr)
    return fixed_cidrs


def update_ipv6_cidrs(connection, module, vpc_obj, vpc_id, ipv6_cidr):
    if ipv6_cidr is None:
        return False

    # Fetch current state from vpc_object
    current_ipv6_cidr = False
    if "Ipv6CidrBlockAssociationSet" in vpc_obj.keys():
        for ipv6_assoc in vpc_obj["Ipv6CidrBlockAssociationSet"]:
            if ipv6_assoc["Ipv6Pool"] == "Amazon" and ipv6_assoc["Ipv6CidrBlockState"]["State"] in [
                "associated",
                "associating",
            ]:
                current_ipv6_cidr = True
                break

    if ipv6_cidr == current_ipv6_cidr:
        return False

    if module.check_mode:
        return True

    # There's no block associated, and we want one to be associated
    if ipv6_cidr:
        associate_vpc_cidr_block(connection, vpc_id=vpc_id, AmazonProvidedIpv6CidrBlock=ipv6_cidr)
    else:
        for ipv6_assoc in vpc_obj["Ipv6CidrBlockAssociationSet"]:
            if ipv6_assoc["Ipv6Pool"] == "Amazon" and ipv6_assoc["Ipv6CidrBlockState"]["State"] in [
                "associated",
                "associating",
            ]:
                disassociate_vpc_cidr_block(connection, association_id=ipv6_assoc["AssociationId"])
    return True


def update_cidrs(connection, module, vpc_obj, cidr_block, purge_cidrs):
    if not cidr_block:
        return False, None

    associated_cidrs = dict(
        (cidr["CidrBlock"], cidr["AssociationId"])
        for cidr in vpc_obj.get("CidrBlockAssociationSet", [])
        if cidr["CidrBlockState"]["State"] not in ["disassociating", "disassociated"]
    )

    current_cidrs = set(associated_cidrs.keys())
    desired_cidrs = set(cidr_block)
    if not purge_cidrs:
        desired_cidrs = desired_cidrs.union(current_cidrs)

    cidrs_to_add = list(desired_cidrs.difference(current_cidrs))
    cidrs_to_remove = list(current_cidrs.difference(desired_cidrs))

    if not cidrs_to_add and not cidrs_to_remove:
        return False, None

    if not module.check_mode:
        for cidr in cidrs_to_add:
            try:
                associate_vpc_cidr_block(connection, vpc_id=vpc_obj["VpcId"], CidrBlock=cidr)
            except AnsibleEC2Error as e:
                module.fail_json_aws(e, f"Unable to associate CIDR {cidr}.")

        for cidr in cidrs_to_remove:
            try:
                disassociate_vpc_cidr_block(connection, associated_cidrs[cidr])
            except AnsibleEC2Error as e:
                module.fail_json_aws(
                    e,
                    (
                        f"Unable to disassociate {associated_cidrs[cidr]}. You must detach or delete all gateways and resources"
                        " that are associated with the CIDR block before you can disassociate it."
                    ),
                )
    return True, list(desired_cidrs)


def update_dns_enabled(connection, module, vpc_id, dns_support):
    if dns_support is None:
        return False

    current_dns_enabled = describe_vpc_attribute(connection, attribute="enableDnsSupport", vpc_id=vpc_id)[
        "EnableDnsSupport"
    ]["Value"]
    if current_dns_enabled == dns_support:
        return False

    if module.check_mode:
        return True

    modify_vpc_attribute(connection, vpc_id=vpc_id, EnableDnsSupport={"Value": dns_support})
    return True


def update_dns_hostnames(connection, module, vpc_id, dns_hostnames):
    if dns_hostnames is None:
        return False

    current_dns_hostnames = describe_vpc_attribute(connection, attribute="enableDnsHostnames", vpc_id=vpc_id)[
        "EnableDnsHostnames"
    ]["Value"]
    if current_dns_hostnames == dns_hostnames:
        return False

    if module.check_mode:
        return True

    modify_vpc_attribute(connection, vpc_id=vpc_id, EnableDnsHostnames={"Value": dns_hostnames})
    return True


def wait_for_updates(connection, module, vpc_id, ipv6_cidr, expected_cidrs, dns_support, dns_hostnames, tags, dhcp_id):
    if module.check_mode:
        return

    if expected_cidrs:
        wait_for_resource_state(
            connection,
            module,
            "vpc_available",
            VpcIds=[vpc_id],
            Filters=[{"Name": "cidr-block-association.cidr-block", "Values": expected_cidrs}],
        )
    wait_for_vpc_ipv6_state(module, connection, vpc_id, ipv6_cidr)

    if tags is not None:
        tag_list = ansible_dict_to_boto3_tag_list(tags)
        filters = [{"Name": f"tag:{t['Key']}", "Values": [t["Value"]]} for t in tag_list]
        wait_for_resource_state(connection, module, "vpc_available", VpcIds=[vpc_id], Filters=filters)

    wait_for_vpc_attribute(connection, module, vpc_id, "enableDnsSupport", dns_support)
    wait_for_vpc_attribute(connection, module, vpc_id, "enableDnsHostnames", dns_hostnames)

    if dhcp_id is not None:
        # Wait for DhcpOptionsId to be updated
        filters = [{"Name": "dhcp-options-id", "Values": [dhcp_id]}]
        wait_for_resource_state(connection, module, "vpc_available", VpcIds=[vpc_id], Filters=filters)

    return


def ensure_present(connection, module: AnsibleAWSModule, vpc_id: Optional[str]) -> None:
    name = module.params.get("name")
    cidr_block = module.params.get("cidr_block")
    ipv6_cidr = module.params.get("ipv6_cidr")
    purge_cidrs = module.params.get("purge_cidrs")
    tenancy = module.params.get("tenancy")
    dns_support = module.params.get("dns_support")
    dns_hostnames = module.params.get("dns_hostnames")
    dhcp_id = module.params.get("dhcp_opts_id")
    tags = module.params.get("tags")
    purge_tags = module.params.get("purge_tags")

    if not vpc_id:
        if not name:
            module.fail_json("The name parameter must be specified when creating a new VPC.")
        vpc_obj = create_vpc_net(connection, module, cidr_block[0], tenancy, tags, ipv6_cidr, name)
        vpc_id = vpc_obj["VpcId"]
        changed = True
        # Set on-creation defaults
        if dns_hostnames is None:
            dns_hostnames = True
        if dns_support is None:
            dns_support = True
    else:
        changed = False
        vpc_obj = get_vpc(module, connection, vpc_id)
        changed |= update_ipv6_cidrs(connection, module, vpc_obj, vpc_id, ipv6_cidr)
        changed |= update_vpc_tags(connection, module, vpc_id, tags, name, purge_tags)

    cidrs_changed, desired_cidrs = update_cidrs(connection, module, vpc_obj, cidr_block, purge_cidrs)
    changed |= cidrs_changed
    changed |= update_dhcp_opts(connection, module, vpc_obj, dhcp_id)
    changed |= update_dns_enabled(connection, module, vpc_id, dns_support)
    changed |= update_dns_hostnames(connection, module, vpc_id, dns_hostnames)

    wait_for_updates(connection, module, vpc_id, ipv6_cidr, desired_cidrs, dns_support, dns_hostnames, tags, dhcp_id)

    updated_obj = get_vpc(module, connection, vpc_id)
    final_state = camel_dict_to_snake_dict(updated_obj)
    final_state["tags"] = boto3_tag_list_to_ansible_dict(updated_obj.get("Tags", []))
    final_state["name"] = final_state["tags"].get("Name", None)
    final_state["id"] = final_state.pop("vpc_id")

    module.exit_json(changed=changed, vpc=final_state)


def ensure_absent(connection, module: AnsibleAWSModule, vpc_id: str) -> None:
    changed = False
    if vpc_id:
        if module.check_mode:
            changed = True
        else:
            changed = delete_vpc(connection, vpc_id=vpc_id)
    module.exit_json(changed=changed, vpc={})


def main():
    argument_spec = dict(
        name=dict(required=False),
        vpc_id=dict(type="str", required=False, default=None),
        cidr_block=dict(type="list", elements="str"),
        ipv6_cidr=dict(type="bool", default=None),
        tenancy=dict(choices=["default", "dedicated"], default="default"),
        dns_support=dict(type="bool"),
        dns_hostnames=dict(type="bool"),
        dhcp_opts_id=dict(),
        tags=dict(type="dict", aliases=["resource_tags"]),
        purge_tags=dict(type="bool", default=True),
        state=dict(choices=["present", "absent"], default="present"),
        multi_ok=dict(type="bool", default=False),
        purge_cidrs=dict(type="bool", default=False),
    )
    required_one_of = [
        ["vpc_id", "name"],
        ["vpc_id", "cidr_block"],
    ]

    module = AnsibleAWSModule(argument_spec=argument_spec, required_one_of=required_one_of, supports_check_mode=True)

    dns_support = module.params.get("dns_support")
    dns_hostnames = module.params.get("dns_hostnames")
    state = module.params.get("state")

    if dns_hostnames and not dns_support:
        module.fail_json(msg="In order to enable DNS Hostnames you must also enable DNS support")

    connection = module.client("ec2")
    try:
        vpc_id = module.params.get("vpc_id") or get_vpc_id(connection, module)
        if state == "present":
            ensure_present(connection, module, vpc_id)
        else:
            ensure_absent(connection, module, vpc_id)
    except AnsibleEC2Error as e:
        module.fail_json_aws_error(e)


if __name__ == "__main__":
    main()