fix(eks): throw error when kubectl subnets are isolated

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

@@ -1385,6 +1385,28 @@ export class Cluster extends ClusterBase {
         throw new UnscopedValidationError('RequiresPrivateEndpointAccess', 'Private endpoint access requires the VPC to have DNS support and DNS hostnames enabled. Use `enableDnsHostnames: true` and `enableDnsSupport: true` when creating the VPC.');
       }
 
+      // Validate that kubectl subnets are not isolated. Isolated subnets have no
+      // internet access by definition, so the kubectl Lambda will not be able to
+      // reach the EKS API, STS, or other AWS service endpoints required for
+      // kubectl operations (including the CoreDNS compute type patch).
+      // Only check for CDK-created VPCs where we know isolated subnets have no egress.
+      // Imported VPCs may have VPC endpoints configured that we can't detect.
+      // See https://github.com/aws/aws-cdk/issues/26613
+      if (this.vpc instanceof ec2.Vpc) {
+        const isolatedSubnetIds = new Set(this.vpc.isolatedSubnets.map(s => s.subnetId));
+        const hasIsolatedSubnets = privateSubnets.some(s => isolatedSubnetIds.has(s.subnetId));
+        if (hasIsolatedSubnets) {
+          throw new ValidationError(
+            'IsolatedKubectlSubnet',
+            'Isolated subnets cannot be used for kubectl private subnets. Isolated subnets have no internet access, '
+            + 'which is required for the kubectl Lambda to reach the EKS API, STS, and other AWS service endpoints. '
+            + 'Use PRIVATE_WITH_EGRESS subnets with a NAT Gateway instead, or configure VPC endpoints for STS, EKS, ECR, S3 '
+            + 'and other AWS services detailed here https://docs.aws.amazon.com/eks/latest/userguide/private-clusters.html',
+            this,
+          );
+        }
+      }
+
       kubectlSubnets = privateSubnets;
 
       // the vpc must exist in order to properly delete the cluster (since we run `kubectl delete`).

packages/aws-cdk-lib/aws-eks-v2/test/cluster.test.ts

@@ -1349,6 +1349,79 @@ describe('cluster', () => {
       });
     });
 
+    test('throws when kubectl subnets include isolated subnets', () => {
+      // GIVEN
+      const { stack } = testFixtureNoVpc();
+      const vpc = new ec2.Vpc(stack, 'Vpc', {
+        maxAzs: 2,
+        natGateways: 0,
+        subnetConfiguration: [
+          { name: 'Isolated', subnetType: ec2.SubnetType.PRIVATE_ISOLATED, cidrMask: 24 },
+        ],
+      });
+
+      // THEN
+      expect(() => {
+        new eks.Cluster(stack, 'Cluster', {
+          version: CLUSTER_VERSION,
+          vpc,
+          vpcSubnets: [{ subnetType: ec2.SubnetType.PRIVATE_ISOLATED }],
+          endpointAccess: eks.EndpointAccess.PRIVATE,
+          kubectlProviderOptions: {
+            kubectlLayer: new KubectlV33Layer(stack, 'kubectlLayer'),
+          },
+          prune: false,
+        });
+      }).toThrow(/Isolated subnets cannot be used for kubectl private subnets/);
+    });
+
+    test('does not throw when kubectl subnets are PRIVATE_WITH_EGRESS', () => {
+      // GIVEN
+      const { stack } = testFixtureNoVpc();
+      const vpc = new ec2.Vpc(stack, 'Vpc', {
+        maxAzs: 2,
+        natGateways: 1,
+        subnetConfiguration: [
+          { name: 'Public', subnetType: ec2.SubnetType.PUBLIC, cidrMask: 24 },
+          { name: 'Private', subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS, cidrMask: 24 },
+        ],
+      });
+
+      // THEN - should not throw
+      new eks.Cluster(stack, 'Cluster', {
+        version: CLUSTER_VERSION,
+        vpc,
+        vpcSubnets: [{ subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS }],
+        endpointAccess: eks.EndpointAccess.PRIVATE,
+        kubectlProviderOptions: {
+          kubectlLayer: new KubectlV33Layer(stack, 'kubectlLayer'),
+        },
+        prune: false,
+      });
+    });
+
+    test('does not throw for imported VPC with isolated subnets (may have VPC endpoints)', () => {
+      // GIVEN
+      const { stack } = testFixtureNoVpc();
+      const vpc = ec2.Vpc.fromVpcAttributes(stack, 'Vpc', {
+        vpcId: 'vpc-123',
+        availabilityZones: ['us-east-1a', 'us-east-1b'],
+        isolatedSubnetIds: ['subnet-1', 'subnet-2'],
+      });
+
+      // THEN - should not throw because imported VPCs may have VPC endpoints
+      new eks.Cluster(stack, 'Cluster', {
+        version: CLUSTER_VERSION,
+        vpc,
+        vpcSubnets: [{ subnets: vpc.isolatedSubnets }],
+        endpointAccess: eks.EndpointAccess.PRIVATE,
+        kubectlProviderOptions: {
+          kubectlLayer: new KubectlV33Layer(stack, 'kubectlLayer'),
+        },
+        prune: false,
+      });
+    });
+
     test('if openIDConnectProvider a new OpenIDConnectProvider resource is created and exposed', () => {
       // GIVEN
       const { stack } = testFixtureNoVpc();

packages/aws-cdk-lib/aws-eks/lib/cluster.ts

@@ -1868,6 +1868,28 @@ export class Cluster extends ClusterBase {
         throw new ValidationError('RequiresPrivateEndpointAccess', 'Private endpoint access requires the VPC to have DNS support and DNS hostnames enabled. Use `enableDnsHostnames: true` and `enableDnsSupport: true` when creating the VPC.', this);
       }
 
+      // Validate that kubectl subnets are not isolated. Isolated subnets have no
+      // internet access by definition, so the kubectl Lambda will not be able to
+      // reach the EKS API, STS, or other AWS service endpoints required for
+      // kubectl operations (including the CoreDNS compute type patch).
+      // Only check for CDK-created VPCs where we know isolated subnets have no egress.
+      // Imported VPCs may have VPC endpoints configured that we can't detect.
+      // See https://github.com/aws/aws-cdk/issues/26613
+      if (this.vpc instanceof ec2.Vpc) {
+        const isolatedSubnetIds = new Set(this.vpc.isolatedSubnets.map(s => s.subnetId));
+        const hasIsolatedSubnets = privateSubnets.some(s => isolatedSubnetIds.has(s.subnetId));
+        if (hasIsolatedSubnets) {
+          throw new ValidationError(
+            'IsolatedKubectlSubnet',
+            'Isolated subnets cannot be used for kubectl private subnets. Isolated subnets have no internet access, '
+            + 'which is required for the kubectl Lambda to reach the EKS API, STS, and other AWS service endpoints. '
+            + 'Use PRIVATE_WITH_EGRESS subnets with a NAT Gateway instead, or configure VPC endpoints for STS, EKS, ECR, S3 '
+            + 'and other AWS services detailed here https://docs.aws.amazon.com/eks/latest/userguide/private-clusters.html',
+            this,
+          );
+        }
+      }
+
       this.kubectlPrivateSubnets = privateSubnets;
 
       // the vpc must exist in order to properly delete the cluster (since we run `kubectl delete`).

packages/aws-cdk-lib/aws-eks/test/cluster.test.ts

@@ -2328,6 +2328,73 @@ describe('cluster', () => {
       });
     });
 
