AWS Constructs

This repo contains thin wrappers for CDK constructs to ensure a consistent standard is applied to generated cloud resources and to avoid repetitive boilerplate code.

Preamble

There are a few conventions when using this library to be aware of.

1. Constructs expect the CDK context values ENVIRONMENT and CUSTOMER to be declared via the CLI: 2. ENVIRONMENT - eg: dev, stage, prod etc but you can use whatever you want 3. CUSTOMER - a string representing the end client of your software. This library is built with a SaaS mindset, where each customer can have their own configuration. If this doesn't apply to you we recommend simply using your own business name.
2. Your cdk.context.json file should adopt a structure of:

{
  "cuckoo": {
    // <--- customer(s)
    "prod": {
      // <--- environment(s)
      "logLevel": "debug" // <--- option(s)
    }
  }
}

Where a more complete example might look something like:

{
  "cuckoo": {
    "dev": {
      "logLevel": "debug"
    },
    "prod": {
      "logLevel": "info"
    }
  },
  "acme": {
    "dev": {
      "logLevel": "info",
      "alarmNotificationsTopic": "acme-sns-topic-dev",
      "yourCustomOptions": "foo"
    },
    "prod": {
      "logLevel": "error",
      "alarmNotificationsTopic": "acme-sns-topic-prod",
      "yourCustomOptions": "bar"
    }
  }
}

lambda.Function

As well as the usual defaults, this construct will additionally configure the following for you:

• Function description set to ${id}-${ENVIRONMENT}
• Runtime set to Node v18
• Architecture set to arm64
• Log retention set to 6 months
• X-Ray tracing set to active
• Set an environment variable called ENVIRONMENT based on the CDK context value ENVIRONMENT
• Set an environment variable called LOG_LEVEL based on the CDK context value <customer>.<environment>.logLevel (Default: debug)
• An alarm to report when the function errors
• An alarm to report when the function execution times are approaching their max timeout (>75% threshold)
• An alarm to report when the function is repeatedly throttled
• An alarm to report when the function memory utilization is >75% (only available if insightsVersion is configured)
• Alarms that trigger will send notifications for OK or in alarm state, to an SNS topic specified via the CDK context value <customer>.<environment>.alarmNotificationsTopic
• You can override the default alarms by providing a 4th parameter to customise their configuration
• You can configure access to SSM Parameters by providing the ssmParameterPaths property via the 4th parameter

Usage

import * as lambda from "aws-cdk-lib/aws-lambda";
import * as AWSConstructs from "@cuckoointernet/aws-constructs";

class ExampleFunction extends AWSConstructs.lambda.Function {
  constructor(
    scope: Construct,
    id: string,
    props: lambda.FunctionProps,
    customProps?: CustomLambdaProps
  ) {
    super(
      scope,
      ExampleFunction.name,
      {
        handler: "index.handler",
        code: lambda.Code.fromAsset(path.join(__dirname, "../build")),

        // To override the default behaviour of this construct you can supply your own props here...
        // See: https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.Function.html#construct-props
      },
      {
        // Custom AWS Construct options
      }
    );
  }
}

lambda.NodejsFunction

As well as the usual defaults, this construct will additionally configure the same properties as lambda.Function. This construct is specifically aimed at taking advantage of the same great defaults, but giving the option to use esbuild to build Lambda source code.

Usage

import * as lambdaNode from "aws-cdk-lib/aws-lambda-nodejs";
import * as CuckooConstructs from "@cuckoointernet/cuckoo-constructs";

class ExampleFunction extends CuckooConstructs.lambda.NodejsFunction {
  constructor(
    scope: Construct,
    id: string,
    props: lambdaNode.NodejsFunctionProps,
    customProps?: CustomLambdaProps
  ) {
    super(
      scope,
      ExampleFunction.name,
      {
        entry: "src/lambda/node-mock-handler.ts",
        handler: "handleTheStuff",

        // To override the default behaviour of this construct you can supply your own props here...
        // See: https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.Function.html#construct-props
      },
      {
        // Custom Cuckoo Construct options
      }
    );
  }
}

sqs.Queue

As well as the usual defaults, this construct will additionally configure the following for you:

• Enforce SSL for data in transit.
• An alarm on the queue to report if the number of in-flight messages is close to the maximum allowed by SQS
• Alarms that trigger will send notifications to an SNS topic specified via the CDK context value <customer>.<environment>.alarmNotificationsTopic
• You can customise or disable alarms by providing a 4th parameter.

Usage

import * as AWSConstructs from "@cuckoointernet/aws-constructs";

