Network-Utils: IpAddresses.cidr() silently adjusts misaligned base addresses to the next valid CIDR block

[DaltJM]

Describe the bug

When using aws_ec2.IpAddresses.cidr() in the AWS CDK to define a VPC or subnet CIDR block, if the provided base IP address is not properly aligned for the specified prefix length, the CDK silently "rounds up" the address to the next valid CIDR block without issuing a warning or error. This can result in unexpected address space being allocated, which may go unnoticed during deployment and lead to future routing or peering issues.

Last Known Working CDK Library Version

No response

Expected Behavior

The CDK should validate the base address against the specified prefix length and throw an error if the base address is not aligned correctly for that prefix. At minimum, it should issue a warning or explicitly document that rounding will occur.

Current Behavior

CDK accepts misaligned CIDR specifications without validation. It internally adjusts the base address to the next aligned block for the given prefix length and proceeds with deployment. This adjustment is not surfaced to the user, leading to potential confusion or misconfiguration of network boundaries.

Reproduction Steps

1. Create a new CDK stack using TypeScript.

2. Define a VPC or subnet using an invalid CIDR block such as 10.0.40.0/19:

ec2.Vpc.fromVpcAttributes(this, 'MyVpc', {
  vpcId: 'vpc-abc123',
  ipAddresses: ec2.IpAddresses.cidr('10.0.40.0/19')
});

3. Synthesize or deploy the stack.

4. Observe that the resulting CIDR block is 10.0.64.0/19 rather than the originally specified 10.0.40.0/19.

Possible Solution

Implement validation in IpAddresses.cidr() to check whether the base IP address is aligned for the given prefix length.

If misaligned, throw an error to prevent silent correction.

Alternatively, provide a clear warning or log message during synthesis to inform the user that the input CIDR block has been modified.

Document this behavior explicitly in the method's API documentation to prevent confusion for users relying on deterministic network design.

Additional Information/Context

No response

AWS CDK Library version (aws-cdk-lib)

2.1019.1

AWS CDK CLI version

2.27.40

Node.js Version

22.16.0lts

OS

Windows 10

Language

TypeScript

Language Version

5.8.3

Other information

No response

[pahud]

Hi @DaltJM,

Thank you for reporting this issue! You've identified an usability concern with the IpAddresses.cidr() method. The current behavior of silently adjusting misaligned CIDR blocks can indeed lead to unexpected network configurations and potential routing issues.

The root cause is in the CidrBlock constructor in network-util.ts, which automatically aligns IP addresses to valid network boundaries without validation or notification. The minAddress() method performs this alignment calculation.

Your suggested solutions are excellent:

• Adding validation in IpAddresses.cidr() to check CIDR alignment
• Throwing an error for misaligned inputs to prevent silent corrections
• Providing clear warnings or documentation about this behavior

This would be a great contribution to improve the developer experience and prevent network misconfigurations. Would you be interested in submitting a pull request to address this issue? The fix would involve adding validation logic to detect when the provided base IP address doesn't align with the specified prefix length.

The implementation could check if NetworkUtils.ipToNum(baseIp) & ((1 << (32 - prefixLength)) - 1) === 0 to validate proper alignment before proceeding with CIDR block creation.

[DaltJM]

Thanks for your reply, @pahud ,

I'll work on a PR :)