How to install AWS CDK (step-by-step guide)

The AWS CDK Toolkit provides the command line interface (CLI) command cdk. This is the primary tool to synthesize your AWS CDK App so it can generate AWS CloudFormation stacks that can be deployed to AWS Cloud.

To install AWS CDK, run the following command in your terminal: npm install -g aws-cdk.

This will install the AWS CDK package globally on your system which then allows you to initialize your first project and start building and deploying code in your AWS account using AWS CDK.

In this article, you’ll learn how you can install AWS CDK and set up the configuration to help you start building and deploying your first CDK app.

How to install AWS Cloud Development Kit (CDK)

We’re using the NPM package manager to install AWS CDK on our machine.

This is a universal installation method, meaning that the following steps can be applied to macOS, Windows, and Linux (Ubuntu).

To install the AWS CDK toolkit on your machine, we use the node package manager in your terminal to install the package globally:

➜ npm install -g aws-cdk

added 180 packages, and audited 181 packages in 7s
found 0 vulnerabilities
~ took 7s

Check the AWS CDK version

Once you’ve installed AWS CDK you can validate that you’re running on the latest version by running the following command in the terminal:

➜ cdk version

2.23.0 (build 50444aa)

As you can see, the AWS CDK is running on version 2 (v2). Version 1 entered maintenance on June 1, 2022. If you have any AWS CDK projects running on AWS CDK v1, I’d highly recommend you migrate to v2.

What are the available AWS CDK commands?

Now that you’ve installed AWS CDK on your system. You might wonder how to run cdk commands in your shell.

You can easily find which commands and arguments are available in the AWS CDK Toolkit by running:

➜ cdk --help

Usage: cdk -a <cdk-app> COMMAND
Commands:
  cdk list [STACKS..]             Lists all stacks in the app      [aliases: ls]
  cdk synthesize [STACKS..]       Synthesizes and prints the CloudFormation
                                  template for this stack       [aliases: synth]
  cdk bootstrap [ENVIRONMENTS..]  Deploys the CDK toolkit stack into an AWS
                                  environment
  cdk deploy [STACKS..]           Deploys the stack(s) named STACKS into your
                                  AWS account
  cdk import [STACK]              Import existing resource(s) into the given
                                  STACK
  cdk watch [STACKS..]            Shortcut for 'deploy --watch'
  cdk destroy [STACKS..]          Destroy the stack(s) named STACKS
  cdk diff [STACKS..]             Compares the specified stack with the deployed
                                  stack or a local template file, and returns
                                  with status 1 if any difference is found
  cdk metadata [STACK]            Returns all metadata associated with this
                                  stack
  cdk acknowledge [ID]            Acknowledge a notice so that it does not show
                                  up anymore                      [aliases: ack]
  cdk notices                     Returns a list of relevant notices
  cdk init [TEMPLATE]             Create a new, empty CDK project from a
                                  template.
  cdk context                     Manage cached context values
  cdk docs                        Opens the reference documentation in a browser
                                                                  [aliases: doc]
  cdk doctor                      Check your set-up for potential problems

