Configuration Reference¶

Configuration File Structure¶

Table of Contents¶

Configuration File Structure
Section 1: Client Configuration
Section 2: Environment Configuration
Section 3: VPC Configuration
Section 4: Tags Configuration
Traffic Assumptions File
Complete Configuration Examples
VPC Naming Convention
CIDR Planning Guide
Configuration Validation Rules
Configuration Best Practices
Troubleshooting Configuration Issues
Additional Resources

The VPC Provisioner uses a YAML configuration file with three main sections:

client:
  company_name: Edge Corp
  company_prefix: edge
  account_id: "123456789012"
  tenant_id: "b001"

environment:
  env: prod
  region: us-west-2

vpc:
  vpc_name_override: ""
  cidr_block: 10.0.0.0/16
  availability_zones:
    - us-west-2a
    - us-west-2b
  subnets:
    public:
      - name: public-subnet-1
        cidr: 10.0.1.0/24
        az: us-west-2a
      - name: public-subnet-2
        cidr: 10.0.2.0/24
        az: us-west-2b
    private:
      - name: private-app-subnet-1
        cidr: 10.0.11.0/24
        az: us-west-2a
      - name: private-app-subnet-2
        cidr: 10.0.12.0/24
        az: us-west-2b
      - name: private-ml-subnet-1
        cidr: 10.0.13.0/24
        az: us-west-2a
    database:
      - name: database-subnet-1
        cidr: 10.0.21.0/26
        az: us-west-2a
      - name: database-subnet-2
        cidr: 10.0.22.0/26
        az: us-west-2b
  internet_gateway:
    enabled: true
  nat_gateway:
    enabled: true
    high_availability: true

tags:
  cost_center: Engineering
  project: ML-Platform
  owner: devops-team

Section 1: Client Configuration¶

company_name¶

Type: string
Required: Yes
Description: Full company name
Example: Edge Corp, Acme Corporation

company_prefix¶

Type: string
Required: Yes
Description: Short company identifier (lowercase, no spaces)
Constraints: Used in VPC naming
Example: edge, acme

account_id¶

Type: string (quoted)
Required: Yes
Description: 12-digit AWS account ID
Format: Must be quoted to preserve leading zeros
Example: "123456789012"

tenant_id¶

Type: string (quoted)
Required: Yes
Description: Human-readable account identifier
Format: Must be quoted to preserve leading zeros
Example: "b001"

Section 2: Environment Configuration¶

env¶

Type: string
Required: Yes
Description: Environment name
Valid Values: prod, dev, test, staging
Example: prod

region¶

Type: string
Required: Yes
Description: AWS region for VPC
Valid Values: Any valid AWS region (us-east-1, us-west-2, eu-west-1, etc.)
Example: us-west-2

Section 3: VPC Configuration¶

vpc_name_override¶

Type: string
Required: No (can be empty)
Default: Auto-generated from client/environment values
Description: Override auto-generated VPC name
Format: Alphanumeric and hyphens only

vpc:
  vpc_name_override: ""  # Use auto-generated name
  # OR
  vpc_name_override: "my-custom-vpc-name"

cidr_block¶

Type: string
Required: Yes
Description: VPC IPv4 CIDR block
Valid Range: /16 to /28
Format: x.x.x.x/y
Recommended: Use RFC 1918 private ranges

# Valid
vpc:
  cidr_block: 10.0.0.0/16      # 65,536 IPs
  cidr_block: 172.16.0.0/16    # 65,536 IPs
  cidr_block: 192.168.0.0/16   # 65,536 IPs

# Invalid
vpc:
  cidr_block: 10.0.0.0/8       # Too large
  cidr_block: 10.0.0.0/29      # Too small

availability_zones¶

Type: array of strings
Required: Yes
Description: List of availability zones for subnet placement
Format: {region}{letter}

vpc:
  availability_zones:
    - us-west-2a
    - us-west-2b
    - us-west-2c

