feat: Add IPAM Pool and Static CIDR support to Virtual Network Manager

[archit017]

Add IPAM Pool and Static CIDR Support to Virtual Network Manager

Overview

This PR adds comprehensive IP Address Management (IPAM) capabilities to the Azure Virtual Network Manager module, enabling centralized IP address space management at scale.

What's Changed

New Constructs

• IpamPool: Manages IP address pools with automatic overlap detection and hierarchical organization
• IpamPoolStaticCidr: Enables static CIDR block allocation within pools for dedicated purposes

CIDR Validation Utilities

Added comprehensive CIDR validation utilities in cidr-validator.ts:

• isValidCidr() - Validates CIDR notation format
• cidrsOverlap() - Detects overlapping CIDR blocks
• calculateAddressCount() - Calculates IP addresses in a CIDR
• isSubnet() - Validates parent-child CIDR relationships
• isPrivateRange() - Checks if CIDR is within RFC 1918 ranges
• parseCidr() - Parses CIDR into structured information
• Plus additional validation functions

Key Features

✅ Centralized IP Management - Manage IP addresses across multiple VNets from a single location
✅ Overlap Prevention - Automatic validation prevents overlapping CIDR blocks
✅ Hierarchical Pools - Support for parent-child pool relationships
✅ Static Allocations - Reserve specific CIDR blocks within pools
✅ Multi-Version Support - Supports API versions 2023-11-01 and 2024-05-01
✅ Type-Safe - Full TypeScript support with comprehensive interfaces
✅ Well-Tested - Extensive unit tests for all constructs and utilities

Files Changed

New Files

• src/azure-virtualnetworkmanager/lib/ipam-pool.ts - IPAM Pool construct
• src/azure-virtualnetworkmanager/lib/ipam-pool-schemas.ts - IPAM Pool API schemas
• src/azure-virtualnetworkmanager/lib/ipam-pool-static-cidr.ts - Static CIDR construct
• src/azure-virtualnetworkmanager/lib/ipam-pool-static-cidr-schemas.ts - Static CIDR API schemas
• src/azure-virtualnetworkmanager/lib/utils/cidr-validator.ts - CIDR validation utilities
• src/azure-virtualnetworkmanager/test/ipam-pool.spec.ts - IPAM Pool unit tests
• src/azure-virtualnetworkmanager/test/ipam-pool-static-cidr.spec.ts - Static CIDR unit tests
• src/azure-virtualnetworkmanager/test/cidr-validator.spec.ts - CIDR validator unit tests

Modified Files

• src/azure-virtualnetworkmanager/lib/index.ts - Export new constructs and utilities
• src/azure-virtualnetworkmanager/README.md - Add comprehensive IPAM documentation
• src/azure-virtualnetworkmanager/lib/virtual-network-manager.ts - Minor updates
• src/azure-virtualnetworkmanager/test/virtual-network-manager.spec.ts - Updated tests
• src/azure-virtualnetworkmanager/test/virtual-network-manager.integ.ts - Updated integration tests
• API.md - Updated API documentation

Usage Example

import { IpamPool, IpamPoolStaticCidr } from "@microsoft/terraform-cdk-constructs/azure-virtualnetworkmanager";

// Create root IPAM pool
const ipamPool = new IpamPool(this, "RootPool", {
  name: "production-pool",
  location: "eastus",
  networkManagerId: networkManager.id,
  addressPrefixes: ["10.0.0.0/8"],
  description: "Root IP address pool for production workloads",
  displayName: "Production Root Pool",
});

// Create child pool with hierarchical relationship
const childPool = new IpamPool(this, "ChildPool", {
  name: "eastus-pool",
  location: "eastus",
  networkManagerId: networkManager.id,
  addressPrefixes: ["10.1.0.0/16"],
  parentPoolName: ipamPool.props.name,
  description: "East US regional pool",
});

// Allocate static CIDR block
const staticCidr = new IpamPoolStaticCidr(this, "WebServers", {
  name: "web-servers-cidr",
  ipamPoolId: childPool.id,
  addressPrefixes: ["10.1.10.0/24"],
  description: "Reserved for production web servers",
});

// Use validation utilities
import { isValidCidr, cidrsOverlap, calculateAddressCount } from "@microsoft/terraform-cdk-constructs/azure-virtualnetworkmanager";

const valid = isValidCidr("10.0.0.0/8"); // true
const overlap = cidrsOverlap("10.0.0.0/8", "10.1.0.0/16"); // true
const count = calculateAddressCount("10.0.0.0/24"); // 256

Testing

Unit Tests

All new constructs include comprehensive unit tests:

• ✅ IPAM Pool construct tests (130+ test cases)
• ✅ IPAM Pool Static CIDR tests (100+ test cases)
• ✅ CIDR validator utility tests (150+ test cases)

Run tests with:

npm test

Integration Tests

Integration tests updated to include IPAM pool scenarios.

Documentation

• Complete IPAM section added to README.md including:
  • Feature overview
  • Usage examples (basic and advanced)
  • API reference for all constructs
  • CIDR validation utilities documentation
  • Regional limitations
  • Best practices
  • Troubleshooting guide

Regional Limitations

⚠️ Note: IPAM is not available in the following regions:

• Chile Central
• Jio India West
• Malaysia West
• Qatar Central
• South Africa West
• West India
• West US 3

Breaking Changes

None - This is a purely additive change that introduces new functionality without modifying existing constructs.

Checklist

• Code follows project conventions and style
• Comprehensive unit tests added
• Integration tests updated
• Documentation added to README
• API schemas for supported versions (2023-11-01, 2024-05-01)
• TypeScript types and interfaces defined
• JSII compliance maintained
• Examples provided

Related Issues

Implements IPAM functionality for Azure Virtual Network Manager as part of the networking constructs expansion.