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
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.
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 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.
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
.
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 errorsnpm run format
format the code using Prettiernpm 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.
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
✨ 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:
- Raise a PR. The PR title must follow the Angular / Karma format. Don't worry, CI checks this!
- Once reviewed and approved, merge your PR.
- 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
.
- Enjoy a comment on your PR to inform you that your change has been released.