feat(eks-v2-alpha): add support for EKS hybrid nodes (#36749)

### Issue # (if applicable)
### Reason for this change

This change allows users to specify the networking primitives for an EKS
Hybrid nodes cluster through L2 constructs.

### Description of changes

This PR introduces two new top-level fields called remoteNodeNetworks
and remotePodNetworks in the Cluster construct. Together, these allow
users to specify the exact CIDRs ranges they want to use for their
on-premises nodes and (optionally) pods. The Hybrid nodes feature
requires that none of the node and pod CIDRs overlap with each other so
I have also added validations for that.

Network utils from EC2 had to be exported so they can be used in
eks-v2-alpha, which is in a different package
(@aws-cdk/aws-eks-v2-alpha). It cannot be used directly without an
export like in eks v1 which is in aws-cdk-lib. Because of that, they are
marked as internal.

Similar to #32389

This aligns EKS v2 with v1. I also confirmed it works with EKS auto
mode.

### Describe any new or updated permissions being added

None

### Description of how you validated changes


Integ test deployed
### 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*

---------

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

Author: aemada-aws

packages/@aws-cdk/aws-eks-v2-alpha/README.md

@@ -711,6 +711,31 @@ declare const cluster: eks.Cluster;
 const clusterEncryptionConfigKeyArn = cluster.clusterEncryptionConfigKeyArn;
 ```
 
+### Hybrid Nodes
+
+When you create an Amazon EKS cluster, you can configure it to leverage the [EKS Hybrid Nodes](https://aws.amazon.com/eks/hybrid-nodes/) feature, allowing you to use your on-premises and edge infrastructure as nodes in your EKS cluster. Refer to the Hyrid Nodes [networking documentation](https://docs.aws.amazon.com/eks/latest/userguide/hybrid-nodes-networking.html) to configure your on-premises network, node and pod CIDRs, access control, etc before creating your EKS Cluster.
+
+Once you have identified the on-premises node and pod (optional) CIDRs you will use for your hybrid nodes and the workloads running on them, you can specify them during cluster creation using the `remoteNodeNetworks` and `remotePodNetworks` (optional) properties:
+
+```ts
+import { KubectlV34Layer } from '@aws-cdk/lambda-layer-kubectl-v34';
+
+new eks.Cluster(this, 'Cluster', {
+  version: eks.KubernetesVersion.V1_34,
+  remoteNodeNetworks: [
+    {
+      cidrs: ['10.0.0.0/16'],
+    },
+  ],
+  remotePodNetworks: [
+    {
+      cidrs: ['192.168.0.0/16'],
+    },
+  ],
+});
+```
+
+
 ## Permissions and Security
 
 In the new EKS module, `ConfigMap` is deprecated. Clusters created by the new module will use `API` as authentication mode. Access Entry will be the only way for granting permissions to specific IAM users and roles.

packages/@aws-cdk/aws-eks-v2-alpha/lib/cluster.ts

@@ -8,6 +8,7 @@ import type * as kms from 'aws-cdk-lib/aws-kms';
 import * as ssm from 'aws-cdk-lib/aws-ssm';
 import type { IResource, Duration, ArnComponents } from 'aws-cdk-lib/core';
 import { Annotations, CfnOutput, CfnResource, Resource, Tags, Token, Stack, UnscopedValidationError, FeatureFlags } from 'aws-cdk-lib/core';
+import { ValidationError } from 'aws-cdk-lib/core/lib/errors';
 import { memoizedGetter } from 'aws-cdk-lib/core/lib/helpers-internal';
 import { MethodMetadata, addConstructMetadata } from 'aws-cdk-lib/core/lib/metadata-resource';
 import { propertyInjectable } from 'aws-cdk-lib/core/lib/prop-injectable';
@@ -433,6 +434,19 @@ export interface ClusterCommonOptions {
    * If not defined, kubectl provider will not be created by default.
    */
   readonly kubectlProviderOptions?: KubectlProviderOptions;
+
+  /**
+   * IPv4 CIDR blocks defining the expected address range of hybrid nodes
+   * that will join the cluster.
+   * @default - none
+   */
+  readonly remoteNodeNetworks?: RemoteNodeNetwork[];
+
+  /**
+   * IPv4 CIDR blocks for Pods running Kubernetes webhooks on hybrid nodes.
+   * @default - none
+   */
+  readonly remotePodNetworks?: RemotePodNetwork[];
 }
 
 /**
@@ -527,6 +541,26 @@ export class EndpointAccess {
   }
 }
 
+/**
+ * Remote network configuration for hybrid nodes
+ */
+export interface RemoteNodeNetwork {
+  /**
+   * IPv4 CIDR blocks for the remote node network
+   */
+  readonly cidrs: string[];
+}
+
+/**
+ * Remote network configuration for pods on hybrid nodes
+ */
+export interface RemotePodNetwork {
+  /**
+   * IPv4 CIDR blocks for the remote pod network
+   */
+  readonly cidrs: string[];
+}
+
 /**
  * Options for configuring EKS Auto Mode compute settings.
  * When enabled, EKS will automatically manage compute resources like node groups and Fargate profiles.
@@ -1150,6 +1184,8 @@ export class Cluster extends ClusterBase {
 
     this.tagSubnets();
 
+    this.validateRemoteNetworkConfig(props);
+
     // this is the role used by EKS when interacting with AWS resources
     this.role = props.role || new iam.Role(this, 'Role', {
       assumedBy: new iam.ServicePrincipal('eks.amazonaws.com'),
@@ -1261,6 +1297,14 @@ export class Cluster extends ClusterBase {
           enabled: autoModeEnabled,
         },
       },
+      ...(props.remoteNodeNetworks ? {
+        remoteNetworkConfig: {
+          remoteNodeNetworks: props.remoteNodeNetworks,
+          ...(props.remotePodNetworks ? {
+            remotePodNetworks: props.remotePodNetworks,
+          }: {}),
+        },
+      } : {}),
       resourcesVpcConfig: {
         securityGroupIds: [securityGroup.securityGroupId],
         subnetIds,
@@ -1679,6 +1723,81 @@ export class Cluster extends ClusterBase {
     return autoModeEnabled;
   }
 
+  private validateRemoteNetworkConfig(props: ClusterProps) {
+    if (!props.remoteNodeNetworks) {
+      if (props.remotePodNetworks) {
+        throw new ValidationError('remotePodNetworks cannot be specified without remoteNodeNetworks also being specified', this);
+      }
+      return;
+    }
+
+    this.validateNetworkCidrs(props.remoteNodeNetworks, 'node');
+
+    if (!props.remotePodNetworks) return;
+
+    this.validateNetworkCidrs(props.remotePodNetworks, 'pod');
+    this.validateCrossNetworkOverlap(props.remoteNodeNetworks, props.remotePodNetworks);
+  }
+
+  /**
+   * Validates all CIDR rules for a single network type (within same network + across networks).
+   */
+  private validateNetworkCidrs(networks: RemoteNodeNetwork[] | RemotePodNetwork[], networkType: 'node' | 'pod') {
+    const resolvedCidrs = networks.map(n => n.cidrs.filter(c => !Token.isUnresolved(c)));
+
+    // Within same network
+    resolvedCidrs.forEach((cidrs, index) => {
+      for (let i = 0; i < cidrs.length; i++) {
+        for (let j = i + 1; j < cidrs.length; j++) {
+          if (ec2.NetworkUtils.validateCidrPairOverlap(cidrs[i], cidrs[j])) {
+            throw new ValidationError(
+              `CIDR ${cidrs[i]} should not overlap with another CIDR in remote ${networkType} network #${index + 1}`,
+              this,
+            );
+          }
+        }
+      }
+    });
+
+    // Across different networks
+    for (let i = 0; i < resolvedCidrs.length; i++) {
+      if (resolvedCidrs[i].length === 0) continue;
+      for (let j = i + 1; j < resolvedCidrs.length; j++) {
+        if (resolvedCidrs[j].length === 0) continue;
+        const [overlap, cidr1, cidr2] = ec2.NetworkUtils.validateCidrBlocksOverlap(resolvedCidrs[i], resolvedCidrs[j]);
+        if (overlap) {
+          throw new ValidationError(
+            `CIDR block ${cidr1} in remote ${networkType} network #${i + 1} should not overlap with CIDR block ${cidr2} in remote ${networkType} network #${j + 1}`,
+            this,
+          );
+        }
+      }
+    }
+  }
+
+  /**
+   * Validates that node network CIDRs do not overlap with pod network CIDRs.
+   */
+  private validateCrossNetworkOverlap(nodeNetworks: RemoteNodeNetwork[], podNetworks: RemotePodNetwork[]) {
+    for (const nodeNetwork of nodeNetworks) {
+      const nodeCidrs = nodeNetwork.cidrs.filter(c => !Token.isUnresolved(c));
+      if (nodeCidrs.length === 0) continue;
+
+      for (const podNetwork of podNetworks) {
+        const podCidrs = podNetwork.cidrs.filter(c => !Token.isUnresolved(c));
+        if (podCidrs.length === 0) continue;
+
+        const [overlap, nodeCidr, podCidr] = ec2.NetworkUtils.validateCidrBlocksOverlap(nodeCidrs, podCidrs);
+        if (overlap) {
+          throw new ValidationError(
+            `Remote node network CIDR block ${nodeCidr} should not overlap with remote pod network CIDR block ${podCidr}`,
+            this,
+          );
+        }
+      }
+    }
+  }
+
   private addNodePoolRole(id: string): iam.Role {
     const role = new iam.Role(this, id, {
       assumedBy: new iam.ServicePrincipal('ec2.amazonaws.com'),