Options:
  -a, --app                REQUIRED: command-line for executing your app or a
                           cloud assembly directory (e.g. "node bin/my-app.js")
                                                                        [string]
      --build              Command-line for a pre-synth build           [string]
  -c, --context            Add contextual string parameter (KEY=VALUE)   [array]
  -p, --plugin             Name or path of a node package that extend the CDK
                           features. Can be specified multiple times     [array]
      --trace              Print trace for stack warnings              [boolean]
      --strict             Do not construct stacks with warnings       [boolean]
      --lookups            Perform context lookups (synthesis fails if this is
                           disabled and context lookups need to be performed)
                                                       [boolean] [default: true]
      --ignore-errors      Ignores synthesis errors, which will likely produce
                           an invalid output          [boolean] [default: false]
  -j, --json               Use JSON output instead of YAML when templates are
                           printed to STDOUT          [boolean] [default: false]
  -v, --verbose            Show debug logs (specify multiple times to increase
                           verbosity)                   [count] [default: false]
      --debug              Enable emission of additional debugging information,
                           such as creation stack traces of tokens
                                                      [boolean] [default: false]
      --profile            Use the indicated AWS profile as the default
                           environment                                  [string]
      --proxy              Use the indicated proxy. Will read from HTTPS_PROXY
                           environment variable if not specified        [string]
      --ca-bundle-path     Path to CA certificate to use when validating HTTPS
                           requests. Will read from AWS_CA_BUNDLE environment
                           variable if not specified                    [string]
  -i, --ec2creds           Force trying to fetch EC2 instance credentials.
                           Default: guess EC2 instance status          [boolean]
      --version-reporting  Include the "AWS::CDK::Metadata" resource in
                           synthesized templates (enabled by default)  [boolean]
      --path-metadata      Include "aws:cdk:path" CloudFormation metadata for
                           each resource (enabled by default)
                                                       [boolean] [default: true]
      --asset-metadata     Include "aws:asset:*" CloudFormation metadata for
                           resources that uses assets (enabled by default)
                                                       [boolean] [default: true]
  -r, --role-arn           ARN of Role to use when invoking CloudFormation
                                                                        [string]
      --staging            Copy assets to the output directory (use --no-staging
                           to disable, needed for local debugging the source
                           files with SAM CLI)         [boolean] [default: true]
  -o, --output             Emits the synthesized cloud assembly into a directory
                           (default: cdk.out)                           [string]
      --notices            Show relevant notices                       [boolean]
      --no-color           Removes colors and other style from console output
                                                      [boolean] [default: false]
      --version            Show version number                         [boolean]
  -h, --help               Show help                                   [boolean]

If your app has a single stack, there is no need to specify the stack name

If one of cdk.json or ~/.cdk.json exists, options specified there will be used
as defaults. Settings in cdk.json take precedence.

How to upgrade CDK to latest version

Keeping your AWS CDK up-to-date is crucial for taking advantage of new features and security patches.

The good news is that upgrading to the latest version is a straightforward process. You can use either npm or yarn as your package manager to handle the upgrade, and I’ll walk you through both methods.

Upgrade CDK using npm package manager

If you’ve initially installed AWS CDK using npm, run the following command to update the AWS CDK Toolkit to the latest version:

npm update -g aws-cdk

This command will fetch the latest version of AWS CDK and update it globally on your system.

Once the process is complete, you can verify the upgrade by running cdk --version.

Upgrade CDK using yarn package manager

For those who prefer using yarn as their package manager, the process is equally simple.

Open your terminal and execute the following command to upgrade AWS CDK:

yarn global upgrade aws-cdk

Just like with npm, this will update the AWS CDK Toolkit to the latest version globally.

To confirm that the upgrade was successful, you can run cdk --version.

By keeping your AWS CDK updated, you ensure that you’re leveraging the latest features and improvements, making your cloud infrastructure more robust and efficient.

Create an AWS CDK project

To create an AWS CDK project you can initialize it using the cdk init command. Here you specify your desired template and programming language, see the example for possible options:

➜ cdk init --list

Available templates:
* app: Template for a CDK Application
   └─ cdk init app --language=[csharp|fsharp|go|java|javascript|python|typescript]
* lib: Template for a CDK Construct Library
   └─ cdk init lib --language=typescript
* sample-app: Example CDK Application with some constructs
   └─ cdk init sample-app --language=[csharp|fsharp|java|javascript|python|typescript]

It might be the first time that you’re running AWS CDK. So let’s start out with the sample-app. This project contains some sample resources and demonstrates how a stack is created.

To create the CDK project run the cdk init sample-app --language typescript command in your project folder:

➜ cdk init sample-app --language=typescript

