User Guide¶

Complete reference for all commands and features.

Table of Contents¶

Quick Start
Security Scanning
Configuration
Commands Reference
Common Workflows
Volume Mounts
AWS Credentials
Best Practices

Quick Start¶

Pre-Deployment Checklist¶

Before deploying, ensure you have:

Docker 20.10+ installed and running (docker --version)
AWS credentials configured (aws sts get-caller-identity works)
AWS Marketplace subscription active for VPC Provisioner
IAM permissions verified (see IAM_PERMISSIONS.md)
Configuration file created and validated
CIDR blocks planned (no overlaps with existing VPCs or on-premises networks)
Availability zones confirmed for your region
Reviewed generated CloudFormation template
Tested in dev/staging environment first

1. Create Directories and Copy Documentation¶

cd ~
mkdir -p mlops-infra-suite/vpc/{configs,policies,reports,templates}
cd mlops-infra-suite
mkdir -p vpc/docs

# Create a temporary container
container_id=$(docker create vpc-provisioner:latest)

# Copy docs from container to host
docker cp $container_id:/app/docs/. vpc/docs/

# Remove the temporary container
docker rm $container_id

ls vpc/docs/

The following directory tree is created and the documentation files are copied.

└── mlops-infra-suite
    └── vpc
        ├── configs
        ├── docs
        │   ├── _sources/
        │   ├── _static/
        │   ├── APPLICATION_ARCHITECTURE.html
        │   ├── BACKUP_RECOVERY.html
        │   ├── CONFIGURATION.html
        │   ├── IAM_PERMISSIONS.html
        │   ├── MONITORING_HEALTH_CHECKS.html
        │   ├── README.html
        │   ├── RELEASE_NOTES.html
        │   ├── ROADMAP.html
        │   ├── SECURITY.html
        │   ├── SECURITY_GUIDELINES.html
        │   ├── SUPPORT.html
        │   ├── TROUBLESHOOTING.html
        │   ├── UPDATE_PROCEDURES.html
        │   ├── USER_GUIDE.html
        │   ├── api_reference.html
        │   ├── genindex.html
        │   ├── index.html
        │   ├── objects.inv
        │   ├── py-modindex.html
        │   ├── search.html
        │   └── searchindex.js
        ├── policies
        ├── reports
        └── templates

Open vpc/docs/index.html in your browser to view the documentation.”

2. Prepare Configuration File¶

Create a YAML configuration file in mlops-infra-suite/vpc/configs/ directory on host.

└── mlops-infra-suite
    └── vpc
      └── configs
         └── edge-prod-a001-us-west-2-vpc.yaml

Here is and example YAML configuration file. Replace data elements with your data.

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

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

3. Validate Configuration YAML Template¶

docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action validate-config

4. Create Policy JSON File¶

docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/policies:/app/policies \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action create-policy

5. Generate CloudFormation Template¶

docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  -v $(pwd)/vpc/templates:/app/templates \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action create-prov-template

6. Create VPC¶

docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  -v $(pwd)/vpc/templates:/app/templates \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action create-vpc

7. Delete VPC¶

docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action delete-vpc \
  --force

8. Expected Output Files¶

After running the complete workflow (steps 3-7), your directory structure will contain:

vpc/
├── configs/
│   ├── edge-prod-a001-us-west-2-vpc.yaml
│   └── edge-prod-a001-us-west-2-vpc-traffic.yaml
├── policies/
│   └── edge-prod-a001-us-west-2-vpc-iam-policy.json
├── reports/
│   ├── edge-prod-a001-us-west-2-vpc-validate-config-20260224_172425_821.log
│   ├── edge-prod-a001-us-west-2-vpc-create-policy-20260224_173327_277.log
│   ├── edge-prod-a001-us-west-2-vpc-create-prov-template-20260224_173643_921.log
│   ├── edge-prod-a001-us-west-2-vpc-create-prov-template-20260224_173643_921.html
│   ├── edge-prod-a001-us-west-2-vpc-create-vpc-20260224_174156_473.log
│   ├── edge-prod-a001-us-west-2-vpc-deployment-20260224_174420.html
│   ├── edge-prod-a001-us-west-2-vpc-cost-estimate-20260224_175012_531.log
│   ├── edge-prod-a001-us-west-2-vpc-cost-estimate-20260224_175012_531.html
│   └── edge-prod-a001-us-west-2-vpc-delete-vpc-20260224_182935_042.log
└── templates/
    └── edge-prod-a001-us-west-2-vpc-template.yaml

