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.

Dev Account

Hosted Zone dev.acme.com

Staging Account

Hosted Zone staging.acme.com

Prod Account

Hosted Zone prod.acme.com app.acme.com