Getting Started With the AWS CDK

This topic describes how to install and configure the AWS CDK and create your first AWS CDK app.

Prerequisites

AWS CDK command line tools

Node.js (>= 8.11.x)
You must specify both your credentials and an AWS Region to use the AWS CDK Toolkit;, as described in Specifying Your Credentials and Region.

TypeScriptJavaScriptJavaC#Python

TypeScript

TypeScript >= 2.7

JavaScript

none

Java

Maven 3.5.4 and Java 8
Set the JAVA_HOME environment variable to the path to where you have installed the JDK on your machine

C#

.NET standard 2.0 compatible implementation:

.NET Core >= 2.0
.NET Framework >= 4.6.1
Mono >= 5.4

Python

Python >= 3.6

Installing the AWS CDK

Install the AWS CDK using the following command.


npm install -g aws-cdk

Run the following command to see the version number of the AWS CDK.


cdk --version

Updating Your Language Dependencies

If you get an error message that your language framework is out of date, use one of the following commands to update the components that the AWS CDK needs to support the language.

TypeScriptJavaScriptJavaC#Python

TypeScript


npx npm-check-updates -u

JavaScript


npx npm-check-updates -u

Java


mvn versions:use-latest-versions

C#


nuget update

Python


pip install --upgrade aws-cdk.cdk

You might have to call this multiple times to update all dependencies.

Using the env Property to Specify Account and Region

You can use the env property on a stack to specify the account and region used when deploying a stack, as shown in the following example, where REGION is the region and ACCOUNT is the account ID.


new MyStack(app, { env: { region: 'REGION', account: 'ACCOUNT' } });

Note

The AWS CDK team recommends that you explicitly set your account and region using the env property on a stack when you deploy stacks to production.

Since you can create any number of stacks in any of your accounts in any region that supports all of the stack's resources, the AWS CDK team recommends that you create your production stacks in one AWS CDK app, and deploy them as necessary. For example, if you own three accounts, with account IDs ONE, TWO, and THREE and want to be able to deploy each one in us-west-2 and us-east-1, you might declare them as:


new MyStack(app, 'Stack-One-W', { env: { account: 'ONE', region: 'us-west-2' }});
new MyStack(app, 'Stack-One-E', { env: { account: 'ONE', region: 'us-east-1' }});
new MyStack(app, 'Stack-Two-W', { env: { account: 'TWO', region: 'us-west-2' }});
new MyStack(app, 'Stack-Two-E', { env: { account: 'TWO', region: 'us-east-1' }});
new MyStack(app, 'Stack-Three-W', { env: { account: 'THREE', region: 'us-west-2' }});
new MyStack(app, 'Stack-Three-E', { env: { account: 'THREE', region: 'us-east-1' }});

And deploy the stack for account TWO in us-east-1 with:


cdk deploy Stack-Two-E

Note

If the existing credentials do not have permission to create resources within the account you specify, the AWS CDK returns an AWS CloudFormation error when you attempt to deploy the stack.

Specifying Your Credentials and Region

You must specify your credentials and an AWS Region to use the AWS CDK Toolkit. The CDK looks for credentials and region in the following order:

Using the --profile option to cdk commands.
Using environment variables.
Using the default profile as set by the AWS Command Line Interface (AWS CLI).

Using the --profile Option to Specify Credentials and Region

Use the --profile PROFILE option to a cdk command to use a specific profile when executing the command.

For example, if the ~/.aws/config (Linux or Mac) or %USERPROFILE%\.aws\config (Windows) file contains the following profile:


[profile test]
aws_access_key_id=AKIAI44QH8DHBEXAMPLE
aws_secret_access_key=je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY
region=us-west-2

You can deploy your app using the test profile with the following command.


cdk deploy --profile test

Note

The profile must contain the access key, secret access key, and region.

See Named Profiles in the AWS CLI documentation for details.

Using Environment Variables to Specify Credentials and a Region

Use environment variables to specify your credentials and region.

AWS_ACCESS_KEY_ID – Specifies your access key.
AWS_SECRET_ACCESS_KEY – Specifies your secret access key.
AWS_DEFAULT_REGION – Specifies your default Region.

For example, to set the region to us-east-2 on Linux or macOS:


export AWS_DEFAULT_REGION=us-east-2

To do the same on Windows:


set AWS_DEFAULT_REGION=us-east-2