File Naming Conventions:

Logs: <vpc-name>-<action>-YYYYMMDD_HHMMSS_mmm.log
HTML Reports: <vpc-name>-<action>-YYYYMMDD_HHMMSS_mmm.html
Templates: <vpc-name>-template.yaml
Policies: <vpc-name>-iam-policy.json
Traffic Assumptions: <vpc-name>-traffic.yaml

File Types:

.log files contain detailed execution logs for troubleshooting
.html files are professional reports for visualization and documentation
.yaml files are CloudFormation templates or traffic assumptions for cost estimation
.json files are IAM policies for permission management

Security Scanning¶

Optional: Scan Docker Image for Vulnerabilities¶

You can scan the VPC Provisioner Docker image for security vulnerabilities using Trivy or any container scanning tool your organization uses.

Install Trivy:

# macOS
brew install trivy

# Linux
sudo apt-get install trivy

Run scan:

trivy image vpc-provisioner:latest

Filter by severity:

trivy image --severity HIGH,CRITICAL vpc-provisioner:latest

Note: OS-level vulnerabilities in the base image (Debian) are common and typically have no fixed version available yet. Python package vulnerabilities are more actionable — report any findings to support.

Configuration¶

Configuration File Structure¶

The VPC Provisioner uses a three-section YAML configuration:

client:
  company_name: string          # Full company name
  company_prefix: string        # Short identifier (lowercase)
  account_id: "string"          # 12-digit AWS account ID (quoted)
  tenant_id: "string"       # Account alias (quoted)

environment:
  env: string                   # Environment: prod, dev, test, staging
  region: string                # AWS region

vpc:
  vpc_name_override: string     # Custom VPC name (optional)
  cidr_block: string            # VPC CIDR block (e.g., 10.0.0.0/16)
  availability_zones: []        # List of AZs
  subnets:
    public: []                  # Public subnets
    private: []                 # Private subnets
    database: []                # Database subnets (optional)
  internet_gateway:
    enabled: boolean            # Enable Internet Gateway
  nat_gateway:
    enabled: boolean            # Enable NAT Gateway
    high_availability: boolean  # NAT Gateway in each AZ

tags:                           # Custom tags (optional)
  key: value

For detailed configuration reference, see CONFIGURATION.md.

Commands Reference¶

Validation Commands¶

validate-config¶

Check YAML configuration for schema compliance and syntax errors.

Purpose: Verify YAML syntax and schema compliance before deployment

Command:

docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action validate-config

Output:

Report in console
File reports/<config-name>-validate-config-yyyymmdd_mmhhss_NNN.log

Policy Commands¶

create-policy¶

Generate and export the least-privilege IAM policy tailored to your resources.

Purpose: Create IAM policy document with required permissions

Command:

docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/policies:/app/policies \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action create-policy

Output:

Report in console
File reports/<config-name>-create-policy-yyyymmdd_mmhhss_NNN.log
File reports/<vpc-name>-iam-policy.json

Use Case: Attach generated policy to IAM user/role before running AWS operations

CloudFormation Template Commands¶

create-prov-template¶

Generate a CloudFormation template based on your configuration.

Purpose: Create infrastructure-as-code template for VPC deployment

Command:

docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  -v $(pwd)/vpc/templates:/app/templates \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action create-prov-template

