(BREAKING) Enhancement - Custom VPC Subnets

packages/@aws-cdk/ec2/lib/network-util.ts

@@ -86,4 +86,154 @@ export class NetworkUtils {
 
     }
 
+    public static validIp(ipAddress: string): boolean {
+        return ipAddress.split('.').map((octet: string) => parseInt(octet, 10)).
+            filter((octet: number) => octet >= 0 && octet <= 255).length === 4;
+    }
+    /**
+     *
+     * takes an IP Address (e.g. 174.66.173.168) and converts to a number
+     * (e.g 2923605416); currently only supports IPv4
+     *
+     * Uses the formula:
+     * (first octet * 256³) + (second octet * 256²) + (third octet * 256) +
+     * (fourth octet)
+     *
+     * @param  {string} the IP address (e.g. 174.66.173.168)
+     * @returns {number} the integer value of the IP address (e.g 2923605416)
+     */
+
+    public static ipToNum(ipAddress: string): number {
+        if (!this.validIp(ipAddress)) {
+            throw new Error(`${ipAddress} is not valid`);
+        }
+
+        return ipAddress
+            .split('.')
+            .reduce(
+                (p: number, c: string, i: number) => p + parseInt(c, 10) * 256 ** (3 - i),
+                0
+            );
+    }
+
+    /**
+     *
+     * Takes a number (e.g 2923605416) and converts it to an IPv4 address string
+     * currently only supports IPv4
+     *
+     * @param  {number} the integer value of the IP address (e.g 2923605416)
+     * @returns {string} the IPv4 address (e.g. 174.66.173.168)
+     */
+
+    public static numToIp(ipNum: number): string {
+        // this all because bitwise math is signed
+        let remaining = ipNum;
+        const address = [];
+        for (let i = 0; i < 4; i++) {
+            if (remaining !== 0) {
+                address.push(Math.floor(remaining / 256 ** (3 - i)));
+                remaining = remaining % 256 ** (3 - i);
+            } else {
+                address.push(0);
+            }
+        }
+        const ipAddress: string = address.join('.');
+        if ( !this.validIp(ipAddress) ) {
+            throw new Error(`${ipAddress} is not a valid IP Address`);
+        }
+        return ipAddress;
+    }
+
+}
+
+export class NetworkBuilder {
+    public readonly networkCidr: CidrBlock;
+    protected subnetCidrs: CidrBlock[];
+    protected maxIpConsumed: string;
+
+    constructor(cidr: string) {
+        this.networkCidr = new CidrBlock(cidr);
+        this.subnetCidrs = [];
+        this.maxIpConsumed = NetworkUtils.numToIp(NetworkUtils.
+            ipToNum(this.networkCidr.minIp()) - 1);
+    }
+
+    public addSubnet(mask: number): string {
+        return this.addSubnets(mask, 1)[0];
+    }
+
+    public addSubnets(mask: number, count?: number): string[] {
+        if (mask < 16 || mask > 28) {
+            throw new InvalidCidrRangeError(`x.x.x.x/${mask}`);
+        }
+        const subnets: CidrBlock[] = [];
+        if (!count) {
+            count = 1;
+        }
+        for (let i = 0; i < count; i ++) {
+            const subnet: CidrBlock = CidrBlock.fromOffsetIp(this.maxIpConsumed, mask);
+            this.maxIpConsumed = subnet.maxIp();
+            this.subnetCidrs.push(subnet);
+            if (!this.validate()) {
+                throw new Error(`${this.networkCidr.cidr} does not fully contain ${subnet.cidr}`);
+            }
+            subnets.push(subnet);
+        }
+        return subnets.map((subnet) => (subnet.cidr));
+    }
+
+    public get subnets(): string[] {
+        return this.subnetCidrs.map((subnet) => (subnet.cidr));
+    }
+
+    public validate(): boolean {
+        return this.subnetCidrs.map(
+            (cidrBlock) => this.networkCidr.containsCidr(cidrBlock)).
+            filter( (contains) => (contains === false)).length === 0;
+    }
+
+}
+
+export class CidrBlock {
+
+    public static calculateNetmask(mask: number): string {
+        return NetworkUtils.numToIp(2 ** 32 - 2 ** (32 - mask));
+    }
+
+    public static fromOffsetIp(ipAddress: string, mask: number): CidrBlock {
+        const initialCidr = new CidrBlock(`${ipAddress}/${mask}`);
+        const baseIpNum = NetworkUtils.ipToNum(initialCidr.maxIp()) + 1;
+        return new this(`${NetworkUtils.numToIp(baseIpNum)}/${mask}`);
+    }
+
+    public readonly cidr: string;
+    public readonly netmask: string;
+    public readonly mask: number;
+
+    constructor(cidr: string) {
+        this.cidr = cidr;
+        this.mask = parseInt(cidr.split('/')[1], 10);
+        this.netmask = CidrBlock.calculateNetmask(this.mask);
+    }
+
+    public maxIp(): string {
+        const minIpNum = NetworkUtils.ipToNum(this.minIp());
+        return NetworkUtils.numToIp(minIpNum + 2 ** (32 - this.mask) - 1);
+    }
+
+    public minIp(): string {
+        const netmaskOct = this.netmask.split('.');
+        const ipOct = this.cidr.split('/')[0].split('.');
+        // tslint:disable:no-bitwise
+        return netmaskOct.map(
+            (maskOct, index) => parseInt(maskOct, 10) & parseInt(ipOct[index], 10)).join('.');
+        // tslint:enable:no-bitwise
+    }
+
+    public containsCidr(cidr: CidrBlock): boolean {
+        return [
+            NetworkUtils.ipToNum(this.minIp()) <= NetworkUtils.ipToNum(cidr.minIp()),
+            NetworkUtils.ipToNum(this.maxIp()) >= NetworkUtils.ipToNum(cidr.maxIp()),
+        ].filter((contains) => (contains === false)).length === 0;
+    }
 }

