What are Feature Flags in AWS CDK


Borislav Hadzhiev

Wed Apr 13 20223 min read


Photo by Meng Jia

Updated - Wed Apr 13 2022

Feature Flags in AWS CDK #

Feature flags are key-value pairs that enable us to opt in or opt out of breaking changes, introduced outside of major version releases of an AWS CDK package.

Feature flags enable the AWS CDK team to implement features that add breaking changes without waiting to release a major version.

By switching the boolean value of a feature flag to false, we roll back the behavior of the specific CDK package.

We manage feature flags in the cdk.json file in the root directory of our project.

Here is an example of how a cdk.json file that contains feature flags looks.

{ "app": "npx ts-node --prefer-ts-exts infra/app.ts", "context": { "@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 } }

We first have the app key, which maps to a command that tells the CDK CLI how to run our code. In this case, because I'm using TypeScript, the code will be compiled down to javascript using ts-node.

Next, we have the context key, which maps to an object, containing different feature flags.

We can see that there is a pattern in the names of the feature flags - they start with the name of the package that introduces the breaking change - for example @aws-cdk/aws-rds.

To roll back a specific functionality to an the old behavior, we can set the corresponding feature flag to false.

Since most feature flags are necessary bug fixes or improvements that introduce breaking changes, setting a specific feature flag to false means that we keep the previous behavior of the CDK package, along with the limitation.

The default behavior is that when we initialize a CDK application using cdk init all of the feature flags are set to true.

npx aws-cdk init --language typescript

Having the feature flags functionality enables the AWS CDK team to introduce breaking changes, outside of major version releases, and default the feature flags to false for existing projects.

Existing projects are not affected by the breaking changes, unless they explicitly set the feature flag to true.

On an existing project we can pick and choose which features and breaking changes we want to introduce, by configuring the key-value pairs in our cdk.json file.

Accessing Feature Flag values in our CDK Code #

In order to get access to the value of a feature flag we have to use the FeatureFlags class.

Let's use the isEnabled method on the FeatureFlags class and print the values to the console:

import * as cdk from 'aws-cdk-lib'; export class MyCdkStack extends cdk.Stack { constructor(scope: cdk.App, id: string, props?: cdk.StackProps) { super(scope, id, props); console.log( 'apig usage plan key order insensitive id 👉', cdk.FeatureFlags.of(this).isEnabled( '@aws-cdk/aws-apigateway:usagePlanKeyOrderInsensitiveId', ), ); console.log( 'aws rds lowercaseDbIdentifier 👉', cdk.FeatureFlags.of(this).isEnabled( '@aws-cdk/aws-rds:lowercaseDbIdentifier', ), ); } }

In the snippet above we call the isEnabled method passing in the name of the feature flag.

For demonstration purposes I'll set the value of the @aws-cdk/aws-rds:lowercaseDbIdentifier flag to true in the cdk.json file:

{ "app": "npx ts-node --prefer-ts-exts infra/app.ts", "context": { // ... rest "@aws-cdk/aws-secretsmanager:parseOwnedSecretName": false, "@aws-cdk/aws-rds:lowercaseDbIdentifier": true } }

Let's synth our cdk stack:

npx aws-cdk synth

If we now look at the output from our console.log calls, we get:

feature flag values

Conclusion #

Feature flags enable the AWS CDK team to introduce breaking changes without waiting for major CDK version releases.

For an existing project, feature flags will default to false, which means that there won't be any breaking changes, however we also won't be opted in for the functionality improvement or bug fix that was introduced.

In order to see if any breaking changes were introduced in a particular version of a CDK package, we can look at the changelog.

Further Reading #

Use the search field on my Home Page to filter through my more than 1,000 articles.