feat(ec2): user-defined subnet selectors

packages/@aws-cdk/aws-ec2/README.md

@@ -163,6 +163,8 @@ Which subnets are selected is evaluated as follows:
     in the given availability zones will be returned.
   * `onePerAz`: per availability zone, a maximum of one subnet will be returned (Useful for resource
     types that do not allow creating two ENIs in the same availability zone).
+* `subnetFilters`: additional filtering on subnets using any number of user-provided filters which
+  implement the ISubnetSelector interface.
 
 ### Using NAT instances
 

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

@@ -10,6 +10,7 @@ export * from './network-acl';
 export * from './network-acl-types';
 export * from './port';
 export * from './security-group';
+export * from './subnet';
 export * from './peer';
 export * from './volume';
 export * from './vpc';

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

@@ -0,0 +1,88 @@
+import { CidrBlock, NetworkUtils } from './network-util';
+import { ISubnet } from './vpc';
+
+/**
+ * Contains logic which chooses a set of subnets from a larger list, in conjunction
+ * with SubnetSelection, to determine where to place AWS resources such as VPC
+ * endpoints, EC2 instances, etc.
+ */
+export interface ISubnetSelector {
+
+  /**
+   * Executes the subnet filtering logic, returning a filtered set of subnets.
+   */
+  selectSubnets(subnets: ISubnet[]): ISubnet[];
+}
+
+/**
+ * Chooses subnets which are in one of the given availability zones.
+ */
+export class AvailabilityZoneSubnetSelector implements ISubnetSelector {
+
+  private readonly availabilityZones: string[];
+
+  constructor(availabilityZones: string[]) {
+    this.availabilityZones = availabilityZones;
+  }
+
+  /**
+   * Executes the subnet filtering logic.
+   */
+  public selectSubnets(subnets: ISubnet[]): ISubnet[] {
+    return subnets.filter(s => this.availabilityZones.includes(s.availabilityZone));
+  }
+}
+
+/**
+ * Chooses subnets such that there is at most one per availability zone.
+ */
+export class OnePerAZSubnetSelector implements ISubnetSelector {
+
+  constructor() {}
+
+  /**
+   * Executes the subnet filtering logic.
+   */
+  public selectSubnets(subnets: ISubnet[]): ISubnet[] {
+    return this.retainOnePerAz(subnets);
+  }
+
+  private retainOnePerAz(subnets: ISubnet[]): ISubnet[] {
+    const azsSeen = new Set<string>();
+    return subnets.filter(subnet => {
+      if (azsSeen.has(subnet.availabilityZone)) { return false; }
+      azsSeen.add(subnet.availabilityZone);
+      return true;
+    });
+  }
+}
+
+/**
+ * Chooses subnets which contain any of the specified IP addresses.
+ */
+export class ContainsIpAddressesSubnetSelector implements ISubnetSelector {
+
+  private readonly ipAddresses: string[];
+
+  constructor(ipAddresses: string[]) {
+    this.ipAddresses = ipAddresses;
+  }
+
+  /**
+   * Executes the subnet filtering logic.
+   */
+  public selectSubnets(subnets: ISubnet[]): ISubnet[] {
+    return this.retainByIp(subnets, this.ipAddresses);
+  }
+
+  private retainByIp(subnets: ISubnet[], ips: string[]): ISubnet[] {
+    const cidrBlockObjs = ips.map(ip => {
+      const ipNum = NetworkUtils.ipToNum(ip);
+      return new CidrBlock(ipNum, 32);
+    });
+    return subnets.filter(s => {
+      const subnetCidrBlock = new CidrBlock(s.ipv4CidrBlock);
+      return cidrBlockObjs.some(cidr => subnetCidrBlock.containsCidr(cidr));
+    });
+  }
+}

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

