feat(ec2): support IPAM CIDR allocation for Subnet

packages/@aws-cdk-testing/framework-integ/test/aws-ec2/test/integ.subnet-ipam.ts

@@ -0,0 +1,74 @@
+import * as cdk from 'aws-cdk-lib';
+import { ExpectedResult, IntegTest } from '@aws-cdk/integ-tests-alpha';
+import { CfnIPAM, CfnIPAMPool, IpAddresses, Subnet, Vpc } from 'aws-cdk-lib/aws-ec2';
+import { EC2_RESTRICT_DEFAULT_SECURITY_GROUP } from 'aws-cdk-lib/cx-api';
+
+/*
+ * Stack verification steps:
+ * * The subnet is created without a CidrBlock property; IPAM allocates its CIDR at deploy time
+ * * The assertion checks that the allocated CIDR is the first /24 of the pool's provisioned range
+ *
+ * ### MANUAL CLEAN UP REQUIRED ###
+ *
+ * As in integ.vpc-ipam.ts, the IPAM and the pool are retained after the test run and must be
+ * deleted manually.
+ */
+
+const app = new cdk.App();
+const stack = new cdk.Stack(app, 'aws-cdk-ec2-ipam-subnet');
+stack.node.setContext(EC2_RESTRICT_DEFAULT_SECURITY_GROUP, false);
+
+const ipam = new CfnIPAM(stack, 'IPAM', {
+  operatingRegions: [
+    { regionName: stack.region },
+  ],
+  tags: [{
+    key: 'stack',
+    value: stack.stackId,
+  }],
+});
+ipam.applyRemovalPolicy(cdk.RemovalPolicy.RETAIN);
+
+// A VPC with a concrete CIDR and no subnets of its own
+const vpc = new Vpc(stack, 'Vpc', {
+  ipAddresses: IpAddresses.cidr('10.0.0.0/16'),
+  subnetConfiguration: [],
+});
+
+// A pool that plans the VPC's address space for subnets: it provisions the VPC CIDR
+const pool = new CfnIPAMPool(stack, 'Pool', {
+  description: 'Subnet pool for the VPC',
+  addressFamily: 'ipv4',
+  autoImport: false,
+  locale: stack.region,
+  ipamScopeId: ipam.attrPrivateDefaultScopeId,
+  provisionedCidrs: [{
+    cidr: '10.0.0.0/16',
+  }],
+});
+pool.applyRemovalPolicy(cdk.RemovalPolicy.RETAIN);
+
+const subnet = new Subnet(stack, 'IpamSubnet', {
+  vpcId: vpc.vpcId,
+  availabilityZone: vpc.availabilityZones[0],
+  ipv4IpamAllocation: {
+    ipamPool: pool,
+    netmaskLength: 24,
+  },
+});
+
+const integ = new IntegTest(app, 'SubnetIpam', {
+  testCases: [stack],
+  allowDestroy: ['EC2::IPAM'],
+});
+
+// The first allocation from a fresh pool is the lowest /24 of the provisioned range
+integ.assertions.awsApiCall('EC2', 'describeSubnets', {
+  SubnetIds: [subnet.subnetId],
+}).expect(ExpectedResult.objectLike({
+  Subnets: [
+    {
+      CidrBlock: '10.0.0.0/24',
+    },
+  ],
+}));

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

