This documentation is for the developer preview release of the AWS CDK. Do not use this version of the AWS CDK in production. Subsequent releases of the AWS CDK will likely include breaking changes.

Getting Started with the AWS CDK

This topic describes how to download, install, and configure the AWS CDK.

Installing the AWS CDK

This section describes how to install the AWS CDK, and lists the prerequsites for each supported language.

Prerequisites

You must install Node.js (>= 8.11.x) to use the command-line toolkit and language bindings.

If you use Java, you must set the JAVA_HOME environment variable to the path to where you have installed the JDK on your machine to build an AWS CDK app in Java.

Specify your credentials and region with the AWS CLI. You must specify both your credentials and a region to use the toolkit. See credentials for information on using the AWS CLI to specify your credentials.

Installing the Command-Line Toolkit

Install the toolkit using the following npm command:

npm install -g aws-cdk

Run the following command to see the currently installed version of the toolkit (this guide was written for 0.22.0):

cdk --version

Configuring the AWS CDK

You must specify your default credentials and region to use the toolkit.

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

You can also set environment variables for your default credentials and region. Environment variables take precedence over settings in the credentials or config file.

  • AWS_ACCESS_KEY_ID specifies your access key
  • AWS_SECRET_ACCESS_KEY specifies your secret access key
  • AWS_DEFAULT_REGION specifies your default region

See Environment Variables in the CLI User Guide for details.

Note

The China regions (cn-north-1 and cn-northwest-1) do not support version reporting.

See version_reporting for more details and how to opt-out

The AWS CDK toolkit needs to know how to execute your AWS CDK app. It requires that the --app command-line option points to an executable program that adheres to the toolkit’s protocol. Although you can include an --app option every time you use the toolkit, we recommend that you instead create a cdk.json file at the root of your project directory with the following content:

Define the --app option in a cdk.json file:

{
  "app": "dotnet run --project HelloCdk.csproj"
}

Define the --app option in cdk.json to execute hello-cdk.js using node:

{
  "app": "node bin/hello-cdk.js"
}

Define the --app option in cdk.json to execute hello-cdk.js using node:

{
  "app": "node bin/hello-cdk.js"
}

Specify a CLASSPATH, which contains both the compiled code and dependencies, to execute the Java program.

Use maven-dependency-plugin in your pom.xml file to produce the file .classpath.txt whenever the project is compiled:

<build>
    <plugins>
        <!-- ... -->

        <!-- Emit the classpath to ./.classpath.txt so cdk.json can use it -->
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-dependency-plugin</artifactId>
            <version>2.8</version>
            <executions>
            <execution>
                <id>build-classpath</id>
                <phase>generate-sources</phase>
                <goals>
                    <goal>build-classpath</goal>
                </goals>
                <configuration>
                    <outputFile>.classpath.txt</outputFile>
                </configuration>
            </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Run mvn compile and verify that .classpath.txt exists:

mvn compile
ls .classpath.txt

Create a shim app.sh to execute the AWS CDK Java app:

#!/bin/bash
exec java -cp target/classes:$(cat .classpath.txt) com.acme.MyApp app $@

Define the --app option in cdk.json:

{
  "app": "/bin/bash ./app.sh"
}