feat(ec2): add support for IPAM CIDR allocation in Subnet configuration

Author: betchi207

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

@@ -2603,3 +2603,66 @@ new ec2.Instance(this, 'Instance', {
   instanceProfile,
 });
 ```
+
+### Using IPAM for Subnet CIDR Allocation
+
+Instead of specifying a CIDR block directly, you can allocate a CIDR from an [IPAM pool](https://docs.aws.amazon.com/vpc/latest/ipam/what-it-is-ipam.html) for your subnet. This allows for more flexible and managed IP address allocation.
+
+For IPv4, use the `ipv4IpamAllocation` property:
+
+```ts
+import * as ec2 from 'aws-cdk-lib/aws-ec2';
+
+const vpc = new ec2.Vpc(this, 'Vpc');
+
+// Create a subnet with IPv4 CIDR allocated from an IPAM pool
+new ec2.Subnet(this, 'Subnet', {
+  vpcId: vpc.vpcId,
+  availabilityZone: 'us-east-1a',
+  ipv4IpamAllocation: {
+    ipamPoolId: 'ipam-pool-12345',
+    netmaskLength: 24, // Optional: if not specified, uses the default netmask length from the IPAM pool
+  },
+});
+```
+
+For IPv6, use the `ipv6IpamAllocation` property:
+
+```ts
+// Create a subnet with IPv6 CIDR allocated from an IPAM pool
+new ec2.Subnet(this, 'Subnet', {
+  vpcId: vpc.vpcId,
+  availabilityZone: 'us-east-1a',
+  cidrBlock: '10.0.0.0/24', // IPv4 CIDR is required
+  ipv6IpamAllocation: {
+    ipamPoolId: 'ipam-pool-67890',
+    netmaskLength: 64, // Optional: if not specified, uses the default netmask length from the IPAM pool
+  },
+  assignIpv6AddressOnCreation: true,
+});
+```
+
+You can also use both IPv4 and IPv6 IPAM allocations together:
+
+```ts
+// Create a subnet with both IPv4 and IPv6 CIDR allocated from IPAM pools
+new ec2.Subnet(this, 'Subnet', {
+  vpcId: vpc.vpcId,
+  availabilityZone: 'us-east-1a',
+  ipv4IpamAllocation: {
+    ipamPoolId: 'ipam-pool-12345',
+    // netmaskLength is optional and will use the IPAM pool's default if not specified
+  },
+  ipv6IpamAllocation: {
+    ipamPoolId: 'ipam-pool-67890',
+    // netmaskLength is optional and will use the IPAM pool's default if not specified
+  },
+  assignIpv6AddressOnCreation: true,
+});
+```
+
+Note that:
+- You cannot specify both `cidrBlock` and `ipv4IpamAllocation` at the same time
+- You cannot specify both `ipv6CidrBlock` and `ipv6IpamAllocation` at the same time
+- If you specify `assignIpv6AddressOnCreation: true`, you must also specify either `ipv6CidrBlock` or `ipv6IpamAllocation`
+- The `netmaskLength` property in both `ipv4IpamAllocation` and `ipv6IpamAllocation` is optional. If not specified, the default netmask length configured in the IPAM pool will be used.

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

@@ -1962,7 +1962,45 @@ function subnetTypeTagValue(type: SubnetType) {
 }
 
 /**
- * Specify configuration parameters for a VPC subnet
+ * IPv4 IPAM pool allocation configuration.
+ */
+export interface Ipv4IpamAllocation {
+  /**
+   * The ID of the IPv4 IPAM pool from which to allocate the CIDR.
+   */
+  readonly ipamPoolId: string;
+
+  /**
+   * The netmask length of the IPv4 CIDR to allocate to the subnet.
+   *
+   * If not specified, the default netmask length configured for the IPAM pool will be used.
+   *
+   * @default - The default netmask length configured in the IPAM pool
+   */
+  readonly netmaskLength?: number;
+}
+
+/**
+ * IPv6 IPAM pool allocation configuration.
+ */
+export interface Ipv6IpamAllocation {
+  /**
+   * The ID of the IPv6 IPAM pool from which to allocate the CIDR.
+   */
+  readonly ipamPoolId: string;
+
+  /**
+   * The netmask length of the IPv6 CIDR to allocate to the subnet.
+   *
+   * If not specified, the default netmask length configured for the IPAM pool will be used.
+   *
+   * @default - The default netmask length configured in the IPAM pool
+   */
+  readonly netmaskLength?: number;
+}
+
+/**
+ * Properties for defining a Subnet.
  */
 export interface SubnetProps {
 
@@ -1978,8 +2016,11 @@ export interface SubnetProps {
 
   /**
    * The CIDR notation for this subnet
+   *
+   * Either `cidrBlock` or `ipv4IpamAllocation` must be specified, but not both.
+   * @default - No CIDR block is specified. Use ipv4IpamAllocation to specify IPv4 allocation.
    */
-  readonly cidrBlock: string;
+  readonly cidrBlock?: string;
 
   /**
    * Controls if a public IP is associated to an instance at launch
@@ -1993,18 +2034,42 @@ export interface SubnetProps {
    *
    * If you specify AssignIpv6AddressOnCreation, you must also specify Ipv6CidrBlock.
    *
+   * Either `ipv6CidrBlock` or `ipv6IpamAllocation` must be specified, but not both.
+   *
    * @default - no IPv6 CIDR block.
    */
   readonly ipv6CidrBlock?: string;
 
   /**
    * Indicates whether a network interface created in this subnet receives an IPv6 address.
    *
-   * If you specify AssignIpv6AddressOnCreation, you must also specify Ipv6CidrBlock.
+   * If you specify AssignIpv6AddressOnCreation, you must also specify Ipv6CidrBlock or ipv6IpamAllocation.
    *
    * @default false
    */
   readonly assignIpv6AddressOnCreation?: boolean;
+
+  /**
+   * IPv4 IPAM pool allocation configuration.
+   *
+   * Use this property to allocate a CIDR from an IPv4 IPAM pool to this subnet.
+   *
+   * Either `cidrBlock` or `ipv4IpamAllocation` must be specified, but not both.
+   *
+   * @default - IPAM is not used for IPv4 address allocation
+   */
+  readonly ipv4IpamAllocation?: Ipv4IpamAllocation;
+
+  /**
+   * IPv6 IPAM pool allocation configuration.
+   *
+   * Use this property to allocate a CIDR from an IPv6 IPAM pool to this subnet.
+   *
+   * Either `ipv6CidrBlock` or `ipv6IpamAllocation` must be specified, but not both.
+   *
+   * @default - IPAM is not used for IPv6 address allocation
+   */
+  readonly ipv6IpamAllocation?: Ipv6IpamAllocation;
 }
 
 /**
@@ -2091,19 +2156,40 @@ export class Subnet extends Resource implements ISubnet {
     // Enhanced CDK Analytics Telemetry
     addConstructMetadata(this, props);
 
+    // Validate the properties
+    if (props.cidrBlock === undefined && props.ipv4IpamAllocation === undefined) {
+      throw new ValidationError('Either cidrBlock or ipv4IpamAllocation must be specified', this);
+    }
+    if (props.cidrBlock !== undefined && props.ipv4IpamAllocation !== undefined) {
+      throw new ValidationError('Cannot specify both cidrBlock and ipv4IpamAllocation', this);
+    }
+    if (props.ipv6CidrBlock !== undefined && props.ipv6IpamAllocation !== undefined) {
+      throw new ValidationError('Cannot specify both ipv6CidrBlock and ipv6IpamAllocation', this);
+    }
+    if (props.assignIpv6AddressOnCreation && props.ipv6CidrBlock === undefined && props.ipv6IpamAllocation === undefined) {
+      throw new ValidationError('If you specify assignIpv6AddressOnCreation, you must also specify ipv6CidrBlock or ipv6IpamAllocation', 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;
+    // If ipv4IpamAllocation is used, ipv4CidrBlock will be determined by CloudFormation at runtime
+    this.ipv4CidrBlock = props.cidrBlock ?? '';
     const subnet = new CfnSubnet(this, 'Subnet', {
       vpcId: props.vpcId,
       cidrBlock: props.cidrBlock,
       availabilityZone: props.availabilityZone,
       mapPublicIpOnLaunch: props.mapPublicIpOnLaunch,
       ipv6CidrBlock: props.ipv6CidrBlock,
       assignIpv6AddressOnCreation: props.assignIpv6AddressOnCreation,
+      // Add IPv4 IPAM properties if provided
+      ipv4IpamPoolId: props.ipv4IpamAllocation?.ipamPoolId,
+      ipv4NetmaskLength: props.ipv4IpamAllocation?.netmaskLength,
+      // Add IPv6 IPAM properties if provided
+      ipv6IpamPoolId: props.ipv6IpamAllocation?.ipamPoolId,
+      ipv6NetmaskLength: props.ipv6IpamAllocation?.netmaskLength,
     });
     this.subnetId = subnet.ref;
     this.subnetVpcId = subnet.attrVpcId;