What does CDK.JSON do in AWS CDK


Borislav Hadzhiev

Fri Apr 16 20213 min read

The purpose of CDK.JSON in a CDK project #

When we initialize a new CDK app with the cdk init command the CDK CLI bootstraps a cdk.json file in the root directory.

For example:

mkdir cdk-app cd cdk-app npx cdk init app --language=typescript

The contents of the cdk.json file look something like:

{ "app": "npx ts-node --prefer-ts-exts bin/cdk-app.ts", "context": { "aws-cdk:enableDiffNoFail": "true" // ...rest } }

First we have the app key, which points to a command telling the CDK CLI how to execute our CDK code.

npx ts-node --prefer-ts-exts bin/cdk-app.ts

The bin/cdk-app.ts file is where our CDK App and stacks are instantiated, it's the entry point of our CDK application:

const app = new cdk.App(); new CdkAppStack(app, 'cdk-stack', { env: { account: process.env.CDK_DEFAULT_ACCOUNT, region: process.env.CDK_DEFAULT_REGION, }, });

This example was initialized using TypeScript so our code has to be compiled down to JavaScript before it can be executed, that's exactly what the ts-node command does.

The value of the app key is going to be programming language specific.

Next, we have the context key. Context is a combination of key-value pairs, that we can set in our CDK application.

CDK uses context to keep track of the so called feature flags. Feature flags enable the CDK team to push new features that introduce breaking changes, outside of major version releases.

The feature flags point to a boolean value, i.e.:

{ "context": { "@aws-cdk/aws-kms:defaultKeyPolicies": true } }

The name of the feature flag starts with the name of the package that introduces the breaking change.

For new projects, initialized with the cdk init command the value of all feature flags is set to true. However, if we're working on an existing project we can decide for ourselves, if we want to opt in, after we research, whether this feature or bug fix might cause breaking changes in our CDK application.

Another property that's available in the cdk.json file is the versionReporting property:

{ // ๐Ÿ‘‡ turn off metadata reporting "versionReporting": false, "app": "npx ts-node --prefer-ts-exts infra/app.ts", "context": { "@aws-cdk/core:enableStackNameDuplicates": "true", // ... rest } }

The versionReporting property allows us to turn off Metadata Reporting in CDK.

In short, Metadata is a CloudFormation feature, that allows us to specify additional details about our template.

The CDK team uses Metadata to collect analytics in regards to how developers use the CDK service.

I have nothing against that, however I don't like having any extra stuff in my CloudFormation templates.

When we run the cdk synth command the CDK CLI generates a CloudFormation template in the cdk.out directory.

It's a matter of personal preference, judge for yourself.

Template with metadata:

cdk out metadata

Template without metadata:

cdk out no metadata

Summary #

The two main objectives of the cdk.json file are:

  • to tell the CDK CLI how to execute our CDK code
  • and keep track of feature flags, which enable the CDK team to safely roll out new features and bug fixes that cause breaking changes

Further Reading #

Add me on LinkedIn

I'm a Web Developer with TypeScript, React.js, Node.js and AWS experience.

Let's connect on LinkedIn

Join my newsletter

I'll send you 1 email a week with links to all of the articles I've written that week

Buy Me A Coffee