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.

Let's take a look at an example cdk.json file in a project bootstrapped with cdk init:

{
  "app": "npx ts-node --prefer-ts-exts infra/app.ts",
  "context": {
    "@aws-cdk/core:enableStackNameDuplicates": "true",
    "aws-cdk:enableDiffNoFail": "true",
    "@aws-cdk/core:stackRelativeExports": "true",
    "@aws-cdk/aws-ecr-assets:dockerIgnoreSupport": true,
    "@aws-cdk/aws-secretsmanager:parseOwnedSecretName": true,
    "@aws-cdk/aws-kms:defaultKeyPolicies": true
  }
}

We first have the app key, which maps to a command that tells the CDK CLI how to execute 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-kms.

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 / 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 cdk init my-app --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/core';

export class MyCdkStack extends cdk.Stack {
  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    console.log(
      'kms defaultKeyPolicies 👉',
      cdk.FeatureFlags.of(this).isEnabled(
        '@aws-cdk/aws-kms:defaultKeyPolicies',
      ),
    );

    console.log(
      'aws-secretsmngr parseOwnedSecretName 👉',
      cdk.FeatureFlags.of(this).isEnabled(
        '@aws-cdk/aws-secretsmanager:parseOwnedSecretName',
      ),
    );
  }
}

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

For demonstration purposes I'll flip the value of the @aws-cdk/aws-secretsmanager:parseOwnedSecretName to false 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-kms:defaultKeyPolicies": true
  }
}

Let's synth our cdk stack:

npx 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.

If we initialize a new CDK project with cdk init all feature flags will be set to true.

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