feat(ec2): regional NAT Gateway

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

@@ -1,4 +1,5 @@
 import { Connections, IConnectable } from './connections';
+import { CfnNatGateway } from './ec2.generated';
 import { Instance } from './instance';
 import { InstanceArchitecture, InstanceType } from './instance-types';
 import { IKeyPair } from './key-pair';
@@ -9,7 +10,8 @@ import { ISecurityGroup, SecurityGroup } from './security-group';
 import { UserData } from './user-data';
 import { PrivateSubnet, PublicSubnet, RouterType, Vpc } from './vpc';
 import * as iam from '../../aws-iam';
-import { Fn, Token, UnscopedValidationError } from '../../core';
+import { Duration, Fn, Token, UnscopedValidationError } from '../../core';
+import { IEIPRef } from '../../interfaces/generated/aws-ec2-interfaces.generated';
 
 /**
  * Direction of traffic to allow all by default.
@@ -52,8 +54,6 @@ export interface GatewayConfig {
  *
  * Determines what type of NAT provider to create, either NAT gateways or NAT
  * instance.
- *
- *
  */
 export abstract class NatProvider {
   /**
@@ -100,6 +100,19 @@ export abstract class NatProvider {
     return new NatInstanceProviderV2(props);
   }
 
+  /**
+   * Use a Regional NAT Gateway to provide NAT services for your VPC
+   *
+   * Regional NAT Gateways provide automatic multi-AZ redundancy with a single
+   * gateway that scales across availability zones. AWS automatically manages
+   * AZ coverage and EIP allocation.
+   *
+   * @see https://docs.aws.amazon.com/vpc/latest/userguide/nat-gateways-regional.html
+   */
+  public static regionalGateway(props: RegionalNatGatewayProviderProps = {}): NatProvider {
+    return new RegionalNatGatewayProvider(props);
+  }
+
   /**
    * Return list of gateways spawned by the provider
    */
@@ -158,9 +171,41 @@ export interface NatGatewayProps {
 }
 
 /**
- * Properties for a NAT instance
- *
+ * Properties for a Regional NAT Gateway Provider
  *
+ * Regional NAT Gateways provide automatic multi-AZ redundancy with a single
+ * gateway that scales across availability zones.
+ */
+export interface RegionalNatGatewayProviderProps {
+  /**
+   * Maximum amount of time to wait before forcibly releasing IP addresses
+   * if connections are still in progress.
+   *
+   * @default Duration.seconds(350)
+   */
+  readonly maxDrainDuration?: Duration;
+
+  /**
+   * The allocation ID of the Elastic IP address to use for this NAT gateway.
+   *
+   * Cannot be specified together with `eip`.
+   *
+   * @default - A new EIP is automatically allocated
+   */
+  readonly allocationId?: string;
+
+  /**
+   * Reference to an existing EIP to use for this NAT gateway.
+   *
+   * Cannot be specified together with `allocationId`.
+   *
+   * @default - A new EIP is automatically allocated
+   */
+  readonly eip?: IEIPRef;
+}
+
+/**
+ * Properties for a NAT instance
  */
 export interface NatInstanceProps {
   /**
@@ -333,6 +378,62 @@ export class NatGatewayProvider extends NatProvider {
   }
 }
 
+/**
+ * Provider for Regional NAT Gateways
+ *
+ * Regional NAT Gateways provide automatic multi-AZ redundancy with a single gateway that scales across availability zones.
+ * Unlike zonal NAT gateways, a regional NAT gateway does not require a public subnet and is created at the VPC level.
+ *
+ * @see https://docs.aws.amazon.com/vpc/latest/userguide/nat-gateways-regional.html
+ */
+export class RegionalNatGatewayProvider extends NatProvider {
+  private natGateway?: CfnNatGateway;
+
+  constructor(private readonly props: RegionalNatGatewayProviderProps = {}) {
+    super();
+
+    if (this.props.allocationId && this.props.eip) {
+      throw new UnscopedValidationError(
+        'Cannot specify both allocationId and eip. Use one or the other.',
+      );
+    }
+  }
+
+  public configureNat(options: ConfigureNatOptions) {
+    this.natGateway = new CfnNatGateway(options.vpc, 'RegionalNatGateway', {
+      vpcId: options.vpc.vpcId,
+      availabilityMode: 'regional',
+      connectivityType: 'public',
+      allocationId: this.props.allocationId ?? this.props.eip,
+      maxDrainDurationSeconds: this.props.maxDrainDuration?.toSeconds(),
+    });
+
+    // Add routes to the regional NAT gateway in all private subnets
+    for (const sub of options.privateSubnets) {
+      this.configureSubnet(sub);
+    }
+  }
+
+  public configureSubnet(subnet: PrivateSubnet) {
+    if (!this.natGateway) {
+      throw new UnscopedValidationError('Cannot configure subnet before configuring NAT gateway');
+    }
+    // All private subnets use the same regional NAT gateway ID
+    subnet.addRoute('DefaultRoute', {
+      routerType: RouterType.NAT_GATEWAY,
+      routerId: this.natGateway.attrNatGatewayId,
+      enablesInternetConnectivity: true,
+    });
+  }
+
+  public get configuredGateways(): GatewayConfig[] {
+    // Regional NAT gateway is a single gateway covering all AZs
+    return this.natGateway
+      ? [{ az: 'regional', gatewayId: this.natGateway.attrNatGatewayId }]
+      : [];
+  }
+}
+
 /**
  * NAT provider which uses NAT Instances
  *

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

@@ -24,7 +24,7 @@ import {
   Ipv6Addresses,
   RequestedSubnet,
 } from './ip-addresses';
-import { NatProvider } from './nat';
+import { NatProvider, RegionalNatGatewayProvider } from './nat';
 import { INetworkAcl, NetworkAcl, SubnetNetworkAclAssociation } from './network-acl';
 import { SubnetFilter } from './subnet';
 import {
@@ -1655,7 +1655,9 @@ export class Vpc extends VpcBase {
     this.subnetConfiguration = ifUndefined(props.subnetConfiguration, defaultSubnet);
 
     const natGatewayPlacement = props.natGatewaySubnets || { subnetType: SubnetType.PUBLIC };
-    const natGatewayCount = determineNatGatewayCount(props.natGateways, this.subnetConfiguration, this.availabilityZones.length);
+    const natGatewayCount = determineNatGatewayCount(
+      props.natGateways, this.subnetConfiguration, this.availabilityZones.length, props.natGatewayProvider,
+    );
 
     if (this.useIpv6) {
       this.ipv6Addresses = props.ipv6Addresses ?? Ipv6Addresses.amazonProvided();
@@ -1702,6 +1704,23 @@ export class Vpc extends VpcBase {
       // if gateways are needed create them
       if (natGatewayCount > 0) {
         const provider = props.natGatewayProvider || NatProvider.gateway();
+
+        // Add warnings for Regional NAT Gateway if unnecessary options are specified
+        if (provider instanceof RegionalNatGatewayProvider) {
+          if (props.natGateways !== undefined && props.natGateways !== 1) {
+            Annotations.of(this).addWarningV2(
+              '@aws-cdk/aws-ec2:regionalNatGatewayCount',
+              'natGateways is ignored when using Regional NAT Gateway. A single regional gateway covers all AZs.',
+            );
+          }
+          if (props.natGatewaySubnets !== undefined) {
+            Annotations.of(this).addWarningV2(
+              '@aws-cdk/aws-ec2:regionalNatGatewaySubnets',
+              'natGatewaySubnets is ignored when using Regional NAT Gateway. The gateway is created at VPC level without requiring a public subnet.',
+            );
+          }
+        }
+
         this.createNatGateways(provider, natGatewayCount, natGatewayPlacement);
       }
     }
@@ -1797,6 +1816,17 @@ export class Vpc extends VpcBase {
   }
 
   private createNatGateways(provider: NatProvider, natCount: number, placement: SubnetSelection): void {
+    // Regional NAT Gateway does not require public subnets
+    if (provider instanceof RegionalNatGatewayProvider) {
+      provider.configureNat({
+        vpc: this,
+        natSubnets: [], // Regional NAT Gateway doesn't use natSubnets
+        privateSubnets: this.privateSubnets as PrivateSubnet[],
+      });
+      return;
+    }
+
+    // Zonal NAT Gateway requires public subnets
     const natSubnets: PublicSubnet[] = this.selectSubnetObjects(placement) as PublicSubnet[];
     for (const sub of natSubnets) {
       if (this.publicSubnets.indexOf(sub) === -1) {
@@ -2787,19 +2817,29 @@ class ImportedSubnet extends Resource implements ISubnet, IPublicSubnet, IPrivat
  * Do we want to require that there are private subnets if there are NatGateways?
  * They seem pointless but I see no reason to prevent it.
  */
-function determineNatGatewayCount(requestedCount: number | undefined, subnetConfig: SubnetConfiguration[], azCount: number) {
+function determineNatGatewayCount(
+  requestedCount: number | undefined,
+  subnetConfig: SubnetConfiguration[],
+  azCount: number,
+  natGatewayProvider?: NatProvider,
+) {
   const hasPrivateSubnets = subnetConfig.some(c => (c.subnetType === SubnetType.PRIVATE_WITH_EGRESS
     || c.subnetType === SubnetType.PRIVATE || c.subnetType === SubnetType.PRIVATE_WITH_NAT) && !c.reserved);
   const hasPublicSubnets = subnetConfig.some(c => c.subnetType === SubnetType.PUBLIC && !c.reserved);
   const hasCustomEgress = subnetConfig.some(c => c.subnetType === SubnetType.PRIVATE_WITH_EGRESS);
 
-  const count = requestedCount !== undefined ? Math.min(requestedCount, azCount) : (hasPrivateSubnets ? azCount : 0);
+  // Regional NAT Gateway uses a single gateway regardless of AZ count
+  const isRegionalNatGateway = natGatewayProvider instanceof RegionalNatGatewayProvider;
+  const count = requestedCount !== undefined
+    ? Math.min(requestedCount, azCount)
+    : (hasPrivateSubnets ? (isRegionalNatGateway ? 1 : azCount) : 0);
 
   if (count === 0 && hasPrivateSubnets && !hasCustomEgress) {
     throw new UnscopedValidationError('If you do not want NAT gateways (natGateways=0), make sure you don\'t configure any PRIVATE(_WITH_NAT) subnets in \'subnetConfiguration\' (make them PUBLIC or ISOLATED instead)');
   }
 
-  if (count > 0 && !hasPublicSubnets) {
+  // Regional NAT Gateway does not require public subnets
+  if (count > 0 && !hasPublicSubnets && !isRegionalNatGateway) {
     throw new UnscopedValidationError(`If you configure PRIVATE subnets in 'subnetConfiguration', you must also configure PUBLIC subnets to put the NAT gateways into (got ${JSON.stringify(subnetConfig)}.`);
   }