feat(ec2): regional NAT Gateway by badmintoncryer · Pull Request #36538 · aws/aws-cdk

badmintoncryer · 2025-12-31T17:04:29Z

Issue # (if applicable)

Closes #36198

Reason for this change

AWS NAT Gateway now supports regional availability in 2025 November.

https://aws.amazon.com/about-aws/whats-new/2025/11/aws-nat-gateway-regional-availability/

https://docs.aws.amazon.com/vpc/latest/userguide/nat-gateways-regional.html

Description of changes

Add NatProvider.regionalGateway() static method to create Regional NAT Gateway providers
- Implement RegionalNatGatewayProvider class that creates a single NAT gateway covering all AZs with availabilityMode: 'regional'
- Support configuration options:
  - maxDrainDuration: Maximum wait time before forcibly releasing IP addresses
  - allocationId / eip: Use an existing Elastic IP allocation
  - availabilityZoneAddresses: Manual control over per-AZ EIP allocation
- Update determineNatGatewayCount() to always return 1 for Regional NAT Gateway regardless of AZ count

Describe any new or updated permissions being added

None

Description of how you validated changes

Add both unit and integ tests.

Checklist

My code adheres to the CONTRIBUTING GUIDE and DESIGN GUIDELINES

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

…d EIP support

aws-cdk-automation

(This review is outdated)

…ional gateways

…h AvailabilityZoneAddresses

…nnectivity

github-actions · 2026-01-01T04:21:13Z

⚠️ Experimental Feature: This security report is currently in experimental phase. Results may include false positives and the rules are being actively refined.
This security report is NOT a review blocker. Please try merge from main to avoid findings unrelated to the PR.

	Tests	Passed ✅	Skipped	Failed
Security Guardian Results	48 ran	48 passed

Test	Result
No test annotations available

View Security Guardian Results

github-actions · 2026-01-01T04:21:15Z

⚠️ Experimental Feature: This security report is currently in experimental phase. Results may include false positives and the rules are being actively refined.
This security report is NOT a review blocker. Please try merge from main to avoid findings unrelated to the PR.

	Tests	Passed ✅	Skipped	Failed
Security Guardian Results with resolved templates	48 ran	48 passed

Test	Result
No test annotations available

View Security Guardian Results with resolved templates

badmintoncryer · 2026-01-01T04:29:19Z

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

+   * Required for zonal NAT gateways, not used for regional NAT gateways.
   */
-  readonly natSubnets: PublicSubnet[];
+  readonly natSubnets?: PublicSubnet[];


Because RegionalNatGateway.configureNat() doesn't use natSubnets, I made natSubnets optional.

Cleaner if it doesn't break type declarations and/or requires deprecation.

export interface ConfigureRegionalNatOptions { readonly vpc: Vpc; readonly privateSubnets: PrivateSubnet[]; } export interface ConfigureNatOptions extends ConfigureRegionalNatOptions { readonly natSubnets: PublicSubnet[]; }

badmintoncryer · 2026-01-01T04:36:50Z

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

+   * Maximum amount of time to wait before forcibly releasing IP addresses
+   * if connections are still in progress.
+   *
+   * @default Duration.seconds(350)


Default value is described in the docs.

https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-resource-ec2-natgateway.html#cfn-ec2-natgateway-maxdraindurationseconds

badmintoncryer · 2026-01-01T04:40:39Z

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

+  /**
+   * The allocation ID of the Elastic IP address to use for this NAT gateway.
+   *
+   * Cannot be specified together with `eip`.
+   * Ignored when `availabilityZoneAddresses` is specified.
+   *
+   * @default - A new EIP is automatically allocated by AWS
+   */
+  readonly allocationId?: string;
+
+  /**
+   * Reference to an existing EIP to use for this NAT gateway.
+   *
+   * Cannot be specified together with `allocationId`.
+   * Ignored when `availabilityZoneAddresses` is specified.
+   *
+   * @default - A new EIP is automatically allocated by AWS
+   */
+  readonly eip?: IEIPRef;


The allocationId of the L1 construct can accept not only string but also IEIPRef. I wanted to make L2 similarly accept both of these types.

As implementation approaches, there are two options: (i) define the L2 argument as a union, or (ii) provide separate arguments for string and IEIPRef types. Since I was unsure whether union definitions are allowed in L2 arguments due to any type problem in go language, I adopted approach (ii). I will modify it to implementation (i) if necessary.

(i) union type

redaonly eip?: string | IETPRef;

(ii) separate argument

readonly allocationId?: string; redaonly eip?: IETPRef;

