Opinionated set of AWS Account & Application Environment configuration combinations and utilities to manage them for CDK Projects.

Important

🚧 This tool is work-in-progress and experimental!

All @almamedia-open-source/cdk- prefixed constructs/utilities are based on existing CDK constructs/utilities we've developed & used (in production) internally at Alma Media since 2019.

Breaking changes may occur at any given time without prior warning before first v1 major is released, as we rewrite them for CDK v2 and use this opportunity to also redesign & refactor.

Feedback is most welcome, but do note that we intend to implement these new constructs/utilities and their APIs in such manner that our existing CDK v1 production workloads can easily migrate into these new @almamedia-open-source/cdk- constructs/utilities.

Overview

TODO

Installation

1. Ensure you meet following requirements:

   • NodeJS v14.17.6 or newer
   • AWS Cloud Development Kit v2.0.0 or newer

2. Install peer dependency @almamedia-open-source/cdk-project-context:

   npm i -D @almamedia-open-source/cdk-project-context

3. Install this tool:

   npm i -D @almamedia-open-source/cdk-project-target

Usage

1. Initialize your CDK App with Project construct as documented in @almamedia-open-source/cdk-project-context but also use one of the following methods of Accounts class:

   • Accounts.one
   • Accounts.two
   • Accounts.three

   // bin/app.ts
   import { Project } from '@almamedia-open-source/cdk-project-context';
   import { Accounts } from '@almamedia-open-source/cdk-project-target';
   
   // new Project instead of new App
   const project = new Project({
     name: 'my-cool-project',
     author: {
       organization: 'Acme Corp',
       name: 'Mad Scientists',
       email: '[email protected]',
     },
     defaultRegion: 'eu-west-1', // defaults to one of: $CDK_DEFAULT_REGION, $AWS_REGION or us-east-1
     accounts: Accounts.two({
       dev: {
         id: '111111111111',
         config: {
           baseDomain: 'example.net',
         },
       },
       prod: {
         id: '222222222222',
         config: {
           baseDomain: 'example.com',
         },
       },
     }),
   })

2. TODO

Migration

This section only applies if you're an Alma Media employee who is migrating from our internal CDK v1 compatible constructs.

Account Context

Match ProjectContext (PC) casing:

-Ac
+AC

Methods follow the format used in ProjectContext (where there is overlap):

Account ID

-Ac.getId
+AC.getAccountId

Account Description

-Ac.getDescription

Account Base Domain

-Ac.getDomain

Account Type

-Ac.getType
+AC.getAccountType

Is Prod account type

-Ac.isProd
+AC.isProd

Is Dev account type

-Ac.isDev
+AC.isDev

Is PreProd account type

-Ac.isPreprod
+AC.isPreprod

not used

Is Shared account type

-Ac.isShared
+AC.isShared

Is Mock account type

TODO

Get Configuration

-Ac.getConfig(ths, 'path', defaultValue)
+AC.getAccountConfig(this, 'path', defaultValue) # TODO: Implement the lodash path in ProjectContext

Environment Context

Environment Name

-Ec.getName
+EC.getName

Environment URL/DNS compatible name

-Ec.getSubdomain   # foo-bar.feature
+EC.getUrlName     # feature-foo-bar

Environment Label (New)

+Ec.getLabel

Environment Type (Category)

-Ec.getType
+EC.getCategory

Return values:

mock
development
-preview
+feature
verification
stable

Environment Description

-Ec.getDescription

Environment Domain

Implemented in separate construct.

-Ec.getDomain

Preview (Feature) Environment Info

-Ec.getPreviewInfo
+EC.getFeatureInfo

Is Mock Environment

-Ec.isMock
+EC.isMock

Is Development Environment

-Ec.isDevelopment
+EC.isDevelopment

Is Preview (Feature) Environment

-Ec.isPreview
+EC.isFeature

Is Pre Environment

-Ec.isPre
+EC.isVerification

Is Stable Environment

-Ec.isStable
+EC.isStable

Stack Context

Removed completely: Use @almamedia-open-source/cdk-project-stack instead.