API Reference

This section contains the complete API documentation auto-generated from source code docstrings.

Core Modules

VPC Manager

class vpc_provisioner.core.vpc_manager.VpcManager(config_file_name, action, dry_run=False, log_level='INFO', force=False, app_config=None)

Bases: object

Manages AWS VPC provisioning and lifecycle operations using CloudFormation.

This class provides comprehensive VPC infrastructure management for enterprise workloads, including multi-tier subnet architecture, NAT Gateway high availability, VPC Flow Logs, and Parameter Store integration for infrastructure outputs.

The VpcManager supports flexible network topologies with public, private, and isolated subnet tiers across multiple availability zones. It generates CloudFormation templates dynamically based on configuration and manages the complete VPC lifecycle from creation to deletion.

Key Features:

  • CloudFormation template generation for VPC infrastructure

  • Multi-tier subnet architecture (public, private, isolated)

  • Multi-AZ deployment with automatic subnet distribution

  • NAT Gateway high availability (single or per-AZ)

  • VPC Flow Logs with CloudWatch integration

  • Route table management with automatic associations

  • IAM policy generation for least-privilege access

  • Parameter Store integration for infrastructure outputs

  • Dry-run mode for safe testing

  • Force deletion with automatic cleanup

vpc_name

Name of the VPC being managed

Type:

str

region

AWS region for VPC deployment

Type:

str

action

Current action being performed

Type:

str

dry_run

If True, simulates operations without making changes

Type:

bool

force

If True, forces mutating AWS operations without confirmation

Type:

bool

vpc_stack_name

CloudFormation stack name for the VPC

Type:

str

cidr_block

CIDR block for the VPC (e.g., ‘10.0.0.0/16’)

Type:

str

enable_dns_hostnames

Enable DNS hostnames in VPC

Type:

bool

enable_dns_support

Enable DNS resolution in VPC

Type:

bool

enable_flow_logs

Enable VPC Flow Logs

Type:

bool

nat_gateway_mode

NAT Gateway deployment mode (‘single’ or ‘ha’)

Type:

str

subnets

List of subnet configurations

Type:

list

cf_client

Boto3 CloudFormation client

ec2_client

Boto3 EC2 client

ssm_client

Boto3 Systems Manager client

logger

Configured logger instance

Class Constants:

STACK_CREATE_WAITER_DELAY (int): Delay between stack creation checks (seconds) STACK_CREATE_WAITER_MAX_ATTEMPTS (int): Maximum stack creation wait attempts STACK_DELETE_WAITER_DELAY (int): Delay between stack deletion checks (seconds) STACK_DELETE_WAITER_MAX_ATTEMPTS (int): Maximum stack deletion wait attempts

Example

>>> from vpc_provisioner.core import VpcManager
>>> manager = VpcManager(
...     config_file_name='vpc-config.yaml',
...     action='create-vpc',
...     dry_run=False
... )
>>> exit_code = manager.execute()

Note

  • Requires valid AWS credentials with appropriate IAM permissions

  • Configuration file must pass JSON schema validation

  • VPC CIDR blocks must not overlap with existing VPCs

  • Use dry_run=True to preview changes before execution

  • NAT Gateways incur hourly charges and data transfer costs

STACK_CREATE_WAITER_DELAY = 10
STACK_CREATE_WAITER_MAX_ATTEMPTS = 60
STACK_DELETE_WAITER_DELAY = 10
STACK_DELETE_WAITER_MAX_ATTEMPTS = 60
DRIFT_POLL_INTERVAL = 10
DRIFT_POLL_TIMEOUT = 600
CHANGESET_POLL_INTERVAL = 5
CHANGESET_MAX_ATTEMPTS = 60
__init__(config_file_name, action, dry_run=False, log_level='INFO', force=False, app_config=None)

Initializes class members from config file and parameters.

