Skip to content

Latest commit

 

History

History
443 lines (363 loc) · 33.6 KB

README.md

File metadata and controls

443 lines (363 loc) · 33.6 KB
Raw

AWS VPC Terraform Module

⚠️ Please do not rely on this being stable. The goal of this project is to explore changes to the upstream terraform-aws-vpc module and eventually land those changes there as v5.0. For now, this is just for exploring and open collaboration on what that next version might look like, and how users can migrate from v4.x to v5.x. Feel free to watch along if you are curious.

High Level Diagram

high level diagram

TODOs

  • Align conventions
    • ✅ cidr_block -> ipv4_cidr_block to compliment ipv6_cidr_block
      • Except for ipam where resources use the pairing of cidr and address_family (due to AWS provider/API)
    • ✅ default routes vs custom routes
    • ✅ default NACLs vs custom NACLs

Notes

Supported Resources

VPC (Core)

  • ✅ aws_vpc
  • ✅ aws_vpc_ipv4_cidr_block_association
  • ✅ aws_vpc_ipv6_cidr_block_association
  • ✅ aws_route53_resolver_dnssec_config
  • ✅ aws_route53_resolver_query_log_config
    • ✅ aws_route53_resolver_query_log_config_association
    • ❌ aws_ram_resource_association -> users can use a shared query log config within the module
  • ✅ aws_route53_resolver_firewall_config
    • ✅ aws_route53_resolver_firewall_rule_group_association
  • ✅ aws_vpc_dhcp_options
    • ✅ aws_vpc_dhcp_options_association
  • ✅ aws_internet_gateway
    • ✅ aws_internet_gateway_attachment
  • ✅ aws_egress_only_internet_gateway
  • ✅ aws_customer_gateway
  • ✅ aws_vpn_gateway
  • ✅ aws_default_security_group
  • ✅ aws_default_network_acl
    • ✅ aws_network_acl_rule: ingress
    • ✅ aws_network_acl_rule: egress
  • ✅ aws_default_route_table
    • ✅ aws_route
  • ✅ aws_default_vpc
  • ✅ aws_default_vpc_dhcp_options
  • ❌ aws_main_route_table_association -> conflicts with aws_default_route_table
  • ❌ aws_default_subnet

Subnet

This is where most of the network logic is captured; the design is centered around the subnet and its usage patterns

  • ✅ aws_subnet
    • ✅ aws_ram_resource_association
  • ✅ aws_ec2_subnet_cidr_reservation
  • ✅ aws_network_acl
    • ❌ aws_network_acl_association -> subnet association handled in aws_subnet_acl
  • ✅ aws_network_acl_rule
  • ✅ aws_route_table
    • ✅ aws_route
    • ✅ aws_route_table_association
      • ✅ aws_route_table_association: subnet
      • ✅ aws_route_table_association: gateway(s)
  • ✅ aws_nat_gateway
    • ✅ aws_eip

VPC Endpoint

  • ✅ aws_vpc_endpoint
  • aws_vpc_endpoint_connection_accepter
  • aws_vpc_endpoint_connection_notification
  • aws_vpc_endpoint_route_table_association
  • aws_vpc_endpoint_service
  • aws_vpc_endpoint_service_allowed_principal
  • aws_vpc_endpoint_subnet_association
  • aws_vpc_endpoint_policy

Network Firewall

DNS Firewall Rule Group

  • ✅ aws_route53_resolver_firewall_rule_group
    • ✅ aws_ram_resource_association
  • ✅ aws_route53_resolver_firewall_domain_list
  • ✅ aws_route53_resolver_firewall_rule

IPAM

  • ✅ aws_vpc_ipam
  • ✅ aws_vpc_ipam_scope
  • ✅ aws_vpc_ipam_pool
    • ✅ aws_ram_resource_association
  • ❌ aws_vpc_ipam_organization_admin_account -> provision in root account for multi-account setup

IPAM Pool

  • ✅ aws_vpc_ipam_pool
    • ✅ aws_ram_resource_association
  • ✅ aws_vpc_ipam_pool_cidr
  • ✅ aws_vpc_ipam_pool_cidr_allocation
  • ✅ aws_vpc_ipam_preview_next_cidr

