CDK Lambda Deployer JS (CLD)

Library with CDK resources and utilities that help to deploy JavaScript functions to AWS lambda.

Pre-requisites

You will need a Personal Access Token for your GitHub Repository. You can find more info about Personal Access Tokens here.

This solution is composed of two parts:

• CLD_BUILD
• CLD_DEPLOY

CLD_BUILD is a library that will help build the metadata files needed to deploy the functions source to AWS Lambda.

CLD_DEPLOY is a set of CDK constructs that will be in charge of hosting the functions and layers source using Amazon S3 as well as deploying that source to AWS lambda.

You will generally want to use the CLD_BUILD in your main project; whilst the CLD_DEPLOY is meant to be used in a CDK infrastructure project. Those projects can be in different or the same repository.

Set up CLD_BUILD

npm i --dev cdk_lambda_deployer_js

You need to add this configuration to your package.json

{
  "cld": {
    "build": {
      "functionsRelativePath": "src/functions",
      "functionFileName": "function.js",
      "libsRelativePath": "src/libs",
      "functionGroups": ["admin", "customer", "deliverer"],
      "libs": ["db", "util"],
      "functionGroupLibs": {
        "customer": ["util", "db"],
        "deliverer": ["util", "db"]
      },
      "outputRelativePath": "build/cld"
    }
  }
}

• functionsRelativePath: This property tells CLD where to find the functions that will be the source of the lambda functions.

• functionFileName: Default: 'function.js'. This property tells cld what file names inside the functionsRelativePath will be considered to be lambda functions source code. Note: Only one file will be deployed to the lambda function.

• libsRelativePath: This property tells CLD where the files are located for the lambda layers. You can use this for you project libraries.

• functionGroups: These are the sub-folder names inside the functionsRelativePath that will be scanned for files with name functionFileName. These will be used as function name prefixes as well.

• libs: Like the entityNames, these are the sub-folder names inside the libsRelativePath that will be scanned for the files to be the source of the layers.

• functionGroupLibs: It determines a function groups to libs mapping. It will help to define the layers that will get attached to the lambda functions.

• outputRelativePath: Default: 'build/cld'. This folder will be used to save the generated the lambda functions and layers source files. We recommend that you ignore this file in your source code control.

Your outputRelativePath folder will end up with two sub-folders: functions and libs. Functions will be the source of the lambda functions. Libs will be the source of the lambda layers.

Supposing your project looks like this:

- myProject
    - package.json
    - src
        - functions
            - customer
                - order
                    - place
                        - util.js
                        - function.js
            - deliverer
                - offer
                    - publish
                        - function.js
        - libs
            - db
                - connection.js
                - package.json
            - util
                - util.js
                - package.json

And

• functionsRelativePath is: "src/functions"

• functionFileName is: "function.js"

• libsRelativePath is: "src/libs"

• functionGroups is: ["customer", "deliverer"]

• libs is: ["db", "util"]

• functionGroupLibs: {"customer": ["util", "db"], "deliverer": ["util", "db"]}

• outputRelativePath is: "build/cld"

Then, a new "build/cld" folder will be created with this structure:

- functions
    - customer
        - order
            - place
                - function.zip
    - deliverer
        - offer
            - publish
                - function.zip
- libs
    - db
        - nodejs.zip
    - util
        - nodejs.zip

In order to manually generate the output, you can run the command cld_build. Note: this output will be used by the CLD_DEPLOY project on its CI workflow.

Notice you must have a package.json file inside every lib folder.

Set up CLD_DEPLOY

npm i --dev cdk_lambda_deployer_js

You have two options to add the CLD_DEPLOY resources to your CDK project.

1. You can add it as a Constructor on your Stack.

new CDKLambdaDeployerConstruct(
      this,
      'CDKLambdaDeployer',
      {
        githubRepoOwner: 'repo_owner',
        githubRepoName: 'repo_name',
        githubRepoSubFolder: '.',
        cldOutputFolder: 'build/cld',
        githubRepoBranch: 'master',
        githubTokenSecretId: 'github_token_secret_id',
        lambdaSubnets: [],
        lambdaSecurityGroups: [],
        databaseProxyName: ''
      },
    )

2. You can add it as a new stack

new cld_deploy.CDKLambdaDeployerStack(app, 'CDKLambdaDeployer', {
    env: { account: process.env.CDK_DEFAULT_ACCOUNT, region: process.env.CDK_DEFAULT_REGION },
    githubRepoOwner: 'repo_owner',
    githubRepoName: 'repo_name',
    githubRepoSubFolder: '.',
    cldOutputFolder: 'build/cld',
    githubRepoBranch: 'master',
    githubTokenSecretId: 'github_token_secret_id',
    lambdaSubnets: [],
    lambdaSecurityGroups: [],
    databaseProxyName: ''
})

• githubRepoSubFolder: This property is optional and can be used in case the cdk_lambda_deployer_js node module is inside a different folder. Default value: . (root folder)
• cldOutputFolder: This property is relative to the githubRepoSubFolder or the root folder. It represents the route where the cld build process output file is found.
• githubTokenSecretId: This property represents the AWS secret ID (or path) where the Fine-grained GitHub Personal Access Token value is saved in order to pull the repo from GitHub.

This CLD_DEPLOY project has a CodeBuild resource that will use the GitHub repo info to build the lambda and layers based on the zip files and metadata generated by the CLD_BUILD library.