Parameters:

  • config_file_name (str) – Name of the configuration file.

  • action (str) – Action to be performed.

  • dry_run (bool) – Dry run flag, if True no changes are made.

  • log_level (str) – Logging level for the operation.

  • force (bool) – If True, forces mutating AWS operations without confirmation.

  • app_config (AppConfig) – Application configuration object (AppConfig instance).

execute()

Executes the specified action on the VPC.

Returns:

0 for success, 1 for failure

Return type:

int

Configuration

Configuration Loader

class vpc_provisioner.config.loader.AppConfig(config_dict)

Bases: object

Application configuration with embedded defaults.

Loads configuration from YAML files and provides convenient access to configuration values with automatic path resolution.

Features:

  • Loads config from provided dictionary (from YAML)

  • Resolves directory paths to absolute paths

  • Provides access to config values via get() method with dot notation

  • Handles directory path resolution and validation

__init__(config_dict)

Initializes the config object with config dictionary.

Parameters:

config_dict (Dict[str, Any]) – Configuration dictionary loaded from YAML.

get(key_path, default=None)

Gets a config value using dot notation.

Parameters:

  • key_path (str) – Dot-separated path (e.g., ‘directories.configs_dir’)

  • default (Any) – Default value if key not found

Returns:

Config value or default

Return type:

Any

get_directory(dir_name)

Gets a directory path as a Path object.

Parameters:

dir_name (str) – Directory name (configs_dir, reports_dir, etc.)

Returns:

Path object

Return type:

Path

Raises:

ValueError – If directory not configured

vpc_provisioner.config.loader.load_app_config(custom_config_path=None)

Loads and returns application configuration.

Resolution order: 1. Custom config file (if provided via –app-config) 2. Embedded default config (always available)

Parameters:

custom_config_path (Optional[str]) – Optional path to custom config file

Returns:

AppConfig instance

Return type:

AppConfig

Raises:

Utilities

HTML Generator

HTML documentation generator for VPC provisioning.

Provides two report types:

vpc_provisioner.utils.html_generator.generate_template_documentation(config_file, template_file, cfn_template, output_path)

Generate HTML documentation for CloudFormation template.

Parameters:

  • config_file (str) – Path to configuration YAML file.

  • template_file (str) – Path to generated CloudFormation template.

  • cfn_template (Dict[str, Any]) – Parsed CloudFormation template dictionary.

  • output_path (str) – Path where HTML file should be saved.

Returns:

Path to generated HTML file.

Return type:

str

vpc_provisioner.utils.html_generator.generate_deployment_documentation(config_file, stack_name, region, stack_info, output_path)

Generate HTML documentation for VPC deployment.

Parameters:

  • config_file (str) – Path to configuration YAML file.

  • stack_name (str) – CloudFormation stack name.

  • region (str) – AWS region.

  • stack_info (Dict[str, Any]) – Stack information from describe_stacks.

  • output_path (str) – Path where HTML file should be saved.

Returns:

Path to generated HTML file.

Return type:

str

vpc_provisioner.utils.html_generator.generate_cost_report(vpc_name, region, config_file, cost_result, traffic_data, pricing_source, output_path)

Generate HTML cost estimation report for a VPC deployment.

Produces a professional HTML document with two cost tables:

  • Fixed Costs — Hourly resources grouped by type with count and unit cost.

  • Usage-Based Costs — Traffic-based resources with assumed usage and per-GB rate.

Includes a summary box with monthly/annual totals and a note about free resources (VPC, subnets, route tables, etc.).

Parameters:

  • vpc_name (str) – Name of the VPC (e.g., 'techcorp-prod-a001-us-west-2-vpc').

  • region (str) – AWS region code (e.g., 'us-west-2').

  • config_file (str) – Path to the VPC configuration YAML file.

  • cost_result (Dict[str, Any]) – Cost breakdown dictionary from calculate(), containing breakdown, total_fixed_monthly, total_variable_monthly, total_monthly, total_annual, and strategy.

  • traffic_data (Dict[str, Any]) – Traffic assumptions dict keyed by resource name, each value containing data_gb_per_month.

  • pricing_source (str) – Description of the pricing source (e.g., 'vpc-pricing.yaml (us-west-2)' or 'fallback rates').

  • output_path (str) – Filesystem path where the HTML file should be saved.

