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](work-with-cdk-v2.md) 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\$1, 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](work-with-cdk-go.md). We develop the AWS CDK in TypeScript and use [JSII](https://github.com/aws/jsii) to provide a "native" experience in other supported languages. For example, we distribute AWS Construct Library modules using your preferred language's standard repository, and you install them using the language's standard package manager. Methods and properties are even named using your language's recommended naming patterns. ## 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](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/). To find out how to obtain an access key ID and secret access key for your AWS account, see [Understanding and Getting Your Security Credentials](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html). To find out how to configure your workstation so the AWS CDK uses your credentials, see [Setting Credentials in Node.js](https://docs.aws.amazon.com/sdk-for-javascript/v2/developer-guide/setting-credentials-node.html). **Tip** If you have the [AWS CLI](https://aws.amazon.com/cli/) installed, the simplest way to set up your workstation with your AWS credentials is to open a command prompt and type: ``` aws configure ``` All AWS CDK applications require Node.js 10.13 or later, even if you work in Python, Java, C\$1, or Go. You may download a compatible version at [nodejs.org](https://nodejs.org/). We recommend the [active LTS version](https://nodejs.org/en/about/releases/) (at this writing, the latest 16.x release). Node.js versions 13.0.0 through 13.6.0 are not compatible with the AWS CDK due to compatibility issues with its dependencies. 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. + [Working with the AWS CDK in TypeScript](work-with-cdk-typescript.md) + [Working with the AWS CDK in JavaScript](work-with-cdk-javascript.md) + [Working with the AWS CDK in Python](work-with-cdk-python.md) + [Working with the AWS CDK in Java](work-with-cdk-java.md) + [Working with the AWS CDK in C\$1](work-with-cdk-csharp.md) + [Working with the AWS CDK in Go](work-with-cdk-go.md) **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](https://docs.aws.amazon.com/cdk/api/v1/docs/aws-construct-library.html) 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. # Working with the AWS CDK in TypeScript In TypeScript TypeScript is a fully-supported client language for the AWS CDK and is considered stable. Working with the AWS CDK in TypeScript uses familiar tools, including Microsoft's TypeScript compiler (`tsc`), [Node.js](https://nodejs.org/) and the Node Package Manager (`npm`). You may also use [Yarn](https://yarnpkg.com/) if you prefer, though the examples in this Guide use NPM. The modules comprising the AWS Construct Library are distributed via the NPM repository, [npmjs.org](https://www.npmjs.com/). You can use any editor or IDE; many AWS CDK developers use [Visual Studio Code](https://code.visualstudio.com/) (or its open-source equivalent [VSCodium](https://vscodium.com/)), which has excellent support for TypeScript. ## Prerequisites To work with the AWS CDK, you must have an AWS account and credentials and have installed Node.js and the AWS CDK Toolkit. See [AWS CDK Prerequisites](work-with.md#work-with-prerequisites). You also need TypeScript itself (version 2.7 or later). If you don't already have it, you can install it using `npm`. ``` npm install -g typescript ``` **Note** If you get a permission error, and have administrator access on your system, try `sudo npm install -g typescript`. Keep TypeScript up to date with a regular `npm update -g typescript`. **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. ## Creating a project You create a new AWS CDK project by invoking `cdk init` in an empty directory. ``` mkdir my-project cd my-project cdk init app --language typescript ``` Creating a project also installs the [https://docs.aws.amazon.com/cdk/api/v2/docs/core-readme.html](https://docs.aws.amazon.com/cdk/api/v2/docs/core-readme.html) module and its dependencies. `cdk init` uses the name of the project folder to name various elements of the project, including classes, subfolders, and files. Hyphens in the folder name are converted to underscores. However, the name should otherwise follow the form of a TypeScript identifier; for example, it should not start with a number or contain spaces. ## Using local `tsc` and `cdk` For the most part, this guide assumes you install TypeScript and the CDK Toolkit globally (`npm install -g typescript aws-cdk`), and the provided command examples (such as `cdk synth`) follow this assumption. This approach makes it easy to keep both components up to date, and since both take a strict approach to backward compatibility, there is generally little risk in always using the latest versions. Some teams prefer to specify all dependencies within each project, including tools like the TypeScript compiler and the CDK Toolkit. This practice lets you pin these components to specific versions and ensure that all developers on your team (and your CI/CD environment) use exactly those versions. This eliminates a possible source of change, helping to make builds and deployments more consistent and repeatable. The CDK includes dependencies for both TypeScript and the CDK Toolkit in the TypeScript project template's `package.json`, so if you want to use this approach, you don't need to make any changes to your project. All you need to do is use slightly different commands for building your app and for issuing `cdk` commands. | Operation | Use global tools | Use local tools | | --- |--- |--- | | Initialize project | `cdk init --language typescript` | `npx aws-cdk init --language typescript` | | --- |--- |--- | | Build | `tsc` | `npm run build` | | --- |--- |--- | | Run CDK Toolkit command | `cdk ...` | `npm run cdk ...` or `npx aws-cdk ...` | | --- |--- |--- | `npx aws-cdk` runs the version of the CDK Toolkit installed locally in the current project, if one exists, falling back to the global installation, if any. If no global installation exists, `npx` downloads a temporary copy of the CDK Toolkit and runs that. You may specify an arbitrary version of the CDK Toolkit using the `@` syntax: `npx aws-cdk@1.120 --version` prints `1.120.0`. **Tip** Set up an alias so you can use the `cdk` command with a local CDK Toolkit installation. ``` alias cdk="npx aws-cdk" ``` ``` doskey cdk=npx aws-cdk $* ``` ## Managing AWS Construct Library modules Use the Node Package Manager (`npm`) to install and update AWS Construct Library modules for use by your apps, as well as other packages you need. (You may use `yarn` instead of `npm` if you prefer.) `npm` also installs the dependencies for those modules automatically. The AWS CDK core module is named `@aws-cdk/core`. AWS Construct Library modules are named like `@aws-cdk/SERVICE-NAME`. The service name has an *aws* prefix. If you're unsure of a module's name, [search for it on NPM](https://www.npmjs.com/search?q=%40aws-cdk). **Note** The [CDK API Reference](https://docs.aws.amazon.com/cdk/api/v1/docs/aws-construct-library.html) also shows the package names. For example, the command below installs the modules for Amazon S3 and AWS Lambda. ``` npm install @aws-cdk/aws-s3 @aws-cdk/aws-lambda ``` Some services' Construct Library support is in more than one module. For example, besides the `@aws-cdk/aws-route53` module, there are three additional Amazon Route 53 modules, named `aws-route53-targets`, `aws-route53-patterns`, and `aws-route53resolver`. Your project's dependencies are maintained in `package.json`. You can edit this file to lock some or all of your dependencies to a specific version or to allow them to be updated to newer versions under certain criteria. To update your project's NPM dependencies to the latest permitted version according to the rules you specified in `package.json`: ``` npm update ``` In TypeScript, you import modules into your code under the same name you use to install them using NPM. We recommend the following practices when importing AWS CDK classes and AWS Construct Library modules in your applications. Following these guidelines will help make your code consistent with other AWS CDK applications as well as easier to understand. + Use ES6-style `import` directives, not `require()`. + Generally, import individual classes from `@aws-cdk/core`. ``` import { App, Construct } from '@aws-cdk/core'; ``` + If you need many classes from the core module, you may use a namespace alias of `cdk` instead of importing the individual classes. Avoid doing both. ``` import * as cdk from '@aws-cdk/core'; ``` + Generally, import AWS Construct Libraries using short namespace aliases. ``` import * as s3 from '@aws-cdk/aws-s3'; ``` **Important** All AWS Construct Library modules used in your project must be the same version. ## AWS CDK idioms in TypeScript ### Props All AWS Construct Library classes are instantiated using three arguments: the *scope* in which the construct is being defined (its parent in the construct tree), an *id*, and *props*, a bundle of key/value pairs that the construct uses to configure the AWS resources it creates. Other classes and methods also use the "bundle of attributes" pattern for arguments. In TypeScript, the shape of `props` is defined using an interface that tells you the required and optional arguments and their types. Such an interface is defined for each kind of `props` argument, usually specific to a single construct or method. For example, the [Bucket](https://docs.aws.amazon.com/cdk/api/v2/docs/@aws-cdk_aws-s3.Bucket.html) construct (in the `@aws-cdk/aws-s3 module`) specifies a `props` argument conforming to the [BucketProps](https://docs.aws.amazon.com/cdk/api/v2/docs/@aws-cdk_aws-s3.BucketProps.html) interface. If a property is itself an object, for example the [websiteRedirect](https://docs.aws.amazon.com/cdk/api/v2/docs/@aws-cdk_aws-s3.BucketProps.html#websiteredirect) property of `BucketProps`, that object will have its own interface to which its shape must conform, in this case [RedirectTarget](https://docs.aws.amazon.com/cdk/api/v2/docs/@aws-cdk_aws-s3.RedirectTarget.html). If you are subclassing an AWS Construct Library class (or overriding a method that takes a props-like argument), you can inherit from the existing interface to create a new one that specifies any new props your code requires. When calling the parent class or base method, generally you can pass the entire props argument you received, since any attributes provided in the object but not specified in the interface will be ignored. A future release of the AWS CDK could coincidentally add a new property with a name you used for your own property. Passing the value you receive up the inheritance chain can then cause unexpected behavior. It's safer to pass a shallow copy of the props you received with your property removed or set to `undefined`. For example: ``` super(scope, name, {...props, encryptionKeys: undefined}); ``` Alternatively, name your properties so that it is clear that they belong to your construct. This way, it is unlikely they will collide with properties in future AWS CDK releases. If there are many of them, use a single appropriately-named object to hold them. ### Missing values Missing values in an object (such as props) have the value `undefined` in TypeScript. Recent versions of the language include operators that simplify working with these values, making it easier to specify defaults and "short-circuit" chaining when an undefined value is reached. For more information about these features, see the [TypeScript 3.7 Release Notes](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html), specifically the first two features, Optional Chaining and Nullish Coalescing. ## Building, synthesizing, and deploying Generally, you should be in the project's root directory when building and running your application. Node.js cannot run TypeScript directly; instead, your application is converted to JavaScript using the TypeScript compiler, `tsc`. The resulting JavaScript code is then executed. The AWS CDK automatically does this whenever it needs to run your app. However, it can be useful to compile manually to check for errors and to run tests. To compile your TypeScript app manually, issue `npm run build`. You may also issue `npm run watch` to enter watch mode, in which the TypeScript compiler automatically rebuilds your app whenever you save changes to a source file. The [stacks](stacks.md) defined in your AWS CDK app can be synthesized and deployed individually or together using the commands below. Generally, you should be in your project's main directory when you issue them. + `cdk synth`: Synthesizes a CloudFormation template from one or more of the stacks in your AWS CDK app. + `cdk deploy`: Deploys the resources defined by one or more of the stacks in your AWS CDK app to AWS. You can specify the names of multiple stacks to be synthesized or deployed in a single command. If your app defines only one stack, you do not need to specify it. ``` cdk synth # app defines single stack cdk deploy Happy Grumpy # app defines two or more stacks; two are deployed ``` You may also use the wildcards \$1 (any number of characters) and ? (any single character) to identify stacks by pattern. When using wildcards, enclose the pattern in quotes. Otherwise, the shell may try to expand it to the names of files in the current directory before they are passed to the AWS CDK Toolkit. ``` cdk synth "Stack?" # Stack1, StackA, etc. cdk deploy "*Stack" # PipeStack, LambdaStack, etc. ``` **Tip** You don't need to explicitly synthesize stacks before deploying them; `cdk deploy` performs this step for you to make sure your latest code gets deployed. For full documentation of the `cdk` command, see [AWS CDK Toolkit (`cdk` command)](cli.md). # Working with the AWS CDK in JavaScript In JavaScript JavaScript is a fully-supported client language for the AWS CDK and is considered stable. Working with the AWS CDK in JavaScript uses familiar tools, including [Node.js](https://nodejs.org/) and the Node Package Manager (`npm`). You may also use [Yarn](https://yarnpkg.com/) if you prefer, though the examples in this Guide use NPM. The modules comprising the AWS Construct Library are distributed via the NPM repository, [npmjs.org](https://www.npmjs.com/). You can use any editor or IDE; many AWS CDK developers use [Visual Studio Code](https://code.visualstudio.com/) (or its open-source equivalent [VSCodium](https://vscodium.com/)), which has good support for JavaScript. ## Prerequisites To work with the AWS CDK, you must have an AWS account and credentials and have installed Node.js and the AWS CDK Toolkit. See [AWS CDK Prerequisites](work-with.md#work-with-prerequisites). JavaScript AWS CDK applications require no additional prerequisites beyond these. **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. ## Creating a project You create a new AWS CDK project by invoking `cdk init` in an empty directory. ``` mkdir my-project cd my-project cdk init app --language javascript ``` Creating a project also installs the [https://docs.aws.amazon.com/cdk/api/v2/docs/core-readme.html](https://docs.aws.amazon.com/cdk/api/v2/docs/core-readme.html) module and its dependencies. `cdk init` uses the name of the project folder to name various elements of the project, including classes, subfolders, and files. Hyphens in the folder name are converted to underscores. However, the name should otherwise follow the form of a JavaScript identifier; for example, it should not start with a number or contain spaces. ## Using local `cdk` For the most part, this guide assumes you install the CDK Toolkit globally (`npm install -g aws-cdk`), and the provided command examples (such as `cdk synth`) follow this assumption. This approach makes it easy to keep the CDK Toolkit up to date, and since the CDK takes a strict approach to backward compatibility, there is generally little risk in always using the latest version. Some teams prefer to specify all dependencies within each project, including tools like the CDK Toolkit. This practice lets you pin such components to specific versions and ensure that all developers on your team (and your CI/CD environment) use exactly those versions. This eliminates a possible source of change, helping to make builds and deployments more consistent and repeatable. The CDK includes a dependency for the CDK Toolkit in the JavaScript project template's `package.json`, so if you want to use this approach, you don't need to make any changes to your project. All you need to do is use slightly different commands for building your app and for issuing `cdk` commands. | Operation | Use global CDK Toolkit | Use local CDK Toolkit | | --- |--- |--- | | Initialize project | `cdk init --language javascript` | `npx aws-cdk init --language javascript` | | --- |--- |--- | | Run CDK Toolkit command | `cdk ...` | `npm run cdk ...` or `npx aws-cdk ...` | | --- |--- |--- | `npx aws-cdk` runs the version of the CDK Toolkit installed locally in the current project, if one exists, falling back to the global installation, if any. If no global installation exists, `npx` downloads a temporary copy of the CDK Toolkit and runs that. You may specify an arbitrary version of the CDK Toolkit using the `@` syntax: `npx aws-cdk@1.120 --version` prints `1.120.0`. **Tip** Set up an alias so you can use the `cdk` command with a local CDK Toolkit installation. ``` alias cdk="npx aws-cdk" ``` ``` doskey cdk=npx aws-cdk $* ``` ## Managing AWS Construct Library modules Use the Node Package Manager (`npm`) to install and update AWS Construct Library modules for use by your apps, as well as other packages you need. (You may use `yarn` instead of `npm` if you prefer.) `npm` also installs the dependencies for those modules automatically. The AWS CDK core module is named `@aws-cdk/core`. AWS Construct Library modules are named like `@aws-cdk/SERVICE-NAME`. The service name has an *aws-* prefix. If you're unsure of a module's name, [search for it on NPM](https://www.npmjs.com/search?q=%40aws-cdk). **Note** The [CDK API Reference](https://docs.aws.amazon.com/cdk/api/v1/docs/aws-construct-library.html) also shows the package names. For example, the command below installs the modules for Amazon S3 and AWS Lambda. ``` npm install @aws-cdk/aws-s3 @aws-cdk/aws-lambda ``` Some services' Construct Library support is in more than one module. For example, besides the `@aws-cdk/aws-route53` module, there are three additional Amazon Route 53 modules, named `aws-route53-targets`, `aws-route53-patterns`, and `aws-route53resolver`. Your project's dependencies are maintained in `package.json`. You can edit this file to lock some or all of your dependencies to a specific version or to allow them to be updated to newer versions under certain criteria. To update your project's NPM dependencies to the latest permitted version according to the rules you specified in `package.json`: ``` npm update ``` In JavaScript, you import modules into your code under the same name you use to install them using NPM. We recommend the following practices when importing AWS CDK classes and AWS Construct Library modules in your applications. Following these guidelines will help make your code consistent with other AWS CDK applications as well as easier to understand. + Use `require()`, not ES6-style `import` directives. Older versions of Node.js do not support ES6 imports, so using the older syntax is more widely compatible. (If you really want to use ES6 imports, use [esm](https://www.npmjs.com/package/esm) to ensure your project is compatible with all supported versions of Node.js.) + Generally, import individual classes from `@aws-cdk/core`. ``` const { App, Construct } = require('@aws-cdk/core'); ``` + If you need many classes from the core module, you may use a namespace alias of `cdk` instead of importing the individual classes. Avoid doing both. ``` const cdk = require('@aws-cdk/core'); ``` + Generally, import AWS Construct Libraries using short namespace aliases. ``` const s3 = require('@aws-cdk/aws-s3'); ``` **Important** All AWS Construct Library modules used in your project must be the same version. ## AWS CDK idioms in JavaScript ### Props All AWS Construct Library classes are instantiated using three arguments: the *scope* in which the construct is being defined (its parent in the construct tree), an *id*, and *props*, a bundle of key/value pairs that the construct uses to configure the AWS resources it creates. Other classes and methods also use the "bundle of attributes" pattern for arguments. Using an IDE or editor that has good JavaScript autocomplete will help avoid misspelling property names. If a construct is expecting an `encryptionKeys` property, and you spell it `encryptionkeys`, when instantiating the construct, you haven't passed the value you intended. This can cause an error at synthesis time if the property is required, or cause the property to be silently ignored if it is optional. In the latter case, you may get a default behavior you intended to override. Take special care here. When subclassing an AWS Construct Library class (or overriding a method that takes a props-like argument), you may want to accept additional properties for your own use. These values will be ignored by the parent class or overridden method, because they are never accessed in that code, so you can generally pass on all the props you received. A future release of the AWS CDK could coincidentally add a new property with a name you used for your own property. Passing the value you receive up the inheritance chain can then cause unexpected behavior. It's safer to pass a shallow copy of the props you received with your property removed or set to `undefined`. For example: ``` super(scope, name, {...props, encryptionKeys: undefined}); ``` Alternatively, name your properties so that it is clear that they belong to your construct. This way, it is unlikely they will collide with properties in future AWS CDK releases. If there are many of them, use a single appropriately-named object to hold them. ### Missing values Missing values in an object (such as `props`) have the value `undefined` in JavaScript. The usual techniques apply for dealing with these. For example, a common idiom for accessing a property of a value that may be undefined is as follows: ``` // a may be undefined, but if it is not, it may have an attribute b // c is undefined if a is undefined, OR if a doesn't have an attribute b let c = a && a.b; ``` However, if `a` could have some other "falsy" value besides `undefined`, it is better to make the test more explicit. Here, we'll take advantage of the fact that `null` and `undefined` are equal to test for them both at once: ``` let c = a == null ? a : a.b; ``` **Tip** Node.js 14.0 and later support new operators that can simplify the handling of undefined values. For more information, see the [optional chaining](https://github.com/tc39/proposal-optional-chaining/blob/master/README.md) and [nullish coalescing](https://github.com/tc39/proposal-nullish-coalescing/blob/master/README.md) proposals. ## Synthesizing and deploying The [stacks](stacks.md) defined in your AWS CDK app can be synthesized and deployed individually or together using the commands below. Generally, you should be in your project's main directory when you issue them. + `cdk synth`: Synthesizes a CloudFormation template from one or more of the stacks in your AWS CDK app. + `cdk deploy`: Deploys the resources defined by one or more of the stacks in your AWS CDK app to AWS. You can specify the names of multiple stacks to be synthesized or deployed in a single command. If your app defines only one stack, you do not need to specify it. ``` cdk synth # app defines single stack cdk deploy Happy Grumpy # app defines two or more stacks; two are deployed ``` You may also use the wildcards \$1 (any number of characters) and ? (any single character) to identify stacks by pattern. When using wildcards, enclose the pattern in quotes. Otherwise, the shell may try to expand it to the names of files in the current directory before they are passed to the AWS CDK Toolkit. ``` cdk synth "Stack?" # Stack1, StackA, etc. cdk deploy "*Stack" # PipeStack, LambdaStack, etc. ``` **Tip** You don't need to explicitly synthesize stacks before deploying them; `cdk deploy` performs this step for you to make sure your latest code gets deployed. For full documentation of the `cdk` command, see [AWS CDK Toolkit (`cdk` command)](cli.md). ## Using TypeScript examples with JavaScript [TypeScript](https://www.typescriptlang.org/) is the language we use to develop the AWS CDK, and it was the first language supported for developing applications, so many available AWS CDK code examples are written in TypeScript. These code examples can be a good resource for JavaScript developers; you just need to remove the TypeScript-specific parts of the code. TypeScript snippets often use the newer ECMAScript `import` and `export` keywords to import objects from other modules and to declare the objects to be made available outside the current module. Node.js has just begun supporting these keywords in its latest releases. Depending on the version of Node.js you're using, you might rewrite imports and exports to use the older syntax. Imports can be replaced with calls to the `require()` function. ------ #### [ TypeScript ] ``` import * as cdk from '@aws-cdk/core'; import { Bucket, BucketPolicy } from '@aws-cdk/aws-s3'; ``` ------ #### [ JavaScript ] ``` const cdk = require('@aws-cdk/core'); const { Bucket, BucketPolicy } = require('@aws-cdk/aws-s3'); ``` ------ Exports can be assigned to the `module.exports` object. ------ #### [ TypeScript ] ``` export class Stack1 extends cdk.Stack { // ... } export class Stack2 extends cdk.Stack { // ... } ``` ------ #### [ JavaScript ] ``` class Stack1 extends cdk.Stack { // ... } class Stack2 extends cdk.Stack { // ... } module.exports = { Stack1, Stack2 } ``` ------ **Note** An alternative to using the old-style imports and exports is to use the [https://www.npmjs.com/package/esm](https://www.npmjs.com/package/esm) module. Once you've got the imports and exports sorted, you can dig into the actual code. You may run into these commonly-used TypeScript features: + Type annotations + Interface definitions + Type conversions/casts + Access modifiers Type annotations may be provided for variables, class members, function parameters, and function return types. For variables, parameters, and members, types are specified by following the identifier with a colon and the type. Function return values follow the function signature and consist of a colon and the type. To convert type-annotated code to JavaScript, remove the colon and the type. Class members must have some value in JavaScript; set them to `undefined` if they only have a type annotation in TypeScript. ------ #### [ TypeScript ] ``` var encrypted: boolean = true; class myStack extends core.Stack { bucket: s3.Bucket; // ... } function makeEnv(account: string, region: string) : object { // ... } ``` ------ #### [ JavaScript ] ``` var encrypted = true; class myStack extends core.Stack { bucket = undefined; // ... } function makeEnv(account, region) { // ... } ``` ------ In TypeScript, interfaces are used to give bundles of required and optional properties, and their types, a name. You can then use the interface name as a type annotation. TypeScript will make sure that the object you use as, for example, an argument to a function has the required properties of the right types. ``` interface myFuncProps { code: lambda.Code, handler?: string } ``` JavaScript does not have an interface feature, so once you've removed the type annotations, delete the interface declarations entirely. When a function or method returns a general-purpose type (such as `object`), but you want to treat that value as a more specific child type to access properties or methods that are not part of the more general type's interface, TypeScript lets you *cast* the value using `as` followed by a type or interface name. JavaScript doesn't support (or need) this, so simply remove `as` and the following identifier. A less-common cast syntax is to use a type name in brackets, ``; these casts, too, must be removed. Finally, TypeScript supports the access modifiers `public`, `protected`, and `private` for members of classes. All class members in JavaScript are public. Simply remove these modifiers wherever you see them. Knowing how to identify and remove these TypeScript features goes a long way toward adapting short TypeScript snippets to JavaScript. But it may be impractical to convert longer TypeScript examples in this fashion, since they are more likely to use other TypeScript features. For these situations, we recommend [Sucrase](https://github.com/alangpierce/sucrase). Sucrase won't complain if code uses an undefined variable, for example, as `tsc` would. If it is syntactically valid, then with few exceptions, Sucrase can translate it to JavaScript. This makes it particularly valuable for converting snippets that may not be runnable on their own. ## Migrating to TypeScript Many JavaScript developers move to [TypeScript](https://www.typescriptlang.org/) as their projects get larger and more complex. TypeScript is a superset of JavaScript—all JavaScript code is valid TypeScript code, so no changes to your code are required—and it is also a supported AWS CDK language. Type annotations and other TypeScript features are optional and can be added to your AWS CDK app as you find value in them. TypeScript also gives you early access to new JavaScript features, such as optional chaining and nullish coalescing, before they're finalized—and without requiring that you upgrade Node.js. TypeScript's "shape-based" interfaces, which define bundles of required and optional properties (and their types) within an object, allow common mistakes to be caught while you're writing the code, and make it easier for your IDE to provide robust autocomplete and other real-time coding advice. Coding in TypeScript does involve an additional step: compiling your app with the TypeScript compiler, `tsc`. For typical AWS CDK apps, compilation requires a few seconds at most. The easiest way to migrate an existing JavaScript AWS CDK app to TypeScript is to create a new TypeScript project using `cdk init app --language typescript`, then copy your source files (and any other necessary files, such as assets like AWS Lambda function source code) to the new project. Rename your JavaScript files to end in `.ts` and begin developing in TypeScript. # Working with the AWS CDK in Python In Python Python is a fully-supported client language for the AWS CDK and is considered stable. Working with the AWS CDK in Python uses familiar tools, including the standard Python implementation (CPython), virtual environments with `virtualenv`, and the Python package installer `pip`. The modules comprising the AWS Construct Library are distributed via [pypi.org](https://pypi.org/search/?q=aws-cdk). The Python version of the AWS CDK even uses Python-style identifiers (for example, `snake_case` method names). You can use any editor or IDE. Many AWS CDK developers use [Visual Studio Code](https://code.visualstudio.com/) (or its open-source equivalent [VSCodium](https://vscodium.com/)), which has good support for Python via an [official extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python). The IDLE editor included with Python will suffice to get started. The Python modules for the AWS CDK do have type hints, which are useful for a linting tool or an IDE that supports type validation. ## Prerequisites To work with the AWS CDK, you must have an AWS account and credentials and have installed Node.js and the AWS CDK Toolkit. See [AWS CDK Prerequisites](work-with.md#work-with-prerequisites). Python AWS CDK applications require Python 3.6 or later. If you don't already have it installed, [download a compatible version](https://www.python.org/downloads/) for your operating system at [python.org](https://www.python.org/). If you run Linux, your system may have come with a compatible version, or you may install it using your distro's package manager (`yum`, `apt`, etc.). Mac users may be interested in [Homebrew](https://brew.sh/), a Linux-style package manager for macOS. **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. The Python package installer, `pip`, and virtual environment manager, `virtualenv`, are also required. Windows installations of compatible Python versions include these tools. On Linux, `pip` and `virtualenv` may be provided as separate packages in your package manager. Alternatively, you may install them with the following commands: ``` python -m ensurepip --upgrade python -m pip install --upgrade pip python -m pip install --upgrade virtualenv ``` If you encounter a permission error, run the above commands with the `--user` flag so that the modules are installed in your user directory, or use `sudo` to obtain the permissions to install the modules system-wide. **Note** It is common for Linux distros to use the executable name `python3` for Python 3.x, and have `python` refer to a Python 2.x installation. Some distros have an optional package you can install that makes the `python` command refer to Python 3. Failing that, you can adjust the command used to run your application by editing `cdk.json` in the project's main directory. **Note** On Windows, you may want to invoke Python (and **pip**) using the **py** executable, the [>Python launcher for Windows](https://docs.python.org/3/using/windows.html#launcher). Among other things, the launcher allows you to easily specify which installed version of Python you want to use. If typing **python** at the command line results in a message about installing Python from the Windows Store, even after installing a Windows version of Python, open Windows' Manage App Execution Aliases settings panel and turn off the two App Installer entries for Python. ## Creating a project You create a new AWS CDK project by invoking `cdk init` in an empty directory. ``` mkdir my-project cd my-project cdk init app --language python ``` `cdk init` uses the name of the project folder to name various elements of the project, including classes, subfolders, and files. Hyphens in the folder name are converted to underscores. However, the name should otherwise follow the form of a Python identifier; for example, it should not start with a number or contain spaces. After initializing the project, activate the project's virtual environment. This allows the project's dependencies to be installed locally in the project folder, instead of globally. ``` source .venv/bin/activate ``` **Note** You may recognize this as the Mac/Linux command to activate a virtual environment. The Python templates include a batch file, `source.bat`, that allows the same command to be used on Windows. The traditional Windows command, `.venv\Scripts\activate.bat`, works, too. If you initialized your AWS CDK project using CDK Toolkit v1.70.0 or earlier, your virtual environment is in the `.env` directory instead of `.venv`. After activating your virtual environment, install the app's standard dependencies: ``` python -m pip install -r requirements.txt ``` **Important** Activate the project's virtual environment whenever you start working on it. Otherwise, you won't have access to the modules installed there, and modules you install will go in the Python global module directory (or will result in a permission error). ## Managing AWS Construct Library modules Use the Python package installer, **pip**, to install and update AWS Construct Library modules for use by your apps, as well as other packages you need. **pip** also installs the dependencies for those modules automatically. If your system does not recognize **pip** as a standalone command, invoke **pip** as a Python module, like this: ``` python -m pip PIP-COMMAND ``` The AWS CDK core module is named `aws-cdk.core`. AWS Construct Library modules are named like `aws-cdk.SERVICE-NAME`. The service name includes an *aws* prefix. If you're unsure of a module's name, [search for it at PyPI](https://pypi.org/search/?q=aws-cdk). For example, the command below installs the modules for Amazon S3 and AWS Lambda. ``` python -m pip install aws-cdk.aws-s3 aws-cdk.aws-lambda ``` Some services' Construct Library support is in more than one module. For example, besides the `aws-cdk.aws-route53` module, there are three additional Amazon Route 53 modules, named `aws-route53-targets`, `aws-route53-patterns`, and `aws-route53resolver`. **Note** The [Python edition of the CDK API Reference](https://docs.aws.amazon.com/cdk/api/v1/python/index.html) also shows the package names. The names used for importing AWS Construct Library modules into your Python code are similar to their package names. Simply replace the hyphens with underscores. ``` import aws_cdk.aws_s3 as s3 import aws_cdk.aws_lambda as lambda_ ``` We recommend the following practices when importing AWS CDK classes and AWS Construct Library modules in your applications. Following these guidelines will help make your code consistent with other AWS CDK applications as well as easier to understand. + Generally, import individual classes from `aws_cdk.core`. ``` from aws_cdk.core import App, Construct ``` + If you need many classes from the core module, you may use a namespace alias of `cdk` instead of importing individual classes. Avoid doing both. ``` import aws_cdk.core as cdk ``` + Generally, import AWS Construct Libraries using short namespace aliases. ``` import aws_cdk.aws_s3 as s3 ``` After installing a module, update your project's `requirements.txt` file, which lists your project's dependencies. It is best to do this manually rather than using `pip freeze`. `pip freeze` captures the current versions of all modules installed in your Python virtual environment, which can be useful when bundling up a project to be run elsewhere. Usually, though, your `requirements.txt` should list only top-level dependencies (modules that your app depends on directly) and not the dependencies of those modules. This strategy makes updating your dependencies simpler. Here is what your `requirements.txt` file might look like if you have installed the Amazon S3 and AWS Lambda modules as shown earlier. ``` aws-cdk.aws-s3==X.YY.ZZ aws-cdk.aws-lambda==X.YY.ZZ ``` You can edit `requirements.txt` to allow upgrades; simply replace the `==` preceding a version number with `~=` to allow upgrades to a higher compatible version, or remove the version requirement entirely to specify the latest available version of the module. With `requirements.txt` edited appropriately to allow upgrades, issue this command to upgrade your project's installed modules at any time: ``` pip install --upgrade -r requirements.txt ``` **Important** All AWS Construct Library modules used in your project must be the same version. ## AWS CDK idioms in Python ### Language conflicts In Python, `lambda` is a language keyword, so you cannot use it as a name for the AWS Lambda construct library module or Lambda functions. The Python convention for such conflicts is to use a trailing underscore, as in `lambda_`, in the variable name. By convention, the second argument to AWS CDK constructs is named `id`. When writing your own stacks and constructs, calling a parameter `id` "shadows" the Python built-in function `id()`, which returns an object's unique identifier. This function isn't used very often, but if you should happen to need it in your construct, rename the argument, for example `construct_id`. ### Arguments and properties All AWS Construct Library classes are instantiated using three arguments: the *scope* in which the construct is being defined (its parent in the construct tree), an *id*, and *props*, a bundle of key/value pairs that the construct uses to configure the resources it creates. Other classes and methods also use the "bundle of attributes" pattern for arguments. *scope* and *id* should always be passed as positional arguments, not keyword arguments, because their names change if the construct accepts a property named *scope* or *id*. In Python, props are expressed as keyword arguments. If an argument contains nested data structures, these are expressed using a class which takes its own keyword arguments at instantiation. The same pattern is applied to other method calls that take a structured argument. For example, in a Amazon S3 bucket's `add_lifecycle_rule` method, the `transitions` property is a list of `Transition` instances. ``` bucket.add_lifecycle_rule( transitions=[ Transition( storage_class=StorageClass.GLACIER, transition_after=Duration.days(10) ) ] ) ``` When extending a class or overriding a method, you may want to accept additional arguments for your own purposes that are not understood by the parent class. In this case you should accept the arguments you don't care about using the `**kwargs` idiom, and use keyword-only arguments to accept the arguments you're interested in. When calling the parent's constructor or the overridden method, pass only the arguments it is expecting (often just `**kwargs`). Passing arguments that the parent class or method doesn't expect results in an error. ``` class MyConstruct(Construct): def __init__(self, id, *, MyProperty=42, **kwargs): super().__init__(self, id, **kwargs) # ... ``` A future release of the AWS CDK could coincidentally add a new property with a name you used for your own property. This won't cause any technical issues for users of your construct or method (since your property isn't passed "up the chain," the parent class or overridden method will simply use a default value) but it may cause confusion. You can avoid this potential problem by naming your properties so they clearly belong to your construct. If there are many new properties, bundle them into an appropriately-named class and pass it as a single keyword argument. ### Missing values The AWS CDK uses `None` to represent missing or undefined values. When working with `**kwargs`, use the dictionary's `get()` method to provide a default value if a property is not provided. Avoid using `kwargs[...]`, as this raises `KeyError` for missing values. ``` encrypted = kwargs.get("encrypted") # None if no property "encrypted" exists encrypted = kwargs.get("encrypted", False) # specify default of False if property is missing ``` Some AWS CDK methods (such as `tryGetContext()` to get a runtime context value) may return `None`, which you will need to check explicitly. ### Using interfaces Python doesn't have an interface feature as some other languages do, though it does have [abstract base classes](https://docs.python.org/3/library/abc.html), which are similar. (If you're not familiar with interfaces, Wikipedia has [a good introduction](https://en.wikipedia.org/wiki/Interface_(computing)#In_object-oriented_languages).) TypeScript, the language in which the AWS CDK is implemented, does provide interfaces, and constructs and other AWS CDK objects often require an object that adheres to a particular interface, rather than inheriting from a particular class. So the AWS CDK provides its own interface feature as part of the [JSII](https://github.com/aws/jsii) layer. To indicate that a class implements a particular interface, you can use the `@jsii.implements` decorator: ``` from aws_cdk.core import IAspect, IConstruct import jsii @jsii.implements(IAspect) class MyAspect(): def visit(self, node: IConstruct) -> None: print("Visited", node.node.path) ``` ### Type pitfalls Python uses dynamic typing, where all variables may refer to a value of any type. Parameters and return values may be annotated with types, but these are "hints" and are not enforced. This means that in Python, it is easy to pass the incorrect type of value to a AWS CDK construct. Instead of getting a type error during build, as you would from a statically-typed language, you may instead get a runtime error when the JSII layer (which translates between Python and the AWS CDK's TypeScript core) is unable to deal with the unexpected type. In our experience, the type errors Python programmers make tend to fall into these categories. + Passing a single value where a construct expects a container (Python list or dictionary) or vice versa. + Passing a value of a type associated with a layer 1 (`CfnXxxxxx`) construct to an L2 or L3 construct, or vice versa. The AWS CDK Python modules include type annotations, so you can use tools that support them to help with types. If you are not using an IDE that supports these, such as [PyCharm](https://www.jetbrains.com/pycharm/), you might want to call the [MyPy](http://mypy-lang.org/) type validator as a step in your build process. There are also runtime type checkers that can improve error messages for type-related errors. ## Synthesizing and deploying The [stacks](stacks.md) defined in your AWS CDK app can be synthesized and deployed individually or together using the commands below. Generally, you should be in your project's main directory when you issue them. + `cdk synth`: Synthesizes a CloudFormation template from one or more of the stacks in your AWS CDK app. + `cdk deploy`: Deploys the resources defined by one or more of the stacks in your AWS CDK app to AWS. You can specify the names of multiple stacks to be synthesized or deployed in a single command. If your app defines only one stack, you do not need to specify it. ``` cdk synth # app defines single stack cdk deploy Happy Grumpy # app defines two or more stacks; two are deployed ``` You may also use the wildcards \$1 (any number of characters) and ? (any single character) to identify stacks by pattern. When using wildcards, enclose the pattern in quotes. Otherwise, the shell may try to expand it to the names of files in the current directory before they are passed to the AWS CDK Toolkit. ``` cdk synth "Stack?" # Stack1, StackA, etc. cdk deploy "*Stack" # PipeStack, LambdaStack, etc. ``` **Tip** You don't need to explicitly synthesize stacks before deploying them; `cdk deploy` performs this step for you to make sure your latest code gets deployed. For full documentation of the `cdk` command, see [AWS CDK Toolkit (`cdk` command)](cli.md). # Working with the AWS CDK in Java In Java Java is a fully-supported client language for the AWS CDK and is considered stable. You can develop AWS CDK applications in Java using familiar tools, including the JDK (Oracle's, or an OpenJDK distribution such as Amazon Corretto) and Apache Maven. The modules comprising the AWS Construct Library are distributed via the [Maven Central Repository](https://search.maven.org/search?q=g:software.amazon.awscdk). The AWS CDK supports Java 8 and later. We recommend using the latest version you can, however, because later versions of the language include improvements that are particularly convenient for developing AWS CDK applications. For example, Java 9 introduces the `Map.of()` method (a convenient way to declare hashmaps that would be written as object literals in TypeScript). Java 10 introduces local type inference using the `var` keyword. **Note** Most code examples in this Developer Guide work with Java 8. A few examples use `Map.of()`; these examples include comments noting that they require Java 9. You can use any text editor, or a Java IDE that can read Maven projects, to work on your AWS CDK apps. We provide [Eclipse](https://www.eclipse.org/downloads/) hints in this Guide, but IntelliJ IDEA, NetBeans, and other IDEs can import Maven projects and can be used for developing AWS CDK applications in Java. It is possible to write AWS CDK applications in JVM-hosted languages other than Java (for example, Kotlin, Groovy, Clojure, or Scala), but the experience may not be particularly idiomatic, and we are unable to provide any support for these languages. ## Prerequisites To work with the AWS CDK, you must have an AWS account and credentials and have installed Node.js and the AWS CDK Toolkit. See [AWS CDK Prerequisites](work-with.md#work-with-prerequisites). Java AWS CDK applications require Java 8 (v1.8) or later. We recommend [Amazon Corretto](https://aws.amazon.com/corretto/), but you can use any OpenJDK distribution or [Oracle's JDK](https://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html). You will also need [Apache Maven](https://maven.apache.org/download.cgi) 3.5 or later. You can also use tools such as Gradle, but the application skeletons generated by the AWS CDK Toolkit are Maven projects. **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. ## Creating a project You create a new AWS CDK project by invoking `cdk init` in an empty directory. ``` mkdir my-project cd my-project cdk init app --language java ``` `cdk init` uses the name of the project folder to name various elements of the project, including classes, subfolders, and files. Hyphens in the folder name are converted to underscores. However, the name should otherwise follow the form of a Java identifier; for example, it should not start with a number or contain spaces. The resulting project includes a reference to the `software.amazon.awscdk.core` Maven package. It and its dependencies are automatically installed by Maven. If you are using an IDE, you can now open or import the project. In Eclipse, for example, choose **File** > **Import** > **Maven** > **Existing Maven Projects**. Make sure that the project settings are set to use Java 8 (1.8). ## Managing AWS Construct Library modules Use Maven to install AWS Construct Library packages, which are in the group `software.amazon.awscdk` and named with a short version (no AWS or Amazon prefix) of their service's name. For example, the Maven artifact ID for Amazon S3 is `s3`. [Search the Maven Central Repository](https://search.maven.org/search?q=software.amazon.awscdk) to find the names of all AWS CDK and AWS Construct Module libraries. **Note** The [Java edition of the CDK API Reference](https://docs.aws.amazon.com/cdk/api/v1/java/index.html) also shows the package names. Some services' AWS Construct Library support is in more than one module. For example, Amazon Route 53 has the three modules in addition to the main `software.amazon.awscdk.route53` module, named `route53-patterns`, `route53resolver`, and `route53-targets`. The AWS CDK's core module, which you'll need in most AWS CDK apps, is imported in Java code as `software.amazon.awscdk.core`. Modules for the various services in the AWS Construct Library live under `software.amazon.awscdk.services` and are named similarly to their Maven package name. For example, the Amazon S3 module's namespace is `software.amazon.awscdk.services.s3`. We recommend writing a separate Java `import` statement for each AWS Construct Library class you use in each of your Java source files, and avoiding wildcard imports. You can always use a type's fully-qualified name (including its namespace) without an `import` statement. **Important** All AWS Construct Library modules used in your project must be the same version. Specify the modules that your application depends on by editing `pom.xml` and adding a new `` element in the `` container. For example, the following `` element specifies the Amazon S3 construct library module: ``` software.amazon.awscdk s3 ${cdk.version} ``` **Tip** If you use a Java IDE, it probably has features for managing Maven dependencies. We recommend editing `pom.xml` directly, however, unless you are absolutely sure the IDE's functionality matches what you'd do by hand. The default `pom.xml` defines the variable `cdk.version` to be the version of the AWS CDK that created the project. You can easily update the version required by updating the value of this variable, which keeps all AWS Construct Library module versions in sync. ``` 1.XX.Y ``` This value can be any valid Maven version specifier. For example, `[1.XX.Y,2.0)` indicates that any version between the current version 1.XX.Y (inclusive) and 2.0 (exclusive), may be installed. However, to avoid mismatched versions, we recommend using a fixed version like 1.XX and updating it when moving a new AWS CDK release. ## AWS CDK idioms in Java ### Props All AWS Construct Library classes are instantiated using three arguments: the *scope* in which the construct is being defined (its parent in the construct tree), an *id*, and *props*, a bundle of key/value pairs that the construct uses to configure the resources it creates. Other classes and methods also use the "bundle of attributes" pattern for arguments. In Java, props are expressed using the [Builder pattern](https://en.wikipedia.org/wiki/Builder_pattern). Each construct type has a corresponding props type; for example, the `Bucket` construct (which represents an Amazon S3 bucket) takes as its props an instance of `BucketProps`. The `BucketProps` class (like every AWS Construct Library props class) has an inner class called `Builder`. The `BucketProps.Builder` type offers methods to set the various properties of a `BucketProps` instance. Each method returns the `Builder` instance, so the method calls can be chained to set multiple properties. At the end of the chain, you call `build()` to actually produce the `BucketProps` object. ``` Bucket bucket = new Bucket(this, "MyBucket", new BucketProps.Builder() .versioned(true) .encryption(BucketEncryption.KMS_MANAGED) .build()); ``` Constructs, and other classes that take a props-like object as their final argument, offer a shortcut. The class has a `Builder` of its own that instantiates it and its props object in one step. This way, you don't need to explicitly instantiate (for example) both `BucketProps` and a `Bucket`—and you don't need an import for the props type. ``` Bucket bucket = Bucket.Builder.create(this, "MyBucket") .versioned(true) .encryption(BucketEncryption.KMS_MANAGED) .build(); ``` When deriving your own construct from an existing construct, you may want to accept additional properties. We recommend that you follow these builder patterns. However, this isn't as simple as subclassing a construct class. You must provide the moving parts of the two new `Builder` classes yourself. You may prefer to simply have your construct accept one or more additional arguments. You should provide additional constructors when an argument is optional. ### Generic structures In some APIs, the AWS CDK uses JavaScript arrays or untyped objects as input to a method. (See, for example, AWS CodeBuild's [https://docs.aws.amazon.com/cdk/api/v2/docs/@aws-cdk_aws-codebuild.BuildSpec.html#to-wbr-build-wbr-spec](https://docs.aws.amazon.com/cdk/api/v2/docs/@aws-cdk_aws-codebuild.BuildSpec.html#to-wbr-build-wbr-spec) method.) In Java, these objects are represented as `java.util.Map`. In cases where the values are all strings, you can use `Map`. Java does not provide a way to write literals for such containers like some other languages do. In Java 9 and later, you can use [https://docs.oracle.com/javase/9/docs/api/java/util/Map.html#ofEntries-java.util.Map.Entry...-](https://docs.oracle.com/javase/9/docs/api/java/util/Map.html#ofEntries-java.util.Map.Entry...-) to conveniently define maps of up to ten entries inline with one of these calls. ``` java.util.Map.of( "base-directory", "dist", "files", "LambdaStack.template.json" ) ``` To create maps with more than ten entries, use [https://docs.oracle.com/javase/9/docs/api/java/util/Map.html#ofEntries-java.util.Map.Entry...-](https://docs.oracle.com/javase/9/docs/api/java/util/Map.html#ofEntries-java.util.Map.Entry...-). If you are using Java 8, you could provide your own methods similar to to these. JavaScript arrays are represented as `List` or `List` in Java. The method `java.util.Arrays.asList` is convenient for defining short `List`s. ``` List cmds = Arrays.asList("cd lambda", "npm install", "npm install typescript") ``` ### Missing values In Java, missing values in AWS CDK objects such as props are represented by `null`. You must explicitly test any value that could be `null` to make sure it contains a value before doing anything with it. Java does not have "syntactic sugar" to help handle null values as some other languages do. You may find Apache ObjectUtil's [defaultIfNull](https://commons.apache.org/proper/commons-lang/apidocs/org/apache/commons/lang3/ObjectUtils.html#defaultIfNull-T-T-) and [firstNonNull](https://commons.apache.org/proper/commons-lang/apidocs/org/apache/commons/lang3/ObjectUtils.html#firstNonNull-T...-) useful in some situations. Alternatively, write your own static helper methods to make it easier to handle potentially null values and make your code more readable. ## Building, synthesizing, and deploying The AWS CDK automatically compiles your app before running it. However, it can be useful to build your app manually to check for errors and to run tests. You can do this in your IDE (for example, press Control-B in Eclipse) or by issuing `mvn compile` at a command prompt while in your project's root directory. Run any tests you've written by running `mvn test` at a command prompt. The [stacks](stacks.md) defined in your AWS CDK app can be synthesized and deployed individually or together using the commands below. Generally, you should be in your project's main directory when you issue them. + `cdk synth`: Synthesizes a CloudFormation template from one or more of the stacks in your AWS CDK app. + `cdk deploy`: Deploys the resources defined by one or more of the stacks in your AWS CDK app to AWS. You can specify the names of multiple stacks to be synthesized or deployed in a single command. If your app defines only one stack, you do not need to specify it. ``` cdk synth # app defines single stack cdk deploy Happy Grumpy # app defines two or more stacks; two are deployed ``` You may also use the wildcards \$1 (any number of characters) and ? (any single character) to identify stacks by pattern. When using wildcards, enclose the pattern in quotes. Otherwise, the shell may try to expand it to the names of files in the current directory before they are passed to the AWS CDK Toolkit. ``` cdk synth "Stack?" # Stack1, StackA, etc. cdk deploy "*Stack" # PipeStack, LambdaStack, etc. ``` **Tip** You don't need to explicitly synthesize stacks before deploying them; `cdk deploy` performs this step for you to make sure your latest code gets deployed. For full documentation of the `cdk` command, see [AWS CDK Toolkit (`cdk` command)](cli.md). # Working with the AWS CDK in C\$1 In C\$1 .NET is a fully-supported client language for the AWS CDK and is considered stable. C\$1 is the main .NET language for which we provide examples and support. You can choose to write AWS CDK applications in other .NET languages, such as Visual Basic or F\$1, but AWS offers limited support for using these languages with the CDK. You can develop AWS CDK applications in C\$1 using familiar tools including Visual Studio, Visual Studio Code, the `dotnet` command, and the NuGet package manager. The modules comprising the AWS Construct Library are distributed via [nuget.org](https://www.nuget.org/packages?q=amazon.cdk.aws). We suggest using [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/) (any edition) on Windows to develop AWS CDK apps in C\$1. ## Prerequisites To work with the AWS CDK, you must have an AWS account and credentials and have installed Node.js and the AWS CDK Toolkit. See [AWS CDK Prerequisites](work-with.md#work-with-prerequisites). C\$1 AWS CDK applications require .NET Core v3.1 or later, [available here](https://dotnet.microsoft.com/download/dotnet-core/3.1). **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. The .NET toolchain includes `dotnet`, a command-line tool for building and running .NET applications and managing NuGet packages. Even if you work mainly in Visual Studio, this command can be useful for batch operations and for installing AWS Construct Library packages. ## Creating a project You create a new AWS CDK project by invoking `cdk init` in an empty directory. ``` mkdir my-project cd my-project cdk init app --language csharp ``` `cdk init` uses the name of the project folder to name various elements of the project, including classes, subfolders, and files. Hyphens in the folder name are converted to underscores. However, the name should otherwise follow the form of a C\$1 identifier; for example, it should not start with a number or contain spaces. The resulting project includes a reference to the `Amazon.CDK` NuGet package. It and its dependencies are installed automatically by NuGet. ## Managing AWS Construct Library modules The .NET ecosystem uses the NuGet package manager. AWS Construct Library modules are named like `Amazon.CDK.AWS.SERVICE-NAME` where the service name is a short name without an AWS or Amazon prefix. For example, the NuGet package name for the Amazon S3 module is `Amazon.CDK.AWS.S3`. If you can't find a package you want, [search Nuget.org](https://www.nuget.org/packages?q=amazon.cdk.aws). **Note** The [.NET edition of the CDK API Reference](https://docs.aws.amazon.com/cdk/api/v1/dotnet/api/index.html) also shows the package names. Some services' AWS Construct Library support is in more than one module. For example, Amazon Route 53 has the three modules in addition to the main `Amazon.CDK.AWS.Route53` module, named `Route53.Patterns`, `Route53.Resolver`, and `Route53.Targets`. The AWS CDK's core module, which you'll need in most AWS CDK apps, is imported in C\$1 code as `Amazon.CDK`. Modules for the various services in the AWS Construct Library live under `Amazon.CDK.AWS` and are named the same as their NuGet package name. For example, the Amazon S3 module's namespace is `Amazon.CDK.AWS.S3`. We recommend writing a single C\$1 `using` directive for each AWS Construct Library module you use in each of your C\$1 source files. You may find it convenient to use an alias for a namespace or type to help resolve name conflicts. You can always use a type's fully-qualfiied name (including its namespace) without a `using` statement. **Important** All AWS Construct Library modules used in your project must be the same version. NuGet has four standard, mostly-equivalent interfaces; you can use the one that suits your needs and working style. You can also use compatible tools, such as [Paket](https://fsprojects.github.io/Paket/) or [MyGet](https://www.myget.org/). ### The Visual Studio NuGet GUI Visual Studio's NuGet tools are accessible from **Tools** > **NuGet Package Manager** > **Manage NuGet Packages for Solution**. Use the **Browse** tab to find the AWS Construct Library packages you want to install. You can choose the desired version, including pre-release versions (mark the **Include prerelease** checkbox) and add them to any of the open projects. **Note** All AWS Construct Library modules deemed "experimental" (see [Versioning](reference.md#versioning)) are flagged as pre-release in NuGet. ![\[NuGet package manager showing Amazon CDKAWS packages with version and download info.\]](http://docs.aws.amazon.com/cdk/v1/guide/images/visual-studio-nuget.png) Look on the **Updates** page to install new versions of your packages. ### The NuGet console The NuGet console is a PowerShell-based interface to NuGet that works in the context of a Visual Studio project. You can open it in Visual Studio by choosing **Tools** > **NuGet Package Manager** > **Package Manager Console**. For more information about using this tool, see [Install and Manage Packages with the Package Manager Console in Visual Studio](https://docs.microsoft.com/en-us/nuget/consume-packages/install-use-packages-powershell). ### The `dotnet` command The `dotnet` command is the primary command-line tool for working with Visual Studio C\$1 projects. You can invoke it from any Windows command prompt. Among its many capabilities, `dotnet` can add NuGet dependencies to a Visual Studio project. Assuming you're in the same directory as the Visual Studio project (`.csproj`) file, issue a command like the following to install a package. ``` dotnet add package Amazon.CDK.AWS.S3 ``` You may issue the command from another directory by including the path to the project file, or to the directory that contains it, after the `add` keyword. The following example assumes that you are in your AWS CDK project's main directory. ``` dotnet add src/PROJECT-DIR package Amazon.CDK.AWS.S3 ``` To install a specific version of a package, include the `-v` flag and the desired version. AWS Construct Library modules that are deemed "experimental" (see [Versioning](reference.md#versioning)) are flagged as pre-release in NuGet, and must be installed using an explicit version number. ``` dotnet add package Amazon.CDK.AWS.S3 -v VERSION-NUMBER ``` To update a package, issue the same `dotnet add` command you used to install it. If you do not specify a version number, the latest version is installed. For experimental modules, again, you must specify an explicit version number. For more information about managing packages using the `dotnet` command, see [Install and Manage Packages Using the dotnet CLI](https://docs.microsoft.com/en-us/nuget/consume-packages/install-use-packages-dotnet-cli). ### The `nuget` command The `nuget` command line tool can install and update NuGet packages. However, it requires your Visual Studio project to be set up differently from the way `cdk init` sets up projects. (Technical details: `nuget` works with `Packages.config` projects, while `cdk init` creates a newer-style `PackageReference` project.) We do not recommend the use of the `nuget` tool with AWS CDK projects created by `cdk init`. If you are using another type of project, and want to use `nuget`, see the [NuGet CLI Reference](https://docs.microsoft.com/en-us/nuget/reference/nuget-exe-cli-reference). ## AWS CDK idioms in C\$1 ### Props All AWS Construct Library classes are instantiated using three arguments: the *scope* in which the construct is being defined (its parent in the construct tree), an *id*, and *props*, a bundle of key/value pairs that the construct uses to configure the resources it creates. Other classes and methods also use the "bundle of attributes" pattern for arguments. In C\$1, props are expressed using a props type. In idiomatic C\$1 fashion, we can use an object initializer to set the various properties. Here we're creating an Amazon S3 bucket using the `Bucket` construct; its corresponding props type is `BucketProps`. ``` var bucket = new Bucket(this, "MyBucket", new BucketProps { Versioned = true }); ``` **Tip** Add the package `Amazon.JSII.Analyzers` to your project to get required-values checking in your props definitions inside Visual Studio. When extending a class or overriding a method, you may want to accept additional props for your own purposes that are not understood by the parent class. To do this, subclass the appropriate props type and add the new attributes. ``` // extend BucketProps for use with MimeBucket class MimeBucketProps : BucketProps { public string MimeType { get; set; } } // hypothetical bucket that enforces MIME type of objects inside it class MimeBucket : Bucket { public MimeBucket( readonly Construct scope, readonly string id, readonly MimeBucketProps props=null) : base(scope, id, props) { // ... } } // instantiate our MimeBucket class var bucket = new MimeBucket(this, "MyBucket", new MimeBucketProps { Versioned = true, MimeType = "image/jpeg" }); ``` When calling the parent class's initializer or overridden method, you can generally pass the props you received. The new type is compatible with its parent, and extra props you added are ignored. A future release of the AWS CDK could coincidentally add a new property with a name you used for your own property. This won't cause any technical issues using your construct or method (since your property isn't passed "up the chain," the parent class or overridden method will simply use a default value) but it may cause confusion for your construct's users. You can avoid this potential problem by naming your properties so they clearly belong to your construct. If there are many new properties, bundle them into an appropriately-named class and pass them as a single property. ### Generic structures In some APIs, the AWS CDK uses JavaScript arrays or untyped objects as input to a method. (See, for example, AWS CodeBuild's [https://docs.aws.amazon.com/cdk/api/v2/docs/@aws-cdk_aws-codebuild.BuildSpec.html#to-wbr-build-wbr-spec](https://docs.aws.amazon.com/cdk/api/v2/docs/@aws-cdk_aws-codebuild.BuildSpec.html#to-wbr-build-wbr-spec) method.) In C\$1, these objects are represented as `System.Collections.Generic.Dictionary`. In cases where the values are all strings, you can use `Dictionary`. JavaScript arrays are represented as `object[]` or `string[]` in C\$1. **Tip** You might define short aliases to make it easier to work with these specific dictionary types. ``` using StringDict = System.Collections.Generic.Dictionary; using ObjectDict = System.Collections.Generic.Dictionary; ``` ### Missing values In C\$1, missing values in AWS CDK objects such as props are represented by `null`. The null-conditional member access operator `?.` and the null coalescing operator `??` are convenient for working with these values. ``` // mimeType is null if props is null or if props.MimeType is null string mimeType = props?.MimeType; // mimeType defaults to text/plain. either props or props.MimeType can be null string MimeType = props?.MimeType ?? "text/plain"; ``` ## Building, synthesizing, and deploying The AWS CDK automatically compiles your app before running it. However, it can be useful to build your app manually to check for errors and run tests. You can do this by pressing F6 in Visual Studio or by issuing `dotnet build src` from the command line, where `src` is the directory in your project directory that contains the Visual Studio Solution (`.sln`) file. The [stacks](stacks.md) defined in your AWS CDK app can be synthesized and deployed individually or together using the commands below. Generally, you should be in your project's main directory when you issue them. + `cdk synth`: Synthesizes a CloudFormation template from one or more of the stacks in your AWS CDK app. + `cdk deploy`: Deploys the resources defined by one or more of the stacks in your AWS CDK app to AWS. You can specify the names of multiple stacks to be synthesized or deployed in a single command. If your app defines only one stack, you do not need to specify it. ``` cdk synth # app defines single stack cdk deploy Happy Grumpy # app defines two or more stacks; two are deployed ``` You may also use the wildcards \$1 (any number of characters) and ? (any single character) to identify stacks by pattern. When using wildcards, enclose the pattern in quotes. Otherwise, the shell may try to expand it to the names of files in the current directory before they are passed to the AWS CDK Toolkit. ``` cdk synth "Stack?" # Stack1, StackA, etc. cdk deploy "*Stack" # PipeStack, LambdaStack, etc. ``` **Tip** You don't need to explicitly synthesize stacks before deploying them; `cdk deploy` performs this step for you to make sure your latest code gets deployed. For full documentation of the `cdk` command, see [AWS CDK Toolkit (`cdk` command)](cli.md). # Working with the AWS CDK in Go In Go Go is a fully-supported client language for the AWS CDK and is considered stable. Working with the AWS CDK in Go uses familiar tools. The Go version of the AWS CDK even uses Go-style identifiers. Unlike the other languages the CDK supports, Go is not a traditional object-oriented programming language. Go uses composition where other languages often leverage inheritance. We have tried to employ idiomatic Go approaches as much as possible, but there are places where the CDK charts its own course. This topic explains the ins and outs of working with the AWS CDK in Go. See the [announcement blog post](https://aws.amazon.com/blogs/developer/getting-started-with-the-aws-cloud-development-kit-and-go/) for a walkthrough of a simple Go project for the AWS CDK. ## Prerequisites To work with the AWS CDK, you must have an AWS account and credentials and have installed Node.js and the AWS CDK Toolkit. See [AWS CDK Prerequisites](work-with.md#work-with-prerequisites). The Go bindings for the AWS CDK use the standard [Go toolchain](https://golang.org/dl/), v1.16 or later. You can use the editor of your choice. **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. ## Creating a project You create a new AWS CDK project by invoking `cdk init` in an empty directory. ``` mkdir my-project cd my-project cdk init app --language go ``` `cdk init` uses the name of the project folder to name various elements of the project, including classes, subfolders, and files. Hyphens in the folder name are converted to underscores. However, the name should otherwise follow the form of a Go identifier; for example, it should not start with a number or contain spaces. The resulting project includes a reference to the AWS CDK Go module, `github.com/aws/aws-cdk-go/awscdk`, in `go.mod`. The CDK and its dependencies are automatically installed when you build your app. ## Managing AWS Construct Library modules In most AWS CDK documentation and examples, the word "module" is used primarily to refer to AWS Construct Library modules, one or more per AWS service, which differs from idiomatic Go usage of the term. The CDK Construct Library is provided in one Go module with the individual Construct Library modules, which support the various AWS services, provided as Go packages within that module. Some services' AWS Construct Library support is in more than one Construct Library module (Go package). For example, Amazon Route 53 has three Construct Library modules in addition to the main `awsroute53` package, named `awsroute53patterns`, `awsroute53resolver`, and `awsroute53targets`. The AWS CDK's core package, which you'll need in most AWS CDK apps, is imported in Go code as `github.com/aws/aws-cdk-go/awscdk`. Packages for the various services in the AWS Construct Library live under `github.com/aws/aws-cdk-go/awscdk`. For example, the Amazon S3 module's namespace is `github.com/aws/aws-cdk-go/awscdk/awss3`. ``` import ( "github.com/aws/aws-cdk-go/awscdk/awss3" 2.16.0 // ... ) ``` The contents of the Amazon S3 Go package are then available in the `awss3` namespace. For example, to instantiate a bucket, you would call `awss3.NewBucket()`. You may specify an alias when importing if you prefer more concise names: ``` import ( s3 "github.com/aws/aws-cdk-go/awscdk/awss3" // use s3.NewBucket etc. // ... ) ``` The code examples in this guide use the actual Go package names, so it is clear which Go packages (AWS Construct Library modules) are needed. ## AWS CDK idioms in Go ### Field and method names Field and method names use camel casing (`likeThis`) in TypeScript, the CDK's language of origin. In Go, these follow Go conventions, so are Pascal-cased (`LikeThis`). ### Missing values and pointer conversion In Go, missing values in AWS CDK objects such as property bundles are represented by `nil`. Go doesn't have nullable types; the only type that can contain `nil` is a pointer. To allow values to be optional, then, all CDK properties, arguments, and return values are pointers, even for primitive types. This applies to required values as well as optional ones, so if a required value later becomes optional, no breaking change in type is needed. When passing literal values or expressions, you can use the following helper functions to create pointers to the values. + `jsii.String` + `jsii.Number` + `jsii.Bool` + `jsii.Time` For consistency, we recommend that you use pointers similarly when defining your own constructs, even though it may seem more convenient to, for example, receive your construct's `id` as a string rather than a pointer to a string. When dealing with optional AWS CDK values, including primitive values as well as complex types, you should explicitly test pointers to make sure they are not `nil` before doing anything with it. Go does not have "syntactic sugar" to help handle empty or missing values as some other languages do. However, required values in property bundles and similar structures are guaranteed to exist (construction fails otherwise), so these values need not be `nil`-checked. ### Constructs and Props Constructs, which represent one or more AWS resources and their associated attributes, are represented in Go as interfaces. For example, `awss3.Bucket` is an interface. Every construct has a factory function, such as `awss3.NewBucket`, to return a struct that implements the corresponding interface. All factory functions take three arguments: the `scope` in which the construct is being defined (its parent in the construct tree), an `id`, and `props`, a bundle of key/value pairs that the construct uses to configure the resources it creates. The "bundle of attributes" pattern is also used elsewhere in the AWS CDK. In Go, props are represented by a specific struct type for each construct. For example, an `awss3.Bucket` takes a props argument of type `awss3.BucketProps`. Use a struct literal to write props arguments. ``` var bucket = awss3.NewBucket(stack, jsii.String("MyBucket"), &awss3.BucketProps{ Versioned: jsii.Bool(true), }) ``` ### Generic structures In some places, the AWS CDK uses JavaScript arrays or untyped objects as input to a method. (See, for example, AWS CodeBuild's [https://docs.aws.amazon.com/cdk/api/v2/docs/@aws-cdk_aws-codebuild.BuildSpec.html#to-wbr-build-wbr-spec](https://docs.aws.amazon.com/cdk/api/v2/docs/@aws-cdk_aws-codebuild.BuildSpec.html#to-wbr-build-wbr-spec) method.) In Go, these objects are represented as slices and an empty interface, respectively. The CDK provides variadic helper functions such as `jsii.Strings` for building slices containing primitive types. ``` jsii.Strings("One", "Two", "Three") ``` ### Developing custom constructs In Go, it is usually more straightforward to write a new construct than to extend an existing one. First, define a new struct type, anonymously embedding one or more existing types if extension-like semantics are desired. Write methods for any new functionality you're adding and the fields necessary to hold the data they need. Define a props interface if your construct needs one. Finally, write a factory function `NewMyConstruct()` to return an instance of your construct. If you are simply changing some default values on an existing construct or adding a simple behavior at instantiation, you don't need all that plumbing. Instead, write a factory function that calls the factory function of the construct you're "extending." In other CDK languages, for example, you might create a `TypedBucket` construct that enforces the type of objects in an Amazon S3 bucket by overriding the `s3.Bucket` type and, in your new type's initializer, adding a bucket policy that allows only specified filename extensions to be added to the bucket. In Go, it is easier to simply write a `NewTypedBucket` that returns an `s3.Bucket` (instantiated using `s3.NewBucket`) to which you have added an appropriate bucket policy. No new construct type is necessary because the functionality is already available in the standard bucket construct; the new "construct" just provides a simpler way to configure it. ## Building, synthesizing, and deploying The AWS CDK automatically compiles your app before running it. However, it can be useful to build your app manually to check for errors and to run tests. You can do this by issuing `go build` at a command prompt while in your project's root directory. Run any tests you've written by running `go test` at a command prompt. The [stacks](stacks.md) defined in your AWS CDK app can be synthesized and deployed individually or together using the commands below. Generally, you should be in your project's main directory when you issue them. + `cdk synth`: Synthesizes a CloudFormation template from one or more of the stacks in your AWS CDK app. + `cdk deploy`: Deploys the resources defined by one or more of the stacks in your AWS CDK app to AWS. You can specify the names of multiple stacks to be synthesized or deployed in a single command. If your app defines only one stack, you do not need to specify it. ``` cdk synth # app defines single stack cdk deploy Happy Grumpy # app defines two or more stacks; two are deployed ``` You may also use the wildcards \$1 (any number of characters) and ? (any single character) to identify stacks by pattern. When using wildcards, enclose the pattern in quotes. Otherwise, the shell may try to expand it to the names of files in the current directory before they are passed to the AWS CDK Toolkit. ``` cdk synth "Stack?" # Stack1, StackA, etc. cdk deploy "*Stack" # PipeStack, LambdaStack, etc. ``` **Tip** You don't need to explicitly synthesize stacks before deploying them; `cdk deploy` performs this step for you to make sure your latest code gets deployed. For full documentation of the `cdk` command, see [AWS CDK Toolkit (`cdk` command)](cli.md).