feat(ec2-alpha): support availability zone id in SubnetV2

[pahud]

Issue # (if applicable)

Closes #35242.

Reason for this change

The SubnetV2 construct was missing support for availabilityZoneId, which is essential for cross-account deployments where availability zone names can map to different physical zones across accounts, but availability zone IDs remain consistent.

Users needed the ability to specify subnets using AZ IDs instead of AZ names to ensure consistent placement across AWS accounts, particularly in scenarios involving:

• Cross-account VPC peering
• Multi-account architectures
• Disaster recovery setups where precise AZ placement is critical

Description of changes

API Enhancement:

• Made availabilityZone property optional in SubnetV2Props
• Added new availabilityZoneId property to SubnetV2Props
• Added mutual exclusion validation ensuring exactly one of availabilityZone or availabilityZoneId is specified
• Updated CloudFormation resource to pass availabilityZoneId when provided
• Enhanced availabilityZone getter to fall back to subnet.attrAvailabilityZone when using AZ ID
• Added availabilityZoneId property to SubnetV2Attributes interface for import scenarios

Documentation:

• Added comprehensive README section explaining when to use AZ IDs vs AZ names
• Documented cross-account use cases and AZ ID account-specific behavior
• Provided clear examples showing both usage patterns
• Added important caveats about AZ ID availability per account

Testing:

• Created comprehensive integration test (integ.subnet-v2-zoneId.ts) with multiple test scenarios
• Added unit tests covering AZ ID validation, different formats, and multi-AZ scenarios
• Added tests for error conditions (both specified, neither specified)
• Added tests for IPv6 compatibility with AZ IDs
• Generated integration test snapshots for CloudFormation template validation

Key Implementation Details:

• Validation ensures mutual exclusivity of availabilityZone and availabilityZoneId
• CloudFormation resource correctly sets either AvailabilityZone or AvailabilityZoneId property
• Maintains backward compatibility - existing code using availabilityZone continues to work
• Integration test includes account-specific AZ ID mapping with proper documentation

Describe any new or updated permissions being added

N/A - No new IAM permissions required. This change only adds a new property to specify availability zones using AZ IDs instead of AZ names.

Description of how you validated changes

Unit Tests:

• Added 6 new unit test cases covering all AZ ID scenarios:
  • Basic AZ ID creation and CloudFormation property validation
  • Error handling for mutual exclusion and missing specification
  • IPv6 compatibility with AZ IDs
  • Different AZ ID formats across regions (use1-az1, usw2-az1, euw1-az1)
  • Multi-AZ scenarios with different AZ IDs
• All existing unit tests continue to pass, ensuring backward compatibility

Integration Tests:

• Created comprehensive integration test with 4 different scenarios:
  • Hardcoded AZ ID usage
  • AZ ID from CloudFormation mapping
  • Context-based AZ ID with fallback
  • Multiple subnets across different AZ IDs
• Generated and validated CloudFormation snapshots
• Test includes proper CIDR allocation and account-specific AZ ID mapping
• Region restriction rationale: Test is restricted to us-east-1 because:
  • AZ ID mapping is hardcoded for us-east-1 format (use1-az1, use1-az2, etc.)
  • Different regions have different AZ ID prefixes (e.g., usw2-az1 for us-west-2, euw1-az1 for eu-west-1)
  • Each region has varying numbers of availability zones
  • Supporting multiple regions would require region-specific mappings for each test account
  • AZ IDs are account-specific, so the hardcoded mapping only works for the specific test account in us-east-1
• Added extensive documentation explaining these region restrictions and AZ ID account-specific behavior

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]

(This review is outdated)

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