subnets¶

Type: object with nested arrays
Required: Yes (at least one subnet type)
Description: Subnet configurations organized by type
Types: public, private, database

vpc:
  subnets:
    public:       # Public subnets (internet-facing)
      - name: public-subnet-1
        cidr: 10.0.1.0/24
        az: us-west-2a
    private:      # Private subnets (application tier)
      - name: private-app-subnet-1
        cidr: 10.0.11.0/24
        az: us-west-2a
    database:     # Database subnets (isolated tier)
      - name: database-subnet-1
        cidr: 10.0.21.0/26
        az: us-west-2a

Subnet Parameters¶

name

Type: string
Required: Yes
Description: Subnet identifier
Example: public-subnet-1, private-app-subnet-1

cidr

Type: string
Required: Yes
Description: Subnet IPv4 CIDR block
Constraints: Must be within VPC CIDR, /16 to /28
Note: AWS reserves 5 IPs per subnet

# VPC: 10.0.0.0/16
# Valid subnets:
cidr: 10.0.1.0/24    # 251 usable IPs
cidr: 10.0.2.0/24    # 251 usable IPs

# Invalid (outside VPC CIDR):
cidr: 192.168.1.0/24

Type: string
Required: Yes
Description: Availability zone for subnet
Format: Must match one of the AZs in availability_zones list

az: us-west-2a
az: us-west-2b

internet_gateway¶

Type: object
Required: Yes
Description: Internet Gateway configuration

vpc:
  internet_gateway:
    enabled: true   # Create Internet Gateway
    # OR
    enabled: false  # No Internet Gateway

enabled

Type: boolean
Required: Yes
Description: Enable Internet Gateway for public subnet internet access
Note: Required if you have public subnets

nat_gateway¶

Type: object
Required: Yes
Description: NAT Gateway configuration for private subnet internet access

vpc:
  nat_gateway:
    enabled: true              # Create NAT Gateway(s)
    high_availability: true    # NAT Gateway in each AZ
    # OR
    enabled: false             # No NAT Gateway

enabled

Type: boolean
Required: Yes
Description: Enable NAT Gateway for private subnet outbound internet access

high_availability

Type: boolean
Required: Yes (if enabled is true)
Description: Create NAT Gateway in each availability zone
Cost Impact: Multiple NAT Gateways increase cost but provide redundancy

High Availability Options:

# Single NAT Gateway (lower cost, single point of failure)
nat_gateway:
  enabled: true
  high_availability: false

# Multiple NAT Gateways (higher cost, no single point of failure)
nat_gateway:
  enabled: true
  high_availability: true

Section 4: Tags Configuration¶

tags¶

Type: object (key-value pairs)
Required: No
Description: Custom tags for VPC and all resources
Note: System tags are automatically applied

tags:
  cost_center: Engineering
  project: ML-Platform
  owner: devops-team
  environment: production
  managed_by: vpc-provisioner

System Tags (Automatically Applied)¶

The VPC Provisioner automatically applies system tags:

Tag Key	Source	Example Value
Company	client.company_name	Edge Corp
CompanyPrefix	client.company_prefix	edge
Environment	environment.env	prod
TenantId	client.tenant_id	b001
Region	environment.region	us-west-2
ConfigFile	Derived	edge-prod-b001-us-west-2-vpc.yaml

Custom Tags (Optional)¶

You can add custom tags for cost allocation, ownership, and compliance:

Tag Constraints:

Maximum 50 tags per resource (including system tags)
Key length: 1-128 characters
Value length: 0-256 characters
Case sensitive

Traffic Assumptions File¶

The cost-traffic action generates a traffic assumptions YAML file used by cost-estimate to calculate usage-based costs. This file is saved in the configs/ directory.

File Naming¶

<vpc-name>-traffic.yaml

Example: edge-prod-b001-us-west-2-vpc-traffic.yaml

