This is the AWS CDK v2 Developer Guide. The older CDK v1 entered maintenance on June 1, 2022 and ended support on June 1, 2023.
Getting started with the AWS CDK
Get started with the AWS Cloud Development Kit (AWS CDK) by installing the AWS CDK CLI and creating your first CDK app.
Topics
Prerequisites
- Recommended resources
-
Before getting started with the AWS CDK, we recommend a basic understanding of the following:
-
An introduction to the AWS CDK. To learn more, see What is the AWS CDK?
-
Core concepts behind the AWS CDK. To learn more, see Learn AWS CDK core concepts.
-
The AWS services that you want to manage with the AWS CDK.
-
AWS Identity and Access Management. For more information, see What is IAM? and What is IAM Identity Center?
-
AWS CloudFormation since the AWS CDK utilizes the AWS CloudFormation service to provision resources created in the CDK. To learn more, see What is AWS CloudFormation?
-
The supported programming language that you plan to use with the AWS CDK.
-
- Prepare your local environment
-
All AWS CDK developers, regardless of your preferred language, need Node.js
14.15.0 or later. All supported programming languages use the same backend, which runs on Node.js. We recommend a version in active long-term support . Your organization may have a different recommendation. Important
Node.js versions 13.0.0 through 13.6.0 are not compatible with the AWS CDK due to compatibility issues with its dependencies.
Other prerequisites depend on the language in which you develop AWS CDK applications and are as follows.
For more detailed information, see the Prerequisites section for your language:
Third-party language deprecation
Each language version is only supported until it is EOL (End Of Life) and is subject to change with prior notice.
Step 1: Create an AWS account
If you are new to AWS, you must sign up for an AWS account and create an administrative user. For more information, see Getting set up with IAM in the IAM User Guide.
When you interact with AWS, you specify your AWS security credentials to verify who you are and whether you have permission to access the resources that you are requesting. AWS uses the security credentials to authenticate and authorize your requests. To learn more, see AWS security credentials in the IAM User Guide.
Step 2: Configure programmatic access
When developing with the AWS CDK in your local environment, you will rely on the AWS CDK CLI to interact with AWS services and manage your AWS resources. To use the AWS CDK CLI, you must configure programmatic access. To learn more about the different ways that you can configure programmatic access, see Authentication and access in the AWS SDKs and Tools Reference Guide.
For new users who aren’t given a method of authentication by their employer, we recommend using AWS IAM Identity Center. This method includes installing the AWS Command Line Interface (AWS CLI) and using it for configuration and signing in to the AWS access portal. To configure programmatic access using IAM Identity Center, see IAM Identity Center authentication in the AWS SDKs and Tools Reference Guide. After completion, your environment should contain the following elements:
-
The AWS CLI, which you use to start an AWS access portal session before you run your application.
-
A shared AWS
config
file having a[default]
profile with a set of configuration values that can be referenced from the AWS CDK. To find the location of this file, see Location of the shared files in the AWS SDKs and Tools Reference Guide. -
The shared
config
file sets theregion
setting. This sets the default AWS Region the AWS CDK uses for AWS requests. -
The AWS CDK uses the profile's SSO token provider configuration to acquire credentials before sending requests to AWS. The
sso_role_name
value, which is an IAM role connected to an IAM Identity Center permission set, should allow access to the AWS services used in your application.The following sample
config
file shows a default profile set up with SSO token provider configuration. The profile'ssso_session
setting refers to the namedsso-session
section. Thesso-session
section contains settings to initiate an AWS access portal session.[default] sso_session =
my-sso
sso_account_id =111122223333
sso_role_name =SampleRole
region =us-east-1
output = json [sso-sessionmy-sso
] sso_region =us-east-1
sso_start_url =https://provided-domain.awsapps.com/start
sso_registration_scopes = sso:account:access
Start an AWS access portal session
Before accessing AWS services, you need an active AWS access portal session for the AWS CDK to use IAM Identity Center authentication to resolve credentials. Depending on your configured session lengths, your access will eventually expire and the AWS CDK will encounter an authentication error. Run the following command in the AWS CLI to sign in to the AWS access portal.
aws sso login
If your SSO token provider configuration is using a named profile instead of the default profile, the command is
aws sso login --profile
. Also specify this profile when issuing
cdk commands using the --profile option or the NAME
AWS_PROFILE
environment variable.
To test if you already have an active session, run the following AWS CLI command.
aws sts get-caller-identity
The response to this command should report the IAM Identity Center account and permission set configured in the shared
config
file.
Note
If you already have an active AWS access portal session and run aws sso login
, you won't be
required to provide credentials.
The sign in process may prompt you to allow the AWS CLI access to your data. Since the AWS CLI is built on top of
the SDK for Python, permission messages may contain variations of the botocore
name.
Step 3: Install the AWS CDK CLI
Install the AWS CDK CLI globally using the following Node Package Manager command.
npm install -g aws-cdk
Note
If you get a permission error, and have administrator access on your system, try sudo npm install -g
aws-cdk
.
Run the following command to verify a successful installation. The AWS CDK CLI should output the version number:
cdk --version
If you receive an error message, try uninstalling the AWS CDK CLI by running the following:
npm uninstall -g aws-cdk
Then, repeat steps to reinstall the AWS CDK CLI.
If you still receive an error, delete the node-modules
folder from the current project and
also from the global node-modules
folder. To locate this folder, run npm config get
prefix
.
The AWS CDK CLI will obtain security credentials from sources that you configured in previous steps.
Note
CDK Toolkit v2 works with existing CDK v1 projects. However, it can't initialize new CDK v1 projects. See New prerequisites if you need to be able to do that.
Step 4: Bootstrap your environment
Each AWS environment that you plan to deploy resources to must be bootstrapped.
To bootstrap, run the following:
cdk bootstrap aws://
ACCOUNT-NUMBER
/REGION
Tip
If you don't have your AWS account number handy, you can get it from the AWS Management Console. Or, if you have the AWS CLI installed, the following command displays your default account information, including the account number.
aws sts get-caller-identity
If you created named profiles in your local AWS configuration, you can use the --profile
option to
display the account information for a specific profile. The following example shows how to display account
information for the prod profile.
aws sts get-caller-identity --profile prod
To display the default Region, use aws configure get
.
aws configure get region aws configure get region --profile prod
Optional AWS CDK tools
The AWS Toolkit for Visual Studio Code
Next steps
Now that you've installed the AWS CDK CLI, use it to build your first AWS CDK app.
To learn more about using the AWS CDK in your preferred programming language, see Working with the AWS CDK in supported programming languages.
The AWS CDK is an open-source project. To contribute, see Contributing to the AWS Cloud Development Kit (AWS CDK)
Learn more
To learn more about the AWS CDK, see the following:
-
CDK Workshop
– In-depth hands-on workshop. -
API reference – Explore constructs available for the AWS services that you will use.
-
Construct Hub
– Find constructs from the CDK community. -
AWS CDK examples
– Explore code examples of AWS CDK projects.