Union type is against the guidelines.

readonly eip?: CfnEIP seems the right type declaration (CfnEIP)

Due to a recent L1 fix, CfnXxx now extends IXxxRef, and all L2 constructs also extend IXxxRef. While there is currently no L2 construct for EIP, if we use IEipRef as the argument type, it will work seamlessly even when an L2 construct is implemented in the future, without requiring any code changes. For this reason, I believe it would be preferable to use IEipRef as the argument type. What do you think?

Agree. Thanks for clarifying!

…ionality

- Created assets JSON for the integration test of the regional NAT gateway. - Added CloudFormation template for the regional NAT gateway integration test. - Generated tree structure JSON for the regional NAT gateway stack, detailing VPC, subnets, NAT gateways, and associated resources.

✅ Updated pull request passes all PRLinter validations. Dismissing previous PRLinter review.

…or Regional NAT Gateway

… redundant note

… Gateway provider

…or messages

…kticks for clarity

…IP based on availabilityZoneAddresses

…ay examples

lpizzinidev · 2026-02-20T13:30:37Z

@badmintoncryer
Sorry for the late reply.

I'm considering using type casting as a workaround

Doesn't look right. A middle ground solution could be:

Keep the original interface with readonly natSubnets: PublicSubnet[]; required parameter
Pass an empty list in createNatGateways for RegionalNatGatewayProvider
Add another warning in RegionalNatGatewayProvider.configureNat if for some reason natSubnets is non-empty and ignore the value. Note: I would do this even if we decide to make the parameter optional.

That would save some ?? and maintain the current interface. Thoughts?

…atSubnets for Regional NAT Gateway

lpizzinidev

Watch out for the build error:

aws-cdk-lib: /codebuild/output/src2783507564/src/actions-runner/_work/aws-cdk/aws-cdk/packages/aws-cdk-lib/aws-ec2/lib/nat.ts
aws-cdk-lib:   18:1  error  Imports "Duration" are only used as type                                  @typescript-eslint/consistent-type-imports
aws-cdk-lib:   19:1  error  All imports in the declaration are only used as types. Use `import type`  @typescript-eslint/consistent-type-imports
aws-cdk-lib: /codebuild/output/src2783507564/src/actions-runner/_work/aws-cdk/aws-cdk/packages/aws-cdk-lib/aws-ec2/lib/vpc.ts
aws-cdk-lib:   33:1  error  Imports "ConfigureNatOptions" are only used as type  @typescript-eslint/consistent-type-imports
aws-cdk-lib: ✖ 3 problems (3 errors, 0 warnings)
aws-cdk-lib:   3 errors and 0 warnings potentially fixable with the `--fix` option.

Seems like a lint issue so should be easy to fix.

…orts

badmintoncryer · 2026-02-23T23:34:06Z

@lpizzinidev Thanks. I've resolved CI failure.

lpizzinidev

Ty!

badmintoncryer · 2026-02-25T13:06:25Z

@lpizzinidev Thanks!!

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

badmintoncryer added 2 commits December 31, 2025 22:33

feat(natgw): add CloudFormation template for Regional NAT Gateway setup

473ab77

feat(ec2): enhance Regional NAT Gateway provider with allocationId an…

6c3dd67

…d EIP support

aws-cdk-automation requested a review from a team December 31, 2025 17:04

github-actions bot added the p2 label Dec 31, 2025

badmintoncryer marked this pull request as draft December 31, 2025 17:04

github-actions bot added the distinguished-contributor [Pilot] contributed 50+ PRs to the CDK label Dec 31, 2025

Merge branch 'main' into regional-natgw

e93aa99

aws-cdk-automation previously requested changes Dec 31, 2025

View reviewed changes

pahud mentioned this pull request Dec 31, 2025

Failed CodeBuild CI - 13 PR(s) pahud/aws-cdk#17

Open

badmintoncryer added 4 commits January 1, 2026 10:43

feat(ec2): update NAT provider to support optional natSubnets for reg…

a24a26c

…ional gateways

Merge remote-tracking branch 'cryer/regional-natgw' into regional-natgw

0a044a3

feat(natgw): add CloudFormation template for Regional NAT Gateway wit…

412860b

…h AvailabilityZoneAddresses

feat(ec2): add dependency for Regional NAT Gateway on VPC internet co…

25bf4fd

…nnectivity

badmintoncryer commented Jan 1, 2026

View reviewed changes

badmintoncryer added 2 commits January 1, 2026 14:23

feat(ec2): add documentation and tests for Regional NAT Gateway funct…

26b5d84

…ionality