Output:

Report in console
File reports/<vpc-name>-create-prov-template-yyyymmdd_mmhhss_NNN.log
File reports/<vpc-name>-create-prov-template-yyyymmdd_mmhhss_NNN.html
File templates/<vpc-name>-template.yaml

Template Includes:

VPC with CIDR block
Public/Private/Database subnets
Internet Gateway (if enabled)
NAT Gateways (if enabled)
Route Tables with associations
Security Groups (if configured)
Tags (system + custom)

validate-prov-template¶

Verify provisioning template syntax and resource property names before deployment.

Purpose: Catch template errors early — YAML syntax, required keys, and internal reference integrity

Command:

docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  -v $(pwd)/vpc/templates:/app/templates \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action validate-prov-template

Output:

Report in console (template size, resource count, output count)
File reports/<vpc-name>-validate-prov-template-yyyymmdd_mmhhss_NNN.log

What It Checks:

YAML syntax is valid
Required top-level keys present (AWSTemplateFormatVersion, Resources)
All !Ref and !GetAtt targets resolve to parameters or resources within the template
Resource types are valid VPC resource types (AWS::EC2::*)

Note: This action does not call AWS APIs directly, but AWS credentials are still required for license validation.

VPC Provisioning Commands¶

test-deploy¶

Run a dry-run deployment to verify permissions and resource limits.

Purpose: Validate that the template deploys successfully without affecting production resources

Command:

docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action test-deploy

Output:

Report in console (stack outputs)
File reports/<vpc-name>-test-deploy-yyyymmdd_mmhhss_NNN.log

How It Works:

Appends a random 6-character suffix to the VPC name (e.g., edge-prod-a001-us-west-2-vpc-test-a1b2c3)
All resource names inherit the test suffix — no collision with production
Generates template in-memory (not persisted to disk)
Deploys via CloudFormation with the test-suffixed stack name
Restores original VPC name after deployment

Cleanup: Delete the test stack when done:

aws cloudformation delete-stack --stack-name edge-prod-a001-us-west-2-vpc-test-a1b2c3-stack --region us-west-2

Note: This action does not require --force. Test deployments are designed to be disposable.

create-vpc¶

Provision a complete VPC including subnets, gateways, and routing.

Purpose: Deploy VPC infrastructure via CloudFormation

Requirements: --force flag

Command:

docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  -v $(pwd)/vpc/templates:/app/templates \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action create-vpc \
  --force

Output:

Report in console
File reports/<vpc-name>-create-vpc-yyyymmdd_mmhhss_NNN.log
File reports/<vpc-name>-deployment-yyyymmdd_mmhhss.html
CFN Stack: <vpc-name>-stack example (edge-prod-a001-us-west-2-vpc-stack)
VPC: <config-name>example (edge-prod-a001-us-west-2)
SSM parameters: /vpc/<vpc-name>/<OutputKey>
- e.g., /vpc/edge-prod-a001-us-west-2-vpc/VPCId
- Available keys: VPCId, VPCCidr, <SubnetName>Id (one per configured subnet)

What It Does:

Reads the CloudFormation template from disk
Provisions VPC infrastructure through CloudFormation
Stores stack outputs in SSM Parameter Store (/vpc/<vpc-name>/<OutputKey>)
- e.g., /vpc/edge-prod-a001-us-west-2-vpc/VPCId
- Available keys: VPCId, VPCCidr, <SubnetName>Id (one per configured subnet)
Generates deployment report

What It Creates:

VPC with specified CIDR block
Public subnets (with auto-assign public IP if configured)
Private subnets (application tier)
Database subnets (optional, isolated tier)
Internet Gateway (if enabled)
NAT Gateways (if enabled, with HA option for multiple AZs)
Route Tables with proper associations
Routes (public → IGW, private → NAT)
Tags on all resources

Change Preview and Drift Detection Commands¶

show-changes¶

Preview projected infrastructure changes before deploying.

