Skip to main content

Opinionated CDK Project “Framework”

Project description



Alma CDK Project

npm i -D @alma-cdk/project

Opinionated CDK “framework” with constructs & utilities for:

  • deploying multiple environments to multiple accounts (with many-to-many relationship)

  • managing account configuration through standardized props (no more random config files)

  • querying account and/or environment specific information within your CDK code

  • enabling dynamic & short-lived “feature-environments”

  • enabling well-defined tagging

  • providing structure & common conventions to CDK projects

  • choosing the target account & environment by passing in runtime context:

    npx cdk deploy -c account=dev -c environment=feature/abc-123
    

    ... which means you don't need to define all the possibile environments ahead of time!


Account Strategies

Depending on the use case, you may choose a configuration between 1-3 AWS accounts with the following environments:

  1. Shared account (shared):

    default-multi

  2. Multi-account (dev+prod)– RECOMMENDED:

    default-multi


  1. Multi-account (dev+preprod+prod):

    default-multi


Getting Started

Steps required to define a environmental project resources; At first, it might seem complex but once you get into the habbit of defining your projects this way it starts to make sense:

  1. Choose your Account Strategy

  2. Initialize a new Project instead of cdk.App:

    // bin/app.ts
    import { Project, AccountStrategy } from '@alma-cdk/project';
    
    const project = new Project({
      // Basic info, you could also read these from package.json if you want
      name: 'my-cool-project',
      author: {
        organization: 'Acme Corp',
        name: 'Mad Scientists',
        email: 'mad.scientists@acme.example.com',
      },
    
      // If not set, defaults to one of: $CDK_DEFAULT_REGION, $AWS_REGION or us-east-1
      defaultRegion: 'eu-west-1',
    
      // Configures the project to use 2 AWS accounts (recommended)
      accounts: AccountStrategy.two({
        dev: {
          id: '111111111111',
          config: {
            // whatever you want here as [string]: any
            baseDomain: 'example.net',
          },
        },
        prod: {
          id: '222222222222',
          config: {
            // whatever you want here as [string]: any
            baseDomain: 'example.com',
          },
        },
      }),
    })
    
  3. Define a stack which extends SmartStack with resources:

    // lib/my-stack.ts
    import { Construct } from 'constructs';
    import { StackProps, RemovalPolicy } from 'aws-cdk-lib';
    import { SmartStack, Name, UrlName, PathName, EC } from '@alma-cdk/project';
    
    export class MyStack extends SmartStack {
      constructor(scope: Construct, id: string, props: StackProps) {
        super(scope, id, props);
    
        new dynamodb.Table(this, 'Table', {
          removalPolicy: EC.isStable(this) ? RemovalPolicy.RETAIN : RemovalPolicy.DESTROY,
    
          tableName: Name.it(this, 'MyTable'),
          partitionKey: {
            type: dynamodb.AttributeType.STRING,
            name: 'pk',
          },
          // StagingMyTable
        });
    
        new events.EventBus(this, 'EventBus', {
          eventBusName: Name.withProject(this, 'MyEventBus'),
          // MyCoolProjectStagingMyEventBus
        });
    
        new s3.Bucket(this, 'Bucket', {
    
          removalPolicy: EC.isStable(this) ? RemovalPolicy.RETAIN : RemovalPolicy.DESTROY,
          autoDeleteObjects: EC.isStable(this) ? false : true,
    
          bucketName: UrlName.globally(this, 'MyBucket'),
          // acme-corp-my-cool-project-feature-foo-bar-my-bucket
        });
    
        new ssm.StringParameter(this, 'Parameter', {
          stringValue: 'Foo',
          tier: ssm.ParameterTier.ADVANCED,
          parameterName: PathName.withProject(this, 'MyNamespace/MyParameter'),
          // /MyCoolProject/Staging/MyNamespace/MyParameter
        });
      }
    }
    
  4. Define a new environmental which extends EnvironmentWrapper and initialize all your environmental SmartStack stacks within:

    // lib/environment.ts
    import { Construct } from 'constructs';
    import { EnvironmentWrapper } from '@alma-cdk/project';
    import { MyStack } from './my-stack';
    
    export class Environment extends EnvironmentWrapper {
      constructor(scope: Construct) {
        super(scope);
        new MyStack(this, 'MyStack', { description: 'This is required' });
      }
    }
    

    Resulting Stack properties (given environment=staging):

    Property Example value
    stackName "MyCoolProject-Environment-Staging-MyExampleStack"
    terminationProtection true
    env.account "111111111111"
    env.region "eu-west-1"

    Resulting Tags for the Stack and its resources (given environment=staging):

    Property Example value
    Account dev
    Environment staging
    Project my-cool-project
    Author Mad Scientists
    Organization Acme Corp
    Contact mad.scientists@acme.example.com
  5. Finally initialize the environment with the Project scope:

    // bin/app.ts
    import { Project, Accounts } from '@alma-cdk/project';
    import { Environment } from '../lib/environment';
    
    const project = new Project({/* removed for brevity, see step 1 */})
    
    new Environment(project);
    

Documentation

See detailed documentation for specific classes & methods at constructs.dev.

Generally speaking you would be most interested in the following:

  • Project
  • AccountStrategy
  • SmartStack
  • AccountWrapper & EnvironmentWrapper
  • AccountContext (AC)
  • EnvironmentContext (EC)
  • Name / UrlName / PathName

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

alma-cdk.project-1.0.0b6.tar.gz (340.1 kB view details)

Uploaded Source

Built Distribution

alma_cdk.project-1.0.0b6-py3-none-any.whl (338.9 kB view details)

Uploaded Python 3

File details

Details for the file alma-cdk.project-1.0.0b6.tar.gz.

File metadata

  • Download URL: alma-cdk.project-1.0.0b6.tar.gz
  • Upload date:
  • Size: 340.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.0.0 CPython/3.12.2

File hashes

Hashes for alma-cdk.project-1.0.0b6.tar.gz
Algorithm Hash digest
SHA256 81e6716d9bdf3776dc8603e4b83f334d63de278901bb671edf6a0f5893397eb5
MD5 55f2f0b76379bc3331dffdab8a5c87ad
BLAKE2b-256 c6c168b8a99119b04e0ccb282dfde8c72903df0c6f0d70570f9fa6f3ec68ff4f

See more details on using hashes here.

File details

Details for the file alma_cdk.project-1.0.0b6-py3-none-any.whl.

File metadata

File hashes

Hashes for alma_cdk.project-1.0.0b6-py3-none-any.whl
Algorithm Hash digest
SHA256 7ecd2d489215c3faecd966ca6db52ad078df443e4d0fa8fa715fefec115e732b
MD5 7d42533dee0442c0a8f111f26e03b20d
BLAKE2b-256 6aa3959463f8c4287c6ac9bac3f091f9a91cd9d0b64c5f35a2cd16c8a2e60f1c

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page