README¶

Enterprise-grade VPC provisioning and management tool for AWS.

Table of Contents¶

What It Does
Quick Start
Common Commands
AWS Credentials
Required IAM Permissions
What Gets Created
VPC Architecture Patterns
Directory Structure
Accessing Documentation
Next Steps
Quick Troubleshooting
License

What It Does¶

Creates and configures VPCs using CloudFormation
Generates IAM policies automatically
Manages subnets (public, private, database tiers)
Deploys Internet Gateways and NAT Gateways
Configures route tables automatically
Validates configurations and templates before deployment
Previews infrastructure changes before applying them
Detects infrastructure drift against deployed stacks
Supports safe test deployments with isolated resource names
Estimates monthly infrastructure costs with detailed breakdowns

Quick Start¶

1. Prerequisites & Installation¶

Requirements¶

Requirement	Version	Notes
Docker	20.10+	Required to run the VPC Provisioner CLI
AWS CLI	2.x	Required for credential configuration and AWS resource verification
AWS Account	—	With permissions to create VPC, CloudFormation, and IAM resources

Installation¶

No installation is required. VPC Provisioner is distributed as a Docker image via AWS Marketplace.

docker pull <your-ecr-url>/vpc-provisioner:latest

AWS Credentials Setup¶

# Configure AWS CLI
aws configure

# Verify credentials
aws sts get-caller-identity

Working Directory Setup¶

Create the required directory structure:

mkdir -p vpc/{configs,policies,reports,templates,docs}

Copy documentation from the Docker image:

docker run --rm \
  -v $(pwd)/vpc/docs:/output \
  --entrypoint cp \
  vpc-provisioner:latest \
  -r /app/docs/. /output/

Copy example configuration files from the Docker image:

docker run --rm \
  -v $(pwd)/vpc/configs:/app/configs \
  --entrypoint cp \
  vpc-provisioner:latest \
  -r /app/examples/configs/. /app/configs/

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

2. Set Up Directories¶

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

3. Add Your Configuration¶

Create configs/my-config.yaml:

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

4. Run Your First 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-b001-us-west-2-vpc.yaml \
  --action validate-config

Success! You’ve validated your configuration.

Common Commands¶

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-b001-us-west-2-vpc.yaml \
  --action validate-config

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-b001-us-west-2-vpc.yaml \
  --action create-policy

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-b001-us-west-2-vpc.yaml \
  --action create-prov-template

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-b001-us-west-2-vpc.yaml \
  --action create-vpc \
  --force

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-b001-us-west-2-vpc.yaml \
  --action validate-prov-template

Preview Changes¶

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-b001-us-west-2-vpc.yaml \
  --action show-changes

Check Infrastructure Drift¶

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-b001-us-west-2-vpc.yaml \
  --action check-drift

Test Deploy (Safe Testing)¶

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-b001-us-west-2-vpc.yaml \
  --action test-deploy

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-b001-us-west-2-vpc.yaml \
  --action delete-vpc \
  --force

Generate Traffic Assumptions¶

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-b001-us-west-2-vpc.yaml \
  --action cost-traffic

Estimate Monthly Costs¶

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-b001-us-west-2-vpc.yaml \
  --action cost-estimate

Refresh Resource Pricing¶

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-b001-us-west-2-vpc.yaml \
  --action cost-refresh-prices

AWS Credentials¶

Option 1: AWS Profile (Recommended)

-v ~/.aws:/home/vpcuser/.aws:ro

Option 2: Environment Variables

-e AWS_ACCESS_KEY_ID=your_key \
-e AWS_SECRET_ACCESS_KEY=your_secret \
-e AWS_DEFAULT_REGION=us-west-2

