Getting started with the AWS CDK
This topic introduces you to important AWS CDK concepts and describes how to install and configure the AWS CDK. When you're done, you'll be ready to create your first AWS CDK app.
Your background
The AWS Cloud Development Kit (AWS CDK) lets you define your cloud infrastructure as code in one of five supported programming languages. It is intended for moderately to highly experienced AWS users.
Ideally, you already have experience with popular AWS services, particularly AWS Identity and Access Management
Familiarity with AWS CloudFormation
Finally, you should be proficient in the programming language you intend to use with the AWS CDK.
Key concepts
The AWS CDK is designed around a handful of important concepts. We will introduce a few of these here briefly. Follow the links to learn more, or see the Concepts topics in this guide's Table of Contents.
An AWS CDK app is an application written in TypeScript, JavaScript, Python, Java, or C# that uses the AWS CDK to define AWS infrastructure. An app defines one or more stacks. Stacks (equivalent to AWS CloudFormation stacks) contain constructs, each of which defines one or more concrete AWS resources, such as Amazon S3 buckets, Lambda functions, Amazon DynamoDB tables, and so on.
Constructs (as well as stacks and apps) are represented as types in your programming language of choice. You instantiate constructs within a stack to declare them to AWS, and connect them to each other using well-defined interfaces.
The AWS CDK includes the AWS CDK Toolkit (also called the CLI), a command-line tool for working with your AWS CDK apps and stacks. Among other functions, the Toolkit provides the ability to convert one or more AWS CDK stacks to AWS CloudFormation templates and related assets (a process called synthesis) and to deploy your stacks to an AWS account.
The AWS CDK includes a library of AWS constructs called the AWS Construct Library. Each AWS service has at least one corresponding module in the library containing the constructs that represent that service's resources.
Constructs come in three fundamental flavors:
-
AWS CloudFormation-only or L1 (short for "level 1"). These constructs correspond directly to resource types defined by AWS CloudFormation. In fact, these constructs are automatically generated from the AWS CloudFormation specification, so when a new AWS service is launched, the AWS CDK supports it as soon as AWS CloudFormation does.
AWS CloudFormation resources always have names that begin with
Cfn
. For example, in the Amazon S3 module,CfnBucket
is the L1 module for an Amazon S3 bucket. -
Curated or L2. These constructs are carefully developed by the AWS CDK team to address specific use cases and simplify infrastructure development. For the most part, they encapsulate L1 modules, providing sensible defaults and best-practice security policies. For example, in the Amazon S3 module,
Bucket
is the L2 module for an Amazon S3 bucket.L2 modules may also define supporting resources needed by the primary resource. Some services have more than one L2 module in the Construct Library for organizational purposes.
-
Patterns or L3. Patterns declare multiple resources to create entire AWS architectures for particular use cases. All the plumbing is already hooked up, and configuration is boiled down to a few important parameters. In the AWS Construct Library, patterns are in separate modules from L1 and L2 constructs.
The AWS CDK's core module (usually imported into code as core
or
cdk
) contains constructs used by the AWS CDK itself as well as base classes for
constructs, apps, resources, and other AWS CDK objects.
Supported programming languages
The AWS CDK has first-class support for TypeScript, JavaScript, Python, Java, and C#. (Other JVM and .NET CLR languages may also be used, at least in theory, but we are unable to offer support for them at this time.)
To facilitate supporting so many languages, the AWS CDK is developed in one language
(TypeScript) and language bindings are generated for the other languages through the
use of a
tool called JSII
We have taken pains to make AWS CDK app development in each language follow that language's usual conventions, so writing AWS CDK apps feels natural, not like writing TypeScript in Python (for example). Take a look:
These code snippets are intended for illustration only. They are incomplete and won't run as they are.
The AWS Construct Library is distributed using each language's standard package management tools, including NPM, PyPi, Maven, and NuGet. There's even a version of the AWS CDK API Reference for each language.
To help you use the AWS CDK in your favorite language, this Guide includes topics that explain how to use the AWS CDK in all supported languages.
TypeScript was the first language supported by the AWS CDK, and much AWS CDK example code is written in TypeScript. This Guide includes a topic specifically to show how to adapt TypeScript AWS CDK code for use with the other supported languages. See Translating TypeScript AWS CDK code to other languages.
Prerequisites
Here's what you need install to use the AWS CDK.
All AWS CDK developers, even those working in Python, Java, or C#, need Node.js
Node.js versions 13.0.0 through 13.6.0 are not compatible with the AWS CDK due to compatibility issues with its dependencies.
You must configure your workstation with your credentials and an AWS Region, if you have not already done so. If you have the AWS CLI installed, the easiest way to satisfy this requirement is issue the following command:
aws configure
Provide your AWS access key ID, secret access key, and default region when prompted.
You may also manually create or edit the ~/.aws/config
and
~/.aws/credentials
(macOS/Linux) or
%USERPROFILE%\.aws\config
and
%USERPROFILE%\.aws\credentials
(Windows) files to contain credentials
and a default region, in the following format.
-
In
~/.aws/config
or%USERPROFILE%\.aws\config
[default] region=us-west-2
-
In
~/.aws/credentials
or%USERPROFILE%\.aws\credentials
[default] aws_access_key_id=AKIAI44QH8DHBEXAMPLE aws_secret_access_key=je7MtGbClwBF/2Zp9Utk/h3yCo8nvbEXAMPLEKEY
Alternatively, you can set the environment variables AWS_ACCESS_KEY_ID
,
AWS_SECRET_ACCESS_KEY
, and AWS_DEFAULT_REGION
to appropriate
values.
We strongly recommend against using your AWS root account for day-to-day tasks. Instead,
create a user in IAM and use its credentials with the CDK. Best practices are to change
this account's access key regularly and to use a least-privileges role (specifying
--role-arn
) when deploying.
Other prerequisites depend on the language in which you develop AWS CDK applications and are as follows.
Install the AWS CDK
Install the AWS CDK Toolkit globally using the following Node Package Manager command.
npm install -g aws-cdk
Run the following command to verify correct installation and print the version number of the AWS CDK.
cdk --version
Bootstrapping
Many AWS CDK stacks that you write will include assets: external files that are deployed with the stack, such as AWS Lambda functions Docker images. The AWS CDK uploads these to an Amazon S3 bucket or other container so they are available to AWS CloudFormation during deployment. Deployment requires that these containers already exist in the account and region you are deploying into. Creating them is called bootstrapping. To bootstrap, issue:
cdk bootstrap
AWS CDK tools
The AWS CDK Toolkit, also known as the Command Line Interface (CLI), is the main tool you use to interact with your AWS CDK app. It executes your code and produces and deploys the AWS CloudFormation templates it generates. It also has deployment, diff, deletion, and troubleshooting capabilities. For more information, see cdk --help or AWS CDK Toolkit (cdk command).
The AWS Toolkit for Visual Studio
Code
Next steps
Where do you go now that you've dipped your toes in the AWS CDK?
-
Come on in; the water's fine! Build your first AWS CDK app.
-
Try the CDK Workshop
for a more in-depth tour involving a more complex project. -
See the API reference to begin exploring the CDK constructs available for your favorite AWS services.
-
Dig deeper into concepts like Environments, Assets, Bootstrapping, Permissions, Runtime context, Parameters, and Escape hatches.
-
Explore Examples
of using the AWS CDK.
The AWS CDK is an open-source project. Want to contribute