See Environment Variables in the AWS Command Line Interface User Guide for details.

Using the AWS CLI to Specify Credentials and a Region

Use the AWS Command Line Interface aws configure command to specify your default credentials and a region.

Hello World Tutorial

The typical workflow for creating a new app is:

Create the app directory.
Initialize the app.
Add code to the app.
Compile the app, if necessary.
To deploy the resources defined in the app.
Test the app.
If there are any issues, loop through modify, compile (if necessary), deploy, and test again.

And of course, keep your code under version control.

This tutorial walks you through how to create and deploy a simple AWS CDK app, from initializing the project to deploying the resulting AWS CloudFormation template. The app contains one resource, an Amazon S3 bucket.

Creating the App Directory

Create a directory for your app with an empty Git repository.


mkdir hello-cdk
cd hello-cdk

Initializing the App

Initialize an app, where LANGUAGE is one of the supported programming languages: csharp (C#), java (Java), python (Python), or typescript (TypeScript) and TEMPLATE is an optional template that creates an app with different resources than the default app that cdk init creates for the language.

cdk init --language LANGUAGE [TEMPLATE]

The following table describes the templates provided by the supported languages.

Language	Template	Description
C#	none	Creates a CDK app with two stacks. Both stacks containing an SQS queue, an SNS topic, an IAM policy document so the topic could send messages to the queue, and a user-created construct. Each stack calls the user-created construct to create five S3 buckets, create a new user, and give the user access to the S3 buckets.
Java	none	Same as C#
Python	none	Creates an empty CDK app.
Python	sample-app	Same as C#, but four buckets
TypeScript	none	Creates an empty CDK app.
TypeScript	sample-app	Creates a CDK app with stack containing an SQS queue, an SNS topic, and an IAM policy document so the topic could send messages to the queue.

TypeScriptJavaScriptJavaC#Python

TypeScript


cdk init --language typescript

JavaScript


cdk init --language javascript

Java


cdk init --language java

Once the init command finishes, we need to modify the template's output.

Open src/main/java/com/myorg/HelloApp.java.
Change the two stacks to one:
```
new HelloStack(app, "HelloCdkStack");
```

C#


cdk init --language csharp

Once the init command finishes, we need to modify the template's output.

Open src/HelloCdk/Program.cs.

Change the two stacks to one:


new HelloStack(app, "HelloCdkStack", new StackProps());

Open src/HelloCdk/HelloStack.cs.
Delete all of the using statements except the first.
```
using Amazon.CDK;
```
Delete everything from the constructor.

Python


cdk init --language python

Once the init command finishes, your prompt should show (.env), indicating you are running under virtualenv. If not, you must perform one or two more tasks, depending upon your operating system.

On Linux/MacOS:


python3 -m venv .env
source .env/bin/activate

On Windows:


.env\Scripts\activate.bat

Once you've got your virtualenv running, run the following command to install the required dependencies.


pip install -r requirements.txt

Change the instantiation of HelloCdkStack in app.py to the following.


HelloCdkStack(app, "HelloCdkStack")

Compiling the App

Compile your program, as follows.

TypeScriptJavaScriptJavaC#Python

TypeScript


npm run build

JavaScript

Nothing to compile.

Java


mvn compile

C#


dotnet build src

Python

Nothing to compile.

Note

If you are using Java and get annoyed by the [INFO] log messages, you can suppress them by including the -q option to your mvn commands. This includes changing cdk.json to:


"app": "mvn -q exec:java"

Listing the Stacks in the App

List the stacks in the app.


cdk ls

The result is just the name of the stack.

HelloCdkStack

Adding an Amazon S3 Bucket

At this point, what can you do with this app? Nothing, because the stack is empty, so there's nothing to deploy. Let's define an Amazon S3 bucket.

Install the @aws-cdk/aws-s3 package.

TypeScriptJavaScriptJavaC#Python

TypeScript


npm install @aws-cdk/aws-s3

JavaScript


npm install @aws-cdk/aws-s3

Java

If necessary, add the following to pom.xml, where CDK-VERSION is the version of the AWS CDK.


<dependency>
  <groupId>software.amazon.awscdk</groupId>
  <artifactId>s3</artifactId>
  <version>CDK-VERSION</version>
</dependency>

C#

Run the following command in the src/HelloCdk directory.


dotnet add package Amazon.CDK.AWS.S3

Python


pip install aws-cdk.aws-s3

You might have to execute this command multiple times to resolve dependencies.

Next, define an Amazon S3 bucket in the stack. Amazon S3 buckets are represented by the Bucket class.

TypeScriptJavaScriptJavaC#Python

TypeScript

In lib/hello-cdk-stack.ts:


import cdk = require('@aws-cdk/cdk');
import s3 = require('@aws-cdk/aws-s3');

export class HelloCdkStack extends cdk.Stack {
  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    new s3.Bucket(this, 'MyFirstBucket', {
      versioned: true
    });
  }
}

