@routineless/nx-aws-cdk

Nx plugin for aws cdk application development.

Table of Contents

• Install
• Usage
• Maintainers
• License

Install

To install this plugin to existing nx workspace run:

npm install -D @routineless/nx-aws-cdk

Usage

Right now this plugin supports nx integrated repos only.

Preset

@routineless/nx-aws-cdk can be used to generate aws cdk app with create-nx-workspace.

You can generate nx workspace using preset.

npx create-nx-workspace nx-aws-cdk-workspace --preset @routineless/nx-aws-cdk

Same can be achieved by running:

npx create-aws-cdk-app nx-aws-cdk-workspace

This command will create a workspace with cdk application and optionaly initial lambda function app. It utilizes cdk-application and aws-lambda generators to generate applications.

├── apps
│   ├── <lambdaApp>
│   │   └── src
│   │       ├── index.ts
│   │       ├── infra
│   │       │   └── index.ts
│   │       └── runtime
│   │           └── main.ts
│   └── <cdkApp>
│       ├── cdk.json
│       └── src
│           ├── main.ts
│           └── stacks
│
├── docker
│   └── docker-compose.yaml
├── libs
└── nx.json

Docker compose file can be used to start localstack environment.

Available Options

Cdk application generator

After installing @routineless/nx-aws-cdk or generating workspace using preset you can add cdk application to your nx workspace by running:

npx nx g cdk-application infra

Note: --setAsRoutinelessInfraApp=true will set generated app as routineless infra app and all generated lambda functions will be added to this application.

Generated application structure:

├── cdk.json
├── jest.config.ts
├── project.json
├── src
│   ├── assets
│   ├── environment.spec.ts
│   ├── environment.ts
│   ├── main.ts
│   └── stacks
│       ├── persistance.spec.ts
│       └── persistance.ts
├── tsconfig.app.json
├── tsconfig.json
└── tsconfig.spec.json

Stacks directory contains all cdk stacks and has generated persistance stack with simple S3 bucket for demonstration purposes. Cdk application configuration is defined in cdk.json file. Project json will have cdk preconfigured target.

"cdk": {
  "executor": "@routineless/nx-aws-cdk:cdk",
  "dependsOn": ["build"]
}

All stacks that should be managed withing generated cdk application should be described in the main.ts file.

Lambda application generator

Lambda generator will generate nx application for lambda runtime and infrastructure code that can be used by cdk. It also can add lambda to existing cdk application if it is configured as routineless infra app.

npx nx g aws-lambda foo-lambda

Generated application structure:

├── jest.config.ts
├── package.json
├── project.json
├── src
│   ├── index.ts
│   ├── infra
│   │   ├── index.spec.ts
│   │   └── index.ts
│   └── runtime
│       ├── main.spec.ts
│       └── main.ts
├── tsconfig.json
├── tsconfig.lib.json
└── tsconfig.spec.json

Runtime code is located in src/runtime/main.ts file. Infrastructure code is located in src/infra/index.ts file.

Cdk executor

Cdk executor is responsible for cdk commands execution. It can be used to bootstrap, deploy, destroy and executing other cdk commands. General usage pattern is npx nx cdk <cdk-project-name> <cdk command> ...args.

In order to use cdk executor you need a valid cdk.json configuration in the root of your application, bare minimal configuration looks like this:

"cdk": {
  "executor": "@routineless/nx-aws-cdk:cdk",
  "dependsOn": ["build"]
}

Local setup

By default all infrastructure would be deployed to your localstack. If you were using @routineless/nx-aws-cdk preset you can start localstack by running:

(cd docker && docker-compose up --wait)

Otherwice you need to follow localstack insallation guide.

Then you can run cdk diff against localstack environment:

npx nx cdk <cdk-project-name> diff

Then you can deploy your application to aws by running:

npx nx cdk <cdk-project-name> bootstrap
npx nx cdk <cdk-project-name> deploy --all

You can inspect deployed resources using awslocal cli. Note that awslocal uses us-east-1 region by default. If you have configured another default region in your ~/.aws/config file you need to provide --region flag to awslocal commands or define DEFAULT_REGION env variable to have the same value.

pip install awscli-local
awslocal lambda list-functions
awslocal lambda invoke --function-name <functionName> '/dev/stdout'

Then you can destroy your infrastructure by running:

npx nx cdk <cdk-project-name> destroy --all

All commands can be run with --watch flag to enable watch mode.

Note: Insert gif demo here

AWS setup

In order to deploy cdk application to aws account you need to have configured aws credentials and provide --env <env> flag to cdk executor. Env flag can be anything except local as it is reserved for localstack environment.

npx nx cdk <cdk-project-name> diff --env dev
npx nx cdk <cdk-project-name> bootstrap --env dev
npx nx cdk <cdk-project-name> deploy --all --env dev
// In order to prevent aws cli from sending output to vi you can provide --no-cli-pager
// or run aws configure set cli_pager ""
aws lambda list-functions
aws lambda invoke --function-name <functionName> '/dev/stdout'
npx nx cdk <cdk-project-name> destroy --all --env dev

You can provide --profile <profile> flag to cdk executor to use specific aws profile. Same can be achieved by setting AWS_PROFILE env variable. Bu default all stacks will resolve their region and account using aws pseudo parameters that will be resolved during deployment. You can provide specific account region information using --region <region> and --account <account> flags. You can use --resolve flag to try to resolve account/region information from aws config, it will fallback to pseudo parameters if resolution failes.

AWS_ENV=dev npx nx cdk <cdk-project-name> diff --resolve

Maintainers

@KozelAnatoliy

License

MIT © 2023 Anatoli Kozel