feat(vpcv2): vpc peering connection construct (#31645)

### Issue # (if applicable)

Contributes to closing [RFC#507](https://github.com/aws/aws-cdk-rfcs/blob/57fd92a7f20e242b96885264c12567493f5e867f/text/0507-subnets.md?plain=1#L252)

Tracking: #30762

### Reason for this change

This PR implements a new L2 construct to setup VPC Peering Connection.

### Description of changes

- L2 class(VPCPeeringConnection)
- Function `validateVpcCidrOverlap` to ensure IPv4 CIDR blocks don't overlap for subnets in the VPCs

### Description of how you validated changes

- Unit tests to test combination of accounts (cross account & cross region, default same account & same region)
- Unit tests to see simulate when CIDR blocks overlap
  - Primary CIDR block overlaps
  - Secondary CIDR block overlaps
  - Primary and secondary CIDR block overlaps
- Integration test for peering connection

### Checklist
- [x] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md)

----

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

packages/@aws-cdk/aws-ec2-alpha/README.md

@@ -225,8 +225,159 @@ new Route(this, 'DynamoDBRoute', {
   destination: '0.0.0.0/0',
   target: { endpoint: dynamoEndpoint },
 });
+
+```
+
+## VPC Peering Connection
+
+VPC peering connection allows you to connect two VPCs and route traffic between them using private IP addresses. The VpcV2 construct supports creating VPC peering connections through the `VPCPeeringConnection` construct from the `route` module.
+
+Peering Connection cannot be established between two VPCs with overlapping CIDR ranges. Please make sure the two VPC CIDRs do not overlap with each other else it will throw an error.
+
+For more information, see [What is VPC peering?](https://docs.aws.amazon.com/vpc/latest/peering/what-is-vpc-peering.html).
+
+The following show examples of how to create a peering connection between two VPCs for all possible combinations of same-account or cross-account, and same-region or cross-region configurations.
+
+Note: You cannot create a VPC peering connection between VPCs that have matching or overlapping CIDR blocks
+
+**Case 1: Same Account and Same Region Peering Connection**
+
+```ts
+const stack = new Stack();
+
+const vpcA = new VpcV2(this, 'VpcA', {
+  primaryAddressBlock: IpAddresses.ipv4('10.0.0.0/16'),
+});
+
+const vpcB = new VpcV2(this, 'VpcB', {
+  primaryAddressBlock: IpAddresses.ipv4('10.1.0.0/16'),
+});
+
+const peeringConnection = vpcA.createPeeringConnection('sameAccountSameRegionPeering', {
+  acceptorVpc: vpcB,
+});
+```
+
+**Case 2: Same Account and Cross Region Peering Connection**
+
+There is no difference from Case 1 when calling `createPeeringConnection`. The only change is that one of the VPCs are created in another stack with a different region. To establish cross region VPC peering connection, acceptorVpc needs to be imported to the requestor VPC stack using `fromVpcV2Attributes` method. 
+
+```ts
+const app = new App();
+
+const stackA = new Stack(app, 'VpcStackA', { env: { account: '000000000000', region: 'us-east-1' } });
+const stackB = new Stack(app, 'VpcStackB', { env: { account: '000000000000', region: 'us-west-2' } });
+
+const vpcA = new VpcV2(stackA, 'VpcA', {
+  primaryAddressBlock: IpAddresses.ipv4('10.0.0.0/16'),
+});
+
+new VpcV2(stackB, 'VpcB', {
+  primaryAddressBlock: IpAddresses.ipv4('10.1.0.0/16'),
+});
+
+const vpcB = VpcV2.fromVpcV2Attributes(stackA, 'ImportedVpcB', {
+      vpcId: 'MockVpcBid',
+      vpcCidrBlock: '10.1.0.0/16',
+      region: 'us-west-2',
+      ownerAccountId: '000000000000',
+    });
+
+
+const peeringConnection = vpcA.createPeeringConnection('sameAccountCrossRegionPeering', {
+  acceptorVpc: vpcB,
+});
 ```
 
+**Case 3: Cross Account Peering Connection**
+
+For cross-account connections, the acceptor account needs an IAM role that grants the requestor account permission to initiate the connection. Create a new IAM role in the acceptor account using method `createAcceptorVpcRole` to provide the necessary permissions. 
+
+Once role is created in account, provide role arn for field `peerRoleArn` under method `createPeeringConnection`
+
+```ts
+const stack = new Stack();
+
+const acceptorVpc = new VpcV2(this, 'VpcA', {
+  primaryAddressBlock: IpAddresses.ipv4('10.0.0.0/16'),
+});
+
+const acceptorRoleArn = acceptorVpc.createAcceptorVpcRole('000000000000'); // Requestor account ID
+```
+
+After creating an IAM role in the acceptor account, we can initiate the peering connection request from the requestor VPC. Import accpeptorVpc to the stack using `fromVpcV2Attributes` method, it is recommended to specify owner account id of the acceptor VPC in case of cross account peering connection, if acceptor VPC is hosted in different region provide region value for import as well. 
+The following code snippet demonstrates how to set up VPC peering between two VPCs in different AWS accounts using CDK:
+
+```ts
+const stack = new Stack();
+
+const acceptorVpc = VpcV2.fromVpcV2Attributes(this, 'acceptorVpc', {
+      vpcId: 'vpc-XXXX',
+      vpcCidrBlock: '10.0.0.0/16',
+      region: 'us-east-2',
+      ownerAccountId: '111111111111',
+    });
+
+const acceptorRoleArn = 'arn:aws:iam::111111111111:role/VpcPeeringRole';
+
+const requestorVpc = new VpcV2(this, 'VpcB', {
+  primaryAddressBlock: IpAddresses.ipv4('10.1.0.0/16'),
+});
+
+const peeringConnection = requestorVpc.createPeeringConnection('crossAccountCrossRegionPeering', {
+  acceptorVpc: acceptorVpc,
+  peerRoleArn: acceptorRoleArn,
+});
+```
+
+### Route Table Configuration
+
+After establishing the VPC peering connection, routes must be added to the respective route tables in the VPCs to enable traffic flow. If a route is added to the requestor stack, information will be able to flow from the requestor VPC to the acceptor VPC, but not in the reverse direction. For bi-directional communication, routes need to be added in both VPCs from their respective stacks.
+
+For more information, see [Update your route tables for a VPC peering connection](https://docs.aws.amazon.com/vpc/latest/peering/vpc-peering-routing.html).
+
+```ts
+const stack = new Stack();
+
+const acceptorVpc = new VpcV2(this, 'VpcA', {
+  primaryAddressBlock: IpAddresses.ipv4('10.0.0.0/16'),
+});
+
+const requestorVpc = new VpcV2(this, 'VpcB', {
+  primaryAddressBlock: IpAddresses.ipv4('10.1.0.0/16'),
+});
+
+const peeringConnection = requestorVpc.createPeeringConnection('peeringConnection', {
+  acceptorVpc: acceptorVpc,
+});
+
+const routeTable = new RouteTable(this, 'RouteTable', {
+  vpc: requestorVpc,
+});
+
+routeTable.addRoute('vpcPeeringRoute', '10.0.0.0/16', { gateway: peeringConnection });
+```
+
+This can also be done using AWS CLI. For more information, see [create-route](https://docs.aws.amazon.com/cli/latest/reference/ec2/create-route.html).
+
+```bash
+# Add a route to the requestor VPC route table
+aws ec2 create-route --route-table-id rtb-requestor --destination-cidr-block 10.0.0.0/16 --vpc-peering-connection-id pcx-xxxxxxxx
+
+# For bi-directional add a route in the acceptor vpc account as well
+aws ec2 create-route --route-table-id rtb-acceptor --destination-cidr-block 10.1.0.0/16 --vpc-peering-connection-id pcx-xxxxxxxx
+```
+
+### Deleting the Peering Connection
+
+To delete a VPC peering connection, use the following command:
+
+```bash
+aws ec2 delete-vpc-peering-connection --vpc-peering-connection-id pcx-xxxxxxxx
+```
+
+For more information, see [Delete a VPC peering connection](https://docs.aws.amazon.com/vpc/latest/peering/create-vpc-peering-connection.html#delete-vpc-peering-connection).
+
 ## Adding Egress-Only Internet Gateway to VPC
 
 An egress-only internet gateway is a horizontally scaled, redundant, and highly available VPC component that allows outbound communication over IPv6 from instances in your VPC to the internet, and prevents the internet from initiating an IPv6 connection with your instances.

packages/@aws-cdk/aws-ec2-alpha/lib/route.ts

@@ -1,8 +1,8 @@
-import { CfnEIP, CfnEgressOnlyInternetGateway, CfnInternetGateway, CfnNatGateway, CfnRoute, CfnRouteTable, CfnVPCGatewayAttachment, CfnVPNGateway, CfnVPNGatewayRoutePropagation, GatewayVpcEndpoint, IRouteTable, IVpcEndpoint, RouterType } from 'aws-cdk-lib/aws-ec2';
+import { CfnEIP, CfnEgressOnlyInternetGateway, CfnInternetGateway, CfnNatGateway, CfnVPCPeeringConnection, CfnRoute, CfnRouteTable, CfnVPCGatewayAttachment, CfnVPNGateway, CfnVPNGatewayRoutePropagation, GatewayVpcEndpoint, IRouteTable, IVpcEndpoint, RouterType } from 'aws-cdk-lib/aws-ec2';
 import { Construct, IDependable } from 'constructs';
 import { Annotations, Duration, IResource, Resource } from 'aws-cdk-lib/core';
 import { IVpcV2, VPNGatewayV2Options } from './vpc-v2-base';
-import { NetworkUtils, allRouteTableIds } from './util';
+import { NetworkUtils, allRouteTableIds, CidrBlock } from './util';
 import { ISubnetV2 } from './subnet-v2';
 
 /**
@@ -175,6 +175,40 @@ export interface NatGatewayProps extends NatGatewayOptions {
   readonly vpc?: IVpcV2;
 }
 
+/**
+ * Options to define a VPC peering connection.
+ */
+export interface VPCPeeringConnectionOptions {
+  /**
+   * The VPC that is accepting the peering connection.
+   */
+  readonly acceptorVpc: IVpcV2;
+
+  /**
+   * The role arn created in the acceptor account.
+   *
+   * @default - no peerRoleArn needed if not cross account connection
+   */
+  readonly peerRoleArn?: string;
+
+  /**
+   * The resource name of the peering connection.
+   *
+   * @default - peering connection provisioned without any name
+   */
+  readonly vpcPeeringConnectionName?: string;
+}
+
+/**
+ * Properties to define a VPC peering connection.
+ */
+export interface VPCPeeringConnectionProps extends VPCPeeringConnectionOptions {
+  /**
+   * The VPC that is requesting the peering connection.
+   */
+  readonly requestorVpc: IVpcV2;
+}
+
 /**
  * Creates an egress-only internet gateway
  * @resource AWS::EC2::EgressOnlyInternetGateway
@@ -312,7 +346,7 @@ export class VPNGatewayV2 extends Resource implements IRouteTarget {
     const routeTableIds = allRouteTableIds(subnets);
 
     if (routeTableIds.length === 0) {
-      Annotations.of(this).addWarningV2('@aws-cdk:aws-ec2-elpha:enableVpnGatewayV2', `No subnets matching selection: '${JSON.stringify(vpnRoutePropagation)}'. Select other subnets to add routes to.`);
+      Annotations.of(scope).addWarningV2('@aws-cdk:aws-ec2-elpha:enableVpnGatewayV2', `No subnets matching selection: '${JSON.stringify(vpnRoutePropagation)}'. Select other subnets to add routes to.`);
     }
 
     this._routePropagation = new CfnVPNGatewayRoutePropagation(this, 'RoutePropagation', {
@@ -402,6 +436,103 @@ export class NatGateway extends Resource implements IRouteTarget {
   }
 }
 
+/**
+ * Creates a peering connection between two VPCs
+ * @resource AWS::EC2::VPCPeeringConnection
+ */
+export class VPCPeeringConnection extends Resource implements IRouteTarget {
+
+  /**
+   * The type of router used in the route.
+   */
+  readonly routerType: RouterType;
+
+  /**
+   * The ID of the route target.
+   */
+  readonly routerTargetId: string;
+
+  /**
+   * The VPC peering connection CFN resource.
+   */
+  public readonly resource: CfnVPCPeeringConnection;
+
+  constructor(scope: Construct, id: string, props: VPCPeeringConnectionProps) {
+    super(scope, id);
+
+    this.routerType = RouterType.VPC_PEERING_CONNECTION;
+
+    const isCrossAccount = props.requestorVpc.ownerAccountId !== props.acceptorVpc.ownerAccountId;
+
+    if (!isCrossAccount && props.peerRoleArn) {
+      throw new Error('peerRoleArn is not needed for same account peering');
+    }
+
+    if (isCrossAccount && !props.peerRoleArn) {
+      throw new Error('Cross account VPC peering requires peerRoleArn');
+    }
+
+    const overlap = this.validateVpcCidrOverlap(props.requestorVpc, props.acceptorVpc);
+    if (overlap) {
+      throw new Error('CIDR block should not overlap with each other for establishing a peering connection');
+    }
+
+    this.resource = new CfnVPCPeeringConnection(this, 'VPCPeeringConnection', {
+      vpcId: props.requestorVpc.vpcId,
+      peerVpcId: props.acceptorVpc.vpcId,
+      peerOwnerId: props.acceptorVpc.ownerAccountId,
+      peerRegion: props.acceptorVpc.region,
+      peerRoleArn: isCrossAccount ? props.peerRoleArn : undefined,
+    });
+
+    this.routerTargetId = this.resource.attrId;
+    this.node.defaultChild = this.resource;
+  }
+
+  /**
+   * Validates if the provided IPv4 CIDR block overlaps with existing subnet CIDR blocks within the given VPC.
+   *
+   * @param requestorVpc The VPC of the requestor.
+   * @param acceptorVpc The VPC of the acceptor.
+   * @returns True if the IPv4 CIDR block overlaps with each other for two VPCs, false otherwise.
+   * @internal
+   */
+  private validateVpcCidrOverlap(requestorVpc: IVpcV2, acceptorVpc: IVpcV2): boolean {
+
+    const requestorCidrs = [requestorVpc.ipv4CidrBlock];
+    const acceptorCidrs = [acceptorVpc.ipv4CidrBlock];
+
+    if (requestorVpc.secondaryCidrBlock) {
+      requestorCidrs.push(...requestorVpc.secondaryCidrBlock
+        .map(block => block.cidrBlock)
+        .filter((cidr): cidr is string => cidr !== undefined));
+    }
+
+    if (acceptorVpc.secondaryCidrBlock) {
+      acceptorCidrs.push(...acceptorVpc.secondaryCidrBlock
+        .map(block => block.cidrBlock)
+        .filter((cidr): cidr is string => cidr !== undefined));
+    }
+
+    for (const requestorCidr of requestorCidrs) {
+      const requestorRange = new CidrBlock(requestorCidr);
+      const requestorIpRange: [string, string] = [requestorRange.minIp(), requestorRange.maxIp()];
+
+      for (const acceptorCidr of acceptorCidrs) {
+        const acceptorRange = new CidrBlock(acceptorCidr);
+        const acceptorIpRange: [string, string] = [acceptorRange.minIp(), acceptorRange.maxIp()];
+
+        if (requestorRange.rangesOverlap(acceptorIpRange, requestorIpRange)) {
+          return true;
+        }
+      }
+    }
+
+    return false;
+  }
+
+}
+
 /**
  * The type of endpoint or gateway being targeted by the route.
  */
@@ -534,7 +665,7 @@ export class Route extends Resource implements IRouteV2 {
   /**
    * The type of router the route is targetting
    */
-  public readonly targetRouterType: RouterType
+  public readonly targetRouterType: RouterType;
 
   /**
    * The route CFN resource.

packages/@aws-cdk/aws-ec2-alpha/lib/util.ts

@@ -378,5 +378,4 @@ export class CidrBlockIpv6 {
     }
     return ipv6Number;
   }
-}
-
+}