CDK Infrastructure

AWS CDK is a framework for defining cloud infrastructure in code and provisioning it through AWS CloudFormation.

The TypeScript infrastructure generator creates an AWS CDK infrastructure application written in TypeScript. The generated application includes security best practices through CFN Guard checks.

Usage

Generate an Infrastructure Project

You can generate a new infrastructure project in two ways:

VSCode

1. Install the Nx Console VSCode Plugin if you haven't already
2. Open the Nx Console in VSCode
3. Click Generate (UI) in the "Common Nx Commands" section
4. Search for @aws/nx-plugin - ts#infra
5. Fill in the required parameters
6. Click Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#infra

yarn

yarn nx g @aws/nx-plugin:ts#infra

npm

npx nx g @aws/nx-plugin:ts#infra

bun

bunx nx g @aws/nx-plugin:ts#infra

You can also perform a dry-run to see what files would be changed

pnpm

pnpm nx g @aws/nx-plugin:ts#infra --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#infra --dry-run

npm

npx nx g @aws/nx-plugin:ts#infra --dry-run

bun

bunx nx g @aws/nx-plugin:ts#infra --dry-run

Options

Parameter	Type	Default	Description
name required	string	-	The name of the application.
ruleSet	string	aws_prototyping	Rule set to validate your AWS resources with.
directory	string	packages	The directory of the new application.

Generator Output

The generator will create the following project structure in the <directory>/<name> directory:

• Directorysrc

  • main.ts Application entry point instantiating CDK stacks to deploy
  • Directorystacks CDK Stack definitions

    • application-stack.ts Main application stack
• cdk.json CDK configuration
• project.json Project configuration and build targets

Tip

Your infrastructure is a TypeScript project, so you can refer to the TypeScript project documentation for more details about their general usage.

Implementing your CDK Infrastructure

You can start writing your CDK infrastructure inside src/stacks/application-stack.ts, for example:

src/stacks/application-stack.ts

import * as cdk from 'aws-cdk-lib';
import { Bucket } from 'aws-cdk-lib/aws-s3'
import { Construct } from 'constructs';

export class ApplicationStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // Declare your infrastructure here
    new Bucket(this, 'MyBucket');
  }
}

API Infrastructure

If you have used the tRPC API or FastAPI generators to create APIs, you will notice you already have some constructs available in packages/common/constructs to deploy them.

If, for example, you created a tRPC API called my-api, you can simply import and instantiate the construct to add all necessary infrastructure to deploy it:

src/stacks/application-stack.ts

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { MyApi } from ':my-scope/common-constructs';

export class ApplicationStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // Add infrastructure for your API
    new MyApi(this, 'MyApi');
  }
}

Website Infrastructure

If you have used the CloudScape website generator, you will notice you already have a construct in packages/common/constructs to deploy it. For example:

src/stacks/application-stack.ts

import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { MyWebsite } from ':my-scope/common-constructs';

export class ApplicationStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // Add infrastructure for your website
    new MyWebsite(this, 'MyWebsite');
  }
}

It is important to ensure that the website is declared after any API constructs in order for the website Runtime Config to include all API config.

Synthesizing your Infrastructure

As part of your build target, as well as running the default compile, lint and test targets, your infrastructure project is synthesized to CloudFormation. This can also be executed in a standalone fashion, by running the synth target:

pnpm

pnpm nx run <my-infra>:synth

yarn

yarn nx run <my-infra>:synth

npm

npx nx run <my-infra>:synth

bun

bunx nx run <my-infra>:synth

You will find your synthesized cloud assembly in the root dist folder, under dist/packages/<my-infra-project>/cdk.out.

Bootstrapping your AWS Account(s)

If you are deploying a CDK application to an AWS Account for the first time, it will need to be bootstrapped first.

First, ensure that you have configured credentials for your AWS account.

Next, you can use the cdk bootstrap command:

npx cdk bootstrap aws://<account-id>/<region>

For more details, please refer to the CDK documentation.

Deploying to AWS

After a build, you can deploy your infrastructure to AWS using the deploy target.

First, ensure that you have configured credentials for your AWS account.

Next, run the deploy target:

pnpm

pnpm nx run <my-infra>:deploy --all

yarn

yarn nx run <my-infra>:deploy --all

npm

npx nx run <my-infra>:deploy --all

bun

bunx nx run <my-infra>:deploy --all

Tip

The above command deploys all stacks defined in main.ts. You may wish to target an individual stack, especially if you have configured multiple stages of an application for example:

pnpm

pnpm nx run <my-infra>:deploy my-sandbox-stack

yarn

yarn nx run <my-infra>:deploy my-sandbox-stack

npm

npx nx run <my-infra>:deploy my-sandbox-stack

bun

bunx nx run <my-infra>:deploy my-sandbox-stack

More Information

For more information about CDK, please refer to the CDK Developer Guide and API Reference.