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

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

• https://docs.aws.amazon.com/ram/latest/userguide/shareable.html
• VPC Endpoints
  • One per AZ; subnets may wrap around and double/triple/etc. within an AZ, but VPC endpoints have to be separate
• IPAM
  • One public scope - default public scope created by IPAM
  • IPAM pools can be nested up to a depth of 10 max

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

• https://github.com/terraform-aws-modules/terraform-aws-network-firewall
• ✅ aws_networkfirewall_firewall
• ✅ aws_networkfirewall_firewall_policy
  • ✅ aws_ram_resource_association
• ✅ aws_networkfirewall_rule_group
  • ✅ aws_ram_resource_association
• ✅ aws_networkfirewall_resource_policy
• ✅ aws_networkfirewall_logging_configuration

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!

• Complete
• Default
• IPAM

Requirements

Name	Version
terraform	>= 1.0
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.