vpc
This component is responsible for provisioning a VPC and corresponding Subnets with advanced configuration capabilities.
Key Features:
- Independent control over public and private subnet counts per Availability Zone
- Flexible NAT Gateway placement (index-based or name-based)
- Named subnets with different naming schemes for public vs private
- Cost optimization through strategic NAT Gateway placement
- VPC Flow Logs support for auditing and compliance
- VPC Endpoints for AWS services (S3, DynamoDB, and interface endpoints)
- AWS Shield Advanced protection for NAT Gateway EIPs (optional)
What's New in v3.0.1:
- Uses
terraform-aws-dynamic-subnetsv3.0.1 with enhanced subnet configuration - Separate public/private subnet counts and names per AZ
- Precise NAT Gateway placement control for cost optimization
- NAT Gateway IDs exposed in subnet stats outputs
- Requires AWS Provider v5.0+
- Fixes critical bug in NAT routing when
max_nats < num_azs
Usage
Stack Level: Regional
Basic Configuration
Here's a basic example using legacy configuration (fully backward compatible):
# catalog/vpc/defaults
components:
terraform:
vpc/defaults:
metadata:
type: abstract
component: vpc
settings:
spacelift:
workspace_enabled: true
vars:
enabled: true
name: vpc
availability_zones:
- "a"
- "b"
- "c"
nat_gateway_enabled: true
nat_instance_enabled: false
max_subnet_count: 3
vpc_flow_logs_enabled: true
vpc_flow_logs_bucket_environment_name: <environment>
vpc_flow_logs_bucket_stage_name: audit
vpc_flow_logs_traffic_type: "ALL"
subnet_type_tag_key: "example.net/subnet/type"
# Legacy subnet configuration (still supported)
subnets_per_az_count: 1
subnets_per_az_names: ["common"]
# stacks/ue2-dev.yaml
import:
- catalog/vpc
components:
terraform:
vpc:
metadata:
component: vpc
inherits:
- vpc/defaults
vars:
ipv4_primary_cidr_block: "10.111.0.0/18"
Cost-Optimized NAT Configuration
Reduce NAT Gateway costs by placing NAT Gateways in only one public subnet per AZ:
components:
terraform:
vpc:
vars:
# Create 2 public subnets per AZ
public_subnets_per_az_count: 2
public_subnets_per_az_names: ["loadbalancer", "web"]
# Create 3 private subnets per AZ
private_subnets_per_az_count: 3
private_subnets_per_az_names: ["app", "database", "cache"]
# Place NAT Gateway ONLY in the first public subnet (index 0)
# This saves ~67% on NAT Gateway costs compared to NAT in all public subnets
nat_gateway_public_subnet_indices: [0]
Cost Savings Example (3 AZs, us-east-1):
- Without optimization: 6 NAT Gateways (2 per AZ) = ~$270/month
- With optimization: 3 NAT Gateways (1 per AZ) = ~$135/month
- Monthly Savings:
$135 ($1,620/year)
Important: You can use EITHER nat_gateway_public_subnet_indices OR nat_gateway_public_subnet_names, but not both. The plan will fail if both are specified.
Named NAT Gateway Placement
Place NAT Gateways by subnet name instead of index:
components:
terraform:
vpc:
vars:
# Must specify both count and names when using named subnets
public_subnets_per_az_count: 2
public_subnets_per_az_names: ["loadbalancer", "web"]
private_subnets_per_az_count: 2
private_subnets_per_az_names: ["app", "database"]
# Place NAT Gateway only in "loadbalancer" subnet
nat_gateway_public_subnet_names: ["loadbalancer"]
Important: When using public_subnets_per_az_names or private_subnets_per_az_names, you must also specify the corresponding count variables (public_subnets_per_az_count / private_subnets_per_az_count).
High-Availability NAT Configuration
For production environments requiring redundancy:
components:
terraform:
vpc:
vars:
public_subnets_per_az_count: 2
nat_gateway_public_subnet_indices: [0, 1] # NAT in both public subnets per AZ
Separate Public/Private Subnet Architecture
Different subnet counts and names for public vs private:
components:
terraform:
vpc:
vars:
# 2 public subnets per AZ for load balancers and public services
public_subnets_per_az_count: 2
public_subnets_per_az_names: ["alb", "nat"]
# 4 private subnets per AZ for different application tiers
private_subnets_per_az_count: 4
private_subnets_per_az_names: ["web", "app", "data", "cache"]
# NAT Gateway in "nat" subnet
nat_gateway_public_subnet_names: ["nat"]
VPC Endpoints Configuration
Add VPC Endpoints for AWS services to reduce data transfer costs and improve security:
components:
terraform:
vpc:
vars:
# Gateway endpoints (no hourly charges)
gateway_vpc_endpoints:
- "s3"
- "dynamodb"
# Interface endpoints (hourly charges apply)
interface_vpc_endpoints:
- "ec2"
- "ecr.api"
- "ecr.dkr"
- "logs"
- "secretsmanager"
Complete Production Example
components:
terraform:
vpc:
vars:
enabled: true
name: vpc
ipv4_primary_cidr_block: "10.0.0.0/16"
availability_zones:
- "a"
- "b"
- "c"
# Public subnets for ALB and NAT
public_subnets_per_az_count: 2
public_subnets_per_az_names: ["loadbalancer", "nat"]
# Private subnets for different tiers
private_subnets_per_az_count: 3
private_subnets_per_az_names: ["app", "database", "cache"]
# Cost-optimized NAT placement
nat_gateway_enabled: true
nat_gateway_public_subnet_names: ["nat"]
# VPC Flow Logs
vpc_flow_logs_enabled: true
vpc_flow_logs_bucket_environment_name: mgmt
vpc_flow_logs_bucket_stage_name: audit
vpc_flow_logs_traffic_type: "ALL"
# VPC Endpoints
gateway_vpc_endpoints:
- "s3"
- "dynamodb"
interface_vpc_endpoints:
- "ecr.api"
- "ecr.dkr"
- "logs"
subnet_type_tag_key: "example.net/subnet/type"
Variables
Required Variables
region(string) requiredAWS Region
subnet_type_tag_key(string) requiredKey for subnet type tag to provide information about the type of subnets, e.g.
cpco/subnet/type=privateorcpcp/subnet/type=public
Optional Variables
assign_generated_ipv6_cidr_block(bool) optionalWhen
true, assign AWS generated IPv6 CIDR block to the VPC. Conflicts withipv6_ipam_pool_id.Default value:
falseavailability_zone_ids(list(string)) optionalList of Availability Zones IDs where subnets will be created. Overrides
availability_zones.
Can be the full name, e.g.use1-az1, or just the part after the AZ ID region code, e.g.-az1,
to allow reusable values across regions. Consider contention for resources and spot pricing in each AZ when selecting.
Useful in some regions when using only some AZs and you want to use the same ones across multiple accounts.Default value:
[ ]availability_zones(list(string)) optionalList of Availability Zones (AZs) where subnets will be created. Ignored when
availability_zone_idsis set.
Can be the full name, e.g.us-east-1a, or just the part after the region, e.g.ato allow reusable values across regions.
The order of zones in the list must be stable or else Terraform will continually make changes.
If no AZs are specified, thenmax_subnet_countAZs will be selected in alphabetical order.
Ifmax_subnet_count > 0andlength(var.availability_zones) > max_subnet_count, the list
will be truncated. We recommend settingavailability_zonesandmax_subnet_countexplicitly as constant
(not computed) values for predictability, consistency, and stability.Default value:
[ ]gateway_vpc_endpoints(set(string)) optionalA list of Gateway VPC Endpoints to provision into the VPC. Only valid values are "dynamodb" and "s3".
Default value:
[ ]interface_vpc_endpoints(set(string)) optionalA list of Interface VPC Endpoints to provision into the VPC.
Default value:
[ ]ipv4_additional_cidr_block_associationsoptionalIPv4 CIDR blocks to assign to the VPC.
ipv4_cidr_blockcan be set explicitly, or set tonullwith the CIDR block derived fromipv4_ipam_pool_idusingipv4_netmask_length.
Map keys must be known atplantime, and are only used to track changes.Type:
map(object({
ipv4_cidr_block = string
ipv4_ipam_pool_id = string
ipv4_netmask_length = number
}))Default value:
{ }ipv4_cidr_block_association_timeoutsoptionalTimeouts (in
goduration format) for creating and destroying IPv4 CIDR block associationsType:
object({
create = string
delete = string
})Default value:
nullipv4_cidrsoptionalLists of CIDRs to assign to subnets. Order of CIDRs in the lists must not change over time.
Lists may contain more CIDRs than needed.Type:
list(object({
private = list(string)
public = list(string)
}))Default value:
[ ]ipv4_primary_cidr_block(string) optionalThe primary IPv4 CIDR block for the VPC.
Eitheripv4_primary_cidr_blockoripv4_primary_cidr_block_associationmust be set, but not both.Default value:
nullipv4_primary_cidr_block_associationoptionalConfiguration of the VPC's primary IPv4 CIDR block via IPAM. Conflicts with
ipv4_primary_cidr_block.
One ofipv4_primary_cidr_blockoripv4_primary_cidr_block_associationmust be set.
Additional CIDR blocks can be set viaipv4_additional_cidr_block_associations.Type:
object({
ipv4_ipam_pool_id = string
ipv4_netmask_length = number
})Default value:
nullmap_public_ip_on_launch(bool) optionalInstances launched into a public subnet should be assigned a public IP address
Default value:
truemax_nats(number) optionalUpper limit on number of NAT Gateways/Instances to create.
Set to 1 or 2 for cost savings at the expense of availability.
Default creates a NAT Gateway in each public subnet.Default value:
nullmax_subnet_count(number) optionalSets the maximum amount of subnets to deploy. 0 will deploy a subnet for every provided availability zone (in
region_availability_zonesvariable) within the regionDefault value:
0nat_eip_aws_shield_protection_enabled(bool) optionalEnable or disable AWS Shield Advanced protection for NAT EIPs. If set to 'true', a subscription to AWS Shield Advanced must exist in this account.
Default value:
falsenat_gateway_enabled(bool) optionalFlag to enable/disable NAT gateways
Default value:
truenat_gateway_public_subnet_indices(list(number)) optionalIndices (0-based) of public subnets where NAT Gateways should be placed.
Use this for index-based NAT Gateway placement (e.g., [0, 1] to place NATs in first 2 public subnets per AZ).
Conflicts withnat_gateway_public_subnet_names.
If both are null, NAT Gateways are placed in all public subnets by default.Default value:
nullnat_gateway_public_subnet_names(list(string)) optionalNames of public subnets where NAT Gateways should be placed.
Use this for name-based NAT Gateway placement (e.g., ["loadbalancer"] to place NATs only in "loadbalancer" subnets).
Conflicts withnat_gateway_public_subnet_indices.
If both are null, NAT Gateways are placed in all public subnets by default.Default value:
nullnat_instance_ami_id(list(string)) optionalA list optionally containing the ID of the AMI to use for the NAT instance.
If the list is empty (the default), the latest official AWS NAT instance AMI
will be used. NOTE: The Official NAT instance AMI is being phased out and
does not support NAT64. Use of a NAT gateway is recommended instead.Default value:
[ ]nat_instance_enabled(bool) optionalFlag to enable/disable NAT instances
Default value:
falsenat_instance_type(string) optionalNAT Instance type
Default value:
"t3.micro"private_subnets_per_az_count(number) optionalThe number of private subnets to provision per Availability Zone.
If null, defaults to the value ofsubnets_per_az_countfor backward compatibility.
Use this to create different numbers of private and public subnets per AZ.Default value:
nullprivate_subnets_per_az_names(list(string)) optionalThe names of private subnets to provision per Availability Zone.
If null, defaults to the value ofsubnets_per_az_namesfor backward compatibility.
Use this to create different named private subnets than public subnets.Default value:
nullpublic_subnets_enabled(bool) optionalIf false, do not create public subnets.
Since NAT gateways and instances must be created in public subnets, these will also not be created whenfalse.Default value:
truepublic_subnets_per_az_count(number) optionalThe number of public subnets to provision per Availability Zone.
If null, defaults to the value ofsubnets_per_az_countfor backward compatibility.
Use this to create different numbers of public and private subnets per AZ.Default value:
nullpublic_subnets_per_az_names(list(string)) optionalThe names of public subnets to provision per Availability Zone.
If null, defaults to the value ofsubnets_per_az_namesfor backward compatibility.
Use this to create different named public subnets than private subnets.Default value:
nullsubnets_per_az_count(number) optionalThe number of subnet of each type (public or private) to provision per Availability Zone.
Default value:
1subnets_per_az_names(list(string)) optionalThe subnet names of each type (public or private) to provision per Availability Zone.
This variable is optional.
If a list of names is provided, the list items will be used as keys in the outputsnamed_private_subnets_map,named_public_subnets_map,
named_private_route_table_ids_mapandnamed_public_route_table_ids_mapDefault value:
[
"common"
]vpc_flow_logs_bucket_component_name(string) optionalThe name of the VPC flow logs bucket component
Default value:
"vpc-flow-logs-bucket"vpc_flow_logs_bucket_environment_name(string) optionalThe name of the environment where the VPC Flow Logs bucket is provisioned
Default value:
""vpc_flow_logs_bucket_stage_name(string) optionalThe stage (account) name where the VPC Flow Logs bucket is provisioned
Default value:
""vpc_flow_logs_bucket_tenant_name(string) optionalThe name of the tenant where the VPC Flow Logs bucket is provisioned.
If the
tenantlabel is not used, leave this asnull.Default value:
nullvpc_flow_logs_destination_options_file_format(string) optionalVPC Flow Logs file format
Default value:
"parquet"vpc_flow_logs_destination_options_hive_compatible_partitions(bool) optionalFlag to enable/disable VPC Flow Logs hive compatible partitions
Default value:
falsevpc_flow_logs_destination_options_per_hour_partition(bool) optionalFlag to enable/disable VPC Flow Logs per hour partition
Default value:
falsevpc_flow_logs_enabled(bool) optionalEnable or disable the VPC Flow Logs
Default value:
truevpc_flow_logs_log_destination_type(string) optionalThe type of the logging destination. Valid values:
cloud-watch-logs,s3Default value:
"s3"vpc_flow_logs_traffic_type(string) optionalThe type of traffic to capture. Valid values:
ACCEPT,REJECT,ALLDefault value:
"ALL"
Context Variables
The following variables are defined in the context.tf file of this module and part of the terraform-null-label pattern.
context.tf file of this module and part of the terraform-null-label pattern.additional_tag_map(map(string)) optionalAdditional key-value pairs to add to each map in
tags_as_list_of_maps. Not added totagsorid.
This is for some rare cases where resources want additional configuration of tags
and therefore take a list of maps with tag key, value, and additional configuration.Required: No
Default value:
{ }attributes(list(string)) optionalID element. Additional attributes (e.g.
workersorcluster) to add toid,
in the order they appear in the list. New attributes are appended to the
end of the list. The elements of the list are joined by thedelimiter
and treated as a single ID element.Required: No
Default value:
[ ]context(any) optionalSingle object for setting entire context at once.
See description of individual variables for details.
Leave string and numeric variables asnullto use default value.
Individual variable settings (non-null) override settings in context object,
except for attributes, tags, and additional_tag_map, which are merged.Required: No
Default value:
{
"additional_tag_map": {},
"attributes": [],
"delimiter": null,
"descriptor_formats": {},
"enabled": true,
"environment": null,
"id_length_limit": null,
"label_key_case": null,
"label_order": [],
"label_value_case": null,
"labels_as_tags": [
"unset"
],
"name": null,
"namespace": null,
"regex_replace_chars": null,
"stage": null,
"tags": {},
"tenant": null
}delimiter(string) optionalDelimiter to be used between ID elements.
Defaults to-(hyphen). Set to""to use no delimiter at all.Required: No
Default value:
nulldescriptor_formats(any) optionalDescribe additional descriptors to be output in the
descriptorsoutput map.
Map of maps. Keys are names of descriptors. Values are maps of the form
\{<br/> format = string<br/> labels = list(string)<br/> \}
(Type isanyso the map values can later be enhanced to provide additional options.)
formatis a Terraform format string to be passed to theformat()function.
labelsis a list of labels, in order, to pass toformat()function.
Label values will be normalized before being passed toformat()so they will be
identical to how they appear inid.
Default is{}(descriptorsoutput will be empty).Required: No
Default value:
{ }enabled(bool) optionalSet to false to prevent the module from creating any resources
Required: NoDefault value:
nullenvironment(string) optionalID element. Usually used for region e.g. 'uw2', 'us-west-2', OR role 'prod', 'staging', 'dev', 'UAT'
Required: NoDefault value:
nullid_length_limit(number) optionalLimit
idto this many characters (minimum 6).
Set to0for unlimited length.
Set tonullfor keep the existing setting, which defaults to0.
Does not affectid_full.Required: No
Default value:
nulllabel_key_case(string) optionalControls the letter case of the
tagskeys (label names) for tags generated by this module.
Does not affect keys of tags passed in via thetagsinput.
Possible values:lower,title,upper.
Default value:title.Required: No
Default value:
nulllabel_order(list(string)) optionalThe order in which the labels (ID elements) appear in the
id.
Defaults to ["namespace", "environment", "stage", "name", "attributes"].
You can omit any of the 6 labels ("tenant" is the 6th), but at least one must be present.Required: No
Default value:
nulllabel_value_case(string) optionalControls the letter case of ID elements (labels) as included in
id,
set as tag values, and output by this module individually.
Does not affect values of tags passed in via thetagsinput.
Possible values:lower,title,upperandnone(no transformation).
Set this totitleand setdelimiterto""to yield Pascal Case IDs.
Default value:lower.Required: No
Default value:
nulllabels_as_tags(set(string)) optionalSet of labels (ID elements) to include as tags in the
tagsoutput.
Default is to include all labels.
Tags with empty values will not be included in thetagsoutput.
Set to[]to suppress all generated tags.
Notes:
The value of thenametag, if included, will be theid, not thename.
Unlike othernull-labelinputs, the initial setting oflabels_as_tagscannot be
changed in later chained modules. Attempts to change it will be silently ignored.Required: No
Default value:
[
"default"
]name(string) optionalID element. Usually the component or solution name, e.g. 'app' or 'jenkins'.
This is the only ID element not also included as atag.
The "name" tag is set to the fullidstring. There is no tag with the value of thenameinput.Required: No
Default value:
nullnamespace(string) optionalID element. Usually an abbreviation of your organization name, e.g. 'eg' or 'cp', to help ensure generated IDs are globally unique
Required: NoDefault value:
nullregex_replace_chars(string) optionalTerraform regular expression (regex) string.
Characters matching the regex will be removed from the ID elements.
If not set,"/[^a-zA-Z0-9-]/"is used to remove all characters other than hyphens, letters and digits.Required: No
Default value:
nullstage(string) optionalID element. Usually used to indicate role, e.g. 'prod', 'staging', 'source', 'build', 'test', 'deploy', 'release'
Required: NoDefault value:
nulltags(map(string)) optionalAdditional tags (e.g.
{'BusinessUnit': 'XYZ'}).
Neither the tag keys nor the tag values will be modified by this module.Required: No
Default value:
{ }tenant(string) optionalID element (Rarely used, not included by default). A customer identifier, indicating who this instance of a resource is for
Required: NoDefault value:
null
Outputs
availability_zone_idsList of Availability Zones IDs where subnets were created, when available
availability_zonesList of Availability Zones where subnets were created
az_private_route_table_ids_mapMap of AZ names to list of private route table IDs in the AZs
az_private_subnets_mapMap of AZ names to list of private subnet IDs in the AZs
az_public_route_table_ids_mapMap of AZ names to list of public route table IDs in the AZs
az_public_subnets_mapMap of AZ names to list of public subnet IDs in the AZs
flow_log_destinationDestination bucket for VPC flow logs
flow_log_idID of the VPC flow log
gateway_vpc_endpointsMap of Gateway VPC Endpoints in this VPC, keyed by service (e.g. "s3").
igw_idThe ID of the Internet Gateway
interface_vpc_endpointsMap of Interface VPC Endpoints in this VPC.
max_subnet_countMaximum allowed number of subnets before all subnet CIDRs need to be recomputed
named_private_subnets_stats_mapMap of subnet names (specified in
private_subnets_per_az_namesorsubnets_per_az_namesvariable) to lists of objects with each object having four items: AZ, private subnet ID, private route table ID, NAT Gateway ID (the NAT Gateway that this private subnet routes to for egress)named_public_subnets_stats_mapMap of subnet names (specified in
public_subnets_per_az_namesorsubnets_per_az_namesvariable) to lists of objects with each object having four items: AZ, public subnet ID, public route table ID, NAT Gateway ID (the NAT Gateway in this public subnet, if any)named_route_tablesMap of route table IDs, keyed by subnets_per_az_names.
If subnets_per_az_names is not set, items are grouped by key 'common'named_subnetsMap of subnets IDs, keyed by subnets_per_az_names.
If subnets_per_az_names is not set, items are grouped by key 'common'nat_eip_allocation_idsElastic IP allocations in use by NAT
nat_eip_protectionsList of AWS Shield Advanced Protections for NAT Elastic IPs.
nat_gateway_idsNAT Gateway IDs
nat_gateway_public_ipsNAT Gateway public IPs
nat_instance_ami_idID of AMI used by NAT instance
nat_instance_idsNAT Instance IDs
nat_ipsElastic IP Addresses in use by NAT
private_network_acl_idID of the Network ACL created for private subnets
private_route_table_idsPrivate subnet route table IDs
private_subnet_arnsPrivate subnet ARNs
private_subnet_cidrsPrivate subnet CIDRs
private_subnet_idsPrivate subnet IDs
private_subnet_ipv6_cidrsPrivate subnet IPv6 CIDR blocks
public_network_acl_idID of the Network ACL created for public subnets
public_route_table_idsPublic subnet route table IDs
public_subnet_arnsPublic subnet ARNs
public_subnet_cidrsPublic subnet CIDRs
public_subnet_idsPublic subnet IDs
public_subnet_ipv6_cidrsPublic subnet IPv6 CIDR blocks
route_tablesRoute tables info map
subnetsSubnets info map
vpcVPC info map
vpc_cidrVPC CIDR
vpc_default_network_acl_idThe ID of the network ACL created by default on VPC creation
vpc_default_security_group_idThe ID of the security group created by default on VPC creation
vpc_endpoint_dynamodb_idID of the DynamoDB gateway endpoint
vpc_endpoint_dynamodb_prefix_list_idPrefix list ID for DynamoDB gateway endpoint
vpc_endpoint_interface_security_group_idSecurity group ID for interface VPC endpoints
vpc_endpoint_s3_idID of the S3 gateway endpoint
vpc_endpoint_s3_prefix_list_idPrefix list ID for S3 gateway endpoint
vpc_idVPC ID
Dependencies
Requirements
terraform, version:>= 1.0.0aws, version:>= 5.0.0null, version:>= 3.0
Providers
aws, version:>= 5.0.0null, version:>= 3.0
Modules
| Name | Version | Source | Description |
|---|---|---|---|
endpoint_security_groups | 2.2.0 | cloudposse/security-group/aws | We could create a security group per endpoint, but until we are ready to customize them by service, it is just a waste of resources. We use a single security group for all endpoints. Security groups can be updated without recreating the endpoint or interrupting service, so this is an easy change to make later. |
iam_roles | latest | ../account-map/modules/iam-roles | n/a |
subnets | 3.0.1 | cloudposse/dynamic-subnets/aws | n/a |
this | 0.25.0 | cloudposse/label/null | n/a |
utils | 1.4.0 | cloudposse/utils/aws | n/a |
vpc | 3.0.0 | cloudposse/vpc/aws | n/a |
vpc_endpoints | 3.0.0 | cloudposse/vpc/aws//modules/vpc-endpoints | n/a |
vpc_flow_logs_bucket | 1.8.0 | cloudposse/stack-config/yaml//modules/remote-state | n/a |
Resources
The following resources are used by this module:
aws_flow_log.default(resource)aws_shield_protection.nat_eip_shield_protection(resource)null_resource.nat_placement_validation(resource)
Data Sources
The following data sources are used by this module:
aws_caller_identity.current(data source)aws_eip.eip(data source)