Skip to main content
Sponsor @cloudposse

Module: dynamic-subnets

Terraform module to provision public and private subnets in an existing VPC

Note: This module is intended for use with an existing VPC and existing Internet Gateway. To create a new VPC, use terraform-aws-vpc module.

Note: Due to Terraform limitations, many optional inputs to this module are specified as a list(string) that can have zero or one element, rather than as a string that could be empty or null. The designation of an input as a list type does not necessarily mean that you can supply more than one value in the list, so check the input's description before supplying more than one value.

The core function of this module is to create 2 sets of subnets, a "public" set with bidirectional access to the public internet, and a "private" set behind a firewall with egress-only access to the public internet. This includes dividing up a given CIDR range so that a each subnet gets its own distinct CIDR range within that range, and then creating those subnets in the appropriate availability zones. The intention is to keep this module relatively simple and easy to use for the most popular use cases. In its default configuration, this module creates 1 public subnet and 1 private subnet in each of the specified availability zones. The public subnets are configured for bi-directional traffic to the public internet, while the private subnets are configured for egress-only traffic to the public internet. Rather than provide a wealth of configuration options allowing for numerous special cases, this module provides some common options and further provides the ability to suppress the creation of resources, allowing you to create and configure them as you like from outside this module. For example, rather than give you the option to customize the Network ACL, the module gives you the option to create a completely open one (and control access via Security Groups and other means) or not create one at all, allowing you to create and configure one yourself.

Public subnets​

This module defines a public subnet as one that has direct access to an internet gateway and can accept incoming connection requests. In the simplest configuration, the module creates a single route table with a default route targeted to the VPC's internet gateway, and associates all the public subnets with that single route table.

Likewise it creates a single Network ACL with associated rules allowing all ingress and all egress, and associates that ACL with all the public subnets.

Private subnets​

A private subnet may be able to initiate traffic to the public internet through a NAT gateway, a NAT instance, or an egress-only internet gateway, or it might only have direct access to other private subnets. In the simple configuration, for IPv4 and/or IPv6 with NAT64 enabled via public_dns64_enabled or private_dns64_enabled, the module creates 1 NAT Gateway or NAT Instance for each private subnet (in the public subnet in the same availability zone), creates 1 route table for each private subnet, and adds to that route table a default route from the subnet to its NAT Gateway or Instance. For IPv6, the module adds a route to the Egress-Only Internet Gateway configured via input.

As with the Public subnets, the module creates a single Network ACL with associated rules allowing all ingress and all egress, and associates that ACL with all the private subnets.

Customization for special use cases​

Various features are controlled by bool inputs with names ending in _enabled. By changing the default values, you can enable or disable creation of public subnets, private subnets, route tables, NAT gateways, NAT instances, or Network ACLs. So for example, you could use this module to create only private subnets and the open Network ACL, and then add your own route table associations to the subnets and route all non-local traffic to a Transit Gateway or VPN.

CIDR allocation​

For IPv4, you provide a CIDR and the module divides the address space into the largest CIDRs possible that are still small enough to accommodate max_subnet_count subnets of each enabled type (public or private). When max_subnet_count is left at the default 0, it is set to the total number of availability zones in the region. Private subnets are allocated out of the first half of the reserved range, and public subnets are allocated out of the second half.

For IPv6, you provide a /56 CIDR and the module assigns /64 subnets of that CIDR in consecutive order starting at zero. (You have the option of specifying a list of CIDRs instead.) As with IPv4, enough CIDRs are allocated to cover max_subnet_count private and public subnets (when both are enabled, which is the default), with the private subnets being allocated out of the lower half of the reservation and the public subnets allocated out of the upper half.

Usage​

module "subnets" {
  source = "cloudposse/dynamic-subnets/aws"
  # Cloud Posse recommends pinning every module to a specific version
  # version = "x.x.x"
  namespace           = "eg"
  stage               = "prod"
  name                = "app"
  vpc_id              = "vpc-XXXXXXXX"
  igw_id              = ["igw-XXXXXXXX"]
  ipv4_cidr_block     = ["10.0.0.0/16"]
  availability_zones  = ["us-east-1a", "us-east-1b"]
}

Create only private subnets, route to transit gateway:

module "private_tgw_subnets" {
  source = "cloudposse/dynamic-subnets/aws"
  # Cloud Posse recommends pinning every module to a specific version
  # version = "x.x.x"
  namespace           = "eg"
  stage               = "prod"
  name                = "app"
  vpc_id              = "vpc-XXXXXXXX"
  igw_id              = ["igw-XXXXXXXX"]
  ipv4_cidr_block     = ["10.0.0.0/16"]
  availability_zones  = ["us-east-1a", "us-east-1b"]

  nat_gateway_enabled    = false
  public_subnets_enabled = false
}

resource "aws_route" "private" {
  count = length(module.private_tgw_subnets.private_route_table_ids)

  route_table_id         = module.private_tgw_subnets.private_route_table_ids[count.index]
  destination_cidr_block = "0.0.0.0/0"
  transit_gateway_id     = "tgw-XXXXXXXXX"
}

See examples for working examples. In particular, see examples/nacls for an example of how to create custom Network Access Control Lists (NACLs) outside of but in conjunction with this module.

Subnet calculation logic​

terraform-aws-dynamic-subnets creates a set of subnets based on various CIDR inputs and the maximum possible number of subnets, which is max_subnet_count when specified or the number of Availability Zones in the region when max_subnet_count is left at its default value of zero.

You can explicitly provide CIDRs for subnets via ipv4_cidrs and ipv6_cidrs inputs if you want, but the usual use case is to provide a single CIDR which this module will subdivide into a set of CIDRs as follows:

  1. Get number of available AZ in the region:
existing_az_count = length(data.aws_availability_zones.available.names)
  1. Determine how many sets of subnets are being created. (Usually it is 2: public and private): subnet_type_count.
  2. Multiply the results of (1) and (2) to determine how many CIDRs to reserve:
cidr_count = existing_az_count * subnet_type_count
  1. Calculate the number of bits needed to enumerate all the CIDRs:
subnet_bits = ceil(log(cidr_count, 2))
  1. Reserve CIDRs for private subnets using cidrsubnet:
private_subnet_cidrs = [ for netnumber in range(0, existing_az_count): cidrsubnet(cidr_block, subnet_bits, netnumber) ]
  1. Reserve CIDRs for public subnets in the second half of the CIDR block:
public_subnet_cidrs = [ for netnumber in range(existing_az_count, existing_az_count * 2): cidrsubnet(cidr_block, subnet_bits, netnumber) ]

Note that this means that, for example, in a region with 4 availability zones, if you specify only 3 availability zones in var.availability_zones, this module will still reserve CIDRs for the 4th zone. This is so that if you later want to expand into that zone, the existing subnet CIDR assignments will not be disturbed. If you do not want to reserve these CIDRs, set max_subnet_count to the number of zones you are actually using.