File Structure¶

# Auto-generated traffic assumptions for cost estimation
# Edit values to match your expected monthly usage
# All traffic values are in GB per month

traffic:
  NATGateway2A:
    type: AWS::EC2::NatGateway
    data_gb_per_month: 100
  NATGateway2B:
    type: AWS::EC2::NatGateway
    data_gb_per_month: 100

Parameters¶

type

Type: string
Generated: Yes (do not modify)
Description: CloudFormation resource type

data_gb_per_month

Type: integer
Generated: Yes (with defaults)
Description: Expected monthly data transfer in GB
Default: 100 GB for NAT Gateways, 50 GB for VPC Endpoints
Action: Edit this value to match your expected usage

Usage¶

Run cost-traffic to generate the file with defaults
Edit data_gb_per_month values to reflect your expected traffic
Run cost-estimate to calculate costs based on your assumptions
Re-edit and re-run to model different scenarios

Complete Configuration Examples¶

Example 1: Simple Public VPC¶

Single public subnet for simple applications:

client:
  company_name: Edge Corp
  company_prefix: edge
  account_id: "123456789012"
  tenant_id: "b001"

environment:
  env: dev
  region: us-west-2

vpc:
  vpc_name_override: ""
  cidr_block: 10.0.0.0/16
  availability_zones:
    - us-west-2a
  subnets:
    public:
      - name: public-subnet-1
        cidr: 10.0.1.0/24
        az: us-west-2a
  internet_gateway:
    enabled: true
  nat_gateway:
    enabled: false

tags:
  cost_center: Engineering
  project: Development

Result: Simple VPC with one public subnet and Internet Gateway.

Example 2: Public-Private VPC¶

Public subnet for web tier, private subnet for app tier:

client:
  company_name: Edge Corp
  company_prefix: edge
  account_id: "123456789012"
  tenant_id: "b001"

environment:
  env: staging
  region: us-west-2

vpc:
  vpc_name_override: ""
  cidr_block: 10.0.0.0/16
  availability_zones:
    - us-west-2a
  subnets:
    public:
      - name: public-web-subnet-1
        cidr: 10.0.1.0/24
        az: us-west-2a
    private:
      - name: private-app-subnet-1
        cidr: 10.0.11.0/24
        az: us-west-2a
  internet_gateway:
    enabled: true
  nat_gateway:
    enabled: true
    high_availability: false

tags:
  cost_center: Engineering
  project: Staging-Environment

Result: VPC with public and private subnets, single NAT Gateway.

Example 3: 3-Tier Architecture (Recommended)¶

Public, private, and database tiers with high availability:

client:
  company_name: Edge Corp
  company_prefix: edge
  account_id: "123456789012"
  tenant_id: "b001"

environment:
  env: prod
  region: us-west-2

vpc:
  vpc_name_override: ""
  cidr_block: 10.0.0.0/16
  availability_zones:
    - us-west-2a
    - us-west-2b
  subnets:
    public:
      - name: public-subnet-1
        cidr: 10.0.1.0/24
        az: us-west-2a
      - name: public-subnet-2
        cidr: 10.0.2.0/24
        az: us-west-2b
    private:
      - name: private-app-subnet-1
        cidr: 10.0.11.0/24
        az: us-west-2a
      - name: private-app-subnet-2
        cidr: 10.0.12.0/24
        az: us-west-2b
      - name: private-ml-subnet-1
        cidr: 10.0.13.0/24
        az: us-west-2a
    database:
      - name: database-subnet-1
        cidr: 10.0.21.0/26
        az: us-west-2a
      - name: database-subnet-2
        cidr: 10.0.22.0/26
        az: us-west-2b
  internet_gateway:
    enabled: true
  nat_gateway:
    enabled: true
    high_availability: true

tags:
  cost_center: Engineering
  project: ML-Platform
  owner: devops-team
  compliance: required