JavaScript

In index.js:


const cdk = require('@aws-cdk/cdk');
const s3 = require('@aws-cdk/aws-s3');

class MyStack extends cdk.Stack {
    constructor(scope, id, props) {
        super(scope, id, props);

        new s3.Bucket(this, 'MyFirstBucket', {
            versioned: true
        });
    }
}

Java

In src/main/java/com/myorg/HelloStack.java:


package com.myorg;

import software.amazon.awscdk.Construct;
import software.amazon.awscdk.Stack;
import software.amazon.awscdk.StackProps;
import software.amazon.awscdk.services.s3.Bucket;
import software.amazon.awscdk.services.s3.BucketProps;

public class HelloStack extends Stack {
    public HelloStack(final Construct parent, final String id) {
        this(parent, id, null);
    }

    public HelloStack(final Construct parent, final String id, final StackProps props) {
        super(parent, id, props);

        new Bucket(this, "MyFirstBucket", BucketProps.builder()
            .withVersioned(true)
            .build());
    }
}

C#

Update HelloStack.cs to include a Amazon S3 bucket with versioning enabled.


using Amazon.CDK;
using Amazon.CDK.AWS.S3;

namespace HelloCdk
{
    public class HelloStack : Stack
    {
        public HelloStack(Construct parent, string id, IStackProps props) : base(parent, id, props)
        {
            new Bucket(this, "MyFirstBucket", new BucketProps
            {
                Versioned = true
            });
        }
    }
}

Python

Replace the import statement in hello_cdk_stack.py in the hello_cdk directory with the following code.


from aws_cdk import (
    aws_s3 as s3,
    cdk
)

Replace the comment with the following code.


bucket = s3.Bucket(self, 
    "MyFirstBucket", 
    versioned=True,)

Notice a few things:

Bucket is a construct. This means it's initialization signature has scope, id, and props and it is a child of the stack.
MyFirstBucket is the id of the bucket construct, not the physical name of the Amazon S3 bucket. The logical ID is used to uniquely identify resources in your stack across deployments. To specify a physical name for your bucket, set the bucketName property when you define your bucket.
Because the bucket's versioned property is true, versioning is enabled on the bucket.

Compile your program, as follows.

TypeScriptJavaScriptJavaC#Python

TypeScript


npm run build

JavaScript

Nothing to compile.

Java


mvn compile

C#


dotnet build src

Python

Nothing to compile.

Synthesizing an AWS CloudFormation Template

Synthesize an AWS CloudFormation template for the app, as follows. If you get an error like "--app is required...", it's because you are running the command from within the hello_cdk sub-directory. Navigate to the parent directory and try again.


cdk synth

This command executes the AWS CDK app and synthesizes an AWS CloudFormation template for the HelloCdkStack stack. You should see something similar to the following, where VERSION is the version of the AWS CDK.

Resources:
  MyFirstBucketB8884501:
    Type: AWS::S3::Bucket
    Properties:
      VersioningConfiguration:
        Status: Enabled
    Metadata:
      aws:cdk:path: HelloCdkStack/MyFirstBucket/Resource
  CDKMetadata:
    Type: AWS::CDK::Metadata
    Properties:
      Modules: "@aws-cdk/aws-codepipeline-api=VERSION,@aws-cdk/aws-events=VERSION,@aws-c\
        dk/aws-iam=VERSION,@aws-cdk/aws-kms=VERSION,@aws-cdk/aws-s3=VERSION,@aws-c\
        dk/aws-s3-notifications=VERSION,@aws-cdk/cdk=VERSION,@aws-cdk/cx-api=VERSION\
        .0,hello-cdk=0.1.0"

You can see that the stack contains an AWS::S3::Bucket resource with the versioning configuration we want.

