chore(release): 2.248.0 (#37509)

See [CHANGELOG](https://github.com/aws/aws-cdk/blob/bump/2.248.0/CHANGELOG.md)

Author: mergify[bot]

CHANGELOG.v2.alpha.md

@@ -2,6 +2,8 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [2.248.0-alpha.0](https://github.com/aws/aws-cdk/compare/v2.247.0-alpha.0...v2.248.0-alpha.0) (2026-04-02)
+
 ## [2.247.0-alpha.0](https://github.com/aws/aws-cdk/compare/v2.246.0-alpha.0...v2.247.0-alpha.0) (2026-04-02)
 
 

CHANGELOG.v2.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [2.248.0](https://github.com/aws/aws-cdk/compare/v2.247.0...v2.248.0) (2026-04-02)
+
+
+### Bug Fixes
+
+* **eks:** downgrade isolated subnet validation from error to warning ([#37500](https://github.com/aws/aws-cdk/issues/37500)) ([470856c](https://github.com/aws/aws-cdk/commit/470856cadcee34b2ec5e0620fab63838c223fd97)), closes [#37491](https://github.com/aws/aws-cdk/issues/37491)
+
 ## [2.247.0](https://github.com/aws/aws-cdk/compare/v2.246.0...v2.247.0) (2026-04-02)
 
 

docs/MIXINS_DESIGN_GUIDELINES.md

@@ -23,12 +23,24 @@ Mixins are appropriate when:
 - You want to allow users to compose features independently of the L2
   construct's props.
 
-Mixins are _not_ appropriate when the feature serves an external consumer rather
-than the target resource (use a Facade). For example, granting a role access to
-a bucket is about the role's needs, not the bucket's behavior.
+Mixins are _not_ appropriate when:
+
+- The feature serves an external consumer rather than the target resource (use
+  a Facade). For example, granting a role access to a bucket is about the
+  role's needs, not the bucket's behavior.
+- The feature advertises a capability to other constructs (use a Trait).
+- You need to change the optionality of construct properties or change construct defaults.
+- The feature should remain a normal construct property and the implementation
+  is primarily passing values through to the L1 resource. In that case, use
+  `CfnPropsMixin` in the L2 glue code instead of writing a standalone mixin.
 
 Mixins are _not_ a replacement for construct properties. They cannot change the
-optionality of properties or change defaults.
+optionality of construct properties or change construct defaults.
+Applying a mixin is an explicit user action. A mixin may, however, define
+its own inputs/props with default values that control the mixin's behavior
+once applied. For example, `BucketVersioning` defaults to enabling versioning
+when constructed without an explicit argument, but it does not change the
+`Bucket` construct's own default behavior.
 
 ## Base Class
 
@@ -136,6 +148,21 @@ supports(construct: IConstruct): construct is CfnBucket {
 When applied to an L2 construct via `.with()`, the mixin framework
 automatically delegates to the L1 default child.
 
+### Auxiliary Resources
+
+A mixin may create auxiliary resources when the feature requires additional
+infrastructure beyond directly configuring the target resource.
+An auxiliary resource is any construct created by the mixin whose sole purpose
+is to support the target resource's own behavior or lifecycle.
+
+Examples include:
+- Custom resource handlers (e.g., auto-delete objects handler in `BucketAutoDeleteObjects`)
+- Delivery sources and destinations (e.g., vended log delivery configuration in LogsDelivery Mixins)
+- Policy resources (e.g., bucket policy statements in `BucketPolicyStatements`)
+
+Auxiliary resources must serve the primary resource itself. If the additional
+resource primarily serves an external consumer, the feature belongs in a Facade, not a Mixin.
+
 ### Validation
 
 Mixins have two distinct phases: initialization and application. During
@@ -304,4 +331,13 @@ Mixins are accessed through the `mixins` namespace export:
 ## README Documentation
 
 Each service module with mixins must include a `## Mixins` section in its
-README documenting each mixin with a brief description and usage example.
+README documenting each mixin with:
+
+- a brief description of what the mixin does
+- a usage code example
+- the behavioral impact of applying the mixin
+
+The documented impact must describe what changes occur when the
+mixin is applied, including any modified L1 properties, lifecycle
+or deletion behavior changes, validation constraints, and any
+permissions, policy, or deployment-time implications.

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

@@ -1397,13 +1397,11 @@ export class Cluster extends ClusterBase {
         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(
-            lit`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,
+          Annotations.of(this).addWarningV2(
+            '@aws-cdk/aws-eks:isolatedSubnetsForKubectlPrivateSubnets',
+            'Isolated subnets are being used for kubectl private subnets. Isolated subnets have no internet access. '
+            + 'Ensure that VPC endpoints are configured for STS, EKS, ECR, S3 and other AWS services detailed here '
+            + 'https://docs.aws.amazon.com/eks/latest/userguide/private-clusters.html',
           );
         }
       }

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

@@ -5,7 +5,7 @@ import * as cdk8s from 'cdk8s';
 import { Construct } from 'constructs';
 import * as YAML from 'yaml';
 import { testFixture, testFixtureNoVpc } from './util';
-import { Match, Template } from '../../assertions';
+import { Annotations, Match, Template } from '../../assertions';
 import * as asg from '../../aws-autoscaling';
 import * as ec2 from '../../aws-ec2';
 import * as iam from '../../aws-iam';
@@ -1349,7 +1349,7 @@ describe('cluster', () => {
       });
     });
 
-    test('throws when kubectl subnets include isolated subnets', () => {
+    test('warns when kubectl subnets include isolated subnets', () => {
       // GIVEN
       const { stack } = testFixtureNoVpc();
       const vpc = new ec2.Vpc(stack, 'Vpc', {
@@ -1360,19 +1360,20 @@ describe('cluster', () => {
         ],
       });
 
+      // WHEN
+      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,
+      });
+
       // 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/);
+      Annotations.fromStack(stack).hasWarning('/Stack/Cluster', Match.stringLikeRegexp('Isolated subnets are being used for kubectl private subnets'));
     });
 
     test('does not throw when kubectl subnets are PRIVATE_WITH_EGRESS', () => {

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

@@ -1880,13 +1880,11 @@ export class Cluster extends ClusterBase {
         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(
-            lit`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,
+          Annotations.of(this).addWarningV2(
+            '@aws-cdk/aws-eks:isolatedSubnetsForKubectlPrivateSubnets',
+            'Isolated subnets are being used for kubectl private subnets. Isolated subnets have no internet access. '
+            + 'Ensure that VPC endpoints are configured for STS, EKS, ECR, S3 and other AWS services detailed here '
+            + 'https://docs.aws.amazon.com/eks/latest/userguide/private-clusters.html',
           );
         }
       }

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

@@ -2328,7 +2328,7 @@ describe('cluster', () => {
       });
     });
 
-    test('throws when kubectl private subnets include isolated subnets', () => {
+    test('warns when kubectl private subnets include isolated subnets', () => {
       // GIVEN
       const { stack } = testFixtureNoVpc();
       const vpc = new ec2.Vpc(stack, 'Vpc', {
@@ -2339,17 +2339,18 @@ describe('cluster', () => {
         ],
       });
 
+      // WHEN
+      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,
+      });
+
       // 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/);
+      Annotations.fromStack(stack).hasWarning('/Stack/Cluster', Match.stringLikeRegexp('Isolated subnets are being used for kubectl private subnets'));
     });
 
     test('does not throw when kubectl private subnets are PRIVATE_WITH_EGRESS', () => {

version.v2.json

@@ -1,4 +1,4 @@
 {
-  "version": "2.247.0",
-  "alphaVersion": "2.247.0-alpha.0"
+  "version": "2.248.0",
+  "alphaVersion": "2.248.0-alpha.0"
 }

yarn.lock

@@ -11448,9 +11448,9 @@ lodash.truncate@^4.4.2:
   integrity sha512-jttmRe7bRse52OsWIMDLaXxWqRAmtIUccAQ3garviCqJjafXOfNMO0yMfNpdD6zbGaTU0P5Nz7e7gAT6cKmJRw==
 
 lodash@^4.17.15, lodash@^4.17.21, lodash@^4.17.23:
-  version "4.17.23"
-  resolved "https://registry.npmjs.org/lodash/-/lodash-4.17.23.tgz#f113b0378386103be4f6893388c73d0bde7f2c5a"
-  integrity sha512-LgVTMpQtIopCi79SJeDiP0TfWi5CNEc/L/aRdTh3yIvmZXTnheWpKjSZhnvMl8iXbC1tFg9gdHHDMLoV7CnG+w==
+  version "4.18.1"
+  resolved "https://registry.npmjs.org/lodash/-/lodash-4.18.1.tgz#ff2b66c1f6326d59513de2407bf881439812771c"
+  integrity sha512-dMInicTPVE8d1e5otfwmmjlxkZoUpiVLwyeTdUsi/Caj/gfzzblBcCE5sRHV/AsjuCmxWrte2TNGSYuCeCq+0Q==
 
 log-symbols@^4.0.0, log-symbols@^4.1.0:
   version "4.1.0"