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 stages to deploy
  • Directorystages CDK Stage definitions

    • application-stage.ts Defines a collection of stacks to deploy in a stage
  • 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 { Stack, StackProps } from 'aws-cdk-lib';
import { Bucket } from 'aws-cdk-lib/aws-s3'
import { Construct } from 'constructs';

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

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

Stages and Stacks

You will notice that the top level src/main.ts file instantiates a CDK Stage named <namespace>-sandbox. This stage is intended for your own development and testing.

src/main.ts

new ApplicationStage(app, 'project-sandbox', {
  env: {
    account: process.env.CDK_DEFAULT_ACCOUNT,
    region: process.env.CDK_DEFAULT_REGION,
  },
});

You can add more stages, for example you may wish to define beta and prod stages which deploy to separate environments:

src/main.ts

new ApplicationStage(app, 'project-beta', {
  env: {
    account: '123456789012', // beta account
    region: 'us-west-2',
  },
});
new ApplicationStage(app, 'project-prod', {
  env: {
    account: '098765432109', // prod account
    region: 'us-west-2',
  },
});

A Stage defines a collection of stacks that should be deployed together to make up your application. You can instantiate as many stacks as you like within a stage, for example:

src/stages/application-stage.ts

import { Stage, StageProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { BackendStack } from '../stacks/backend-stack.js';
import { FrontendStack } from '../stacks/frontend-stack.js';

/**
 * Defines a collection of CDK Stacks which make up your application
 */
export class ApplicationStage extends Stage {
  constructor(scope: Construct, id: string, props?: StageProps) {
    super(scope, id, props);

    new BackendStack(this, 'Backend', {
      crossRegionReferences: true,
    })

    new FrontendStack(this, 'Frontend', {
      crossRegionReferences: true,
    });
  }
}

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', {
      integrations: MyApi.defaultIntegrations(this).build(),
    });
  }
}

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.

Caution

Use the deploy-ci target if deploying in a CI/CD pipeline. See below for more details.

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

Next, run the deploy target:

pnpm

pnpm nx run <my-infra>:deploy <my-infra>-sandbox/*

yarn

yarn nx run <my-infra>:deploy <my-infra>-sandbox/*

npm

npx nx run <my-infra>:deploy <my-infra>-sandbox/*

bun

bunx nx run <my-infra>:deploy <my-infra>-sandbox/*

Tip

The above command deploys all stacks for the <my-infra>-sandbox stage. You can specify other stages so long as they are defined in main.ts.

You can also deploy individual stacks by specifying the full stack name, for example:

pnpm

pnpm nx run <my-infra>:deploy <my-infra>-sandbox/Application

yarn

yarn nx run <my-infra>:deploy <my-infra>-sandbox/Application

npm

npx nx run <my-infra>:deploy <my-infra>-sandbox/Application

bun

bunx nx run <my-infra>:deploy <my-infra>-sandbox/Application

Deploying to AWS in a CI/CD Pipeline

Use the deploy-ci target if you are deploying to AWS as part of a CI/CD pipeline.

pnpm

pnpm nx run <my-infra>:deploy-ci my-stage/*

yarn

yarn nx run <my-infra>:deploy-ci my-stage/*

npm

npx nx run <my-infra>:deploy-ci my-stage/*

bun

bunx nx run <my-infra>:deploy-ci my-stage/*

This target differs slightly from the regular deploy target in that it ensures pre-synthesized cloud-assembly is deployed, rather than synthesizing on the fly. This helps to avoid potential issues with non-determinism due to changes package versions, ensuring that every pipeline stage deploys using the same cloud-assembly.

Tearing Down AWS Infrastructure

Use the destroy target to tear down your resources:

pnpm

pnpm nx run <my-infra>:destroy <my-infra>-sandbox/*

yarn

yarn nx run <my-infra>:destroy <my-infra>-sandbox/*

npm

npx nx run <my-infra>:destroy <my-infra>-sandbox/*

bun

bunx nx run <my-infra>:destroy <my-infra>-sandbox/*

More Information

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