/aws-cloudformation-vpc

name: aws-cloudformation-vpc
description: Provides AWS CloudFormation patterns for VPC foundations, including subnets, route tables, internet and NAT gateways, endpoints, and reusable outputs. Use when creating a new network baseline, segmenting public and private workloads, or preparing CloudFormation networking stacks for application deployments.
allowed-tools: Read, Write, Bash

AWS CloudFormation VPC Infrastructure

Overview

Build a VPC foundation with CloudFormation that stays readable, reusable, and safe to evolve. Provides a clear subnet and routing model with predictable connectivity for public and private workloads, plus outputs that downstream stacks can consume without duplicating network logic.

Use the `references/` files for larger templates and extended service combinations.

When to Use

• Creating a new VPC stack for an application or shared platform
• Adding public and private subnets across one or more Availability Zones
• Wiring internet access, NAT egress, or private endpoints
• Exporting VPC, subnet, route table, and security-group-adjacent identifiers for other stacks
• Preparing reusable infrastructure for ECS, EKS, Lambda, EC2, or RDS stacks

Instructions

1. Start with the address plan

Before writing resources, define:

• VPC CIDR range
• Number of Availability Zones
• Public, private, and isolated subnet ranges
• Which workloads need internet ingress, NAT egress, or only private AWS service access

This prevents route-table sprawl and painful subnet replacement later.

2. Build the core network resources in layers

Create the stack in this order: 1. VPC and subnets 2. Internet Gateway for public ingress and egress 3. NAT gateways if private subnets need outbound internet access 4. Route tables and subnet associations 5. Optional VPC endpoints for private access to AWS services

Keep each layer easy to inspect in the template and avoid mixing unrelated application resources into the same stack.

3. Parameterize only the environment-dependent values

Useful parameters include:

• Environment name
• VPC CIDR and subnet CIDRs
• Number of AZs or explicit subnet IDs in nested-stack scenarios
• Flags for optional endpoints or NAT layout

Do not parameterize every route or tag unless it meaningfully changes between environments.

4. Export only what consumers really need

Typical outputs:

• VPC ID
• Public, private, and isolated subnet IDs
• Route table IDs when downstream stacks must attach routes
• Security boundaries or prefix-list references only when another stack consumes them

Stable outputs make application stacks easier to compose and migrate.

5. Validate before deployment

Run these commands to validate the template and verify routing:

# Validate CloudFormation template syntax
aws cloudformation validate-template --template-body file://vpc.yaml

# Review change set before applying
aws cloudformation create-change-set \
  --stack-name my-vpc \
  --template-body file://vpc.yaml \
  --change-set-type CREATE

# Verify route table associations
aws ec2 describe-route-tables \
  --filters "Name=vpc-id,Values=<vpc-id>"

# Check subnet to route table mappings
aws ec2 describe-route-tables \
  --filters "Name=association.subnet-id,Values=<subnet-id>"

# Verify internet gateway attachment
aws ec2 describe-internet-gateways \
  --filters "Name=attachment.vpc-id,Values=<vpc-id>"

Examples

Example 1: Complete two-tier VPC with routing

This template creates a VPC with public and private subnets, internet gateway, NAT gateway, and properly configured route tables.

AWSTemplateFormatVersion: "2010-09-09"
Description: "Two-tier VPC with public and private subnets"

Resources:
  # VPC
  MainVpc:
    Type: AWS::EC2::VPC
    Properties:
      CidrBlock: 10.0.0.0/16
      EnableDnsHostnames: true
      EnableDnsSupport: true
      Tags:
        - Key: Name
          Value: !Sub "${AWS::StackName}-main"

  # Internet Gateway
  InternetGateway:
    Type: AWS::EC2::InternetGateway
    Properties:
      Tags:
        - Key: Name
          Value: !Sub "${AWS::StackName}-igw"

  # Attach IGW to VPC
  GatewayToInternet:
    Type: AWS::EC2::VPCGatewayAttachment
    Properties:
      VpcId: !Ref MainVpc
      InternetGatewayId: !Ref InternetGateway

  # Public Subnet (AZ 1)
  PublicSubnetA:
    Type: AWS::EC2::Subnet
    Properties:
      VpcId: !Ref MainVpc
      CidrBlock: 10.0.1.0/24
      AvailabilityZone: !Select [0, !GetAZs ""]
      MapPublicIpOnLaunch: true
      Tags:
        - Key: Name
          Value: !Sub "${AWS::StackName}-public-a"

  # Private Subnet (AZ 1)
  PrivateSubnetA:
    Type: AWS::EC2::Subnet
    Properties:
      VpcId: !Ref MainVpc
      CidrBlock: 10.0.11.0/24
      AvailabilityZone: !Select [0, !GetAZs ""]
      Tags:
        - Key: Name
          Value: !Sub "${AWS::StackName}-private-a"

  # Elastic IP for NAT Gateway
  NatEip:
    Type: AWS::EC2::EIP
    DependsOn: GatewayToInternet
    Properties:
      Domain: vpc

  # NAT Gateway
  NatGateway:
    Type: AWS::EC2::NatGateway
    Properties:
      SubnetId: !Ref PublicSubnetA
      AllocationId: !GetAtt NatEip.AllocationId

  # Public Route Table
  PublicRouteTable:
    Type: AWS::EC2::RouteTable
    Properties:
      VpcId: !Ref MainVpc
      Tags:
        - Key: Name
          Value: !Sub "${AWS::StackName}-public-rt"

  # Default route to IGW
  PublicDefaultRoute:
    Type: AWS::EC2::Route
    DependsOn: GatewayToInternet
    Properties:
      RouteTableId: !Ref PublicRouteTable
      DestinationCidrBlock: 0.0.0.0/0
      GatewayId: !Ref InternetGateway

  # Associate public subnet
  PublicSubnetARouteTableAssociation:
    Type: AWS::EC2::SubnetRouteTableAssociation
    Properties:
      SubnetId: !Ref PublicSubnetA
      RouteTableId: !Ref PublicRouteTable

  # Private Route Table
  PrivateRouteTable:
    Type: AWS::EC2::RouteTable
    Properties:
      VpcId: !Ref MainVpc
      Tags:
        - Key: Name
          Value: !Sub "${AWS::