@@ -413,6 +413,28 @@ new ec2.Vpc(this, 'TheVPC', {
 
 With this method of IP address management, no attempt is made to guess at subnet group sizes or to exhaustively allocate the IP range. All subnet groups must have an explicit `cidrMask` set as part of their subnet configuration, or `defaultSubnetIpv4NetmaskLength` must be set for a default size. If not, synthesis will fail and you must provide one or the other.
 
+#### Allocating a subnet CIDR from AWS IPAM
+
+A standalone `Subnet` (or `PublicSubnet`/`PrivateSubnet`) can also have its IPv4 CIDR block allocated from an IPAM pool at deploy time instead of taking a concrete `cidrBlock`. Pass the pool and the netmask length of the block to allocate in `ipv4IpamAllocation`; exactly one of `cidrBlock` and `ipv4IpamAllocation` must be set:
+
+```ts
+declare const vpc: ec2.Vpc;
+declare const pool: ec2.CfnIPAMPool;
+
+const subnet = new ec2.Subnet(this, 'IpamSubnet', {
+  vpcId: vpc.vpcId,
+  availabilityZone: vpc.availabilityZones[0],
+  ipv4IpamAllocation: {
+    ipamPool: pool,
+    netmaskLength: 24,
+  },
+});
+```
+
+The CIDR block allocated from the pool must lie within the CIDR of the VPC. To use a pool that is not defined in your CDK app (for example one shared with your account through AWS RAM), reference it by ID with `ec2.CfnIPAMPool.fromIpamPoolId(this, 'Pool', 'ipam-pool-0123456789abcdef0')`. If the pool's address space is provisioned through separate `CfnIPAMPoolCidr` resources, add a dependency from the subnet on them so the pool has space to allocate from when the subnet is created.
+
+Because the CIDR block is only known at deploy time, `subnet.ipv4CidrBlock` is a CloudFormation attribute reference rather than a concrete string. Subnet filters that parse the CIDR (`SubnetFilter.byCidrMask()`, `SubnetFilter.byCidrRanges()` and `SubnetFilter.containsIpAddresses()`) therefore cannot be used with IPAM-allocated subnets. Subnets created by `Vpc` from `subnetConfiguration` are not affected by this option; they keep getting their CIDRs from the VPC's `IpAddresses` provider.
+
 ### Dual Stack configuration
 
 To allocate both IPv4 and IPv6 addresses in your VPC, you can configure your VPC to have a dual stack protocol.

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

@@ -4,6 +4,7 @@ import type { ClientVpnEndpointOptions } from './client-vpn-endpoint';
 import { ClientVpnEndpoint } from './client-vpn-endpoint';
 import type {
   CfnVPCCidrBlock,
+  IIPAMPoolRef,
   ISubnetRef,
   IVPCRef, SubnetReference, VPCReference,
 } from './ec2.generated';
@@ -2085,6 +2086,26 @@ function subnetTypeTagValue(type: SubnetType) {
   }
 }
 
+/**
+ * Allocation of a subnet's IPv4 CIDR block from an Amazon VPC IP Address Manager (IPAM) pool
+ */
+export interface SubnetIpamAllocation {
+  /**
+   * The IPAM pool from which the CIDR block is allocated at deploy time
+   *
+   * The allocated CIDR block must lie within the CIDR of the VPC the subnet belongs to.
+   * To reference a pool that is not defined in this app, use `CfnIPAMPool.fromIpamPoolId()`.
+   */
+  readonly ipamPool: IIPAMPoolRef;
+
+  /**
+   * The netmask length of the CIDR block to allocate from the pool
+   *
+   * Must be between 16 and 28 (inclusive), the sizes allowed for an IPv4 subnet.
+   */
+  readonly netmaskLength: number;
+}
+
 /**
  * Specify configuration parameters for a VPC subnet
  */
@@ -2102,8 +2123,25 @@ export interface SubnetProps {
 
   /**
    * The CIDR notation for this subnet
+   *
+   * Exactly one of `cidrBlock` and `ipv4IpamAllocation` must be specified.
+   *
+   * @default - the CIDR block is allocated from the IPAM pool given in `ipv4IpamAllocation`
    */
-  readonly cidrBlock: string;
+  readonly cidrBlock?: string;
+
+  /**
+   * Allocate the IPv4 CIDR block of this subnet from an IPAM pool at deploy time
+   *
+   * When set, `ipv4CidrBlock` resolves to a deploy-time attribute of the subnet instead of a
+   * concrete string, so `SubnetFilter.byCidrMask()`, `SubnetFilter.byCidrRanges()` and
+   * `SubnetFilter.containsIpAddresses()` cannot be used with this subnet.
+   *
+   * Exactly one of `cidrBlock` and `ipv4IpamAllocation` must be specified.
+   *
+   * @default - the subnet uses the concrete `cidrBlock`
+   */
+  readonly ipv4IpamAllocation?: SubnetIpamAllocation;
 
   /**
    * Controls if a public IP is associated to an instance at launch
@@ -2166,6 +2204,11 @@ export class Subnet extends Resource implements ISubnet {
   public readonly availabilityZone: string;
 
   /**
+   * The IPv4 CIDR block for this subnet
+   *
+   * If the subnet is allocated from an IPAM pool (`ipv4IpamAllocation`), this is a
+   * deploy-time attribute of the subnet rather than a concrete string.
+   *
    * @attribute
    */
   public readonly ipv4CidrBlock: string;
@@ -2224,20 +2267,34 @@ export class Subnet extends Resource implements ISubnet {
     // Enhanced CDK Analytics Telemetry
     addConstructMetadata(this, props);
 
+    if (props.cidrBlock !== undefined && props.ipv4IpamAllocation !== undefined) {
+      throw new ValidationError(lit`CannotSpecifyBothCidrBlockAndIpv4IpamAllocation`, 'Cannot specify both \'cidrBlock\' and \'ipv4IpamAllocation\'; supply exactly one of them', this);
+    }
+    if (props.cidrBlock === undefined && props.ipv4IpamAllocation === undefined) {
+      throw new ValidationError(lit`MissingCidrBlockOrIpv4IpamAllocation`, 'Either \'cidrBlock\' or \'ipv4IpamAllocation\' must be specified', this);
+    }
+    const netmaskLength = props.ipv4IpamAllocation?.netmaskLength;
+    if (netmaskLength !== undefined && !Token.isUnresolved(netmaskLength) && (netmaskLength < 16 || netmaskLength > 28)) {
+      throw new ValidationError(lit`InvalidIpv4IpamAllocationNetmaskLength`, `'ipv4IpamAllocation.netmaskLength' must be between 16 and 28, got ${netmaskLength}`, this);
+    }
+
     Object.defineProperty(this, VPC_SUBNET_SYMBOL, { value: true });
 
     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,
+      ipv4IpamPoolId: props.ipv4IpamAllocation?.ipamPool.ipamPoolRef.ipamPoolId,
+      ipv4NetmaskLength: netmaskLength,
       availabilityZone: props.availabilityZone,
       mapPublicIpOnLaunch: props.mapPublicIpOnLaunch,
       ipv6CidrBlock: props.ipv6CidrBlock,
       assignIpv6AddressOnCreation: props.assignIpv6AddressOnCreation,
     });
+    // With IPAM the CIDR block is only known at deploy time
+    this.ipv4CidrBlock = props.cidrBlock ?? subnet.attrCidrBlock;
     this.subnetId = subnet.ref;
     this.subnetVpcId = subnet.attrVpcId;
     this.subnetAvailabilityZone = subnet.attrAvailabilityZone;

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

@@ -9,6 +9,7 @@ import {
   AclTraffic,
   BastionHostLinux,
   CfnEIP,
+  CfnIPAMPool,
   CfnSubnet,
   CfnVPC,
   SubnetFilter,
@@ -3541,6 +3542,169 @@ describe('vpc', () => {
   });
 });
 
