This is the AWS CDK v2 Developer Guide. The older CDK v1 entered maintenance on June 1, 2022 and will now receive only critical bug fixes and security patches. New features will be developed for CDK v2 exclusively. Support for CDK v1 will end entirely on June 1, 2023.
Working with the AWS CDK
The AWS Cloud Development Kit (AWS CDK) lets you define your AWS cloud infrastructure in a general-purpose programming language. Currently, the AWS CDK supports TypeScript, JavaScript, Python, Java, C#, and Go. It is also possible to use other JVM and .NET languages, though we are unable to provide support for every such language.
Note
This Guide does not currently include instructions or code examples for Go aside from Working with the AWS CDK in Go.
We develop the AWS CDK in TypeScript and use JSII
AWS CDK prerequisites
To use the AWS CDK, you need an AWS account and a corresponding access key. If you don't
have an AWS account yet, see Create and Activate an AWS Account
Tip
If you have the AWS CLI
aws configure
All AWS CDK applications require Node.js 10.13 or later, even if you work in Python, Java,
C#, or Go. You may download a compatible version at nodejs.org
After installing Node.js, install the AWS CDK Toolkit (the cdk
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
.
Test the installation by issuing cdk --version
.
If you get an error message at this point, try uninstalling (npm uninstall -g
aws-cdk
) and reinstalling. As a last resort, delete the
node-modules
folder from the current project and also from the global
node-modules
folder. To figure out where this folder is, issue
npm config get prefix
.
Language-specific prerequisites
The specific language you work in also has its own prerequisites, described in the corresponding topic listed here.
Note
Third-party Language Deprecation: language version is only supported until its EOL (End Of Life) shared by the vendor or community and is subject to change with prior notice.
AWS Construct Library
The AWS CDK includes the AWS Construct Library, a collection of constructs organized by AWS
service. The library's constructs are mainly in a single module, colloquially called
aws-cdk-lib
because that's its name in TypeScript. The actual package
name of the main CDK package varies by language.
Note
Experimental constructs are provided as separate modules.
The AWS CDK API Reference provides detailed documentation of the constructs (and other components) in the library. A version of the API Reference is provided for each supported programming language.
Each module's reference material is broken into the following sections.
-
Overview: Introductory material you'll need to know to work with the service in the AWS CDK, including concepts and examples.
-
Constructs: Library classes that represent one or more concrete AWS resources. These are the "curated" (L2) resources or patterns (L3 resources) that provide a high-level interface with sane defaults.
-
Classes: Non-construct classes that provide functionality used by constructs in the module.
-
Structs: Data structures (attribute bundles) that define the structure of composite values such as properties (the
props
argument of constructs) and options. -
Interfaces: Interfaces, whose names all begin with "I", define the absolute minimum functionality for the corresponding construct or other class. The CDK uses construct interfaces to represent AWS resources that are defined outside your AWS CDK app and referenced by methods such as
Bucket.fromBucketArn()
. -
Enums: Collections of named values for use in specifying certain construct parameters. Using an enumerated value allows the CDK to check these values for validity during synthesis.
-
CloudFormation Resources: These L1 constructs, whose names begin with "Cfn", represent exactly the resources defined in the CloudFormation specification. They are automatically generated from that specification with each CDK release. Each L2 or L3 construct encapsulates one or more CloudFormation resources.
-
CloudFormation Property Types: The collection of named values that define the properties for each CloudFormation Resource.
Interfaces vs. construct classes
The AWS CDK uses interfaces in a specific way that might not be obvious even if you are familiar with interfaces as a programming concept.
The AWS CDK supports using resources defined outside CDK applications using methods
such as Bucket.fromBucketArn()
. External resources cannot be modified and may
not have all the functionality available with resources defined in your CDK app using
e.g. the Bucket
class. Interfaces, then, represent the bare minimum
functionality available in the CDK for a given AWS resource type,
including external resources.
When instantiating resources in your CDK app, then, you should always use
concrete classes such as Bucket
. When specifying the type of an argument you
are accepting in one of your own constructs, use the interface type such as
IBucket
if you are prepared to deal with external resources (that is, you
won't need to change them). If you require a CDK-defined construct, specify the most
general type you can use.
Some interfaces are minimum versions of properties or options bundles associated with specific classes, rather than constructs. Such interfaces can be useful when subclassing to accept arguments that you'll pass on to your parent class. If you require one or more additional properties, you'll want to implement or derive from this interface, or from a more specific type.
Note
Some programming languages supported by the AWS CDK don't have an interface feature. In
these languages, interfaces are just ordinary classes. You can identify them by their
names, which follow the pattern of an initial "I" followed by the name of some other
construct (e.g. IBucket
). The same rules apply.