packages/@aws-cdk/ec2/lib/vpc.ts

@@ -1,6 +1,7 @@
 import { AvailabilityZoneProvider, Construct, Tag, Token } from '@aws-cdk/core';
 import { ec2 } from '@aws-cdk/resources';
-import { NetworkUtils } from './network-util';
+import { Obj } from '@aws-cdk/util';
+import { NetworkBuilder, NetworkUtils } from './network-util';
 import { VpcNetworkId, VpcNetworkRef, VpcSubnetId, VpcSubnetRef } from './vpc-ref';
 /**
  * VpcNetworkProps allows you to specify configuration options for a VPC
@@ -58,6 +59,33 @@ export interface VpcNetworkProps {
      * @default All AZs in the region
      */
     maxAZs?: number;
+
+    /**
+     * Configure the subnets to build for each AZ
+     *
+     * The subnets are constructed in the context of the VPC so you only need
+     * specify the configuration. The VPC details (VPC ID, specific CIDR,
+     * specific AZ will be calculated during creation)
+     *
+     * For example if you want three private subnets and three public subnets
+     * across 3 AZs then maxAZs = 3 and provide the following:
+     * subnets: [
+     * {
+     *   cidrMask: 24,
+     *   name: ingress,
+     *   subnetType: SubnetType.Public,
+     *   natGateway: true,
+     * },
+     * {
+     *   cidrMask: 24,
+     *   name: application,
+     *   subnetType: SubnetType.Private,
+     * }
+     * ]
+     * @default the VPC CIDR will be evenly divided between 1 public and 1
+     * private subnet per AZ
+     */
+    subnetConfigurations?: SubnetConfiguration[];
 }
 
 /**
@@ -142,6 +170,11 @@ export class VpcNetwork extends VpcNetworkRef {
      */
     public readonly privateSubnets: VpcSubnetRef[] = [];
 
+    /**
+     * List of internal subnets in this VPC
+     */
+    public readonly internalSubnets: VpcSubnetRef[] = [];
+
     /**
      * The VPC resource
      */
