/fwang/aws-cdk

Wiki directory

Browse AI-generated documentation for any repository.

Installation and Setup

Relevant source files

The following files were used as context for generating this wiki page:

The AWS Cloud Development Kit (AWS CDK) is an open-source framework for defining cloud infrastructure in code and provisioning it through AWS CloudFormation. This guide covers the necessary prerequisites, installation of the CDK Toolkit, and the process of initializing a new CDK project.

The CDK allows developers to use modern programming languages to define reusable cloud components called constructs. These are composed into stacks and apps, which can then be managed using the AWS CDK Command Line Interface (CLI). The CLI facilitates synthesizing CloudFormation templates, deploying stacks, and comparing changes against a deployed stack.

Sources: README.md:10-17, README.md:28-34

Prerequisites

Before using the AWS CDK, you must have the required version of your chosen programming language's runtime and any associated build tools installed.

Language	Requirement	Node.js Compatibility
JavaScript/TypeScript	Node.js ≥ 10.13.0 (Active LTS recommended)	Versions `13.0.0` to `13.6.0` are not supported.
Python	Python ≥ 3.6	N/A
Java	Java ≥ 8 and Maven ≥ 3.5.4	N/A
.NET	.NET Core ≥ 3.1	N/A
Go	Go ≥ 1.16.4 (Developer Preview)	N/A

The Node.js version constraint node: ">= 10.13.0 <13 || >=13.7.0" is enforced across CDK packages.

Sources: README.md:19-26, packages/aws-cdk/package.json:104-106, tools/pkglint/lib/rules.ts:1010-1012

AWS CDK CLI Installation

The primary method for installing the AWS CDK CLI is through npm. The CLI requires Node.js.

$ npm i -g aws-cdk

A manual installation option from a signed .zip file is also available, as referenced in the main README.md.

Sources: README.md:62-66, README.md:68

Project Initialization

A new CDK project is created using the cdk init command. This command sets up a new project directory with a sample application based on a specified template and language.

Sources: README.md:71-75, packages/aws-cdk/lib/init.ts:18-20

`cdk init` Command Flow

The cdk init command follows a specific logic to initialize a project. If no template or language is provided, it lists available options. Otherwise, it proceeds with project creation.

The following diagram illustrates the cliInit function's control flow.

Generating architecture diagram...

Sources: packages/aws-cdk/lib/init.ts:18-37

Templates and Languages

The cdk init command uses templates to scaffold new projects. Each template can support one or more programming languages. You can list available templates by running cdk init without any arguments.

The InitTemplate class is responsible for managing the installation of a template for a given language.

Sources: packages/aws-cdk/lib/init.ts:47-52, packages/aws-cdk/lib/init.ts:241-248

Project Creation Process

When cdk init is executed with a valid template and language, it performs several steps to set up the project directory.

The following sequence diagram shows the high-level process managed by the initializeProject function.

Generating architecture diagram...

Sources: packages/aws-cdk/lib/init.ts:250-264

File Installation and Placeholder Expansion

The installFiles method copies files from the template directory. Files ending in .template are processed to replace placeholders with project-specific values.

Placeholder	Description	Example Value
`%name%`	The decamelized name of the project directory.	`hello-cdk`
`%name.camelCased%`	The project name in camelCase.	`helloCdk`
`%name.PascalCased%`	The project name in PascalCase.	`HelloCdk`
`%cdk-version%`	The current version of the AWS CDK.	`1.100.0`
`%cdk-home%`	The CDK home directory path.	`~/.cdk`
`%name.PythonModule%`	The project name formatted as a Python module.	`hello_cdk`
`%python-executable%`	The platform-specific Python executable name.	`python3` or `python`
`%name.StackName%`	The project name sanitized for use as a CloudFormation Stack name.	`hello-cdk`

Sources: packages/aws-cdk/lib/init.ts:110-117, packages/aws-cdk/lib/init.ts:153-162

Post-Installation Steps

After the project files are created, language-specific post-installation steps are executed to set up the development environment.

JavaScript/TypeScript: Runs npm install to download dependencies.
Java: Runs mvn package to compile code and create a JAR file.
Python: Creates a virtual environment in a .venv directory using python -m venv .venv.

These steps can be skipped with the --generate-only flag. If network access is disabled, warnings are printed with instructions to run these commands manually.

Sources: packages/aws-cdk/lib/init.ts:279-317

Project Structure and Commands

A newly initialized project contains a basic CDK application structure, a cdk.json configuration file, and other language-specific files.

Common CLI Commands

Once a project is set up, you can interact with it using the CDK CLI.

