@cuckoointernet/aws-constructs NPM

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.

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

get-value

@everything-registry/sub-chunk-208

1 month ago

7 months ago

8 months ago

9 months ago

9 months ago