VPC Flow Log

  • ✅ aws_flow_log
    • ✅ aws_cloudwatch_log_group
      • ✅ aws_iam_role

Network Manager

⚠️ requires v4.6.0

  • aws_networkmanager_connection
  • aws_networkmanager_customer_gateway_association
  • aws_networkmanager_device
  • aws_networkmanager_global_network
  • aws_networkmanager_link
  • aws_networkmanager_link_association
  • aws_networkmanager_site
  • aws_networkmanager_transit_gateway_connect_peer_association
  • aws_networkmanager_transit_gateway_registration

EC2 Misc

  • aws_ec2_managed_prefix_list
  • aws_ec2_managed_prefix_list_entry
  • aws_ec2_network_insights_path
  • aws_ec2_transit_gateway_connect
  • aws_ec2_transit_gateway_connect_peer

Resources Not Supported

VPC Peering

TODO - consider support as sub-module or standalone module

  • ❌ aws_vpc_peering_connection
  • ❌ aws_vpc_peering_connection_accepter
  • ❌ aws_vpc_peering_connection_options

Resource Access Manager (RAM)

In resource sharing for VPCs, we're really sharing subnets. aws_ram_resource_association is provided in the subnet module which allows the respective subnet to be shared or not, while aws_ram_resource_share in the root module is the collection of resource associations. It is up to users to create and manage aws_ram_principal_association and aws_ram_resource_share_accepter separately, externally.

  • ❌ aws_ram_principal_association
  • ❌ aws_ram_resource_share_accepter

VPN Gateway

See https://github.com/terraform-aws-modules/terraform-aws-vpn-gateway Note below on Client VPN

  • ❌ aws_vpn_connection
  • ❌ aws_vpn_connection_route
  • ❌ aws_vpn_gateway_attachment
  • ❌ aws_vpn_gateway_route_propagation

Client VPN

TODO - change terraform-aws-vpn-gateway into terraform-aws-vpn with two sub-modules:

  1. client
  2. gateway
  • ❌ aws_ec2_client_vpn_authorization_rule
  • ❌ aws_ec2_client_vpn_endpoint
  • ❌ aws_ec2_client_vpn_network_association
  • ❌ aws_ec2_client_vpn_route

Security Group

See https://github.com/terraform-aws-modules/terraform-aws-security-group

  • ❌ aws_security_group
  • ❌ aws_security_group_rule

Network Interface

  • ❌ aws_network_interface
  • ❌ aws_network_interface_attachment
  • ❌ aws_network_interface_sg_attachment

Route53 Resolver

  • ❌ aws_route53_resolver_endpoint
  • ❌ aws_route53_resolver_rule

Transit Gateway

See https://github.com/terraform-aws-modules/terraform-aws-transit-gateway

  • ❌ aws_ec2_transit_gateway
  • ❌ aws_ec2_transit_gateway_peering_attachment
  • ❌ aws_ec2_transit_gateway_peering_attachment_accepter
  • ❌ aws_ec2_transit_gateway_prefix_list_reference
  • ❌ aws_ec2_transit_gateway_route
  • ❌ aws_ec2_transit_gateway_route_table
  • ❌ aws_ec2_transit_gateway_route_table_association
  • ❌ aws_ec2_transit_gateway_route_table_propagation
  • ❌ aws_ec2_transit_gateway_vpc_attachment
  • ❌ aws_ec2_transit_gateway_vpc_attachment_accepter
  • ❌ aws_ec2_transit_gateway_multicast_domain
  • ❌ aws_ec2_transit_gateway_multicast_domain_association
  • ❌ aws_ec2_transit_gateway_multicast_group_member
  • ❌ aws_ec2_transit_gateway_multicast_group_source

Usage

See examples directory for working examples to reference:

module "vpc" {
  source = "clowdhaus/vpc-v5/aws"

  name                 = "example"
  cidr_block           = "10.99.0.0/16"
  enable_dns_hostnames = true