badmintoncryer added 9 commits January 1, 2026 23:10

feat(ec2): improve error messages and simplify EIP allocation logic f…

f502f19

…or Regional NAT Gateway

docs(ec2): update README for Regional NAT Gateway examples and remove…

1431032

… redundant note

refactor(ec2): remove redundant comments in VPC NAT Gateway logic

2f595bb

fix(ec2): clarify dependency requirement for NAT Gateway creation

0ac01a3

test(ec2): add test for single NAT Gateway creation with Regional NAT…

8017f0d

… Gateway provider

fix(ec2): simplify NAT Gateway count logic and improve validation err…

9d42d2a

…or messages

fix(ec2): update warning messages for Regional NAT Gateway to use bac…

9007845

…kticks for clarity

fix(ec2): update Regional NAT Gateway logic to conditionally create E…

42522c7

…IP based on availabilityZoneAddresses

fix(ec2): remove redundant subnetConfiguration for regional NAT Gatew…

0d1b9db

…ay examples

badmintoncryer added 2 commits February 21, 2026 15:23

fix: update NAT configuration to use ConfigureNatOptions and handle n…

ed2029d

…atSubnets for Regional NAT Gateway

Merge remote-tracking branch 'origin/main' into regional-natgw

bf06cd9

lpizzinidev reviewed Feb 23, 2026

View reviewed changes

badmintoncryer added 2 commits February 24, 2026 00:39

fix: update import statements for NAT and VPC modules to use type imp…

b1628a8

…orts

Merge branch 'main' into regional-natgw

184729c

aws-cdk-automation removed the pr/needs-community-review This PR needs a review from a Trusted Community Member or Core Team Member. label Feb 23, 2026

lpizzinidev approved these changes Feb 25, 2026

View reviewed changes

aws-cdk-automation added the pr/needs-maintainer-review This PR needs a review from a Core Team Member label Feb 25, 2026

badmintoncryer temporarily deployed to automation March 18, 2026 01:53 — with GitHub Actions Inactive

badmintoncryer added 2 commits March 18, 2026 10:57

Merge remote-tracking branch 'origin/main' into regional-natgw

368f92a

fix: add error code names to ValidationError calls after merging main

df895f1

badmintoncryer force-pushed the regional-natgw branch from a48b045 to df895f1 Compare March 18, 2026 01:59

badmintoncryer temporarily deployed to automation March 18, 2026 01:59 — with GitHub Actions Inactive

Merge branch 'main' into regional-natgw

7715eb1

badmintoncryer temporarily deployed to automation April 2, 2026 03:08 — with GitHub Actions Inactive

Merge branch 'main' into regional-natgw

58a2f65

badmintoncryer temporarily deployed to automation April 7, 2026 15:30 — with GitHub Actions Inactive

Merge branch 'main' into regional-natgw

30bf7e5

badmintoncryer temporarily deployed to automation April 8, 2026 12:05 — with GitHub Actions Inactive

chore: re-trigger CI

2b28003

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

badmintoncryer temporarily deployed to automation April 8, 2026 13:06 — with GitHub Actions Inactive

Conversation

badmintoncryer commented Dec 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Issue # (if applicable)

Reason for this change

Description of changes

Describe any new or updated permissions being added

Description of how you validated changes

Checklist

Uh oh!

aws-cdk-automation left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Jan 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Jan 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

badmintoncryer Jan 1, 2026

Choose a reason for hiding this comment

Uh oh!

lpizzinidev Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

badmintoncryer Jan 1, 2026

Choose a reason for hiding this comment

Uh oh!

badmintoncryer Jan 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

(i) union type

(ii) separate argument

Uh oh!

lpizzinidev Feb 4, 2026

Choose a reason for hiding this comment

Uh oh!

badmintoncryer Feb 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lpizzinidev Feb 20, 2026

Choose a reason for hiding this comment

Uh oh!

lpizzinidev commented Feb 20, 2026

Uh oh!

lpizzinidev left a comment

Choose a reason for hiding this comment

Uh oh!

badmintoncryer commented Feb 23, 2026

Uh oh!

lpizzinidev left a comment

Choose a reason for hiding this comment

Uh oh!

badmintoncryer commented Feb 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

badmintoncryer commented Dec 31, 2025 •

edited

Loading

aws-cdk-automation left a comment •

edited

Loading

github-actions bot commented Jan 1, 2026 •

edited

Loading

github-actions bot commented Jan 1, 2026 •

edited

Loading

badmintoncryer Jan 1, 2026 •

edited

Loading

badmintoncryer Feb 7, 2026 •

edited

Loading