What are Feature Flags in AWS CDK

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.

Copied!
{
  "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.

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

Copied!
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.

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:

Copied!
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:

Copied!
{
  "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:

Copied!
npx aws-cdk synth

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

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 #

• AWS CDK Tutorial for Beginners - Step-by-Step Guide
• How does AWS CDK work
• What is a Token in AWS CDK
• CDK Constructs - Complete Guide
• What is an identifier (id) in AWS CDK
• How to use Context in AWS CDK
• How to use Parameters in AWS CDK