@unconventional-code/aws-cdk-lib NPM

Unconventional Code AWS CDK Library

This is an opinionated construct library for provisioning and managing common resources in AWS. The majority of AWS CDK configuration is boilerplate and follows well-defined patterns; for example, how a REST API Gateway or AppSync API is set up, or how a Lambda function or EC2 instance is configured. This library abstracts that configuration into simple, repeatable constructs and cuts to the chase on a lot of AWS documentation for dealing with CDK and CloudFormation.

Naming Conventions

Generally, stacks and constructs require a stage and a service prop.

The stage indicates the environment that the resources are deployed in; it is not necessarily one-to-one with an AWS workload, but more related to a conceptual deployment environment such as dev, staging, and prod.

The service should be used with a stack or construct to indicate a logical grouping of resources, generally along service or business domain boundaries. The service will also typically relate to a DNS domain name associated with any human-readable API endpoints. For example, a collection of stacks for managing a Cognito user pool, an AppSync API, and scheduled job Lambdas might all be related to the users service, and generally be associated with users.acme.com as a subdomain endpoint.

The stage and service work together in that we typically will prefix endpoints and resource names as:

${service}.${stage}.domain.com for a subdomain or endpoint
${stage}-${service}-resource-name for a resource identifier in the AWS Console

Most resources will follow a kebab-case or param-case, while certain specific resources do not permit dashes and must use PascalCase. The one resource that definitely enforces param-case is S3 buckets.

A Note on Domain Names and Hosted Zones

The current opinionated workload pattern is to use a Root account with stage workload accounts, such as a dev, staging, and prod workload account.

In the Root account, the domain name will be purchased and owned, automatically creating a Hosted Zone.

In each stage account, a Route53 Hosted Zone should be created for the ${stage}.domain.com.

Then, add the nameserver NS records from the workload Hosted Zones to the top-level Root account domain Hosted Zone.

Note that the exception to the stage pattern is for app or other prefixes that we expect to be visible to users in production; in this case, the prod workload account should own the subdomain hosted zone that will not have a prefix (e.g. app.domain.com), while the dev and staging accounts will dynamically build user-facing URLs and subdomains off of their stage Hosted Zones (e.g. dev.domain.com will be used to hosted app.dev.domain.com).

Root Account

Hosted Zone acme.com

NS Records:

dev.acme.com
- ns-123.awsdns-01.net.
- ns-123.awsdns-02.co.uk.
- ns-123.awsdns-03.com.
- ns-123.awsdns-04.org.
staging.acme.com
- ns-123.awsdns-01.net.
- ns-123.awsdns-02.co.uk.
- ns-123.awsdns-03.com.
- ns-123.awsdns-04.org.
prod.acme.com
- ns-123.awsdns-01.net.
- ns-123.awsdns-02.co.uk.
- ns-123.awsdns-03.com.
- ns-123.awsdns-04.org.
app.acme.com
- ns-123.awsdns-01.net.
- ns-123.awsdns-02.co.uk.
- ns-123.awsdns-03.com.
- ns-123.awsdns-04.org.