Result: Production-ready 3-tier VPC with high availability across 2 AZs.

Example 4: Multi-AZ High Availability¶

Maximum redundancy across 3 availability zones:

client:
  company_name: Edge Corp
  company_prefix: edge
  account_id: "123456789012"
  tenant_id: "b001"

environment:
  env: prod
  region: us-east-1

vpc:
  vpc_name_override: ""
  cidr_block: 10.0.0.0/16
  availability_zones:
    - us-east-1a
    - us-east-1b
    - us-east-1c
  subnets:
    public:
      - name: public-subnet-1a
        cidr: 10.0.1.0/24
        az: us-east-1a
      - name: public-subnet-1b
        cidr: 10.0.2.0/24
        az: us-east-1b
      - name: public-subnet-1c
        cidr: 10.0.3.0/24
        az: us-east-1c
    private:
      - name: private-subnet-1a
        cidr: 10.0.11.0/24
        az: us-east-1a
      - name: private-subnet-1b
        cidr: 10.0.12.0/24
        az: us-east-1b
      - name: private-subnet-1c
        cidr: 10.0.13.0/24
        az: us-east-1c
    database:
      - name: database-subnet-1a
        cidr: 10.0.21.0/26
        az: us-east-1a
      - name: database-subnet-1b
        cidr: 10.0.22.0/26
        az: us-east-1b
      - name: database-subnet-1c
        cidr: 10.0.23.0/26
        az: us-east-1c
  internet_gateway:
    enabled: true
  nat_gateway:
    enabled: true
    high_availability: true

tags:
  cost_center: Engineering
  project: Critical-Infrastructure
  high_availability: true

Result: Maximum redundancy with resources in 3 AZs, 3 NAT Gateways.

VPC Naming Convention¶

When vpc_name_override is empty, the tool auto-generates VPC names using this pattern:

{company_prefix}-{env}-{tenant_id}-{region}

Examples:

edge-prod-b001-us-west-2
acme-dev-100000000002-us-east-1
tech-staging-100000000003-eu-west-1

CIDR Planning Guide¶

VPC CIDR Blocks¶

Size	CIDR	Total IPs	Usable IPs	Use Case
/16	x.x.0.0/16	65,536	65,536	Large production
/20	x.x.0.0/20	4,096	4,096	Medium production
/24	x.x.x.0/24	256	256	Small/dev
/28	x.x.x.x/28	16	16	Minimal/test

Subnet CIDR Blocks¶

Size	CIDR	Total IPs	Usable IPs*	Use Case
/24	x.x.x.0/24	256	251	Standard subnet
/25	x.x.x.0/25	128	123	Small subnet
/26	x.x.x.0/26	64	59	Micro subnet
/28	x.x.x.x/28	16	11	Minimal subnet

*AWS reserves 5 IPs per subnet:

.0: Network address
.1: VPC router
.2: DNS server
.3: Future use
.255: Broadcast address

CIDR Planning Example¶

# VPC: 10.0.0.0/16 (65,536 IPs)

# Public Subnets (256 IPs each, 251 usable)
# 10.0.1.0/24 - public-subnet-1a
# 10.0.2.0/24 - public-subnet-1b
# 10.0.3.0/24 - public-subnet-1c

# Private Subnets (256 IPs each, 251 usable)
# 10.0.11.0/24 - private-app-subnet-1a
# 10.0.12.0/24 - private-app-subnet-1b
# 10.0.13.0/24 - private-ml-subnet-1a

# Database Subnets (64 IPs each, 59 usable)
# 10.0.21.0/26 - database-subnet-1a
# 10.0.22.0/26 - database-subnet-1b

# Reserved for future expansion
# 10.0.30.0/24 - 10.0.255.0/24

Configuration Validation Rules¶

VPC CIDR¶