Returns:

Path to the generated HTML file.

Return type:

str

Raises:

License

License Validator

class vpc_provisioner.license.validator.LicenseValidator

Bases: object

Validates product licenses against the AWS Marketplace License Manager.

This class handles the end-to-end license verification workflow, including secure communication with AWS APIs to confirm customer entitlements. To optimize performance and minimize latency, it employs an in-memory caching mechanism, reducing API calls for frequently validated tokens or customers.

product_sku

AWS Marketplace product sku to validate against.

Type:

str

region

AWS region for the Marketplace API.

Type:

str

license_client

Boto3 client for AWS Marketplace License Manager.

key_fingerprint

The fingerprint of the public key used for license validation.

entitlement_name

The name of the entitlement to check for in the AWS License Manager.

license_cache_file

Path to the local cache file.

Type:

str

cache_duration

Duration for which the cache is considered valid (hours).

Type:

timedelta

Integration Workflow:

  1. Checks cache for active, unexpired validation result.

  2. If missing/expired, calls CheckoutLicense API.

  3. Validates product SKU and entitlement status.

  4. Updates cache and returns validation status.

__init__()

Initialize the LicenseValidator with AWS Marketplace configuration.

Reads configuration from environment variables and sets up the AWS License Manager Client for license validation.

Environment Variables:

MARKETPLACE_PRODUCT_SKU: AWS Marketplace product SKU (required for validation) AWS_REGION: AWS region for Marketplace API (default: ‘us-east-1’)

verify_aws_marketplace_subscription()

Validate AWS Marketplace subscription via License Manager CheckoutLicense API.

Returns:

True if valid license, False otherwise

Return type:

bool

CLI Interface

class vpc_provisioner.cli.VpcProvisionerCLI

Bases: BaseCLI

CLI for VPC Provisioner Tool.

Extends BaseCLI to implement VPC-specific actions and arguments. Supports 9 actions grouped by safety level:

  • Local: validate-config, create-policy, create-prov-template, validate-prov-template

  • Read-only: show-changes, check-drift

  • Mutating: test-deploy, create-vpc, delete-vpc

Includes AWS Marketplace license validation before executing any actions.

__init__()

Initialize the VPC Provisioner CLI.

is_action_required()

Determine if an action argument is required for this CLI.

Return type:

bool

Returns:

Always True for this CLI

get_actions()

Return the list of valid actions for the VPC Provisioner CLI.

Return type:

List[str]

Returns:

List of action strings

get_actions_help()

Return help text describing all available actions.

Return type:

str

Returns:

Formatted help text for all VPC actions

get_manager_class()

Return the manager class for this CLI.

Return type:

Type[Any]

Returns:

VpcManager class reference

get_example_usage()

Return example usage instructions.

Detects Docker environment via /.dockerenv or /proc/1/cgroup and adjusts command examples accordingly.

Return type:

str

Returns:

Example usage string with Docker or native CLI commands

add_custom_arguments(parser)

Add VPC Provisioner-specific CLI arguments.

Parameters:

parser (Any) – The argparse parser to add arguments to.

Return type:

None

create_manager_instance(args)

Create a new VpcManager instance.

Parameters:

args (argparse.Namespace) – Parsed command-line arguments.

Returns:

Instance initialized with CLI arguments and app config.

Return type:

VpcManager

requires_force(action)

Determine if an action requires the --force flag.

Parameters:

action (str) – The action being performed.

Returns:

True for mutating AWS operations (create-vpc, delete-vpc).

Return type:

bool

vpc_provisioner.cli.main()

Entry point for VPC Provisioner CLI.

Validates AWS Marketplace license before running the CLI. Exits with code 1 if license validation fails.