class ExampleQueue extends AWSConstructs.sqs.Queue {
  constructor(scope: Construct) {
    super(
      scope,
      ExampleQueue.name,
      {
        // To override the default behaviour of this construct you can supply your own props here...
        // See: https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_sqs.Queue.html#construct-props
      },
      {
        // Custom AWS Construct options
      }
    );
  }
}

sqs.DeadLetterQueue

The CDK doesn't include a DLQ construct out of the box, this is our take on what one should look like. As well as the usual defaults, this construct will additionally configure the following for you:

• Retention period of 14 days.
• Enforce SSL for data in transit.
• An alarm to report when the DLQ contains any messages
• Alarms that trigger will send notifications to an SNS topic specified via the CDK context value <customer>.<environment>.alarmNotificationsTopic
• You can customise or disable alarms by providing a 4th parameter.

Usage

import * as AWSConstructs from "@cuckoointernet/aws-constructs";

class ExampleDlq extends AWSConstructs.sqs.DeadLetterQueue {
  constructor(scope: Construct) {
    super(
      scope,
      ExampleDlq.name,
      {
        // To override the default behaviour of this construct you can supply your own props here...
        // See: https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_sqs.Queue.html#construct-props
      },
      {
        // Custom AWS Construct options
      }
    );
  }
}

dynamodb.Table

As well as the usual defaults, this construct will additionally configure the following for you:

• (Production only) Set pointInTimeRecovery to true

Usage

import * as AWSConstructs from "@cuckoointernet/aws-constructs";

class ExampleTable extends AWSConstructs.dynamodb.Table {
  constructor(scope: Construct) {
    super(scope, ExampleTable.name, {
      partitionKey: {
        name: "id",
        type: AttributeType.STRING,
      },

      // To override the default behaviour of this construct you can supply your own props here...
      // See: https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_dynamodb.Table.html#construct-props
    });
  }
}

s3.Bucket

As well as the usual defaults, this construct will additionally configure the following for you:

• Versioning set to true.
• Public Access is blocked by default.
• Object encryption is on by default and S3 Managed.
• Encryption in transit is restricted to HTTPS
• Lifecycle rules are set by default on current & non-current object versions:
  • After 3 months (90 days) the version will transition to S3 Standard Infrequent Access.
  • After 6 months (180 days) the version will transition to Glacier Instant Retrieval.

Usage

import * as AWSConstructs from "@cuckoointernet/aws-constructs";

class ExampleBucket extends AWSConstructs.s3.Bucket {
  constructor(scope: Construct) {
    super(scope, ExampleBucket.name, {
      // To override the default behaviour of this construct you can supply your own props here...
      // See: https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.Bucket.html#construct-props
    });
  }
}

stepfunctions.StateMachine

As well as the usual defaults, this construct will additionally configure the following for you:

• State machine type set to Express
• Timeout default to 5 minutes
• Creates a log group to capture:
• • All log levels
• • Execution data
• • Note; any overriding log group must be prefixed with '/aws/vendedlogs/states/'. See https://docs.aws.amazon.com/step-functions/latest/dg/bp-cwl.html.
• X-Ray tracing enabled
• An alarm to report when an execution errors
• An alarm to report when an execution times out.
• Alarms that trigger will send notifications to an SNS topic specified via the CDK context value <customer>.<environment>.alarmNotificationsTopic
• You can override the default alarms by providing a 4th parameter to customise their configuration

Usage

import * as lambda from "aws-cdk-lib/aws-lambda";
import * as sfn from "aws-cdk-lib/aws-stepfunctions";
import * as AWSConstructs from "@cuckoointernet/aws-constructs";

class ExampleStateMachine extends AWSConstructs.stepfunctions.StateMachine {
  constructor(scope: Constructid: string, props: sfn.StateMachineProps, customProps?: CustomStateMachineProps) {
    const definition = new sfn.Pass(scope, "InitialPass");

    super(
      scope,
      ExampleStateMachine.name,
      {
        definition,

        // To override the default behaviour of this construct you can supply your own props here...
        // See: https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_stepfunctions.StateMachine.html#construct-props
      },
      {
        // Custom AWS Construct options
      }
    );
  }
}

utils.getContextByPath

A utility function that can be used to retrieve a nested value from the CDK context:

Usage

Example cdk.context.json:

{
  "cuckoo": {
    "prod": {
      "logLevel": "debug"
    }
  }
}

import { utils } from "@cuckoointernet/aws-constructs";

const logLevel = utils.getContextByPath(
  scope,
  `cuckoo.prod.logLevel`
) as string; // => debug

Contributors