@cuckoointernet/cuckoo-constructs

Cuckoo 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.

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 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 CuckooConstructs from "@cuckoointernet/cuckoo-constructs";

class ExampleFunction extends CuckooConstructs.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 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 CuckooConstructs from "@cuckoointernet/cuckoo-constructs";

class ExampleQueue extends CuckooConstructs.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 Cuckoo 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 CuckooConstructs from "@cuckoointernet/cuckoo-constructs";

class ExampleDlq extends CuckooConstructs.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 Cuckoo 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 CuckooConstructs from "@cuckoointernet/cuckoo-constructs";

class ExampleTable extends CuckooConstructs.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 CuckooConstructs from "@cuckoointernet/cuckoo-constructs";

class ExampleBucket extends CuckooConstructs.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 CuckooConstructs from "@cuckoointernet/cuckoo-constructs";

class ExampleStateMachine extends CuckooConstructs.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 Cuckoo 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/cuckoo-constructs";

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