Purpose: Review pending changes before updating infrastructure

Command:

docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  -v $(pwd)/vpc/templates:/app/templates \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action show-changes

Output:

Report in console (list of pending resource changes)
File reports/<vpc-name>-show-changes-yyyymmdd_mmhhss_NNN.log

How It Works:

Creates a temporary CloudFormation ChangeSet against the deployed stack
Displays pending resource changes (Add, Modify, Remove)
Deletes the ChangeSet after display (no changes applied)

Note: Requires a deployed stack. If no stack exists, the command will report an error.

Dry Run: Use --dry-run to simulate without creating a ChangeSet:

vpc-prov -con edge-prod-a001-us-west-2-vpc.yaml -act show-changes --dry-run

check-drift¶

Detect differences between your live environment and defined configuration.

Purpose: Identify resources that have been modified outside of CloudFormation

Command:

docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action check-drift

Output:

Report in console (per-resource drift status with property-level diffs)
File reports/<vpc-name>-check-drift-yyyymmdd_mmhhss_NNN.log

What It Detects:

Security group rules modified manually
Route table entries changed outside CloudFormation
Subnet configurations altered
Tags modified or removed

Dry Run: Use --dry-run to simulate without initiating drift detection:

vpc-prov -con edge-prod-a001-us-west-2-vpc.yaml -act check-drift --dry-run

delete-vpc¶

Remove the VPC and all associated resources permanently.

Purpose: Remove VPC and all associated resources

Requirements: --force flag

Command:

docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action delete-vpc \
  --force

Output:

Report in console
File reports/<config-name>-delete-vpc-yyyymmdd_mmhhss_NNN.log
CFN Stack: <vpc-name>-stack removed
VPC: <vpc-name> removed

What It Deletes:

NAT Gateways
Elastic IPs (associated with NAT Gateways)
Route Table associations
Route Tables
Internet Gateway
Subnets
VPC
CloudFormation stack

Deletion Order: Automatically managed by CloudFormation to handle dependencies

Warning: This is a destructive operation. All resources in the VPC will be deleted.

Cost Estimation Commands¶

cost-traffic¶

Generate a traffic assumptions file for cost estimation.

Purpose: Create an editable YAML file with default monthly traffic values for resources that incur usage-based costs (e.g., NAT Gateway data processing)

Command:

docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs \
  -v $(pwd)/vpc/templates:/app/templates \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action cost-traffic

Output:

Report in console (resource count with traffic costs)
File configs/<vpc-name>-traffic.yaml
File reports/<vpc-name>-cost-traffic-yyyymmdd_mmhhss_NNN.log

Generated Traffic File:

# 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

Note: Edit the data_gb_per_month values to match your expected usage before running cost-estimate. Requires the provisioning template — run create-prov-template first.

cost-estimate¶

Calculate estimated monthly infrastructure costs with a detailed breakdown.

Purpose: Produce a cost breakdown showing fixed costs (hourly resources) and variable costs (traffic-based resources) with monthly and annual totals

Command:

docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs \
  -v $(pwd)/vpc/templates:/app/templates \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action cost-estimate

Output:

Cost breakdown in console (fixed costs, variable costs, totals)
File reports/<vpc-name>-cost-estimate-yyyymmdd_mmhhss_NNN.html
File reports/<vpc-name>-cost-estimate-yyyymmdd_mmhhss_NNN.log

HTML Report Includes:

Cost summary with monthly and annual totals
Fixed costs table (resource type, count, unit cost, monthly cost)
Usage-based costs table (assumed usage, rate per GB, monthly cost)
Pricing source and region information

Note: Requires both the provisioning template and traffic assumptions file. Run create-prov-template and cost-traffic first. The tool uses region-specific pricing from the built-in pricing data. Edit the traffic assumptions file and re-run to model different scenarios.

cost-refresh-prices¶

Refresh VPC resource pricing from the AWS Pricing API.