+describe('Subnet', () => {
+  const ipamPoolId = 'ipam-pool-0123456789abcdef0';
+
+  test('subnet with a concrete cidrBlock renders CidrBlock and no IPAM properties', () => {
+    // GIVEN
+    const stack = new Stack();
+
+    // WHEN
+    const subnet = new Subnet(stack, 'Subnet', {
+      vpcId: 'vpc-1234',
+      availabilityZone: 'dummy1a',
+      cidrBlock: '10.0.0.0/24',
+    });
+
+    // THEN
+    expect(subnet.ipv4CidrBlock).toEqual('10.0.0.0/24');
+    Template.fromStack(stack).hasResourceProperties('AWS::EC2::Subnet', {
+      VpcId: 'vpc-1234',
+      AvailabilityZone: 'dummy1a',
+      CidrBlock: '10.0.0.0/24',
+      Ipv4IpamPoolId: Match.absent(),
+      Ipv4NetmaskLength: Match.absent(),
+    });
+  });
+
+  test('subnet allocated from an IPAM pool renders Ipv4IpamPoolId and Ipv4NetmaskLength instead of CidrBlock', () => {
+    // GIVEN
+    const stack = new Stack();
+    const pool = CfnIPAMPool.fromIpamPoolId(stack, 'Pool', ipamPoolId);
+
+    // WHEN
+    new Subnet(stack, 'Subnet', {
+      vpcId: 'vpc-1234',
+      availabilityZone: 'dummy1a',
+      ipv4IpamAllocation: { ipamPool: pool, netmaskLength: 24 },
+    });
+
+    // THEN
+    Template.fromStack(stack).hasResourceProperties('AWS::EC2::Subnet', {
+      VpcId: 'vpc-1234',
+      AvailabilityZone: 'dummy1a',
+      CidrBlock: Match.absent(),
+      Ipv4IpamPoolId: ipamPoolId,
+      Ipv4NetmaskLength: 24,
+    });
+  });
+
+  test('subnet allocated from an IPAM pool defined in the same stack references that pool', () => {
+    // GIVEN
+    const stack = new Stack();
+    const pool = new CfnIPAMPool(stack, 'Pool', { addressFamily: 'ipv4', ipamScopeId: 'ipam-scope-0123456789abcdef0' });
+
+    // WHEN
+    new Subnet(stack, 'Subnet', {
+      vpcId: 'vpc-1234',
+      availabilityZone: 'dummy1a',
+      ipv4IpamAllocation: { ipamPool: pool, netmaskLength: 24 },
+    });
+
+    // THEN
+    Template.fromStack(stack).hasResourceProperties('AWS::EC2::Subnet', {
+      Ipv4IpamPoolId: stack.resolve(pool.ipamPoolRef.ipamPoolId),
+      Ipv4NetmaskLength: 24,
+    });
+  });
+
+  test('ipv4CidrBlock of an IPAM-allocated subnet is the CidrBlock attribute of the subnet', () => {
+    // GIVEN
+    const stack = new Stack();
+    const pool = CfnIPAMPool.fromIpamPoolId(stack, 'Pool', ipamPoolId);
+
+    // WHEN
+    const subnet = new Subnet(stack, 'Subnet', {
+      vpcId: 'vpc-1234',
+      availabilityZone: 'dummy1a',
+      ipv4IpamAllocation: { ipamPool: pool, netmaskLength: 24 },
+    });
+
+    // THEN
+    expect(Token.isUnresolved(subnet.ipv4CidrBlock)).toBe(true);
+    expect(stack.resolve(subnet.ipv4CidrBlock)).toEqual({
+      'Fn::GetAtt': [stack.getLogicalId(subnet.node.defaultChild as CfnSubnet), 'CidrBlock'],
+    });
+  });
+
+  test('PublicSubnet and PrivateSubnet accept ipv4IpamAllocation', () => {
+    // GIVEN
+    const stack = new Stack();
+    const ipv4IpamAllocation = { ipamPool: CfnIPAMPool.fromIpamPoolId(stack, 'Pool', ipamPoolId), netmaskLength: 24 };
+
+    // WHEN
+    const publicSubnet = new PublicSubnet(stack, 'Public', { vpcId: 'vpc-1234', availabilityZone: 'dummy1a', ipv4IpamAllocation });
+    new PrivateSubnet(stack, 'Private', { vpcId: 'vpc-1234', availabilityZone: 'dummy1a', ipv4IpamAllocation });
+    publicSubnet.addNatGateway();
+
+    // THEN
+    const template = Template.fromStack(stack);
+    template.resourceCountIs('AWS::EC2::Subnet', 2);
+    template.allResourcesProperties('AWS::EC2::Subnet', {
+      CidrBlock: Match.absent(),
+      Ipv4IpamPoolId: ipamPoolId,
+      Ipv4NetmaskLength: 24,
+    });
+    template.resourceCountIs('AWS::EC2::NatGateway', 1);
+  });
+
+  test('a token netmaskLength is passed through without validation', () => {
+    // GIVEN
+    const stack = new Stack();
+    const pool = CfnIPAMPool.fromIpamPoolId(stack, 'Pool', ipamPoolId);
+
+    // WHEN
+    new Subnet(stack, 'Subnet', {
+      vpcId: 'vpc-1234',
+      availabilityZone: 'dummy1a',
+      ipv4IpamAllocation: { ipamPool: pool, netmaskLength: Lazy.number({ produce: () => 24 }) },
+    });
+
+    // THEN
+    Template.fromStack(stack).hasResourceProperties('AWS::EC2::Subnet', {
+      Ipv4NetmaskLength: 24,
+    });
+  });
+
+  test('fails when both cidrBlock and ipv4IpamAllocation are specified', () => {
+    // GIVEN
+    const stack = new Stack();
+    const pool = CfnIPAMPool.fromIpamPoolId(stack, 'Pool', ipamPoolId);
+
+    // THEN
+    expect(() => new Subnet(stack, 'Subnet', {
+      vpcId: 'vpc-1234',
+      availabilityZone: 'dummy1a',
+      cidrBlock: '10.0.0.0/24',
+      ipv4IpamAllocation: { ipamPool: pool, netmaskLength: 24 },
+    })).toThrow(/Cannot specify both 'cidrBlock' and 'ipv4IpamAllocation'/);
+  });
+
+  test('fails when neither cidrBlock nor ipv4IpamAllocation is specified', () => {
+    // GIVEN
+    const stack = new Stack();
+
+    // THEN
+    expect(() => new Subnet(stack, 'Subnet', {
+      vpcId: 'vpc-1234',
+      availabilityZone: 'dummy1a',
+    })).toThrow(/Either 'cidrBlock' or 'ipv4IpamAllocation' must be specified/);
+  });
+
+  test.each([15, 29])('fails for ipv4IpamAllocation.netmaskLength /%d outside the /16-/28 subnet range', (netmaskLength) => {
+    // GIVEN
+    const stack = new Stack();
+    const pool = CfnIPAMPool.fromIpamPoolId(stack, 'Pool', ipamPoolId);
+
+    // THEN
+    expect(() => new Subnet(stack, 'Subnet', {
+      vpcId: 'vpc-1234',
+      availabilityZone: 'dummy1a',
+      ipv4IpamAllocation: { ipamPool: pool, netmaskLength },
+    })).toThrow(/'ipv4IpamAllocation.netmaskLength' must be between 16 and 28/);
+  });
+});
+
 function getTestStack(): Stack {
   const stack = new Stack(undefined, 'TestStack', { env: { account: '123456789012', region: 'us-east-1' } });
   acknowledgeTestValidationRules(stack);