# VPC Deployment Guide Deploy production-ready VPCs with `spicyVPC`. ## Minimal Setup ```groovy @Library(["spicy-automation@main"]) _ spicyVPC( jenkinsAwsCredentialsId: "aws-credentials", region: "ca-central-1", stackName: "my-vpc", ownerTag: "MyTeam", productTag: "myproduct", componentTag: "vpc", ) ``` This creates a VPC with all defaults - see [What Gets Created](#what-gets-created). ## Full Configuration ```groovy @Library(["spicy-automation@main"]) _ spicyVPC( // Required jenkinsAwsCredentialsId: "aws-credentials", region: "ca-central-1", stackName: "production-vpc", ownerTag: "Platform", productTag: "myapp", componentTag: "network", // Optional - VPC Configuration vpcCidr: "10.0.0.0/16", // Default: 172.1.0.0/16 vpcTenancy: "default", // default | dedicated numberOfAzs: 4, // 2, 3, or 4 availabilityZones: "ca-central-1a,ca-central-1b,ca-central-1c,ca-central-1d", // Optional - Subnet Creation createPrivateSubnets: true, // Default: true createAdditionalPrivateSubnets: true, // Default: true (creates NACL-protected subnets) // Optional - Subnet Tags publicSubnetTag: "Network=Public", privateSubnetATag: "Network=Private", privateSubnetBTag: "Network=Private", // Optional - Custom CIDRs (see Custom CIDR Configuration below) // Optional - Pipeline Behavior showDiff: true, // Show diff before deploy (default: true) showDiffOnPR: true, // Show diff on non-main branches (default: true) // Optional - Hooks onPreDeploy: { args, ctx -> }, // Called before deployment onPostDeploy: { args, ctx -> }, // Called after deployment ) ``` ## Parameters Reference ### Required Parameters | Parameter | Type | Description | | ------------------------- | ------ | ------------------------------------------------------------- | | `jenkinsAwsCredentialsId` | string | Jenkins credential ID for AWS access | | `region` | string | AWS region (e.g., `ca-central-1`) | | `stackName` | string | CloudFormation stack name (must be unique per account/region) | | `ownerTag` | string | Owner tag applied to all resources | | `productTag` | string | Product tag applied to all resources | | `componentTag` | string | Component tag applied to all resources | ### VPC Configuration | Parameter | Type | Default | Description | | ------------------- | ------ | -------------- | ------------------------------------------- | | `vpcCidr` | string | `172.1.0.0/16` | VPC CIDR block | | `vpcTenancy` | string | `default` | Instance tenancy (`default` or `dedicated`) | | `numberOfAzs` | number | `4` | Number of availability zones (2, 3, or 4) | | `availabilityZones` | string | auto | Comma-separated AZ list | ### Subnet Configuration | Parameter | Type | Default | Description | | -------------------------------- | ------- | ------- | ------------------------------------------- | | `createPrivateSubnets` | boolean | `true` | Create private subnets with NAT Gateways | | `createAdditionalPrivateSubnets` | boolean | `true` | Create secondary private subnets with NACLs | ### Subnet Tags | Parameter | Type | Default | Description | | ------------------- | ------ | ----------------- | --------------------------------- | | `publicSubnetTag` | string | `Network=Public` | Tag for public subnets | | `privateSubnetATag` | string | `Network=Private` | Tag for primary private subnets | | `privateSubnetBTag` | string | `Network=Private` | Tag for secondary private subnets | ## What Gets Created With default settings, `spicyVPC` creates: ### Network Resources - **1 VPC** with DNS hostnames and DNS support enabled - **1 Internet Gateway** attached to the VPC - **DHCP Options** configured for the region ### Public Subnets (4 AZs) - 4 public subnets (one per AZ) - 1 shared public route table with route to Internet Gateway - Auto-assign public IP enabled ### Private Subnets Type 1 (4 AZs) - 4 private subnets (one per AZ) - 4 NAT Gateways (one per AZ) with Elastic IPs - 4 route tables with routes to NAT Gateways ### Private Subnets Type 2 (4 AZs) - 4 additional private subnets (one per AZ) - 4 Network ACLs (allow all by default, customizable) - 4 route tables with routes to NAT Gateways ### VPC Endpoints - S3 Gateway Endpoint (free, attached to all private route tables) ## Default CIDR Blocks | Subnet | AZ A | AZ B | AZ C | AZ D | | --------- | -------------- | -------------- | -------------- | -------------- | | Public | 172.1.128.0/20 | 172.1.144.0/20 | 172.1.160.0/20 | 172.1.176.0/20 | | Private 1 | 172.1.0.0/19 | 172.1.32.0/19 | 172.1.64.0/19 | 172.1.96.0/19 | | Private 2 | 172.1.192.0/21 | 172.1.200.0/21 | 172.1.208.0/21 | 172.1.216.0/21 | ## Custom CIDR Configuration Override individual subnet CIDRs: ```groovy spicyVPC( // ... required params ... // Public subnets publicSubnetACidr: "10.0.0.0/20", publicSubnetBCidr: "10.0.16.0/20", publicSubnetCCidr: "10.0.32.0/20", publicSubnetDCidr: "10.0.48.0/20", // Private subnets (type 1) privateSubnetA1Cidr: "10.0.64.0/19", privateSubnetB1Cidr: "10.0.96.0/19", privateSubnetC1Cidr: "10.0.128.0/19", privateSubnetD1Cidr: "10.0.160.0/19", // Private subnets (type 2, with NACLs) privateSubnetA2Cidr: "10.0.192.0/21", privateSubnetB2Cidr: "10.0.200.0/21", privateSubnetC2Cidr: "10.0.208.0/21", privateSubnetD2Cidr: "10.0.216.0/21", ) ``` ## CloudFormation Outputs The stack exports these values for cross-stack references: | Export Name | Description | | --------------------------------------- | ------------------------- | | `{stackName}-VPCID` | VPC ID | | `{stackName}-VPCCIDR` | VPC CIDR block | | `{stackName}-PublicSubnetAID` | Public Subnet A ID | | `{stackName}-PublicSubnetBID` | Public Subnet B ID | | `{stackName}-PublicSubnetCID` | Public Subnet C ID | | `{stackName}-PublicSubnetDID` | Public Subnet D ID | | `{stackName}-PrivateSubnetA1ID` | Private Subnet A1 ID | | `{stackName}-PrivateSubnetB1ID` | Private Subnet B1 ID | | `{stackName}-PrivateSubnetC1ID` | Private Subnet C1 ID | | `{stackName}-PrivateSubnetD1ID` | Private Subnet D1 ID | | `{stackName}-PrivateSubnetA2ID` | Private Subnet A2 ID | | `{stackName}-PrivateSubnetB2ID` | Private Subnet B2 ID | | `{stackName}-PrivateSubnetC2ID` | Private Subnet C2 ID | | `{stackName}-PrivateSubnetD2ID` | Private Subnet D2 ID | | `{stackName}-NATZoneAEIP` | NAT Gateway A Elastic IP | | `{stackName}-NATZoneBEIP` | NAT Gateway B Elastic IP | | `{stackName}-NATZoneCEIP` | NAT Gateway C Elastic IP | | `{stackName}-NATZoneDEIP` | NAT Gateway D Elastic IP | | `{stackName}-PublicSubnetRouteTable` | Public Route Table ID | | `{stackName}-PrivateSubnetA1RouteTable` | Private A1 Route Table ID | | `{stackName}-PrivateSubnetB1RouteTable` | Private B1 Route Table ID | | `{stackName}-PrivateSubnetC1RouteTable` | Private C1 Route Table ID | | `{stackName}-PrivateSubnetD1RouteTable` | Private D1 Route Table ID | ## Using Account Configurations For multi-environment deployments: ```groovy @Library(["spicy-automation@main"]) _ def account = accounts.get().SPICY_CA_CENRAL_1_PROD spicyVPC( jenkinsAwsCredentialsId: account.jenkinsAwsCredentialsId, region: account.region, accountId: account.accountId, stackName: "production-vpc", ownerTag: "Platform", productTag: "spicy", componentTag: "vpc", ) ``` ## Pipeline Hooks ### Pre-Deploy Hook ```groovy spicyVPC( // ... params ... onPreDeploy: { args, ctx -> echo "About to deploy ${args.stackName}" // Run custom validation, notifications, etc. } ) ``` ### Post-Deploy Hook ```groovy spicyVPC( // ... params ... onPostDeploy: { args, ctx -> echo "Deployed stack: ${ctx.stackName}" // Update DNS, notify Slack, etc. } ) ``` ## Examples ### Development VPC (2 AZs, No NACL Subnets) ```groovy spicyVPC( jenkinsAwsCredentialsId: "aws-dev", region: "ca-central-1", stackName: "dev-vpc", ownerTag: "Dev", productTag: "myapp", componentTag: "vpc", numberOfAzs: 2, createAdditionalPrivateSubnets: false, ) ``` ### Production VPC (Full HA) ```groovy spicyVPC( jenkinsAwsCredentialsId: "aws-prod", region: "ca-central-1", stackName: "prod-vpc", ownerTag: "Platform", productTag: "myapp", componentTag: "vpc", vpcCidr: "10.0.0.0/16", numberOfAzs: 4, createPrivateSubnets: true, createAdditionalPrivateSubnets: true, ) ``` ### Public-Only VPC (No NAT Gateways) ```groovy spicyVPC( jenkinsAwsCredentialsId: "aws-credentials", region: "ca-central-1", stackName: "public-vpc", ownerTag: "Dev", productTag: "myapp", componentTag: "vpc", createPrivateSubnets: false, ) ``` ## Local Testing Test VPC synthesis locally: ```bash cd spicy-automation # Synthesize with minimal config npx cdk synth \ -c stackType=vpc \ -c stackName=test-vpc \ -c ownerTag=Test \ -c productTag=test \ -c componentTag=vpc # With custom options npx cdk synth \ -c stackType=vpc \ -c stackName=test-vpc \ -c ownerTag=Test \ -c productTag=test \ -c componentTag=vpc \ -c vpcCidr=10.0.0.0/16 \ -c numberOfAzs=2 \ -c createAdditionalPrivateSubnets=false ```