[DaltJM]

Issue # (if applicable)

Closes #34784.

Reason for this change

When a Vpc is given a CIDR block through IpAddresses.cidr() (or the deprecated cidr property) whose base address is not aligned to its prefix length, such as 10.0.40.0/19, the CDK silently rounds the block up to the next aligned block (10.0.64.0/19). The deployed VPC then has a different address range than the one requested, which can go unnoticed and cause routing or peering issues later.

Rejecting these CIDRs unconditionally would break existing apps that currently synthesize and deploy with a misaligned CIDR, so the validation is introduced behind a feature flag.

Description of changes

• Add the @aws-cdk/aws-ec2:validateVpcCidrAlignment bug-fix feature flag (unconfiguredBehavesLike: false, recommended value true).
• When the flag is enabled, Vpc throws a ValidationError if the CIDR block provided through IpAddresses.cidr() or the deprecated cidr property is not aligned to its prefix length. The error suggests the aligned blocks below and above the given one, e.g.:

  VPC CIDR block '10.0.40.0/19' is not aligned to its /19 prefix length. Use '10.0.32.0/19' or '10.0.64.0/19' instead.
  

• When the flag is disabled, the existing rounding behavior is preserved.
• The check lives in Vpc (where the construct scope needed to read the flag is available) and only applies to the local IpAddresses.cidr() provider. CidrBlock and NetworkBuilder are unchanged, so subnet allocation behaves exactly as before.
• Document the behavior in the aws-ec2 README and fix two doc examples that used a misaligned CIDR (10.0.1.0/20).
• Regenerate FEATURE_FLAGS.md and recommended-feature-flags.json.

Describe any new or updated permissions being added

N/A

Description of how you validated changes

Added unit tests in aws-ec2/test/ip-addresses.test.ts covering:

• a misaligned CIDR is rounded up when the flag is disabled (existing behavior),
• a misaligned CIDR throws when the flag is enabled, via both IpAddresses.cidr() and the deprecated cidr property,
• aligned and default CIDRs are accepted when the flag is enabled.

Added the flag to the defaults check in cx-api/test/features.test.ts. The ip-addresses, network-utils and features test suites pass, and ESLint passes on the changed files.

No integration test was added, as the change only affects synthesis-time validation and is fully covered by unit tests (per review feedback).

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

[aws-cdk-automation]

The pull request linter fails with the following errors:

❌ Fixes must contain a change to an integration test file and the resulting snapshot.

If you believe this pull request should receive an exemption, please comment and provide a justification. A comment requesting an exemption should contain the text Exemption Request. Additionally, if clarification is needed, add Clarification Request to a comment.

✅ A exemption request has been requested. Please wait for a maintainer's review.

[aws-cdk-automation]

AWS CodeBuild CI Report

• CodeBuild project: AutoBuildv2Project1C6BFA3F-wQm2hXv2jqQv
• Commit ID: 7b462fa
• Result: SUCCEEDED
• Build Logs (available for 30 days)

Powered by github-codebuild-logs, available on the AWS Serverless Application Repository

[DaltJM]

@aws-cdk-automation Exemption Request - Requested changes have been committed.

[leonmk-aws]

This adds validation that rejects input which previously synthesized and deployed successfully — a misaligned base like 10.0.1.0/20 used to be rounded to 10.0.0.0/20 and deployed fine. Existing apps that pass a misaligned CIDR (deliberately or by typo that "worked") will now fail at synth the moment they upgrade, with no opt-out.
Adding this validation should be done under a feature flag to preserve backwards compatibility.

[leonmk-aws]

Integ tests for EC2 reside in: packages/@aws-cdk-testing/framework-integ/test/aws-ec2/test, though I don't think we need an integration test for this.

[leonmk-aws]

The changelog is auto generated, no need to edit this file.

[leonmk-aws]

What is this file ?

[leonmk-aws]

Let's not do these linting changes (applies to the other changes as well).

[DaltJM]

@leonmk-aws thanks for the review. I've reworked the PR to address all of your feedback:

• Feature flag: the validation is now behind a new @aws-cdk/aws-ec2:validateVpcCidrAlignment flag (unconfiguredBehavesLike: false, recommended true). With the flag disabled, existing apps keep the current behavior and a misaligned CIDR is still rounded up to the next aligned block. With the flag enabled, Vpc throws for a misaligned CIDR passed via IpAddresses.cidr() or the deprecated cidr property, and the error suggests the aligned blocks on either side (e.g. 10.0.40.0/19 → use 10.0.32.0/19 or 10.0.64.0/19). CidrBlock and NetworkBuilder are unchanged.
• Integ test: removed, along with the .fail.json file (it was meant to assert the synth error, but it isn't needed). The change is covered by unit tests for both flag states.
• Linting changes: reverted; the diff now only contains the functional change.
• CHANGELOG: reverted.

I also fixed the README example, which used a misaligned CIDR (10.0.1.0/20), and regenerated FEATURE_FLAGS.md and recommended-feature-flags.json. The branch is up to date with main.

[DaltJM]

Exemption Request - this change only adds a synthesis-time validation behind a feature flag and is fully covered by unit tests for both flag states. As suggested in review, an integration test isn't needed for this change.