  ipv4_cidr_block_associations = {
    # This matches the provider API to avoid re-creating any existing associations
    "10.98.0.0/16" = {
      cidr_block = "10.98.0.0/16"
    }
  }

  # DNS Query Logging
  enable_dns_query_logging     = true
  dns_query_log_destintion_arn = "arn:aws:s3:::my-dns-query-log-bucket"

  # Flow Log
  create_flow_log                                 = true
  create_flow_log_cloudwatch_iam_role             = true
  create_flow_log_cloudwatch_log_group            = true
  flow_log_cloudwatch_log_group_retention_in_days = 90

  # DHCP
  create_dhcp_options              = true
  dhcp_options_domain_name         = "us-east-1.compute.internal"
  dhcp_options_domain_name_servers = ["AmazonProvidedDNS"]
  dhcp_options_ntp_servers         = ["169.254.169.123"]
  dhcp_options_netbios_node_type   = 2

  tags = {
    Terraform   = "true"
    Environment = "dev"
  }
}

Examples

Examples provided in examples are intended to give users references for how to use the module(s) as well as testing/validating changes to the source code of the module. If contributing to the project, please be sure to make any appropriate updates to the relevant examples to allow maintainers to test your changes and to keep the examples up to date for users. Thank you!

Requirements

Name Version
terraform >= 1.3
aws >= 5.0

Providers

Name Version
aws >= 5.0

Modules

No modules.

Resources

Name Type
aws_customer_gateway.this resource
aws_default_network_acl.this resource
aws_default_route_table.this resource
aws_default_security_group.this resource
aws_default_vpc.this resource
aws_default_vpc_dhcp_options.this resource
aws_egress_only_internet_gateway.this resource
aws_internet_gateway.this resource
aws_internet_gateway_attachment.this resource
aws_network_acl_rule.default_egress resource
aws_network_acl_rule.default_ingress resource
aws_route.default resource
aws_route53_resolver_dnssec_config.this resource
aws_route53_resolver_firewall_config.this resource
aws_route53_resolver_firewall_rule_group_association.this resource
aws_route53_resolver_query_log_config.this resource
aws_route53_resolver_query_log_config_association.this resource
aws_vpc.this resource
aws_vpc_dhcp_options.this resource
aws_vpc_dhcp_options_association.this resource
aws_vpc_ipv4_cidr_block_association.this resource
aws_vpc_ipv6_cidr_block_association.this resource
aws_vpn_gateway.this resource

Inputs

Name Description Type Default Required
assign_generated_ipv6_cidr_block Requests an Amazon-provided IPv6 CIDR block with a /56 prefix length for the VPC. You cannot specify the range of IP addresses, or the size of the CIDR block. Default is false. Conflicts with ipv6_ipam_pool_id bool null no
attach_internet_gateway Controls if an internet gateway is attached to the VPC bool true no
create Controls if VPC should be created (it affects almost all resources) bool true no
create_dhcp_options Controls if custom DHCP options set is created bool false no
create_dns_query_log_config Controls if Route53 Resolver DNS Query Log Config is created. If false, then dns_query_log_config_id must be provided if enable_dns_query_logging is true bool true no
create_egress_only_internet_gateway Controls if an egress only internet gateway is created bool false no
create_internet_gateway Controls if an internet gateway is created bool true no
customer_gateway_tags Additional tags for the Customer Gateway(s) map(string) {} no
customer_gateways Map of Customer Gateway definitions to create any {} no
default_dhcp_options_tags Additional tags for the default DHCP options map(string) {} no
default_network_acl_egress_rules Egress rules to be added to the Default Network ACL any {} no
default_network_acl_ingress_rules Ingress rules to be added to the Default Network ACL any {} no
default_network_acl_tags Additional tags for the default network ACL map(string) {} no
default_route_table_propagating_vgws List of virtual gateways for propagation list(string) [] no
default_route_table_routes Configuration block of routes. See route for more information list(map(string)) [] no
default_route_table_tags Additional tags for the default route table map(string) {} no
default_route_table_timeouts Create and update timeout configurations for the default route table map(string) {} no
default_security_group_egress_rules Egress rules to be added to the Default Security Group list(map(string)) [] no
default_security_group_ingress_rules Ingress rules to be added to the Default Security Group list(map(string)) [] no
default_security_group_tags Additional tags for the Default Security Group map(string) {} no
default_vpc_enable_dns_hostnames A boolean flag to enable/disable DNS hostnames in the VPC. Defaults false bool null no
default_vpc_enable_dns_support A boolean flag to enable/disable DNS support in the VPC. Defaults true bool null no
default_vpc_tags Additional tags for the Default VPC map(string) {} no
dhcp_options_domain_name The suffix domain name to use by default when resolving non fully qualified domain names string null no
dhcp_options_domain_name_servers List of name servers to configure in /etc/resolv.conf list(string) 
[
  "AmazonProvidedDNS"
]
 no