Purpose: Update the built-in pricing data with the latest on-demand rates from AWS for all regions

Command:

docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs \
  -v $(pwd)/vpc/templates:/app/templates \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action cost-refresh-prices

Output:

Report in console (region count, pricing for current region)
File reports/<vpc-name>-cost-refresh-prices-yyyymmdd_mmhhss_NNN.log

What It Fetches:

NAT Gateway hourly and per-GB data processing rates
Elastic IP hourly rates
VPC Endpoint hourly and per-GB rates

Note: This action is optional. The tool ships with pre-loaded pricing data. Run this action periodically to ensure pricing accuracy, or after AWS announces rate changes.

Common Workflows¶

Complete Deployment Workflow¶

# Step 1: Validate configuration
docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action validate-config

# Step 2: Generate IAM policy
docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/policies:/app/policies \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action create-policy

# Step 3: Generate CloudFormation template
docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  -v $(pwd)/vpc/templates:/app/templates \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action create-prov-template

# Step 4: Review generated template and policy
cat templates/edge-prod-a001-us-west-2-vpc-template.yaml
cat policies/edge-prod-a001-us-west-2-vpc-iam-policy.json

# Step 5: Validate generated template
docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  -v $(pwd)/vpc/templates:/app/templates \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action validate-prov-template

# Step 6: Test deploy (safe, isolated resources)
docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action test-deploy

# Step 7: Delete test stack after verification
# aws cloudformation delete-stack --stack-name <test-stack-name> --region us-west-2

# Step 8: Create VPC via CloudFormation
docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  -v $(pwd)/vpc/templates:/app/templates \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action create-vpc \
  --force

# Step 9: Verify in AWS Console
# - Check VPC created
# - Check subnets in correct AZs
# - Check route tables configured
# - Check NAT Gateways running

Quick Test Workflow¶

# Validate only
docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action validate-config

# Generate and validate template (no AWS deployment)
docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  -v $(pwd)/vpc/templates:/app/templates \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action create-prov-template

docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  -v $(pwd)/vpc/templates:/app/templates \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action validate-prov-template

# Review generated template
cat templates/edge-prod-a001-us-west-2-vpc-template.yaml

# Test deploy (safe, disposable resources)
docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action test-deploy

Cleanup Workflow¶

# Delete VPC and all resources
docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action delete-vpc \
  --force

Cost Estimation Workflow¶

# Step 1: Generate CloudFormation template (if not already done)
docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  -v $(pwd)/vpc/templates:/app/templates \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action create-prov-template

# Step 2: Generate traffic assumptions with defaults
docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs \
  -v $(pwd)/vpc/templates:/app/templates \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action cost-traffic

# Step 3: Edit traffic assumptions to match expected usage
# Edit configs/edge-prod-a001-us-west-2-vpc-traffic.yaml

# Step 4: Calculate cost estimate
docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs \
  -v $(pwd)/vpc/templates:/app/templates \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action cost-estimate

# Step 5: View HTML report
# Open reports/edge-prod-a001-us-west-2-vpc-cost-estimate-*.html

# Optional: Refresh pricing data from AWS Pricing API
docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs \
  -v $(pwd)/vpc/templates:/app/templates \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action cost-refresh-prices

Multi-Environment Workflow¶

# Deploy to dev
docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  -v $(pwd)/vpc/templates:/app/templates \
  vpc-provisioner:latest \
  --config edge-dev-a001-us-west-2-vpc.yaml \
  --action create-vpc

# Deploy to staging
docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  -v $(pwd)/vpc/templates:/app/templates \
  vpc-provisioner:latest \
  --config edge-staging-a001-us-west-2-vpc.yaml \
  --action create-vpc

# Deploy to prod
docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  -v $(pwd)/vpc/templates:/app/templates \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action create-vpc

Volume Mounts¶

