What does CDK Synth do in AWS CDK

# CDK synth - introduction

The cdk synth command from the CDK CLI generates and prints the CloudFormation equivalent of the CDK stack we've defined.

The code we write in our CDK applications gets compiled down to CloudFormation before it gets deployed.

CDK is just an abstraction level above CloudFormation that aims to improve developer experience. Our CDK code eventually ends up as CloudFormation before it gets deployed.

# CDK synth - diving deep

In order to synthesize a CloudFormation template, the CDK CLI has to first execute our CDK app.

I often run cdk synth to execute my app and see if I get any errors.

The cdk synth command knows how to execute our app, because we've specified the command as the value of the app key in our cdk.json file. This command is different for the different programming languages CDK supports.

The code for this article is available on GitHub

CDK projects written in TypeScript have to be compiled down to JavaScript, which is done by executing the value of the app key in the cdk.json file:

cdk.json

Copied!
{
  "app": "npx ts-node --prefer-ts-exts infra/app.ts",
  "context": {
    // ...
  }
}

In order to demo the cdk synth command, I'll create a small CDK app, consisting of a single s3 bucket.

lib/cdk-starter-stack.ts

Copied!
import * as s3 from 'aws-cdk-lib/aws-s3';
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);

    new s3.Bucket(this, 'avatars-bucket', {
      removalPolicy: cdk.RemovalPolicy.DESTROY,
    });
  }
}

const app = new cdk.App();

new MyCdkStack(app, 'my-cdk-stack', {
  stackName: 'my-cdk-stack',
  env: {
    region: process.env.CDK_DEFAULT_REGION,
    account: process.env.CDK_DEFAULT_ACCOUNT,
  },
});

I'll now run the synth command:

shell

Copied!
npx aws-cdk synth

The output I get is the CloudFormation equivalent to my CDK stack (if we ignore the metadata section):

Copied!
Resources:
  avatarsbucketE3043F49:
    Type: AWS::S3::Bucket
    UpdateReplacePolicy: Delete
    DeletionPolicy: Delete
    Metadata:
      aws:cdk:path: my-cdk-stack/avatars-bucket/Resource
  CDKMetadata:
    Type: AWS::CDK::Metadata
    Properties:
      Analytics: v2:deflate64:H...
    Metadata:
      aws:cdk:path: my-cdk-stack/CDKMetadata/Default

After I ran the cdk synth command the CDK CLI created a cdk.out folder in the root directory of my project:

cdk out folder

The cdk.out folder contains the generated cloudformation template(s) and asset files if our application requires any assets.

An example of asset files would be the code for a Lambda function if our CDK application provisioned one.

Because a CDK app can consist of more than one CDK stack, we might end up having multiple CloudFormation templates in the cdk.out directory.

Let's test the behavior of cdk synth if we have more than one stack instantiated in our CDK App:

bin/cdk-starter.ts

Copied!
import * as cdk from 'aws-cdk-lib';
import {MyCdkStack} from '../lib/cdk-starter-stack';

const app = new cdk.App();

new MyCdkStack(app, 'my-cdk-stack-dev', {
  stackName: 'my-cdk-stack-dev',
  env: {
    region: process.env.CDK_DEFAULT_REGION,
    account: process.env.CDK_DEFAULT_ACCOUNT,
  },
});

new MyCdkStack(app, 'my-cdk-stack-prod', {
  stackName: 'my-cdk-stack-prod',
  env: {
    region: process.env.CDK_DEFAULT_REGION,
    account: process.env.CDK_DEFAULT_ACCOUNT,
  },
});

I instantiated our CDK stack 2 times.

If I synthesize the stack now with:

shell

Copied!
npx aws-cdk synth

I get the following output:

cdk synth multiple stacks

The output states that the both of the stacks have been synthesized in the cdk.out directory.

If we look at the contents of the cdk.out directory, we can see that both of our CloudFormation stacks have been generated:

cdk out two stacks

When working with multiple stacks it's better to explicitly name the stacks:

shell

Copied!
npx aws-cdk synth \
  my-cdk-stack-dev \
  my-cdk-stack-prod

The printed output of the cdk synth command is in yaml, however the stored output in our cdk.out directory is in json.

If you want to print the output in json when running cdk synth you can pass the --json flag:

shell

Copied!
npx aws-cdk synth --json my-cdk-stack-dev

# Conclusion

The cdk synth command executes our CDK app, generates the equivalent of our CDK code as a CloudFormation template and stores it in the cdk.out directory.

We can look at the command as a preparation step before a stack deployment.

Note that running the cdk synth command before we run cdk deploy is optional, because CDK will run synth for us before each deployment automatically.

# Additional Resources

You can learn more about the related topics by checking out the following tutorials:

I wrote a book in which I share everything I know about how to become a better, more efficient programmer.

You can use the search field on my Home Page to filter through all of my articles.

What does CDK Synth do in AWS CDK

# CDK synth - introduction

# CDK synth - diving deep

# Conclusion

# Additional Resources

Borislav Hadzhiev