@guardian/cdk
    TypeScript icon, indicating that this package has built-in type declarations

    31.3.0 • Public • Published

    Guardian CDK Library

    npm CD

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

    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 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 the 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 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/start-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
    • ./script/cli-docs to update the CLI documentation in this file

    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

    From AWS CDK to Guardian CDK

    If you are migrating from aws-cdk to @guardian/cdk, you will need to make sure that the version of aws-cdk you are using is what is expected. If you run

    npx @guardian/cdk@latest check-package-json
    

    then the output is a json object, and you should set your aws-cdk version to the value of versionExpected.

    Using the @guardian/cdk CLI

    @guardian/cdk COMMAND [args]
    
    Commands:
      @guardian/cdk aws-cdk-version     Print the version of @aws-cdk libraries being
                                   used
      @guardian/cdk account-readiness   Perform checks on an AWS account to see if it is
                                   GuCDK ready
      @guardian/cdk check-package-json  Check a package.json file for compatibility with
                                   GuCDK
    
    Options:
          --profile  AWS profile                                            [string]
          --region   AWS region                      [string] [default: "eu-west-1"]
          --version  Show version number                                   [boolean]
      -h, --help     Show help                                             [boolean]
    
    

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

    For more information, see the docs on testing.

    Keywords

    none

    Install

    npm i @guardian/cdk

    DownloadsWeekly Downloads

    526

    Version

    31.3.0

    License

    none

    Unpacked Size

    689 kB

    Total Files

    487

    Last publish

    Collaborators

    • unmesh_malvankar
    • zekehg
    • rtyley
    • dlawes
    • ghaberis
    • jsherbert
    • david.furey.gu
    • tonymccraeguardian
    • jlieb10
    • guardian-developers
    • simonadcock-gu
    • maxspencer
    • akash1810
    • reetta
    • ajwl
    • tomrf1
    • mchv
    • itsibitzi
    • justinpinner
    • jranks123
    • nicl
    • philmcmahon
    • tjmw
    • thaliasilver
    • sndrs
    • sam.hession
    • jfsoul
    • 0x101
    • frankie_hammond
    • aoifemcl15
    • ioanna0
    • mxdvl
    • mark.addis
    • rhysmills
    • jamie-lynch
    • amyhughes-gu
    • oliverlloyd
    • jacobwinch
    • dskamiotis
    • marjank
    • annabeddow
    • fweddi
    • michaelclapham_gnm
    • olly.namey.guardian