+    test('throws when kubectl private subnets include isolated subnets', () => {
+      // GIVEN
+      const { stack } = testFixtureNoVpc();
+      const vpc = new ec2.Vpc(stack, 'Vpc', {
+        maxAzs: 2,
+        natGateways: 0,
+        subnetConfiguration: [
+          { name: 'Isolated', subnetType: ec2.SubnetType.PRIVATE_ISOLATED, cidrMask: 24 },
+        ],
+      });
+
+      // THEN
+      expect(() => {
+        new eks.Cluster(stack, 'Cluster', {
+          version: CLUSTER_VERSION,
+          vpc,
+          vpcSubnets: [{ subnetType: ec2.SubnetType.PRIVATE_ISOLATED }],
+          endpointAccess: eks.EndpointAccess.PRIVATE,
+          kubectlLayer: new KubectlV31Layer(stack, 'KubectlLayer'),
+          prune: false,
+        });
+      }).toThrow(/Isolated subnets cannot be used for kubectl private subnets/);
+    });
+
+    test('does not throw when kubectl private subnets are PRIVATE_WITH_EGRESS', () => {
+      // GIVEN
+      const { stack } = testFixtureNoVpc();
+      const vpc = new ec2.Vpc(stack, 'Vpc', {
+        maxAzs: 2,
+        natGateways: 1,
+        subnetConfiguration: [
+          { name: 'Public', subnetType: ec2.SubnetType.PUBLIC, cidrMask: 24 },
+          { name: 'Private', subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS, cidrMask: 24 },
+        ],
+      });
+
+      // THEN - should not throw
+      new eks.Cluster(stack, 'Cluster', {
+        version: CLUSTER_VERSION,
+        vpc,
+        vpcSubnets: [{ subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS }],
+        endpointAccess: eks.EndpointAccess.PRIVATE,
+        kubectlLayer: new KubectlV31Layer(stack, 'KubectlLayer'),
+        prune: false,
+      });
+    });
+
+    test('does not throw for imported VPC with isolated subnets (may have VPC endpoints)', () => {
+      // GIVEN
+      const { stack } = testFixtureNoVpc();
+      const vpc = ec2.Vpc.fromVpcAttributes(stack, 'Vpc', {
+        vpcId: 'vpc-123',
+        availabilityZones: ['us-east-1a', 'us-east-1b'],
+        isolatedSubnetIds: ['subnet-1', 'subnet-2'],
+      });
+
+      // THEN - should not throw because imported VPCs may have VPC endpoints
+      new eks.Cluster(stack, 'Cluster', {
+        version: CLUSTER_VERSION,
+        vpc,
+        vpcSubnets: [{ subnets: vpc.isolatedSubnets }],
+        endpointAccess: eks.EndpointAccess.PRIVATE,
+        kubectlLayer: new KubectlV31Layer(stack, 'KubectlLayer'),
+        prune: false,
+      });
+    });
+
     test('if openIDConnectProvider a new OpenIDConnectProvider resource is created and exposed', () => {
       // GIVEN
       const { stack } = testFixtureNoVpc();