@@ -1,7 +1,7 @@
 import * as cxschema from '@aws-cdk/cloud-assembly-schema';
 import {
-  ConcreteDependable, Construct, ContextProvider, DependableTrait, IConstruct,
-  IDependable, IResource, Lazy, Resource, Stack, Token, Tags,
+  Annotations, ConcreteDependable, Construct, ContextProvider, DependableTrait,
+  IConstruct, IDependable, IResource, Lazy, Resource, Stack, Token, Tags,
 } from '@aws-cdk/core';
 import * as cxapi from '@aws-cdk/cx-api';
 import {
@@ -11,6 +11,7 @@ import {
 import { NatProvider } from './nat';
 import { INetworkAcl, NetworkAcl, SubnetNetworkAclAssociation } from './network-acl';
 import { NetworkBuilder } from './network-util';
+import { AvailabilityZoneSubnetSelector, OnePerAZSubnetSelector, ISubnetSelector } from './subnet';
 import { allRouteTableIds, defaultSubnetName, flatten, ImportSubnetGroup, subnetGroupNameFromConstructId, subnetId } from './util';
 import { GatewayVpcEndpoint, GatewayVpcEndpointAwsService, GatewayVpcEndpointOptions, InterfaceVpcEndpoint, InterfaceVpcEndpointOptions } from './vpc-endpoint';
 import { FlowLog, FlowLogOptions, FlowLogResourceType } from './vpc-flow-logs';
@@ -36,6 +37,11 @@ export interface ISubnet extends IResource {
    */
   readonly internetConnectivityEstablished: IDependable;
 
+  /**
+   * The IPv4 CIDR block for this subnet
+   */
+  readonly ipv4CidrBlock: string;
+
   /**
    * The route table for this subnet
    */
@@ -236,6 +242,13 @@ export interface SubnetSelection {
    */
   readonly onePerAz?: boolean;
 
+  /**
+   * List of provided subnet filters.
+   *
+   * @default - none
+   */
+  readonly subnetFilters?: ISubnetSelector[];
+
   /**
    * Explicitly select individual subnets
    *
@@ -460,17 +473,21 @@ abstract class VpcBase extends Resource implements IVpc {
       subnets = this.selectSubnetObjectsByType(type);
     }
 
-    if (selection.availabilityZones !== undefined) { // Filter by AZs, if specified
-      subnets = retainByAZ(subnets, selection.availabilityZones);
-    }
-
-    if (!!selection.onePerAz && subnets.length > 0) { // Ensure one per AZ if specified
-      subnets = retainOnePerAz(subnets);
-    }
+    // Apply all the filters
+    subnets = this.applySubnetFilters(subnets, selection.subnetFilters ?? []);
 
     return subnets;
   }
 
+  private applySubnetFilters(subnets: ISubnet[], filters: ISubnetSelector[]): ISubnet[] {
+    let filtered = subnets;
+    // Apply each filter in sequence
+    for (const filter of filters) {
+      filtered = filter.selectSubnets(filtered);
+    }
+    return filtered;
+  }
+
   private selectSubnetObjectsByName(groupName: string) {
     const allSubnets = [...this.publicSubnets, ...this.privateSubnets, ...this.isolatedSubnets];
     const subnets = allSubnets.filter(s => subnetGroupNameFromConstructId(s) === groupName);
@@ -510,9 +527,12 @@ abstract class VpcBase extends Resource implements IVpc {
    * PUBLIC (in that order) that has any subnets.
    */
   private reifySelectionDefaults(placement: SubnetSelection): SubnetSelection {
+
     if (placement.subnetName !== undefined) {
       if (placement.subnetGroupName !== undefined) {
         throw new Error('Please use only \'subnetGroupName\' (\'subnetName\' is deprecated and has the same behavior)');
+      } else {
+        Annotations.of(this).addWarning('Usage of \'subnetName\' in SubnetSelection is deprecated, use \'subnetGroupName\' instead');
       }
       placement = { ...placement, subnetGroupName: placement.subnetName };
     }
@@ -525,42 +545,26 @@ abstract class VpcBase extends Resource implements IVpc {
 
     if (placement.subnetType === undefined && placement.subnetGroupName === undefined && placement.subnets === undefined) {
       // Return default subnet type based on subnets that actually exist
-      if (this.privateSubnets.length > 0) {
-        return {
-          subnetType: SubnetType.PRIVATE,
-          onePerAz: placement.onePerAz,
-          availabilityZones: placement.availabilityZones,
-        };
-      }
-      if (this.isolatedSubnets.length > 0) {
-        return {
-          subnetType: SubnetType.ISOLATED,
-          onePerAz: placement.onePerAz,
-          availabilityZones: placement.availabilityZones,
-        };
-      }
-      return {
-        subnetType: SubnetType.PUBLIC,
-        onePerAz: placement.onePerAz,
-        availabilityZones: placement.availabilityZones,
-      };
+      let subnetType = this.privateSubnets.length ? SubnetType.PRIVATE : this.isolatedSubnets.length ? SubnetType.ISOLATED : SubnetType.PUBLIC;
+      placement = { ...placement, subnetType: subnetType };
     }
 
-    return placement;
-  }
-}
+    // Establish which subnet filters are going to be used
+    let subnetFilters = placement.subnetFilters ?? [];
 
-function retainByAZ(subnets: ISubnet[], azs: string[]): ISubnet[] {
-  return subnets.filter(s => azs.includes(s.availabilityZone));
-}
+    // Backwards compatibility with existing `availabilityZones` and `onePerAz` functionality
+    if (placement.availabilityZones !== undefined) { // Filter by AZs, if specified
+      subnetFilters.push(new AvailabilityZoneSubnetSelector(placement.availabilityZones));
+    }
+    if (!!placement.onePerAz) { // Ensure one per AZ if specified
+      subnetFilters.push(new OnePerAZSubnetSelector());
+    }
+
+    // Overwrite the provided placement filters
+    placement = { ...placement, subnetFilters: subnetFilters };
 
-function retainOnePerAz(subnets: ISubnet[]): ISubnet[] {
-  const azsSeen = new Set<string>();
-  return subnets.filter(subnet => {
-    if (azsSeen.has(subnet.availabilityZone)) { return false; }
-    azsSeen.add(subnet.availabilityZone);
-    return true;
-  });
+    return placement;
+  }
 }
 
 /**
@@ -654,6 +658,7 @@ export interface VpcAttributes {
 }
 
 export interface SubnetAttributes {
+
   /**
    * The Availability Zone the subnet is located in
    *
@@ -662,16 +667,23 @@ export interface SubnetAttributes {
   readonly availabilityZone?: string;
 
   /**
-   * The subnetId for this particular subnet
+   * The IPv4 CIDR block associated with the subnet
+   *
+   * @default - No CIDR information, cannot use CIDR filter features
    */
-  readonly subnetId: string;
+  readonly ipv4CidrBlock?: string;
 
   /**
    * The ID of the route table for this particular subnet
    *
    * @default - No route table information, cannot create VPC endpoints
    */
   readonly routeTableId?: string;
+
+  /**
+   * The subnetId for this particular subnet
+   */
+  readonly subnetId: string;
 }
 
 /**
@@ -1442,6 +1454,11 @@ export class Subnet extends Resource implements ISubnet {
    */
   public readonly availabilityZone: string;
 
+  /**
+   * @attribute
+   */
+  public readonly ipv4CidrBlock: string;
+
   /**
    * The subnetId for this particular subnet
    */
@@ -1491,6 +1508,7 @@ export class Subnet extends Resource implements ISubnet {
     Tags.of(this).add(NAME_TAG, this.node.path);
 
     this.availabilityZone = props.availabilityZone;
+    this.ipv4CidrBlock = props.cidrBlock;
     const subnet = new CfnSubnet(this, 'Subnet', {
       vpcId: props.vpcId,
       cidrBlock: props.cidrBlock,
@@ -1890,6 +1908,7 @@ class ImportedSubnet extends Resource implements ISubnet, IPublicSubnet, IPrivat
   public readonly subnetId: string;
   public readonly routeTable: IRouteTable;
   private readonly _availabilityZone?: string;
+  private readonly _ipv4CidrBlock?: string;
 
   constructor(scope: Construct, id: string, attrs: SubnetAttributes) {
     super(scope, id);
@@ -1902,6 +1921,7 @@ class ImportedSubnet extends Resource implements ISubnet, IPublicSubnet, IPrivat
       scope.node.addWarning(`No routeTableId was provided to the subnet ${ref}. Attempting to read its .routeTable.routeTableId will return null/undefined. (More info: https://github.com/aws/aws-cdk/pull/3171)`);
     }
 
+    this._ipv4CidrBlock = attrs.ipv4CidrBlock;
     this._availabilityZone = attrs.availabilityZone;
     this.subnetId = attrs.subnetId;
     this.routeTable = {
@@ -1918,6 +1938,14 @@ class ImportedSubnet extends Resource implements ISubnet, IPublicSubnet, IPrivat
     return this._availabilityZone;
   }
 
+  public get ipv4CidrBlock(): string {
+    if (!this._ipv4CidrBlock) {
+      // tslint:disable-next-line: max-line-length
+      throw new Error("You cannot reference an imported Subnet's IPv4 CIDR if it was not supplied. Add the ipv4CidrBlock when importing using Subnet.fromSubnetAttributes()");
+    }
+    return this._ipv4CidrBlock;
+  }
+
   public associateNetworkAcl(id: string, networkAcl: INetworkAcl): void {
     const scope = Construct.isConstruct(networkAcl) ? networkAcl : this;
     const other = Construct.isConstruct(networkAcl) ? this : networkAcl;