What does CDK Diff do in AWS CDK


Borislav Hadzhiev

Fri Apr 23 20213 min read

Updated on Fri Apr 23 2021

The CDK diff command allows us to compare the deployed and local versions of the CloudFormation templates.

CDK diff - introduction #

The cdk diff command outputs the difference between the already deployed CloudFormation template and the CloudFormation template equivalent of our current CDK code.

CDK is just a wrapper around CloudFormation, that enables us to write our infrastructure as code using a programming language (TypeScript, Python, Java ...), rather than a configuration language (yaml, json).

Eventually our CDK code gets compiled down to CloudFormation before it gets deployed.

CDK diff - in depth #

The code for this article is available on GitHub

To demo how the cdk diff command works, I'll create a small CDK app, consisting of a single S3 bucket.

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,

In the code snippet above we just use the Bucket construct to create an S3 bucket.

Let's run the diff command before even deploying:

npx cdk diff

The output looks like:

diff before deploy

The output shows us that if we were to deploy our current CDK code, we'd create an S3 bucket.

When we ran the cdk diff command a couple of things happened behind the scenes:

The CDK CLI ran the cdk synth command.

The cdk synth command first executes the code of our CDK app. It then generates the CloudFormation equivalent of the CDK stack we've defined, and stores the output in the cdk.out directory.

If we look at the contents of the cdk.out directory we can see the CloudFormation equivalent of our CDK stack: CDK out directory

Then the cdk diff command printed the changeset between the template from the cdk.out directory and the deployed CloudFormation template. Since we haven't deployed our stack yet, it just printed what we'd provision if we deployed our stack.

I'll now deploy the stack by running cdk deploy. Then I'll make a small change to the application and run cdk diff again.

- new s3.Bucket(this, 'avatars-bucket', {
+ new s3.Bucket(this, 'another-bucket', {
    removalPolicy: cdk.RemovalPolicy.DESTROY,

I've just changed the id parameter I'm passing to the Bucket construct.

Let's run the cdk diff command again:

npx cdk diff

And look at the output:

diff after change

From the output we see that our bucket will be destroyed and a new one will be created.

By changing the id parameter, we've changed the CloudFormation logical ID of the resource.

We can look at the current Logical ID of our Bucket in the CloudFormation console: cloudformation stack

This is one of the more confusing aspects of CDK and can be quite the footgun, so I've written another article on the topic - Identifiers in AWS CDK.

Running the cdk diff command before deploying is a very good practice, especially when updating stateful resources like databases.

As a side note we can also run the cdk diff command to compare between a cloudformation template on our local file system and our current CDK code:

npx cdk diff \
  --template cdk.out/my-cdk-stack.template.json \

Conclusion #

We use the cdk diff command to compare between the already deployed CloudFormation template and the CloudFormation template that has been generated by running the cdk synth command and is equivalent to the current state of our CDK app.

It's always a good practice to run the cdk diff command before we deploy, to avoid surprises with resources getting deleted due to a change in logical IDs.

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