dhcp_options_netbios_name_servers List of NETBIOS name servers list(string) null no
dhcp_options_netbios_node_type The NetBIOS node type (1, 2, 4, or 8). AWS recommends to specify 2 since broadcast and multicast are not supported in their network number null no
dhcp_options_ntp_servers List of NTP servers to configure list(string) null no
dhcp_options_tags Additional tags for the DHCP option set map(string) {} no
dns_firewall_fail_open Determines how Route 53 Resolver handles queries during failures. Valid values: ENABLED, DISABLED. Defaults is ENABLED string "ENABLED" no
dns_firewall_rule_group_associations Map of Route53 Resolver Firewall Rule Groups to associate with the VPC any {} no
dns_query_log_config_id The ID of an existing Route53 Resolver DNS Query Log Config to associate with the VPC string null no
dns_query_log_destintion_arn The ARN of the resource that you want Route 53 Resolver to send query logs. You can send query logs to an S3 bucket, a CloudWatch Logs log group, or a Kinesis Data Firehose delivery stream string null no
enable_dns_firewall Controls if Route53 Resolver DNS Firewall is enabled/disabled bool false no
enable_dns_hostnames A boolean flag to enable/disable DNS hostnames in the VPC. Defaults false bool null no
enable_dns_query_logging Controls if Route53 Resolver DNS Query Logging is enabled/disabled bool false no
enable_dns_support A boolean flag to enable/disable DNS support in the VPC. Defaults true bool null no
enable_dnssec_config Controls if Route53 Resolver DNSSEC Config is enabled/disabled bool true no
instance_tenancy A tenancy option for instances launched into the VPC. Default is default, which makes your instances shared on the host string null no
internet_gateway_id The ID of an existing internet gateway to attach to the VPC. Reqiured if create_internet_gateway is false and attach_internet_gateway is true string null no
internet_gateway_tags Additional tags for the internet gateway/egress only internet gateway map(string) {} no
ipv4_cidr_block The IPv4 CIDR block for the VPC. CIDR can be explicitly set or it can be derived from IPAM using ipv4_netmask_length string null no
ipv4_cidr_block_associations Map of additional IPv4 CIDR blocks to associate with the VPC to extend the IP address pool any {} no
ipv4_ipam_pool_id The ID of an IPv4 IPAM pool you want to use for allocating this VPC's CIDR string null no
ipv4_netmask_length The netmask length of the IPv4 CIDR you want to allocate to this VPC. Requires specifying a ipv4_ipam_pool_id number null no
ipv6_cidr_block IPv6 CIDR block to request from an IPAM Pool. Can be set explicitly or derived from IPAM using ipv6_netmask_length string null no
ipv6_cidr_block_associations Map of additional IPv6 CIDR blocks to associate with the VPC to extend the IP address pool any {} no
ipv6_cidr_block_network_border_group By default when an IPv6 CIDR is assigned to a VPC a default ipv6_cidr_block_network_border_group will be set to the region of the VPC string null no
ipv6_ipam_pool_id IPAM Pool ID for a IPv6 pool. Conflicts with assign_generated_ipv6_cidr_block string null no
ipv6_netmask_length Netmask length to request from IPAM Pool. Conflicts with ipv6_cidr_block. This can be omitted if IPAM pool as a allocation_default_netmask_length set. Valid values: 56 number null no
manage_default_dhcp_options Determines whether the default DHCP options are adopted and managed by the module bool false no
manage_default_network_acl Determines whether the default network ACL is adopted and managed by the module bool true no
manage_default_route_table Determines whether the default route table is adopted and managed by the module bool true no
manage_default_security_group Determines whether the Default Security Group is adopted and managed by the module bool true no
manage_default_vpc Determines whether the default VPC is adopted and managed by the module bool false no
name Name to be used on all the resources as identifier string "" no
tags A map of tags to add to all resources map(string) {} no
vpc_tags Additional tags for the VPC map(string) {} no
vpn_gateway_tags Additional tags for the VPN Gateway(s) map(string) {} no
vpn_gateways Map of VPN Gateway definitions to create any {} no