Note

The toolkit automatically added the AWS::CDK::Metadata resource to your template. The AWS CDK uses metadata to gain insight into how the AWS CDK is used. One possible benefit is that the CDK team could notify users if a construct is going to be deprecated. For details, including how to opt out of version reporting, see Version Reporting .

Deploying the Stack

Deploy the app, as follows.


cdk deploy

The deploy command synthesizes an AWS CloudFormation template from the app, and then invokes the AWS CloudFormation create/update API to deploy it into your AWS account. If your code includes changes to your existing infrastructure, the command displays information about those changes and requires you to confirm them before it deploys the changes. The command displays information as it completes various steps in the process. There is no mechanism to detect or react to any specific step in the process.

Modifying the App

Configure the bucket to use AWS Key Management Service (AWS KMS) managed encryption.

TypeScriptJavaScriptJavaC#Python

TypeScript

Update lib/hello-cdk-stack.ts


new s3.Bucket(this, 'MyFirstBucket', {
    versioned: true,
    encryption: s3.BucketEncryption.KmsManaged
});

JavaScript

Update index.js.


new s3.Bucket(this, 'MyFirstBucket', {
    versioned: true,
    encryption: s3.BucketEncryption.KmsManaged
});

Java

Update src/main/java/com/myorg/HelloStack.java.


import software.amazon.awscdk.services.s3.BucketEncryption;


new Bucket(this, "MyFirstBucket", BucketProps.builder()
    .withVersioned(true)
    .withEncryption(BucketEncryption.KmsManaged)
    .build());

C#

Update HelloStack.cs.


new Bucket(this, "MyFirstBucket", new BucketProps
{
    Versioned = true,
    Encryption = BucketEncryption.KmsManaged
});

Python


bucket = s3.Bucket(self, 
    "MyFirstBucket", 
    versioned=True,
    encryption=s3.BucketEncryption.KmsManaged,)

Compile your program, as follows.

TypeScriptJavaScriptJavaC#Python

TypeScript


npm run build

JavaScript

Nothing to compile.

Java


mvn compile

C#


dotnet build src

Python

Nothing to compile.

Preparing for Deployment

Before you deploy the updated app, evaluate the difference between the AWS CDK app and the deployed app.


cdk diff

The toolkit queries your AWS account for the current AWS CloudFormation template for the hello-cdk stack, and compares the result with the template synthesized from the app. The Resources section of the output should look like the following.

Stack HelloCdkStack
Resources
[~] AWS::S3::Bucket MyFirstBucket MyFirstBucketB8884501
 |- [+] BucketEncryption
     |- {"ServerSideEncryptionConfiguration":[{"ServerSideEncryptionByDefault":{"SSEAlgorithm":"aws:kms"}}]}

As you can see, the diff indicates that the ServerSideEncryptionConfiguration property of the bucket is now set to enable server-side encryption.

You can also see that the bucket isn't going to be replaced, but will be updated instead (Updating MyFirstBucket...).

Deploy the changes.


cdk deploy

Enter y to approve the changes and deploy the updated stack. The AWS CDK Toolkit updates the bucket configuration to enable server-side AWS KMS encryption for the bucket. The final output is the ARN of the stack, where REGION is your default region, ACCOUNT-ID is your account ID, and ID is a unique identifier for the bucket or stack.

HelloCdkStack: deploying...
HelloCdkStack: creating CloudFormation changeset...
 0/2 | 10:55:30 AM | UPDATE_IN_PROGRESS   | AWS::S3::Bucket    | MyFirstBucket (MyFirstBucketID) 
 1/2 | 10:55:50 AM | UPDATE_COMPLETE      | AWS::S3::Bucket    | MyFirstBucket (MyFirstBucketID) 

HelloCdkStack

Stack ARN:
arn:aws:cloudformation:REGION:ACCOUNT-ID:stack/HelloCdkStack/ID

Destroying the App's Resources

Destroy the app's resources to avoid incurring any costs from the resources created in this tutorial, as follows.


cdk destroy

Enter y to approve the changes and delete any stack resources. In some cases this command fails, such as when a resource isn't empty and must be empty before it can be destroyed. See Delete Stack Fails in the AWS CloudFormation User Guide for details.

Warning Javascript is disabled or is unavailable in your browser.

To use the AWS Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

« Previous Next »