What is the best way to distribute a cdk app to be re-used by other people?

[ecs-jnguyen]

Hello, currently my team manages deployers to create AWS cloudformation stacks. We have python scripts that read in a settings file and then create a cloudformation template dynamically. For example the settings file allows people in our organization to specify if they need an s3 bucket in their stack, then we will add an s3 bucket with the correct permissions / policies. Then we run the cloudformation create / update operation.

Currently we upload our python scripts as an executable into a python package repository (like pypi). The other teams will create their own repositories with the settings file and create a job that will pull down the python package with pip (pip install the-s3-bucket-deployer) and run the executable to create the cloudformation stack with their specified resources.

Considerations:

• The deployer can be run in a number of different places: local machine, circle ci, git lab ci, codebuild job, GitHub actions, Jenkins, travis ci, azure pipelines
• Some repositories could use more than 1 deployer. They can pick and choose which deployer they want (i.e. pull in a different package for a different deployer and run that deployer executable)

I want to achieve something similar to the above process with CDK. Is the above process achievable with CDK?

[ecs-jnguyen]

The main thing I'm concerned about is the feature flags that are set in cdk.json. Having different feature flags can change the generated cloudformation template. If I want to make this cdk stack deployer be re-usable, then my consumers will need to have the same feature flags enabled. Is there an effective way to make sure that the feature flags are the same for anyone that wants to deploy the stack using cdk?

• CDK Feature Flags Documentation

[juanchaves]

What we do is we write a generic cdk app and push that up to our public team repo, where other teams can just do a git clone. We don't do a cdk synth command and we include the cdk.json that is generated at cdk init. In addition to the CDK IaC, we include a configuration file and README to assist end-users in setting up the CDK app correctly. We test the cdk apps by deploying them to our team's test account.

Example cdk.json:

{
  "app": "npx ts-node --prefer-ts-exts bin/<YOUR>-cdk-app.ts",
  "watch": {
    "include": ["**"],
    "exclude": [
      "README.md",
      "cdk*.json",
      "**/*.d.ts",
      "**/*.js",
      "tsconfig.json",
      "package*.json",
      "yarn.lock",
      "node_modules",
      "test"
    ]
  },
  "context": {
    "@aws-cdk/aws-apigateway:usagePlanKeyOrderInsensitiveId": true,
    "@aws-cdk/core:stackRelativeExports": true,
    "@aws-cdk/aws-rds:lowercaseDbIdentifier": true,
    "@aws-cdk/aws-lambda:recognizeVersionProps": true,
    "@aws-cdk/aws-cloudfront:defaultSecurityPolicyTLSv1.2_2021": true,
    "@aws-cdk-containers/ecs-service-extensions:enableDefaultLogDriver": true,
    "@aws-cdk/aws-ec2:uniqueImdsv2TemplateName": true,
    "@aws-cdk/core:target-partitions": ["aws", "aws-cn"]
  }
}

./config/config.ts

export const ACCOUNT = {
    dev: { id: '111111111111', region: 'us-east-1' },
    test: { id: '111111111111', region: 'us-east-1' },
    acc: { id: '111111111111', region: 'us-east-1' },
    prod: { id: '111111111111', region: 'us-east-1' },
}

./bin/your-cdk-app.ts

#!/usr/bin/env node
import 'source-map-support/register'
import * as cdk from 'aws-cdk-lib'
import { YourStack } from '../lib/your-stack'
import { ACCOUNT } from '../config/aws-config'

const tags = commonLib.Core.Tags

const app = new cdk.App()
const yourStack = new YourStack(app, 'YourStack', {
  env: { account: ACCOUNT.dev.id, region: ACCOUNT.dev.region },
})

[juanchaves]

I re-read your question and thought that you might want to just look into Aspects as what you're describing, seems to me, as distributing custom constructs and not a CDK app. You can provide custom aspects from a central team cdk library and your user-developers can then install that lib and use the Aspects to get the desired customization of the native CDK constructs.

Our team went down the road of creating and distributing our own custom L2 Constructs in TS & Py, but unless you have a dedicated team doing that, it can become quite difficult to maintain. Just keeping up with CDK's weekly version upgrade can be a lot, unless you take some time to automate that.

Here are some interesting links regarding creating your own custom CDK Lib:

• https://github.com/cdklabs/construct-hub
• https://aws.amazon.com/blogs/devops/getting-started-with-projen-and-aws-cdk/
• https://dev.to/aws-builders/a-beginner-s-guide-to-create-aws-cdk-construct-library-with-projen-5eh4

I believe there are other ways of distributing CDK custom constructs and apps, like CodeCatalyst blueprints, etc... but that's what I've researched atm.

[ecs-jnguyen]

Hey @juanchaves, thanks for the suggestion. I think this approach would work if we let our consumers use CDK to generate their cloudformation stacks. However we don't want to allow them to create their stacks using IaC directly. Rather the teams will create a json file that outlines what they want (like an s3 bucket or a load balancer). My team creates the scripts that read in the json file and creates the IaC to deploy the cloudformation stack. This way we can create resources securely and with the correct configuration.

We don't want to allow consumer teams create the IaC themselves because then they could possibly create public s3 buckets or other incorrectly configured resources.