AWS CDK Developer Guide

The AWS Cloud Development Kit (AWS CDK) is an open-source software development framework used to define cloud infrastructure in code and provision it through AWS CloudFormation.

It consists of two primary components:

1. AWS CDK Construct Library: A collection of pre-written, modular, and reusable code pieces called constructs. These reduce the complexity of integrating AWS services.
2. AWS CDK Toolkit: Tools to manage and interact with CDK applications, including the CDK CLI (command line interface) and the CDK Toolkit Library (programmatic library).

You can use general-purpose programming languages like TypeScript, JavaScript, Python, Java, C#/.Net, and Go to compose constructs into stacks and apps, which are then deployed via AWS CloudFormation.

The AWS CDK Toolkit Library allows you to execute CDK actions through code instead of using the CDK CLI. This is useful for building custom deployment tools, automating CI/CD pipelines, or integrating CDK capabilities directly into existing applications.

Supported programmatic actions include:

• Synthesis: Generating CloudFormation templates and deployment artifacts.
• Deployment: Provisioning or updating infrastructure.
• Refactor: Preserving resources when renaming constructs or moving them between stacks.
• List: Viewing stack information and dependencies.
• Watch: Monitoring apps for local changes.
• Rollback: Returning stacks to their last stable state.
• Destroy: Removing stacks and associated resources.

import { Toolkit } from '@aws-cdk/toolkit-lib';
const toolkit = new Toolkit();

Testing {aws} CDK applications can be done in the cloud or locally. The standard approach for testing CDK apps uses the assertions module along with popular test frameworks like Jest (for TypeScript/JavaScript) or Pytest (for Python).

There are two primary categories of tests:

1. Fine-grained assertions: These test specific aspects of the generated CloudFormation template (e.g., verifying a resource has a specific property value). They are ideal for detecting regressions and supporting test-driven development.
2. Snapshot tests: These compare the synthesized CloudFormation template against a previously stored baseline. They allow for free refactoring, but because CDK upgrades can change synthesized templates, they should not be the sole method of verification.

The AWS Cloud Development Kit (AWS CDK) provides first-class support for several general-purpose programming languages. While the CDK is developed in TypeScript, it uses a tool called JSII to generate language bindings for other supported languages, allowing you to use the CDK with your preferred language's standard conventions, package managers, and naming patterns.

Supported languages:
* TypeScript
* JavaScript
* Python
* Java
* C#
* Go

You can use the AWS SAM CLI to build and locally test serverless applications defined using the AWS CDK. Since the SAM CLI operates within the existing AWS CDK project structure, you can continue to use the AWS CDK CLI for standard operations like creating, modifying, and deploying your applications.

For comprehensive instructions on SAM-specific workflows, refer to the AWS Serverless Application Model Developer Guide.

An AWS CDK Stage represents a group of one or more CDK stacks that are configured to deploy together.

Stages are primarily used to deploy the same grouping of stacks to multiple environments (e.g., development, testing, and production) by instantiating the same Stage class with different environment configurations (account and region).

An AWS CDK application (or App) is the top-level container for your infrastructure. It is a collection of one or more Stack constructs.

Key characteristics:

• Root Construct: The App is the only construct that can serve as the root of the construct tree and does not require initialization arguments.
• Context Provider: Unlike other constructs, App and Stack do not configure AWS resources directly; they provide the necessary context and scope for other constructs.
• Resource Scoping: All constructs representing AWS resources must be defined, directly or indirectly, within the scope of a Stack. Stacks, in turn, must be defined within the scope of an App.
• Synthesis: Apps are synthesized to generate AWS CloudFormation templates for all contained stacks.

An environment in the AWS CDK is the combination of an AWS account and an AWS Region where you deploy a CDK stack.

• AWS account: A unique 12-digit identifier (e.g., 012345678901) that identifies your AWS account.
• AWS Region: A geographical location combined with a number representing an Availability Zone (e.g., us-east-1).

Bootstrapping is the process of preparing an AWS environment for use with the AWS Cloud Development Kit (CDK). Before you can deploy a CDK stack into an AWS environment, that environment must be bootstrapped to provision the necessary resources required for deployments.

Bootstrapping provisions a set of bootstrap resources, which include:

• Amazon S3 bucket: Stores CDK project files, such as AWS Lambda function code and assets.
• Amazon Elastic Container Registry (Amazon ECR) repository: Primarily used to store Docker images.
• AWS Identity and Access Management (IAM) roles: Configured to grant the permissions required by the CDK to perform deployments.

When you create a cached cloud assembly using synth(), the resulting object acts as both a CloudAssembly and a CloudAssemblySource.

Crucially, any cloud assemblies produced by subsequent Toolkit operations (like those returned by list() or deploy()) are tied to the lifetime of the parent assembly. Only the call to dispose() on the original parent assembly performs the actual resource cleanup. Failing to dispose of a cached cloud assembly is considered a bug.