Working with the AWS CDK
The AWS Cloud Development Kit (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 (in developer preview) Go. It is also possible to use other JVM and .NET languages, though we are unable to provide support for every such language.
This Guide does not currently include instructions or code examples for Go aside from Working with the AWS CDK in Go. Go support is currently in developer preview.
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
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,
or C#. 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
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.
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, along with a generic version.
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 library 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
propsargument 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 resource.
-
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.
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.
