cdk-constructs-lib

AWS CDK Building Blocks and tools

Table of contents

• cdk-constructs-lib
  • Table of contents
  • Usage
  • Documentation
  • Repository structure
    • Relation to build process
    • Bundled Lambda assets
  • Contribution guide

Usage

Install the NPM package with your package manager. Requires access to Finnair Artifactory to be configured

## NPM
npm install @finnairoyj/cdk-constructs-lib

## Yarn
yarn add @finnairoyj/cdk-constructs-lib
Copy

In your CDK code, import the individual modules from the pacakge as needed:

import { EC2BastionHost } from '@finnairoyj/cdk-constructs-lib/ec2'

export class MyCDKStack extends Stack {
  public readonly bastion: EC2BastionHost

  constructor(scope: Construct, id: string, props: MyStackProps) {
    super(scope, id, props)

    //...

    this.bastion = new EC2BastionHost(this, 'MyBastion', {})
  }
}
Copy

Documentation

!!TODO: Generated API docs for the modules to be published

Repository structure

.
├── scripts ## Build scripts etc.
├── src     ## Source code
│   ├── bin ## CLI tools to be packaged in the NPM package
│   │   └── fcli    ## Common CLI tool for working with the infra and AWS resource
│   ├── cdk-modules ## CDK modules to be published to the NPM package
│   │   ├── custom-resources ## Directories that contain individual module code
│   │   │   └── custom-resource-lambdas ## Example of module containing bundled Lambda code
│   │   │       └── lambda-src ## Lambda source code to be bundled in the NPM package
│   │   ├── ec2
│   │   ├── ecs
│   │   ├── ...
│   │   ├── lz-resources ## Interface module to common LandingZone managed resources
│   │   └── rds
│   ├── config ## Common config resources
│   └── shared ## Shared resources, utilities, etc. Not directly included in NPM package
└── test ## Unit test code
Copy

Relation to build process

The automated build process relies on the repository structure to work. The build process itself is defined in the ./scripts/build-workspace.ts file. The build process works on the following logic:

• Modular NPM package structure
• The individual modules to included in the package must be placed as a directory under src/cdk-modules
• The module name is the directory name (for example ec2)
• The directory is identified as a module if it contains index.ts file. The index.ts must export all resources to be included in the module
• The module will be present in the generated NPM package as @finnairoyj/cdk-constructs-lib/ec2
• The configurations for publishing the module are made automatically in the package.json file

Bundled Lambda assets

The CDK module code can include Lambda function assets that are included in the generated NPM package. A typical use case for a bundled Lambda asset is a CloudFormation CustomResource.

The Lambda assets are built and bundled individually, including their dependencies and included in the package. With this approach the Lambda assets will work consistently when used from the NPM package, exactly as implemented and tested in this repository without the need for the user to build them during CDK deployment, or to install the asset dependencies.

For the automated Lambda asset bundling to work, the following requirements must be followed with their implementation:

• The source code for the Lambda assets must be placed in a directory named lambda-src. The lambda-src directories can be at any level under the src/cdk-modules/<module-name> directories. One module can contain multiple lambda-src dirs in its internal directory structure
• The Lambda function handler files MUST be placed directly under the lambda-src directory. Additional function code can be freely structured and imported in the handler file
• The Lambda function handler files MUST be uniquely named, within the scope of the whole library. The build process will throw an error if duplicate handler names are detected. This constraint is due to the way the bundled Lambda assets are included in the NPM package
• The Lambda function handler file MUST export a function named handler which is the entrypoint for the Lambda code
• For the bundled Lambdas to work both locally and when used from the NPM package, the reference implementation must be followed

The CDK implementation of the bundled Lambda assets must work both locally, for unit testing and local development purposes, and when used from the generated NPM package. For this to work consistently, the reference implementation should be followed when implementing bundled Lambdas:

!!TODO: Implement BundledNodejsFunction helper construct that follows the reference implementation

export class BundledLambdaFunctionAsset extends Construct {
  public readonly lambda: NodejsFunction
  public readonly logGroup: ILogGroup

  constructor(scope: Construct, id: string, props: MyFunctionProps) {
    super(scope, id)

    // ...

    /**
     * For the bundled Lambda asset to work both in the generated NPM package and locally,
     * the getBundledLambdaConfig() helper function must be used to get the configuration
     * for the function. This helper identifies if the CDK code is being executed locally
     * or from the NPM package and provides the necessary configuration for the CDK
     * NodejsFunction construct
     */

    const { code, entry, handler } = getBundledLambdaConfig('./lambda-src/my-function-handler.ts', import.meta.url)

    // ...

    this.lambda = new NodejsFunction(this, 'MyBundledLambdaAsset', {
      ...Config.BUNDLED_LAMBDA_DEFAULT_PROPS, // Use the default config for a bundled Lambda as basis
      description: 'My function that does important stuff',
      code, // The 'code' property will be defined when used from NPM pacakge. If defined, other source code related properties are ignored
      entry, // Entrypoint will be defined when Lambda is used locally, causes CDK to build the code
      handler, // The 'handler' property will be defined differently when used locally and from the NPM pacakge
      // Define other Lambda properties as needed
    })

    // ..
  }
}
Copy

Contribution guide

!!TODO: To revised later...