Mount	Purpose	Required For
`configs/`	Input configuration files and traffic assumptions	All actions
`policies/`	Generated IAM policies	create-policy
`reports/`	Execution logs and HTML reports	All actions
`templates/`	CloudFormation templates	create-prov-template, validate-prov-template, create-vpc, show-changes, cost-traffic, cost-estimate
`~/.aws/`	AWS credentials	All actions (required for license validation)

Example with all mounts:

docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/policies:/app/policies \
  -v $(pwd)/vpc/reports:/app/reports \
  -v $(pwd)/vpc/templates:/app/templates \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action create-vpc

AWS Credentials¶

Actions that interact with AWS (show-changes, check-drift, test-deploy, create-vpc, delete-vpc) require AWS credentials. Additionally, all actions require AWS credentials for license validation.

Option 1: AWS Profile (Recommended)¶

Mount your AWS credentials directory:

docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  -v $(pwd)/vpc/templates:/app/templates \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action create-vpc

Benefits: Secure, uses existing AWS CLI configuration, supports MFA

Option 2: Environment Variables¶

Pass credentials as environment variables (less secure):

docker run --rm \
  -e AWS_ACCESS_KEY_ID=AKIA... \
  -e AWS_SECRET_ACCESS_KEY=wJal... \
  -e AWS_DEFAULT_REGION=us-west-2 \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  -v $(pwd)/vpc/templates:/app/templates \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action create-vpc

Warning: Credentials visible in process list and Docker history. Use Option 1 instead.

Option 3: IAM Role (EC2/ECS)¶

When running on EC2 or ECS with IAM role attached, credentials are automatically available:

docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  -v $(pwd)/vpc/templates:/app/templates \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action create-vpc

Benefits: Most secure, no credential management, automatic rotation

Best Practices¶

1. Always Validate First¶

Run validate-config before any AWS operations:

docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action validate-config

2. Review Generated Templates¶

Always review CloudFormation templates before deployment:

# Generate template
docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  -v $(pwd)/vpc/templates:/app/templates \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action create-prov-template

# Review template
cat templates/your-vpc-name-vpc-template.yaml

3. Plan CIDR Blocks Carefully¶

VPC CIDR Block:

Use private IP ranges: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
Recommended: /16 for production (65,536 IPs)
Avoid overlapping with other VPCs or on-premises networks

Subnet CIDR Blocks:

Must be within VPC CIDR range
Cannot overlap with other subnets
Leave room for future expansion

Example:

vpc:
  cidr_block: 10.0.0.0/16        # 65,536 IPs
  subnets:
    public:
      - cidr: 10.0.1.0/24         # 256 IPs
      - cidr: 10.0.2.0/24         # 256 IPs
    private:
      - cidr: 10.0.11.0/24        # 256 IPs
      - cidr: 10.0.12.0/24        # 256 IPs
    database:
      - cidr: 10.0.21.0/26        # 64 IPs
      - cidr: 10.0.22.0/26        # 64 IPs

4. Use High Availability¶

For production, enable NAT Gateway high availability:

vpc:
  nat_gateway:
    enabled: true
    high_availability: true  # NAT Gateway in each AZ

Benefits:

No single point of failure
Better performance (traffic stays in same AZ)
Higher cost (multiple NAT Gateways)

5. Use IAM Roles in Production¶

Prefer IAM roles over access keys when running on EC2/ECS.

6. Test in Dev First¶

Test configurations in dev environment before production:

environment:
  env: dev  # Test here first
  region: us-west-2

7. Use CloudFormation for Infrastructure¶

Always use create-vpc (CloudFormation) instead of manual VPC creation.

8. Proper Cleanup¶

Use delete-vpc with --force for complete infrastructure cleanup:

docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action delete-vpc \
  --force

9. Tag Resources¶

Use meaningful tags for cost allocation and resource tracking:

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

10. Version Control Configurations¶

Store configuration files in Git for change tracking and rollback capability.

