This module can be used to deploy a pragmatic VPC with various subnets types in # AZs. Common deployment examples can be found in examples/.
Note: For information regarding the 4.0 upgrade see our upgrade guide.
The example below builds a dual-stack VPC with public and private subnets in 3 AZs. Each subnet calculates an IPv4 CIDR based on the netmask
argument passed, and an IPv6 CIDR with a /64 prefix length. The public subnets build NAT gateways in each AZ but optionally can be switched to single_az
. An Egress-only Internet gateway is created by using the variable vpc_egress_only_internet_gateway
.
module "vpc" {
source = "aws-ia/vpc/aws"
version = ">= 4.2.0"
name = "multi-az-vpc"
cidr_block = "10.0.0.0/16"
vpc_assign_generated_ipv6_cidr_block = true
vpc_egress_only_internet_gateway = true
az_count = 3
subnets = {
# Dual-stack subnet
public = {
name_prefix = "my_public" # omit to prefix with "public"
netmask = 24
assign_ipv6_cidr = true
nat_gateway_configuration = "all_azs" # options: "single_az", "none"
}
# IPv4 only subnet
private = {
# omitting name_prefix defaults value to "private"
# name_prefix = "private_with_egress"
netmask = 24
connect_to_public_natgw = true
}
# IPv6-only subnet
private_ipv6 = {
ipv6_native = true
assign_ipv6_cidr = true
connect_to_eigw = true
}
}
vpc_flow_logs = {
log_destination_type = "cloud-watch-logs"
retention_in_days = 180
}
}
There are 3 reserved keys for subnet key names in var.subnets corresponding to types "public", "transit_gateway", and "core_network" (an AWS Cloud WAN feature). Other custom subnet key names are valid are and those subnets will be private subnets.
subnets = {
public = {
name_prefix = "my-public" # omit to prefix with "public"
netmask = 24
nat_gateway_configuration = "all_azs" # options: "single_az", "none"
}
# naming private is not required, can use any key
private = {
# omitting name_prefix defaults value to "private"
# name_prefix = "private"
netmask = 24
connect_to_public_natgw = true
}
# can be any valid key name
privatetwo = {
# omitting name_prefix defaults value to "privatetwo"
# name_prefix = "private"
netmask = 24
}
transit_gateway_id = <>
transit_gateway_routes = {
private = "0.0.0.0/0"
vpce = "pl-123"
}
transit_gateway_ipv6_routes = {
private = "::/0"
}
subnets = {
private = {
netmask = 24
assign_ipv6_cidr = true
}
vpce = { netmask = 24}
transit_gateway = {
netmask = 28
assign_ipv6_cidr = true
transit_gateway_default_route_table_association = true
transit_gateway_default_route_table_propagation = true
transit_gateway_appliance_mode_support = "enable"
transit_gateway_dns_support = "disable"
tags = {
subnet_type = "tgw"
}
}
core_network = {
id = <>
arn = <>
}
core_network_routes = {
workload = "pl-123"
}
core_network_ipv6_routes = {
workload = "::/0"
}
subnets = {
workload = {
name_prefix = "workload-private"
netmask = 24
assign_ipv6_cidr = true
}
core_network = {
netmask = 28
assign_ipv6_cidr = true
appliance_mode_support = false
require_acceptance = true
accept_attachment = true
tags = {
env = "prod"
}
}
If using netmask
or assign_ipv6_cidr
to calculate subnets and you wish to either add or remove subnets (ex: adding / removing an AZ), you may have to change from using netmask
/ assign_ipv6_cidr
for some subnets and set to explicit instead. Subnets are calculated in lexicographical order, meaning the subnet named "private" is calculated before "public".
When changing to explicit cidrs, subnets are always ordered by AZ. 0
-> a, 1
-> b, etc.
Example: Changing from 2 azs to 3
Before:
cidr_block = "10.0.0.0/16"
vpc_assign_generated_ipv6_cidr_block = true
az_count = 2
subnets = {
public = {
netmask = 24
assign_ipv6_cidr = true
}
private = {
netmask = 24
assign_ipv6_cidr = true
}
}
After:
cidr_block = "10.0.0.0/16"
vpc_assign_generated_ipv6_cidr_block = true
az_count = 3
subnets = {
public = {
cidrs = ["10.0.0.0/24", "10.0.1.0/24", "10.0.4.0/24"]
ipv6_cidrs = ["2a05:d01c:bc3:b200::/64", "2a05:d01c:bc3:b201::/64", "2a05:d01c:bc3:b204::/64"]
}
private = {
cidrs = ["10.0.2.0/24", "10.0.3.0/24", "10.0.5.0/24"]
ipv6_cidrs = ["2a05:d01c:bc3:b202::/64", "2a05:d01c:bc3:b203::/64", "2a05:d01c:bc3:b205::/64"]
}
}
The above example will cause only creating 2 new subnets in az c
of the region being used.
The outputs in this module attempt to align to a methodology of outputting resource attributes in a reasonable collection. The benefit of this is that, most likely, attributes you want access to are already present without having to create new output {}
for each possible attribute. The [potential] downside is that you will have to extract it yourself using HCL logic. Below are some common examples:
For more examples and explanation see [output docs]((https://github.com/aws-ia/terraform-aws-vpc/blob/main/docs/how-to-use-module-outputs.md)
Example Configuration:
module "vpc" {
source = "aws-ia/vpc/aws"
version = ">= 4.2.0"
name = "multi-az-vpc"
cidr_block = "10.0.0.0/20"
az_count = 3
subnets = {
private = { netmask = 24 }
}
}
Extracting subnet_ids to a list (using terraform console
for example output):
> [ for _, value in module.vpc.private_subnet_attributes_by_az: value.id]
[
"subnet-04a86315c4839b519",
"subnet-02a7249c8652a7136",
"subnet-09af79b5329b3681f",
]
Alternatively, since these are maps, you can use key in another resource for_each
loop. The benefit here is that your dependent resource will have keys that match the AZ the subnet is in:
resource "aws_route53recoveryreadiness_cell" "cell_per_az" {
for_each = module.vpc.private_subnet_attributes_by_az
cell_name = "${each.key}-failover-cell-for-subnet-${each.value.id}"
}
...
Terraform Plan:
# aws_route53recoveryreadiness_cell.cell_per_az["us-east-1a"] will be created
+ resource "aws_route53recoveryreadiness_cell" "cell_per_az" {
+ cell_name = "us-east-1a-failover-cell-for-subnet-subnet-070696086c5864da1"
...
}
# aws_route53recoveryreadiness_cell.cell_per_az["us-east-1b"] will be created
...
Error:
error creating Route in Route Table (rtb-xxx) with destination (YYY): InvalidCoreNetworkArn.NotFound: The core network arn 'arn:aws:networkmanager::XXXX:core-network/core-network-YYYYY' does not exist.
This happens when the Core Network's VPC attachment requires acceptance, so it's not possible to create the routes in the VPC until the attachment is accepted. Check the following:
- If the VPC attachment requires acceptance and you want the module to automatically accept it, configure
require_acceptance
andaccept_attachment
totrue
.
subnets = {
core_network = {
netmask = 28
assign_ipv6_cidr = true
require_acceptance = true
accept_attachment = true
}
}
- If the VPC attachment requires acceptance but you want to accept it outside the module, first configure
require_acceptance
totrue
andaccept_attachment
tofalse
.
subnets = {
core_network = {
netmask = 28
assign_ipv6_cidr = true
require_acceptance = true
accept_attachment = true
}
}
After you apply and the attachment is accepted (outside the module), change the subnet configuration with require_acceptance
to false
.
subnets = {
core_network = {
netmask = 28
assign_ipv6_cidr = true
require_acceptance = false
}
}
- Alternatively, you can also not configure any subnet route (
var.core_network_routes
) to the Core Network until the attachment gets accepted.
Please see our developer documentation for guidance on contributing to this module.
Name | Version |
---|---|
terraform | >= 1.3.0 |
aws | >= 5.0.0 |
Name | Version |
---|---|
aws | >= 5.0.0 |
Name | Source | Version |
---|---|---|
calculate_subnets | ./modules/calculate_subnets | n/a |
calculate_subnets_ipv6 | ./modules/calculate_subnets_ipv6 | n/a |
flow_logs | ./modules/flow_logs | n/a |
subnet_tags | aws-ia/label/aws | 0.0.5 |
tags | aws-ia/label/aws | 0.0.5 |
vpc_lattice_tags | aws-ia/label/aws | 0.0.5 |
Name | Description | Type | Default | Required |
---|---|---|---|---|
az_count | Searches region for # of AZs to use and takes a slice based on count. Assume slice is sorted a-z. | number |
n/a | yes |
azs | A list of availability zones names | list(string) |
[] |
no |
name | Name to give VPC. Note: does not effect subnet names, which get assigned name based on name_prefix. | string |
n/a | yes |
subnets | Configuration of subnets to build in VPC. 1 Subnet per AZ is created. Subnet types are defined as maps with the available keys: "private", "public", "transit_gateway", "core_network". Each Subnet type offers its own set of available arguments detailed below. Attributes shared across subnet types: - cidrs = (Optional|list(string)) Cannot set if netmask is set. List of IPv4 CIDRs to set to subnets. Count of CIDRs defined must match quantity of azs in az_count .- netmask = (Optional|Int) Cannot set if cidrs is set. Netmask of the var.cidr_block to calculate for each subnet.- assign_ipv6_cidr = (Optional|bool) Cannot set if ipv6_cidrs is set. If true, it will calculate a /64 block from the IPv6 VPC CIDR to set in the subnets.- ipv6_cidrs = (Optional|list(string)) Cannot set if assign_ipv6_cidr is set. List of IPv6 CIDRs to set to subnets. The subnet size must use a /64 prefix length. Count of CIDRs defined must match quantity of azs in az_count .- name_prefix = (Optional|String) A string prefix to use for the name of your subnet and associated resources. Subnet type key name is used if omitted (aka private, public, transit_gateway). Example name_prefix = "private" for var.subnets.private is redundant.- tags = (Optional|map(string)) Tags to set on the subnet and associated resources.Any private subnet type options: - All shared keys above - connect_to_public_natgw = (Optional|bool) Determines if routes to NAT Gateways should be created. Must also set var.subnets.public.nat_gateway_configuration in public subnets.- ipv6_native = (Optional|bool) Indicates whether to create an IPv6-ony subnet. Either var.assign_ipv6_cidr or var.ipv6_cidrs should be defined to allocate an IPv6 CIDR block.- connect_to_eigw = (Optional|bool) Determines if routes to the Egress-only Internet gateway should be created. Must also set var.vpc_egress_only_internet_gateway .public subnet type options: - All shared keys above - nat_gateway_configuration = (Optional|string) Determines if NAT Gateways should be created and in how many AZs. Valid values = "none" , "single_az" , "all_azs" . Default = "none". Must also set var.subnets.private.connect_to_public_natgw = true .- connect_to_igw = (Optional|bool) Determines if the default route (0.0.0.0/0 or ::/0) is created in the public subnets with destination the Internet gateway. Defaults to true .- ipv6_native = (Optional|bool) Indicates whether to create an IPv6-ony subnet. Either var.assign_ipv6_cidr or var.ipv6_cidrs should be defined to allocate an IPv6 CIDR block.- map_public_ip_on_launch = (Optional|bool) Specify true to indicate that instances launched into the subnet should be assigned a public IP address. Default to false .transit_gateway subnet type options: - All shared keys above - connect_to_public_natgw = (Optional|string) Determines if routes to NAT Gateways should be created. Specify the CIDR range or a prefix-list-id that you want routed to nat gateway. Usually 0.0.0.0/0 . Must also set var.subnets.public.nat_gateway_configuration .- transit_gateway_default_route_table_association = (Optional|bool) Boolean whether the VPC Attachment should be associated with the EC2 Transit Gateway association default route table. This cannot be configured or perform drift detection with Resource Access Manager shared EC2 Transit Gateways.- transit_gateway_default_route_table_propagation = (Optional|bool) Boolean whether the VPC Attachment should propagate routes with the EC2 Transit Gateway propagation default route table. This cannot be configured or perform drift detection with Resource Access Manager shared EC2 Transit Gateways.- transit_gateway_appliance_mode_support = (Optional|string) Whether Appliance Mode is enabled. If enabled, a traffic flow between a source and a destination uses the same Availability Zone for the VPC attachment for the lifetime of that flow. Valid values: disable (default) and enable .- transit_gateway_dns_support = (Optional|string) DNS Support is used if you need the VPC to resolve public IPv4 DNS host names to private IPv4 addresses when queried from instances in another VPC attached to the transit gateway. Valid values: enable (default) and disable .core_network subnet type options: - All shared keys abovce - connect_to_public_natgw = (Optional|string) Determines if routes to NAT Gateways should be created. Specify the CIDR range or a prefix-list-id that you want routed to nat gateway. Usually 0.0.0.0/0 . Must also set var.subnets.public.nat_gateway_configuration .- appliance_mode_support = (Optional|bool) Indicates whether appliance mode is supported. If enabled, traffic flow between a source and destination use the same Availability Zone for the VPC attachment for the lifetime of that flow. Defaults to false .- require_acceptance = (Optional|bool) Boolean whether the core network VPC attachment to create requires acceptance or not. Defaults to false .- accept_attachment = (Optional|bool) Boolean whether the core network VPC attachment is accepted or not in the segment. Only valid if require_acceptance is set to true . Defaults to true .Example: subnets = { |
any |
n/a | yes |
cidr_block | IPv4 CIDR range to assign to VPC if creating VPC or to associate as a secondary IPv6 CIDR. Overridden by var.vpc_id output from data.aws_vpc. | string |
null |
no |
core_network | AWS Cloud WAN's core network information - to create a VPC attachment. Required when cloud_wan subnet is defined. Two attributes are required: the id and arn of the resource. |
object({ |
{ |
no |
core_network_ipv6_routes | Configuration of IPv6 route(s) to AWS Cloud WAN's core network. For each public and/or private subnets named in the subnets variable, optionally create routes from the subnet to the core network.You can specify either a CIDR range or a prefix-list-id that you want routed to the core network. Example: core_network_ivp6_routes = { |
any |
{} |
no |
core_network_routes | Configuration of route(s) to AWS Cloud WAN's core network. For each public and/or private subnets named in the subnets variable, optionally create routes from the subnet to the core network.You can specify either a CIDR range or a prefix-list-id that you want routed to the core network. Example: core_network_routes = { |
any |
{} |
no |
create_vpc | Determines whether to create the VPC or not; defaults to enabling the creation. | bool |
true |
no |
tags | Tags to apply to all resources. | map(string) |
{} |
no |
transit_gateway_id | Transit gateway id to attach the VPC to. Required when transit_gateway subnet is defined. |
string |
null |
no |
transit_gateway_ipv6_routes | Configuration of IPv6 route(s) to transit gateway. For each public and/or private subnets named in the subnets variable,Optionally create routes from the subnet to transit gateway. Specify the CIDR range or a prefix-list-id that you want routed to the transit gateway. Example: transit_gateway_ipv6_routes = { |
any |
{} |
no |
transit_gateway_routes | Configuration of route(s) to transit gateway. For each public and/or private subnets named in the subnets variable,Optionally create routes from the subnet to transit gateway. Specify the CIDR range or a prefix-list-id that you want routed to the transit gateway. Example: transit_gateway_routes = { |
any |
{} |
no |
vpc_assign_generated_ipv6_cidr_block | Requests and Amazon-provided IPv6 CIDR block with a /56 prefix length. You cannot specify the range of IP addresses, or the size of the CIDR block. Conflicts with vpc_ipv6_ipam_pool_id . |
bool |
null |
no |
vpc_egress_only_internet_gateway | Set to use the Egress-only Internet gateway for all IPv6 traffic going to the Internet. | bool |
false |
no |
vpc_enable_dns_hostnames | Indicates whether the instances launched in the VPC get DNS hostnames. If enabled, instances in the VPC get DNS hostnames; otherwise, they do not. Disabled by default for nondefault VPCs. | bool |
true |
no |
vpc_enable_dns_support | Indicates whether the DNS resolution is supported for the VPC. If enabled, queries to the Amazon provided DNS server at the 169.254.169.253 IP address, or the reserved IP address at the base of the VPC network range "plus two" succeed. If disabled, the Amazon provided DNS service in the VPC that resolves public DNS hostnames to IP addresses is not enabled. Enabled by default. | bool |
true |
no |
vpc_flow_logs | Whether or not to create VPC flow logs and which type. Options: "cloudwatch", "s3", "none". By default creates flow logs to cloudwatch . Variable overrides null value types for some keys, defined in defaults.tf. |
object({ |
{ |
no |
vpc_id | VPC ID to use if not creating VPC. | string |
null |
no |
vpc_instance_tenancy | The allowed tenancy of instances launched into the VPC. | string |
"default" |
no |
vpc_ipv4_ipam_pool_id | Set to use IPAM to get an IPv4 CIDR block. | string |
null |
no |
vpc_ipv4_netmask_length | Set to use IPAM to get an IPv4 CIDR block using a specified netmask. Must be set with var.vpc_ipv4_ipam_pool_id. | string |
null |
no |
vpc_ipv6_cidr_block | IPv6 CIDR range to assign to VPC if creating VPC. You need to use vpc_ipv6_ipam_pool_id and set explicitly the CIDR block to use, or derived from IPAM using using vpc_ipv6_netmask_length . |
string |
null |
no |
vpc_ipv6_ipam_pool_id | Set to use IPAM to get an IPv6 CIDR block. | string |
null |
no |
vpc_ipv6_netmask_length | Set to use IPAM to get an IPv6 CIDR block using a specified netmask. Must be set with var.vpc_ipv6_ipam_pool_id . |
string |
null |
no |
vpc_lattice | Amazon VPC Lattice Service Network VPC association. You can only associate one Service Network to the VPC. This association also support Security Groups (more than 1). This variable expects the following attributes: - service_network_identifier = (Required|string) The ID or ARN of the Service Network to associate. You must use the ARN if the Service Network and VPC resources are in different AWS Accounts.- security_group_ids = (Optional|list(string)) The IDs of the security groups to attach to the association.- tags = (Optional|map(string)) Tags to set on the Lattice VPC association resource. |
any |
{} |
no |
vpc_secondary_cidr | If true the module will create a aws_vpc_ipv4_cidr_block_association and subnets for that secondary cidr. If using IPAM for both primary and secondary CIDRs, you may only call this module serially (aka using -target , etc). |
bool |
false |
no |
vpc_secondary_cidr_natgw | If attaching a secondary IPv4 CIDR instead of creating a VPC, you can map private/ tgw subnets to your public NAT GW with this argument. Simply pass the output nat_gateway_attributes_by_az , ex: vpc_secondary_cidr_natgw = module.vpc.natgw_id_per_az . If you did not build your primary with this module, you must construct a map { az : { id : nat-123asdb }} for each az. |
any |
{} |
no |
Name | Description |
---|---|
azs | List of AZs where subnets are created. |
core_network_attachment | AWS Cloud WAN's core network attachment. Full output of aws_networkmanager_vpc_attachment. |
core_network_subnet_attributes_by_az | Map of all core_network subnets containing their attributes. Example: core_network_subnet_attributes_by_az = { |
egress_only_internet_gateway | Egress-only Internet gateway attributes. Full output of aws_egress_only_internet_gateway. |
flow_log_attributes | Flow Log information. |
internet_gateway | Internet gateway attributes. Full output of aws_internet_gateway. |
nat_gateway_attributes_by_az | Map of nat gateway resource attributes by AZ. Example: nat_gateway_attributes_by_az = { |
natgw_id_per_az | Map of nat gateway IDs for each resource. Will be duplicate ids if your var.subnets.public.nat_gateway_configuration = "single_az". Example: natgw_id_per_az = { |
private_subnet_attributes_by_az | Map of all private subnets containing their attributes. Example: private_subnet_attributes_by_az = { |
public_subnet_attributes_by_az | Map of all public subnets containing their attributes. Example: public_subnet_attributes_by_az = { |
rt_attributes_by_type_by_az | Map of route tables by type => az => route table attributes. Example usage: module.vpc.rt_attributes_by_type_by_az.private.id Example: rt_attributes_by_type_by_az = { |
tgw_subnet_attributes_by_az | Map of all tgw subnets containing their attributes. Example: tgw_subnet_attributes_by_az = { |
transit_gateway_attachment_id | Transit gateway attachment id. |
vpc_attributes | VPC resource attributes. Full output of aws_vpc. |
vpc_lattice_service_network_association | VPC Lattice Service Network VPC association. Full output of aws_vpclattice_service_network_vpc_association |