Required IAM Permissions¶

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "EC2VPCManagement",
            "Effect": "Allow",
            "Action": [
                "ec2:CreateVpc",
                "ec2:DeleteVpc",
                "ec2:DescribeVpcs",
                "ec2:DescribeSubnets",
                "ec2:DescribeRouteTables",
                "ec2:DescribeInternetGateways",
                "ec2:CreateSubnet",
                "ec2:DeleteSubnet",
                "ec2:CreateRouteTable",
                "ec2:DeleteRouteTable",
                "ec2:AssociateRouteTable",
                "ec2:CreateInternetGateway",
                "ec2:AttachInternetGateway",
                "ec2:DetachInternetGateway",
                "ec2:DeleteInternetGateway",
                "ec2:CreateRoute",
                "ec2:DeleteRoute",
                "ec2:DisassociateRouteTable",
                "ec2:CreateTags",
                "ec2:DeleteTags",
                "ec2:ModifyVpcAttribute"
            ],
            "Resource": "arn:aws:ec2:us-west-2:123456789012:*"
        },
        {
            "Sid": "CloudFormationManagement",
            "Effect": "Allow",
            "Action": [
                "cloudformation:CreateStack",
                "cloudformation:DeleteStack",
                "cloudformation:DescribeStacks",
                "cloudformation:UpdateStack",
                "cloudformation:ValidateTemplate",
                "cloudformation:DescribeStackEvents",
                "cloudformation:DescribeStackResources"
            ],
            "Resource": "arn:aws:cloudformation:us-west-2:123456789012:stack/*/*"
        },
        {
            "Sid": "S3TemplateAccess",
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:DeleteObject"
            ],
            "Resource": "arn:aws:s3:::edge-*/templates/*"
        },
        {
            "Sid": "S3BucketList",
            "Effect": "Allow",
            "Action": "s3:ListBucket",
            "Resource": "arn:aws:s3:::edge-*"
        }
    ]
}

See IAM Permissions for complete permissions.

What Gets Created¶

When you run create-vpc, the tool creates:

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

VPC Architecture Patterns¶

Simple Public VPC¶

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

Public-Private VPC¶

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

3-Tier Architecture (Recommended)¶

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

Directory Structure¶

your-project/
├── configs/          # VPC configuration files and traffic assumptions
├── policies/         # Generated IAM policies
├── templates/        # Generated CloudFormation templates
└── reports/          # Execution logs and HTML reports

Accessing Documentation¶

All documentation is embedded in the Docker image:

# List available documentation
docker run --rm --entrypoint ls vpc-provisioner:latest /app/docs

# View specific documentation
docker run --rm --entrypoint cat vpc-provisioner:latest /app/docs/README.md
docker run --rm --entrypoint cat vpc-provisioner:latest /app/docs/USER_GUIDE.md

# Copy all documentation to vpc/docs directory
docker run --rm -v $(pwd)/vpc/docs:/output --entrypoint cp vpc-provisioner:latest -r /app/docs/. /output/

Copy example configuration file from the Docker image:

docker run --rm \
  -v $(pwd)/vpc/configs:/app/configs \
  --entrypoint cp \
  vpc-provisioner:latest \
  -r /app/examples/configs/. /app/configs/

Available Documentation:

README.md - Quick start and overview
USER_GUIDE.md - Complete command reference
CONFIGURATION.md - Configuration parameters
IAM_PERMISSIONS.md - Required AWS permissions
TROUBLESHOOTING.md - Common issues and solutions
SUPPORT.md - Support and contact information
RELEASE_NOTES.md - Version history
ROADMAP.md - Future features

Next Steps¶

Read the User Guide for all commands
See Configuration Reference for all parameters
Check Support for help

Quick Troubleshooting¶

Invalid CIDR block

Use valid format: 10.0.0.0/16
VPC CIDR must be /16 to /28

Subnet CIDR not within VPC CIDR

Ensure subnet CIDR is within VPC CIDR range
Example: VPC 10.0.0.0/16, Subnet 10.0.1.0/24 ✓

Stack already exists

Use delete-vpc --force to remove existing stack
Or use show-changes to preview what would change
Or use different vpc_name_override

NAT Gateway requires Internet Gateway

Set internet_gateway.enabled: true
NAT Gateway needs IGW for outbound internet access

Permission denied

Check IAM permissions (see IAM_PERMISSIONS.md)
Verify AWS credentials are valid

License¶

This product requires a valid AWS Marketplace subscription.