VPC Architecture Patterns¶

Pattern 1: Simple Public VPC¶

Single public subnet for simple applications:

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

Pattern 2: Public-Private VPC¶

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

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

Pattern 3: 3-Tier Architecture (Recommended)¶

Public, private, and database tiers with high availability:

vpc:
  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
    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

Command Summary¶

Action	AWS Creds	–force	Purpose
validate-config	❌	❌	Validate YAML
create-policy	❌	❌	Generate IAM policy
create-prov-template	❌	❌	Generate CFN template
validate-prov-template	❌	❌	Validate CFN template locally
show-changes	✅	❌	Preview pending changes
check-drift	✅	❌	Detect infrastructure drift
test-deploy	✅	❌	Safe test deployment
create-vpc	✅	✅	Create VPC infrastructure
delete-vpc	✅	✅	Delete VPC and resources
cost-traffic	✅	❌	Generate traffic assumptions
cost-estimate	✅	❌	Calculate cost estimate
cost-refresh-prices	✅	❌	Refresh resource pricing

Troubleshooting¶

See TROUBLESHOOTING.md for common issues and solutions.

Quick Fixes¶

Invalid CIDR block:

# Valid
cidr_block: 10.0.0.0/16

# Invalid
cidr_block: 10.0.0.0/8   # Too large

Subnet CIDR not within VPC CIDR:

# VPC: 10.0.0.0/16
# Valid subnet: 10.0.1.0/24
# Invalid subnet: 192.168.1.0/24

Stack already exists:

# Delete first
docker run --rm \
  -v ~/.aws:/home/vpcuser/.aws:ro \
  -v $(pwd)/vpc/configs:/app/configs:ro \
  -v $(pwd)/vpc/reports:/app/reports \
  vpc-provisioner:latest \
  --config edge-prod-a001-us-west-2-vpc.yaml \
  --action delete-vpc \
  --force

Support¶

See SUPPORT.md for help and contact information.

Configuration Reference¶

See CONFIGURATION.md for complete configuration documentation.

IAM Permissions¶

See IAM_PERMISSIONS.md for required AWS permissions.

Frequently Asked Questions¶

Q: Can I modify the generated CloudFormation template? A: Yes, but changes will be overwritten on next create-prov-template. Use configuration parameters (vpc_name_override, cidr_block, tags, etc.) instead.

Q: How do I upgrade to a new version? A: Pull the latest Docker image. Existing VPCs are not affected unless you redeploy.

Q: Can I use this with existing VPCs? A: No, this tool creates new VPC infrastructure via CloudFormation. For existing VPCs, continue managing them with AWS Console, CLI, or your current IaC tool.

Q: What happens if deployment fails? A: CloudFormation automatically rolls back all resources. Check stack events for details. See TROUBLESHOOTING.md.

Q: Can I deploy to multiple regions? A: Yes, create separate configuration files for each region and run the tool for each config.

Q: How much does the infrastructure cost? A: Use the built-in cost estimation feature to calculate costs for your specific configuration. Run cost-traffic to generate traffic assumptions, edit the values to match your expected usage, then run cost-estimate for a detailed breakdown with monthly and annual totals. VPC, subnets, route tables, and Internet Gateway are free. NAT Gateways and Elastic IPs incur hourly charges, and NAT Gateways also have per-GB data processing fees. See COST_OPTIMIZATION.md for optimization strategies.

Q: Do I need NAT Gateway for dev/test? A: No. Set nat_gateway.enabled: false for dev/test environments to save ~$32-96/month. Only enable for environments where private subnets need internet access.

Q: Can I add subnets after deployment? A: Currently, modifying subnets requires deleting and redeploying the stack. Use show-changes to preview modifications before applying.

Q: How do I delete everything? A: Use delete-vpc --force to delete the CloudFormation stack and all VPC resources. Ensure no EC2 instances, RDS databases, or other services are running in the VPC first.