What does CDK Synth do in AWS CDK

avatar

Borislav Hadzhiev

Fri Apr 23 20213 min read

Updated on Fri Apr 23 2021

The cdk synth command generates and prints the CloudFormation equivalent of the CDK stack we've defined. The output is then stored in the cdk.out directory.

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
{
  "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
import * as s3 from '@aws-cdk/aws-s3';
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);

    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
npx cdk synth

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

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
import * as cdk from '@aws-cdk/core';
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,
  },
});

In the code snippet, I've instantiated our CDK stack 2 times.

If I synthesize the stack now with:

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

Further Reading #

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