Command	Description
`cdk deploy`	Deploys the app's stacks to your AWS account.
`cdk synth`	Synthesizes and prints the CloudFormation template for the app.
`cdk diff`	Compares the current app state with the deployed stack.
`npm run test`	(For JS/TS) Performs Jest unit tests.

Sources: README.md:88-92, packages/aws-cdk/lib/init-templates/v2/app/javascript/README.md:7-11

Dependency Management

CDK projects rely on dependencies, including the core library (@aws-cdk/core or aws-cdk-lib), construct libraries for specific AWS services, and the constructs library.

CDK Library Dependencies

Dependencies on other @aws-cdk/ packages must use a specific version, not a version range. These dependencies must also be declared in peerDependencies to ensure version consistency across the project.

For example, a package.json for a CDK construct might contain:

"dependencies": {
  "@aws-cdk/core": "0.0.0",
  "@aws-cdk/aws-iam": "0.0.0",
  "constructs": "^3.3.69"
},
"peerDependencies": {
  "@aws-cdk/core": "0.0.0",
  "@aws-cdk/aws-iam": "0.0.0",
  "constructs": "^3.3.69"
}

Sources: tools/pkglint/lib/rules.ts:910-946, packages/@aws-cdk/aws-iam/package.json:71-82

Python Dependencies

For Python projects, dependencies are specified in setup.py. The template includes common CDK packages.

# packages/aws-cdk/lib/init-templates/v1/sample-app/python/setup.template.py:18-26
install_requires=[
    "aws-cdk.core==%cdk-version%",
    "aws-cdk.aws_iam==%cdk-version%",
    "aws-cdk.aws_sqs==%cdk-version%",
    "aws-cdk.aws_sns==%cdk-version%",
    "aws-cdk.aws_sns_subscriptions==%cdk-version%",
    "aws-cdk.aws_s3==%cdk-version%",
],

Sources: packages/aws-cdk/lib/init-templates/v1/sample-app/python/setup.template.py:18-26

Automatic Module Generation

The CDK build process includes a tool to automatically generate new construct library packages for CloudFormation namespaces that don't have one. This process creates a package.json with the correct dependencies, build scripts, and JSII configuration for multi-language support. It also adds the new package as a dependency to "mega-packages" like aws-cdk-lib.

Sources: packages/@aws-cdk/cfnspec/build-tools/create-missing-libraries.ts:8-12, packages/@aws-cdk/cfnspec/build-tools/create-missing-libraries.ts:255-259

Installation and Setup

Relevant source files

The following files were used as context for generating this wiki page:

Sources: README.md:10-17, README.md:28-34

Prerequisites

Before using the AWS CDK, you must have the required version of your chosen programming language's runtime and any associated build tools installed.

Language	Requirement	Node.js Compatibility
JavaScript/TypeScript	Node.js ≥ 10.13.0 (Active LTS recommended)	Versions `13.0.0` to `13.6.0` are not supported.
Python	Python ≥ 3.6	N/A
Java	Java ≥ 8 and Maven ≥ 3.5.4	N/A
.NET	.NET Core ≥ 3.1	N/A
Go	Go ≥ 1.16.4 (Developer Preview)	N/A

The Node.js version constraint node: ">= 10.13.0 <13 || >=13.7.0" is enforced across CDK packages.

Sources: README.md:19-26, packages/aws-cdk/package.json:104-106, tools/pkglint/lib/rules.ts:1010-1012

AWS CDK CLI Installation

The primary method for installing the AWS CDK CLI is through npm. The CLI requires Node.js.

$ npm i -g aws-cdk

A manual installation option from a signed .zip file is also available, as referenced in the main README.md.

Sources: README.md:62-66, README.md:68

Project Initialization

A new CDK project is created using the cdk init command. This command sets up a new project directory with a sample application based on a specified template and language.

Sources: README.md:71-75, packages/aws-cdk/lib/init.ts:18-20

`cdk init` Command Flow

The cdk init command follows a specific logic to initialize a project. If no template or language is provided, it lists available options. Otherwise, it proceeds with project creation.

The following diagram illustrates the cliInit function's control flow.

Generating architecture diagram...

Sources: packages/aws-cdk/lib/init.ts:18-37

Templates and Languages

The InitTemplate class is responsible for managing the installation of a template for a given language.

Sources: packages/aws-cdk/lib/init.ts:47-52, packages/aws-cdk/lib/init.ts:241-248

Project Creation Process

When cdk init is executed with a valid template and language, it performs several steps to set up the project directory.

The following sequence diagram shows the high-level process managed by the initializeProject function.

