Skip to content

guardian/cdk

Folders and files

NameName
Last commit message
Last commit date

Latest commit

b4ad69d Â· Mar 30, 2021
Mar 18, 2021
Nov 19, 2020
Mar 29, 2021
Mar 29, 2021
Mar 29, 2021
Mar 30, 2021
Mar 19, 2021
Nov 19, 2020
Nov 19, 2020
Dec 30, 2020
Jan 15, 2021
Nov 19, 2020
Nov 19, 2020
Jan 18, 2021
Mar 4, 2021
Mar 29, 2021
Feb 3, 2021
Mar 30, 2021
Mar 30, 2021
Feb 25, 2021
Mar 29, 2021
Mar 30, 2021
Mar 15, 2021

Repository files navigation

Guardian CDK Library

npm

Welcome to the Guardian CDK library! This library contains a number of reusable patterns and constructs which can be used to build up your AWS Cloudformation stacks.

📖 View the available components in the API documentation.

💬 Come and chat to us in Discussions

Wait, what is CDK?

The AWS Cloud Development Kit (AWS CDK) is an open-source software development framework to define cloud infrastructure in code and provision it through AWS CloudFormation.

You can read more about it in the aws-cdk README.

Architecture

Patterns

Patterns are high level classes which compose a number of constructs to produce standard architectures. For example, you should be able to get all of the resources you need to deploy a new lambda function from one GuLambdaStack class. We're still working on these right now but hope to start bringing you some of the most common Guardian stacks soon!

Patterns should be your default entry point to this library.

Constructs

Constructs are lower level classes which will create one or more resources to produce one element of a stack. For example, the GuDatabaseInstance will create an RDS instance as well as a parameter group, if required. This library defines a number of constructs which are combined to create the higher level patterns.

If there is a pattern available for your use case, prefer to use that over composing constructs yourself. We welcome feedback and/or PRs to extend the functionality of patterns. Where you need to do something outside of currently available patterns, you can use the constructs to provide some level of abstraction. In this case, consider whether it's worth defining a pattern.

Decision Records

Architecture Decisions Records are files where we can document the decisions we make around any form of structure, architecture or approach. By documenting them in this way, we can preserve the thought process behind all of the decisions whilst also laying out formally the preferences for all developers working on the library.

The docs/architecture-decision-records directory contains the records for @guardian/cdk.

Useful commands

We follow the script/task pattern, find useful scripts within the script directory for common tasks.

  • ./script/setup to install dependencies
  • ./script/start to run the Jest unit tests in watch mode
  • ./script/docs to generate documentation and view in the browser
  • ./script/lint to lint the code using ESLint
  • ./script/test to run the Jest unit tests
  • ./script/build to compile TypeScript to JS

There are also some other commands defined in package.json:

  • npm run lint --fix attempt to autofix any linter errors
  • npm run format format the code using Prettier
  • npm run watch watch for changes and compile

However, it's advised you configure your IDE to format on save to avoid horrible "correct linting" commits.

Usage

This library can be installed from npm.

npm install --save @guardian/cdk

or

yarn add @guardian/cdk

Patterns can be imported from the top level of the library:

import { GuScheduledLambda } from "@guardian/cdk";

We encourage you to use patterns rather than constructs whenever possible. If you need to use a construct directly, they must be imported from their construct directory:

import { GuAutoScalingGroup } from "@guardian/cdk/lib/constructs/autoscaling";

This is intentional as the patterns ideally solve the majority of use-cases. If they don't, please let us know about your use-case so that we can consider supporting it via a pattern. Alternatively, PRs are always welcome!

There are more details on using the CDK library in docs

Releasing

✨ TL;DR We release new versions of the library to NPM automagically ✨

We use semantic-release and guardian/actions-merge-release-changes-to-protected-branch to automate releases.

To release a new version:

  1. Raise a PR. The PR title must follow the Angular / Karma format. Don't worry, CI checks this!
  2. Once reviewed and approved, merge your PR.
  3. Wait for the robots to:
    • Use your structured commit (we squash commits!) to automatically determine the next version number (following semantic versioning).
    • Release a new version to npm and update package.json.
  4. Enjoy a comment on your PR to inform you that your change has been released.