cdk-constructs-lib

AWS CDK Building Blocks and tools

Library API documentation: https://cdk-constructs-lib-docs.common.tools.app.finnair.com/

Table of contents

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

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:

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 BundledLambda Construct must be used for the function. This construct identifies if
     * the CDK code is being executed locally or from the NPM package and provides the necessary
     * configuration for the underlying CDK NodejsFunction construct
     */

    const fn = new BundledLambda(this, 'EC2KeypairManagerLambda', {
      // Construct will make sure the function name is unique by prepending the provided
      // function name with 'cdk-bundled-' and appending it with 6-char string taken from
      // the resource address in CDK
      functionName: 'my-bundled-function',
      handlerPath: './lambda-src/ec2-keypair-manager.ts',
      basePath: import.meta.url, // If 'handlerPath' is not absolute, provide the 'basePath'
      description: 'CustomResource Lambda for managing EC2 KeyPairs',
      timeout: Duration.minutes(1),
    })

    this.lambda = fn.lambda
    this.logGroup = fn.logGroup

    // ..
  }
}
Copy

Contribution guide

Local development

When developing a new feature, you can test the NPM package locally before publishing with the yalc tool included in the devDependencies. Yalc allows you to publish a version of the package to a local registry, from which it can then be used in other projects external to this one.

Some setup is required if working with the devcontainer setup included in the project. Unfortunately the local disk mount required in order to publish the yalc registry outside of the devcontainer requires modifying the ./.devcontainer/devcontainer.json and adding the below disk mount config. First make sure the ~/.yalc dir exists in your own filesystem, then re-run the devcontainer build. You should be set to use yalc. Do not commit these changes to git, it will break the devcontainer build for people who are not using yalc

{
  // ...
  "mounts": [
    //...
    {
      "source": "${localEnv:HOME}/.yalc",
      "target": "/home/node/.yalc",
      "type": "bind"
    }
  ]
}
Copy

If developing locally without the devcontainer, no additional setup is required to use yalc. After the setup, run the following commands to publish the package to the yalc cache and install it locally in your target project:

## In the cdk-constructs-lib project root
yarn build
yarn yalc --publish --push

## In the target project root (assuming yarn, use whatever commands for your package manager)
yarn yalc add @finnairoyj/cdk-constructs-lib
yarn install
Copy

Yalc will change the @finnairoyj/cdk-constructs-lib dependency to a local file:... dependency to your package.json. To remove the local package, just run the below command and the previous remote dependency definition will be restored.

yarn yalc remove @finnairoyj/cdk-constructs-lib
Copy

!!TODO: To revised later...