Generating architecture diagram...

Sources: packages/aws-cdk/lib/init.ts:250-264

File Installation and Placeholder Expansion

The installFiles method copies files from the template directory. Files ending in .template are processed to replace placeholders with project-specific values.

Placeholder	Description	Example Value
`%name%`	The decamelized name of the project directory.	`hello-cdk`
`%name.camelCased%`	The project name in camelCase.	`helloCdk`
`%name.PascalCased%`	The project name in PascalCase.	`HelloCdk`
`%cdk-version%`	The current version of the AWS CDK.	`1.100.0`
`%cdk-home%`	The CDK home directory path.	`~/.cdk`
`%name.PythonModule%`	The project name formatted as a Python module.	`hello_cdk`
`%python-executable%`	The platform-specific Python executable name.	`python3` or `python`
`%name.StackName%`	The project name sanitized for use as a CloudFormation Stack name.	`hello-cdk`

Sources: packages/aws-cdk/lib/init.ts:110-117, packages/aws-cdk/lib/init.ts:153-162

Post-Installation Steps

After the project files are created, language-specific post-installation steps are executed to set up the development environment.

JavaScript/TypeScript: Runs npm install to download dependencies.
Java: Runs mvn package to compile code and create a JAR file.
Python: Creates a virtual environment in a .venv directory using python -m venv .venv.

These steps can be skipped with the --generate-only flag. If network access is disabled, warnings are printed with instructions to run these commands manually.

Sources: packages/aws-cdk/lib/init.ts:279-317

Project Structure and Commands

A newly initialized project contains a basic CDK application structure, a cdk.json configuration file, and other language-specific files.

Common CLI Commands

Once a project is set up, you can interact with it using the CDK CLI.

Command	Description
`cdk deploy`	Deploys the app's stacks to your AWS account.
`cdk synth`	Synthesizes and prints the CloudFormation template for the app.
`cdk diff`	Compares the current app state with the deployed stack.
`npm run test`	(For JS/TS) Performs Jest unit tests.

Sources: README.md:88-92, packages/aws-cdk/lib/init-templates/v2/app/javascript/README.md:7-11

Dependency Management

CDK projects rely on dependencies, including the core library (@aws-cdk/core or aws-cdk-lib), construct libraries for specific AWS services, and the constructs library.

CDK Library Dependencies

For example, a package.json for a CDK construct might contain:

"dependencies": {
  "@aws-cdk/core": "0.0.0",
  "@aws-cdk/aws-iam": "0.0.0",
  "constructs": "^3.3.69"
},
"peerDependencies": {
  "@aws-cdk/core": "0.0.0",
  "@aws-cdk/aws-iam": "0.0.0",
  "constructs": "^3.3.69"
}

Sources: tools/pkglint/lib/rules.ts:910-946, packages/@aws-cdk/aws-iam/package.json:71-82

Python Dependencies

For Python projects, dependencies are specified in setup.py. The template includes common CDK packages.

# packages/aws-cdk/lib/init-templates/v1/sample-app/python/setup.template.py:18-26
install_requires=[
    "aws-cdk.core==%cdk-version%",
    "aws-cdk.aws_iam==%cdk-version%",
    "aws-cdk.aws_sqs==%cdk-version%",
    "aws-cdk.aws_sns==%cdk-version%",
    "aws-cdk.aws_sns_subscriptions==%cdk-version%",
    "aws-cdk.aws_s3==%cdk-version%",
],

Sources: packages/aws-cdk/lib/init-templates/v1/sample-app/python/setup.template.py:18-26

Automatic Module Generation

Sources: packages/@aws-cdk/cfnspec/build-tools/create-missing-libraries.ts:8-12, packages/@aws-cdk/cfnspec/build-tools/create-missing-libraries.ts:255-259

Installation and Setup

Prerequisites

AWS CDK CLI Installation

Project Initialization

cdk init Command Flow

Templates and Languages

Project Creation Process

File Installation and Placeholder Expansion

Post-Installation Steps

Project Structure and Commands

Common CLI Commands

Dependency Management

CDK Library Dependencies

Python Dependencies

Automatic Module Generation

Installation and Setup

Prerequisites

AWS CDK CLI Installation

Project Initialization

cdk init Command Flow

Templates and Languages

Project Creation Process

File Installation and Placeholder Expansion

Post-Installation Steps

Project Structure and Commands

Common CLI Commands

Dependency Management

CDK Library Dependencies

Python Dependencies

Automatic Module Generation

`cdk init` Command Flow

`cdk init` Command Flow