Must be valid IPv4 CIDR block
Size between /16 and /28
Cannot overlap with existing VPCs (if peering planned)
Recommended: Use RFC 1918 private ranges
- 10.0.0.0/8
- 172.16.0.0/12
- 192.168.0.0/16

Subnet CIDR¶

Must be within VPC CIDR range
Cannot overlap with other subnets
Size between /16 and /28
AWS reserves 5 IPs per subnet

Availability Zones¶

Must be valid AZs for the specified region
Subnet AZs must be in the availability_zones list
Recommended: Use at least 2 AZs for high availability

NAT Gateway¶

Requires internet_gateway.enabled: true
Requires at least one public subnet
high_availability: true creates NAT Gateway in each AZ

Configuration Best Practices¶

1. Plan CIDR Blocks Carefully¶

Cannot be changed after VPC creation
Leave room for future subnet expansion
Avoid overlapping with other VPCs or on-premises networks

2. Use Multiple Availability Zones¶

Minimum 2 AZs for production
3 AZs for critical workloads
Distribute subnets evenly across AZs

3. Separate Subnet Tiers¶

Public subnets: Internet-facing resources (load balancers, bastion hosts)
Private subnets: Application servers, compute resources
Database subnets: Isolated database instances

4. Enable High Availability NAT¶

nat_gateway:
  enabled: true
  high_availability: true  # Production recommendation

5. Tag All Resources¶

tags:
  Environment: production
  CostCenter: Engineering
  Project: ML-Platform
  Owner: devops-team
  ManagedBy: vpc-provisioner

6. Use Descriptive Names¶

subnets:
  public:
    - name: public-web-subnet-1a  # Clear purpose and AZ

7. Version Control Configurations¶

Store configs in Git
Tag releases for production deployments
Document manual changes

8. Test in Dev First¶

environment:
  env: dev  # Test here first

9. Review Generated Templates¶

Always review CloudFormation templates before deployment.

10. Document Architecture¶

Maintain architecture diagrams showing subnet layout and routing.

Troubleshooting Configuration Issues¶

Issue: Invalid CIDR block¶

Error: Invalid CIDR block format

Solution:

# ❌ Wrong
vpc:
  cidr_block: 10.0.0.0/8   # Too large

# ✅ Correct
vpc:
  cidr_block: 10.0.0.0/16

Issue: Subnet CIDR not within VPC CIDR¶

Error: Subnet CIDR must be within VPC CIDR

Solution:

# VPC: 10.0.0.0/16

# ❌ Wrong
subnets:
  public:
    - cidr: 192.168.1.0/24  # Outside VPC CIDR

# ✅ Correct
subnets:
  public:
    - cidr: 10.0.1.0/24     # Within VPC CIDR

Issue: Overlapping subnet CIDRs¶

Error: Subnet CIDRs cannot overlap

Solution:

# ❌ Wrong
subnets:
  public:
    - cidr: 10.0.1.0/24
  private:
    - cidr: 10.0.1.0/24  # Overlaps with public

# ✅ Correct
subnets:
  public:
    - cidr: 10.0.1.0/24
  private:
    - cidr: 10.0.11.0/24  # No overlap

Issue: Invalid availability zone¶

Error: Availability zone not in list

Solution:

# ❌ Wrong
vpc:
  availability_zones:
    - us-west-2a
  subnets:
    public:
      - az: us-west-2c  # Not in AZ list

# ✅ Correct
vpc:
  availability_zones:
    - us-west-2a
    - us-west-2c
  subnets:
    public:
      - az: us-west-2c  # In AZ list

Issue: Account ID not quoted¶

Error: Account ID lost leading zeros

Solution:

# ❌ Wrong
client:
  account_id: 123456789012

# ✅ Correct
client:
  account_id: "123456789012"

Additional Resources¶

User Guide - Complete command reference
IAM Permissions - Required AWS permissions
Troubleshooting - Common issues and solutions
Support - Getting help
AWS VPC Documentation: https://docs.aws.amazon.com/vpc/