Borislav Hadzhiev
Wed Apr 13 2022·3 min read
Photo by Meng Jia
Updated - Wed Apr 13 2022
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
.
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.
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.
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 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.