@almamedia-open-source/cdk-project-context

AWS CDK Project Context

Opinionated CDK utility construct for managing project information & AWS account-specific configuration.

Why you'd use this?

1. If you use multi-account deployments, i.e. separate dev and prod workloads to different accounts.
2. Especially if you develop microservices, you end up with a lot of CDK projects. Without well-defined method of managing project configuration one often ends up reinventing the wheel in each project.
3. A developer can be quaranteed the configuration information is available and in correct format – or otherwise cdk synth|diff|deploy will fail.

Note: This is not a replacement for tools such as AWS AppConfig, Parameter Store or Secrets Manager! Project Context should only contain non-secret values that define "where to deploy" and certain values that you may wish to use for example as part of tagging or naming resources.

Important

🚧 This tool is work-in-progress and experimental: Breaking changes may occur before first v1 major is released!

Installation

1. Ensure you meet following requirements:

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

2. Install:

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

Usage

1. In your CDK application (for example lib/app.ts) use Project instead of App to initialize the CDK app:

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

2. Somewhere in your stacks you may use static methods of ProjectContext class:

   import { Stack, StackProps, CfnOutput } from 'aws-cdk-lib';
   import { ProjectContext } from '@almamedia-open-source/cdk-project-context';
   
   export class MyStack extends Stack {
     constructor(scope: Construct, id: string, props?: StackProps) {
       super(scope, id, props);
   
       // Get the default region for this project
       new CfnOutput(this, 'DefaultRegion', { value: ProjectContext.getDefaultRegion(this) });
   
       // Get the project name
       new CfnOutput(this, 'Name', { value: ProjectContext.getName(this) });
   
       // Get information about the project author
       new CfnOutput(this, 'AuthorOrganization', { value: ProjectContext.getAuthorOrganization(this) });
       new CfnOutput(this, 'AuthorName', { value: ProjectContext.getAuthorName(this) });
       new CfnOutput(this, 'AuthorEmail', { value: ProjectContext.getAuthorEmail(this) });
   
       // Get AWS account specific configuration
       new CfnOutput(this, 'AccountType', { value: ProjectContext.getAccountType(this) });
       new CfnOutput(this, 'AccountId', { value: ProjectContext.getAccountId(this) });
       new CfnOutput(this, 'AccountBaseDomain', { value: ProjectContext.getAccountConfig(this, 'baseDomain') });
   
     }
   }
   

   There's also a shorthand alias PC available, for example: PC.getAccountId(this).

3. Run CDK commands with account-type (or shorthand: account) CLI context flag to select the desired account configuration:

   npx cdk deploy --context account=dev
   

4. You'll get the following CloudFormation outputs:

   Name	Example Value
   DefaultRegion	eu-west-1
   Name	my-cool-project
   AuthorOrganization	Acme Corp
   AuthorName	Mad Scientists
   AuthorEmail	[e-mail]
   AccountType	dev
   AccountId	111111111111
   AccountBaseDomain	example.net

Application Environment Retrieval

Often you may want to deploy multiple different application environments – “isolated copies” of your CDK application such as feature environments – into same AWS account. To manage that, you need some kind of "modifier" which selects the target application environment.

You may use this utility to retrieve application environment information. In the context of this utility, environment is just a string value such as staging or production – not to be confused with CDK environments (which instead define the target AWS Account & Region configuration for a stack).

1. Somewhere in your stacks you may use static method ProjectContext.getEnvironment(scope):

   import { Stack, StackProps, CfnOutput } from 'aws-cdk-lib';
   import { PC } from '@almamedia-open-source/cdk-project-context'; // Using the PC shorthand here
   
   export class MyStack extends Stack {
     constructor(scope: Construct, id: string, props?: StackProps) {
       super(scope, id, props);
   
       // Get the default region for this project
       new CfnOutput(this, 'Environment', { value: PC.getEnvironment(this) });
     }
   }
   

2. Specify environment-type (or shorthand: environment or env) CLI context flag to select the desired environment:

   npx cdk deploy --context account=dev --context environment=staging
   

3. You'll get the following CloudFormation outputs:

   Name	Example Value
   Environment	staging