Outputs

Name Description
arn Amazon Resource Name (ARN) of VPC
customer_gateway_arns List of Customer Gateways ARNs
customer_gateway_ids List of Customer Gateway IDs
customer_gateways Map of Customer Gateways and their attributes
default_dhcp_options_arn The ARN of the default DHCP options set
default_dhcp_options_id The ID of the default DHCP options set
default_network_acl_arn ARN of the Default Network ACL
default_network_acl_id ID of the Default Network ACL
default_route_table_arn ARN of the default route table
default_route_table_id ID of the default route table
default_security_group_arn The ARN of the security group created by default on VPC creation
default_security_group_id The ID of the security group created by default on VPC creation
default_vpc_arn The ARN of the Default VPC
default_vpc_default_network_acl_id The ID of the default network ACL of the Default VPC
default_vpc_default_route_table_id The ID of the default route table of the Default VPC
default_vpc_default_security_group_id The ID of the security group created by default on Default VPC creation
default_vpc_enable_dns_hostnames Whether or not the Default VPC has DNS hostname support
default_vpc_enable_dns_support Whether or not the Default VPC has DNS support
default_vpc_id The ID of the Default VPC
default_vpc_instance_tenancy Tenancy of instances spin up within Default VPC
default_vpc_ipv4_cidr_block The CIDR block of the Default VPC
default_vpc_main_route_table_id The ID of the main route table associated with the Default VPC
dhcp_options_arn The ARN of the DHCP options set
dhcp_options_association_id The ID of the DHCP Options set association
dhcp_options_id The ID of the DHCP options set
dns_firewall_config_id The ID of the firewall configuration
dns_firewall_rule_group_associations Map of Route53 resolver firewall rule group associations and their attributes
dns_query_log_config_arn The ARN (Amazon Resource Name) of the Route 53 Resolver query logging configuration
dns_query_log_config_association_id he ID of the Route 53 Resolver query logging configuration association
dns_query_log_config_id The ID of the Route 53 Resolver query logging configuration
dnssec_config_arn The ARN for a configuration for DNSSEC validation
dnssec_config_id The ID for a configuration for DNSSEC validation
egress_only_internet_gateway_id The ID of the Egress-Only Internet Gateway
id The ID of the VPC
internet_gateway_arn The ARN of the Internet Gateway
internet_gateway_id The ID of the Internet Gateway
ipv4_cidr_block The IPv4 CIDR block of the VPC
ipv4_cidr_block_associations Map of IPv4 CIDR block associations and their attributes
ipv6_association_id The association ID for the IPv6 CIDR block
ipv6_cidr_block The IPv6 CIDR block of the VPC
ipv6_cidr_block_associations Map of IPv6 CIDR block associations and their attributes
ipv6_cidr_block_network_border_group The Network Border Group Zone name
main_route_table_id The ID of the main route table associated with this VPC. Note that you can change a VPC's main route table by using an aws_main_route_table_association
owner_id The ID of the AWS account that owns the VPC
vpn_gateway_arns List of VPN Gateways ARNs
vpn_gateway_ids List of VPN Gateway IDs
vpn_gateways Map of VPN Gateways and their attributes

License

Apache-2.0 Licensed. See LICENSE.