@@ -185,7 +218,7 @@ export class VpcNetwork extends VpcNetworkRef {
             outboundTraffic === OutboundTrafficMode.FromPublicAndPrivateSubnets;
 
         // Create public and private subnets in each AZ
-        this.createSubnets(cidrBlock, outboundTraffic, props.maxAZs);
+        this.createSubnets(cidrBlock, outboundTraffic, props.maxAZs, props.subnetConfigurations);
 
         // Create an Internet Gateway and attach it (if the outbound traffic mode != None)
         if (allowOutbound) {
@@ -213,7 +246,11 @@ export class VpcNetwork extends VpcNetworkRef {
      * createSubnets takes a VPC, and creates a public and private subnet
      * in each Availability Zone.
      */
-    private createSubnets(cidr: string, outboundTraffic: OutboundTrafficMode, maxAZs?: number) {
+    private createSubnets(
+      cidr: string,
+      outboundTraffic: OutboundTrafficMode,
+      maxAZs?: number,
+      subnets?: SubnetConfiguration[]) {
 
         // Calculate number of public/private subnets based on number of AZs
         const zones = new AvailabilityZoneProvider(this).availabilityZones;
@@ -224,11 +261,16 @@ export class VpcNetwork extends VpcNetworkRef {
             zones.splice(maxAZs);
         }
 
-        // Split the CIDR range into each availablity zone
-        const ranges = NetworkUtils.splitCIDR(cidr, zones.length);
+        if (subnets != null) {
+          const networkBuilder = new NetworkBuilder(cidr);
+          this.createCustomSubnets(networkBuilder, subnets, zones);
+        } else {
+          // Split the CIDR range into each availablity zone
+          const ranges = NetworkUtils.splitCIDR(cidr, zones.length);
 
-        for (let i = 0; i < zones.length; i++) {
+          for (let i = 0; i < zones.length; i++) {
             this.createSubnetPair(ranges[i], zones[i], i + 1, outboundTraffic);
+          }
         }
 
     }
@@ -263,9 +305,114 @@ export class VpcNetwork extends VpcNetworkRef {
         this.privateSubnets.push(privateSubnet);
         this.dependencyElements.push(publicSubnet, privateSubnet);
     }
+    private createCustomSubnets(builder: NetworkBuilder, subnets: SubnetConfiguration[], zones: string[]) {
+
+      const natGatewayByAZ: Obj<Token> = {};
+
+      for (const subnet of subnets) {
+        let azs = zones;
+        if (subnet.numAZs != null) {
+          azs = zones.slice(subnet.numAZs);
+        }
+        for (const zone of azs) {
+          const cidr: string = builder.addSubnet(subnet.cidrMask);
+          const name: string = `${subnet.name}AZ${zone.substr(-1)}`;
+          switch (subnet.subnetType) {
+            case SubnetType.Public:
+              const publicSubnet = new VpcPublicSubnet(this, name, {
+                  mapPublicIpOnLaunch: subnet.mapPublicIpOnLaunch || true,
+                  vpcId: this.vpcId,
+                  availabilityZone: zone,
+                  cidrBlock: cidr
+              });
+              if (subnet.natGateway) {
+                natGatewayByAZ[zone] = publicSubnet.addNatGateway();
+              }
+              this.publicSubnets.push(publicSubnet);
+              break;
+            case SubnetType.Private:
+              const privateSubnet = new VpcPrivateSubnet(this, name, {
+                  mapPublicIpOnLaunch: subnet.mapPublicIpOnLaunch || false,
+                  vpcId: this.vpcId,
+                  availabilityZone: zone,
+                  cidrBlock: cidr
+              });
+              this.privateSubnets.push(privateSubnet);
+              break;
+            case SubnetType.Internal:
+              const internalSubnet = new VpcPrivateSubnet(this, name, {
+                  mapPublicIpOnLaunch: subnet.mapPublicIpOnLaunch || false,
+                  vpcId: this.vpcId,
+                  availabilityZone: zone,
+                  cidrBlock: cidr
+              });
+              this.internalSubnets.push(internalSubnet);
+              break;
+          }
+        }
+      }
+      (this.privateSubnets as VpcPrivateSubnet[]).forEach((privateSubnet, i) => {
+        let ngwId = natGatewayByAZ[privateSubnet.availabilityZone];
+        if (ngwId === undefined) {
+          const ngwArray = Array.from(Object.values(natGatewayByAZ));
+          ngwId = ngwArray[i % ngwArray.length];
+        }
+        privateSubnet.addDefaultNatRouteEntry(ngwId);
+      });
+    }
 
 }
 
+/**
+ * The type of Subnet
+ */
+export enum SubnetType {
+
+    /**
+     * Internal Subnets do not route Outbound traffic
+     *
+     * This can be good for subnets with RDS or
+     * Elasticache endpoints
+     */
+    Internal = 1,
+
+    /**
+     * Public subnets route outbound traffic via an Internet Gateway
+     *
+     * If this is set and OutboundTrafficMode.None is configure an error
+     * will be thrown.
+     */
+    Public = 2,
+
+    /**
+     * Private subnets route outbound traffic via a NAT Gateway
+     *
+     * Outbound traffic will be routed via a NAT Gateways preference being in
+     * the same AZ, but if not available will use another AZ. This is common for
+     * experimental cost conscious accounts or accounts where HA outbound
+     * traffic is not needed.
+     */
+    Private = 3
+}
+
+/**
+ * Specify configuration parameters for a VPC to be built
+ */
+export interface SubnetConfiguration {
+    // the cidr mask value from 16-28
+    cidrMask: number;
+    // Public (IGW), Private (Nat GW), Internal (no outbound)
+    subnetType: SubnetType;
+    // name that will be used to generate an AZ specific name e.g. name-2a
+    name: string;
+    // if true will place a NAT Gateway in this subnet, subnetType must be Public
+    natGateway?: boolean;
+    // defaults to true in Subnet.Public, false in Subnet.Private or Subnet.Internal
+    mapPublicIpOnLaunch?: boolean;
+    // number of AZs to build this subnet in
+    numAZs?: number;
+}
+
 /**
  * Specify configuration parameters for a VPC subnet
  */