This is the AWS CDK v1 Developer Guide. The older CDK v1 entered maintenance on June 1, 2022 and will now only receive 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. Migrate to CDK v2 to have access to the latest features and fixes.
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 as well as 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 construct modules organized by AWS service. 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 imported 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 importing resources defined outside CDK applications using
methods such as Bucket.fromBucketArn()
. Imported 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 imported 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 imported 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 (shown in the
AWS CDK API Reference as Structs) that are associated with specific constructs. For example,
IBucketProps
is the smallest set of properties required to instantiate a
bucket. Such interfaces can be useful when subclassing constructs 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 such as
BucketProps
.
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.