Feature flags - AWS Cloud Development Kit (AWS CDK) v2

This is the AWS CDK v2 Developer Guide. The older CDK v1 entered maintenance on June 1, 2022 and will now receive only critical bug fixes and security patches. New features will be developed for CDK v2 exclusively. Support for CDK v1 will end entirely on June 1, 2023.

Feature flags

The AWS CDK uses feature flags to enable potentially breaking behaviors in a release. Flags are stored as Runtime context values in cdk.json (or ~/.cdk.json). They are not removed by the cdk context --reset or cdk context --clear commands.

Feature flags are disabled by default. Existing projects that do not specify the flag will continue to work as before with later AWS CDK releases. New projects created using cdk init include flags enabling all features available in the release that created the project. Edit cdk.json to disable any flags for which you prefer the earlier behavior. You can also add flags to enable new behaviors after upgrading the AWS CDK.

See the CHANGELOG in a given release for a description of any new feature flags added in that release. A list of all current feature flags can be found on the AWS CDK GitHub repository in FEATURE_FLAGS.md.

Enabling features with flags

The following feature flags may be set to true to enable the described behavior.


Makes it impossible to use Secrets Manager values in unsafe locations.


Verify that updating a layer associated with a Lambda function creates a new version of the function.


Verify that Amazon EC2 Systems Manager service principals are generated correctly.


Enables logging in service extensions containers by default.


Causes InstanceRequireImdsv2Aspect to verify that the generated name is unique.


Minimize the creation of IAM policies when possible.


In an Amazon SQS queue subscribed to an Amazon SNS topic, restrict decryption permissions to only the topic instead of all of Amazon SNS.


When using an S3 bucket with a service that will automatically create a bucket policy at deployment, have the AWS CDK configure the necessary policy.


Make sure cross-account key alias is unique in pipelines.


The AWS CDK fails at synthesis time if the SNAPSHOT removal policy is not supported for a given resource.


Use the new ARN format when importing an Amazon EC2 or Fargate cluster.

Reverting to v1 behavior

In CDK v2, the defaults for a set of feature flags have been changed with respect to v1. You can set these back to false to revert to specific AWS CDK v1 behavior. Use the cdk diff command to inspect the changes to your synthesized template to see if any of these flags are needed.


Use the new stack synthesis method, which assumes bootstrap resources with well-known names. Requires modern bootstrapping, but in turn allows CI/CD via CDK Pipelines and cross-account deployments out of the box.


If your application uses multiple Amazon API Gateway API keys and associates them to usage plans.


If your application uses Amazon RDS database instance or database clusters, and explicitly specifies the identifier for these.


If your application uses the TLS_V1_2_2019 security policy with Amazon CloudFront distributions. CDK v2 uses security policy TLSv1.2_2021 by default.


If your application uses multiple stacks and you refer to resources from one stack in another, this determines whether absolute or relative path is used to construct AWS CloudFormation exports.


If set to false, the CDK includes metadata when detecting whether a Lambda function has changed. This can cause deployment failures when only the metadata has changed, since duplicate versions are not allowed. There is no need to revert this flag if you've made at least one change to all Lambda Functions in your application.

The syntax for reverting these flags in cdk.json is shown here.

{ "context": { "@aws-cdk/core:newStyleStackSynthesis": false, "@aws-cdk/aws-apigateway:usagePlanKeyOrderInsensitiveId": false, "@aws-cdk/aws-cloudfront:defaultSecurityPolicyTLSv1.2_2021": false, "@aws-cdk/aws-rds:lowercaseDbIdentifier": false, "@aws-cdk/core:stackRelativeExports": false, "@aws-cdk/aws-lambda:recognizeVersionProps": false } }