Applying project template sample-app for typescript
# Welcome to your CDK TypeScript project!
You should explore the contents of this project. It demonstrates a CDK app with an instance of a stack (`CdkProjectStack`)
which contains an Amazon SQS queue that is subscribed to an Amazon SNS topic.
The `cdk.json` file tells the CDK Toolkit how to execute your app.
## Useful commands
 * `npm run build`   compile typescript to js
 * `npm run watch`   watch for changes and compile
 * `npm run test`    perform the jest unit tests
 * `cdk deploy`      deploy this stack to your default AWS account/region
 * `cdk diff`        compare deployed stack with current state
 * `cdk synth`       emits the synthesized CloudFormation template
Initializing a new git repository...
Executing npm install...
✅ All done!

The command has automatically created the project structure and the necessary code to run the example app in AWS CDK. The project structure looks like this:

├── README.md
├── bin
│   └── cdk-project.ts
├── cdk.json
├── jest.config.js
├── lib
│   └── cdk-project-stack.ts
├── package-lock.json
├── package.json
├── test
│   └── cdk-project.test.ts
└── tsconfig.json

If you look closely you should see a lib folder at the root of your project folder. This contains the stack which contains the code for the resources.

Since we’ve initialized AWS CDK with a sample-app it already creates an SQS queue and an SNS topic + subscription.

Build your AWS CDK App

Now that we have generated an AWS CDK project with a stack (cdk-project-stack.ts) containing a sample AWS SQS queue, it’s time to build the AWS CDK App.

To build the app we’re running the command: cdk synth. What this will do is that it generates CloudFormation templates based on the code that is defined in the AWS CDK App:

➜ cdk synth

Resources:
  CdkProjectQueueD30BD26F:
    Type: AWS::SQS::Queue
    Properties:
      VisibilityTimeout: 300
    UpdateReplacePolicy: Delete
    DeletionPolicy: Delete
    Metadata:
      aws:cdk:path: CdkProjectStack/CdkProjectQueue/Resource
  CdkProjectQueuePolicy60E3A509:
    Type: AWS::SQS::QueuePolicy
    Properties:
      PolicyDocument:
        Statement:
          - Action: sqs:SendMessage
            Condition:
              ArnEquals:
                aws:SourceArn:
                  Ref: CdkProjectTopicCABDBCE5
            Effect: Allow
            Principal:
              Service: sns.amazonaws.com
            Resource:
              Fn::GetAtt:
                - CdkProjectQueueD30BD26F
                - Arn
        Version: "2012-10-17"
      Queues:
        - Ref: CdkProjectQueueD30BD26F
    Metadata:
      aws:cdk:path: CdkProjectStack/CdkProjectQueue/Policy/Resource
  CdkProjectQueueCdkProjectStackCdkProjectTopicEA58E728E3BEF797:
    Type: AWS::SNS::Subscription
    Properties:
      Protocol: sqs
      TopicArn:
        Ref: CdkProjectTopicCABDBCE5
      Endpoint:
        Fn::GetAtt:
          - CdkProjectQueueD30BD26F
          - Arn
    Metadata:
      aws:cdk:path: CdkProjectStack/CdkProjectQueue/CdkProjectStackCdkProjectTopicEA58E728/Resource
  CdkProjectTopicCABDBCE5:
    Type: AWS::SNS::Topic
    Metadata:
      aws:cdk:path: CdkProjectStack/CdkProjectTopic/Resource
  CDKMetadata:
    Type: AWS::CDK::Metadata
    Properties:
      Analytics: v2:deflate64:H4sIAAAAAAAAE1WNQQ6CMBBFz8K+HZEYL8AFFNwbmNZkhpKiHE2AAA
    Metadata:
      aws:cdk:path: CdkProjectStack/CDKMetadata/Default
    Condition: CDKMetadataAvailable
Conditions:
  CDKMetadataAvailable:
    Fn::Or:
      - Fn::Or:
          - Fn::Equals:
              - Ref: AWS::Region
              - af-south-1
          - Fn::Equals:
              - Ref: AWS::Region
              - ap-east-1
          - Fn::Equals:
              - Ref: AWS::Region
              - ap-northeast-1
          - Fn::Equals:
              - Ref: AWS::Region
              - ap-northeast-2
          - Fn::Equals:
              - Ref: AWS::Region
              - ap-south-1
          - Fn::Equals:
              - Ref: AWS::Region
              - ap-southeast-1
          - Fn::Equals:
              - Ref: AWS::Region
              - ap-southeast-2
          - Fn::Equals:
              - Ref: AWS::Region
              - ca-central-1
          - Fn::Equals:
              - Ref: AWS::Region
              - cn-north-1
          - Fn::Equals:
              - Ref: AWS::Region
              - cn-northwest-1
      - Fn::Or:
          - Fn::Equals:
              - Ref: AWS::Region
              - eu-central-1
          - Fn::Equals:
              - Ref: AWS::Region
              - eu-north-1
          - Fn::Equals:
              - Ref: AWS::Region
              - eu-south-1
          - Fn::Equals:
              - Ref: AWS::Region
              - eu-west-1
          - Fn::Equals:
              - Ref: AWS::Region
              - eu-west-2
          - Fn::Equals:
              - Ref: AWS::Region
              - eu-west-3
          - Fn::Equals:
              - Ref: AWS::Region
              - me-south-1
          - Fn::Equals:
              - Ref: AWS::Region
              - sa-east-1
          - Fn::Equals:
              - Ref: AWS::Region
              - us-east-1
          - Fn::Equals:
              - Ref: AWS::Region
              - us-east-2
      - Fn::Or:
          - Fn::Equals:
              - Ref: AWS::Region
              - us-west-1
          - Fn::Equals:
              - Ref: AWS::Region
              - us-west-2
Parameters:
  BootstrapVersion:
    Type: AWS::SSM::Parameter::Value<String>
    Default: /cdk-bootstrap/hnb659fds/version
    Description: Version of the CDK Bootstrap resources in this environment, automatically retrieved from SSM Parameter Store.
Rules:
  CheckBootstrapVersion:
    Assertions:
      - Assert:
          Fn::Not:
            - Fn::Contains:
                - - "1"
                  - "2"
                  - "3"
                - Ref: BootstrapVersion

As you can see in the result above, the command cdk synth shows the CloudFormation template in YAML format in your terminal.

But for the actual deployment, the template is saved in the cdk.out folder in JSON format.

Deploy your AWS CDK App

To deploy the template that you synthesized with CDK synth on an AWS account. It would help if you had AWS CLI installed on your system and set up an AWS Profile.

If you haven’t set it up yet, then check this blog post in which I explain how to set up AWS CLI including AWS Single Sign-On (SSO).

If you’ve done that you can proceed with the deployment. First, make sure to export your AWS profile with export AWS_PROFILE=<your_aws_profile_name>. Then you can deploy the synthesized template with cdk deploy:

➜ cdk deploy

This deployment will make potentially sensitive changes according to your current security approval level (--require-approval broadening).
Please confirm you intend to make the following modifications:
IAM Statement Changes
(NOTE: There may be security-related changes not in this list. See https://github.com/aws/aws-cdk/issues/1299)
Do you wish to deploy these changes (y/n)? y
CdkProjectStack: deploying...
[0%] start: Publishing 8b185148d5516d058cb628a72cfac1ab6eff61aa5c83bc5c396601822bc9d954:current_account-current_region
[100%] success: Published 8b185148d5516d058cb628a72cfac1ab6eff61aa5c83bc5c396601822bc9d954:current_account-current_region
CdkProjectStack: creating CloudFormation changeset...
[██████████████████████████████████████████████████████████] (6/6)
 ✅  CdkProjectStack
Stack ARN:
arn:aws:cloudformation:eu-central-1:012345678901:stack/CdkProjectStack/5a8b31a0-bff0-11eb-833c-06576399fc58

Conclusion

In this article you’ve learned how to set up AWS CDK, initialize an AWS CDK project, synthesize a CloudFormation template and then deploy it to your AWS account.

If you wish to remove the stack from your AWS account, then run the following command cdk destroy.

AWS CDK – FAQ