diff --git a/README.md b/README.md index a095e54d6..7ace67fe6 100644 --- a/README.md +++ b/README.md @@ -48,6 +48,7 @@ $ cdk destroy | [stepfunctions-job-poller](https://github.com/aws-samples/aws-cdk-examples/tree/master/typescript/stepfunctions-job-poller/) | A simple StepFunctions workflow | | [ecs-service-with-logging](https://github.com/aws-samples/aws-cdk-examples/tree/master/typescript/ecs/ecs-service-with-logging/) | Starting a container fronted by a load balancer on ECS | | [fargate-service-with-logging](https://github.com/aws-samples/aws-cdk-examples/tree/master/typescript/ecs/fargate-service-with-logging/) | Starting a container fronted by a load balancer on Fargate | +| [custom-logical-names](https://github.com/aws-samples/aws-cdk-examples/tree/master/typescript/custom-logical-names/) | Example of how to override logical name allocation | ## Java examples diff --git a/typescript/custom-logical-names/README.md b/typescript/custom-logical-names/README.md new file mode 100644 index 000000000..9d64d102d --- /dev/null +++ b/typescript/custom-logical-names/README.md @@ -0,0 +1,79 @@ +# Custom Logical Names + +--- + +![Stability: Stable](https://img.shields.io/badge/stability-Stable-success.svg?style=for-the-badge) + +> **This is a stable example. It should successfully build out of the box** +> +> This examples does is built on Construct Libraries marked "Stable" and does not have any infrastructure prerequisites to build. + +--- + + +This sample shows how you can override the behavior for allocating +logical names for CloudFormation resources in the CDK. + +It implements a feature that allows users to specify a prefix for +all logical names using the `prefix` context key. + +## Usage + +1. Extend your stacks from `BaseStack` instead of from `Stack`. +2. Specify context when calling the CLI through `--context prefix=PREFIX`. + +## Implementation + +The `BaseStack` class implements this custom behavior. Using a base stack is a a +common and recommended pattern for reusing policy within an organization. + +Then, any stack that derives from `BaseStack` will automatically have this +behavior. + +## Build + +To build this app, you need to be in this example's root folder. Then run the following: + +```bash +npm install -g aws-cdk +npm install +npm run build +``` + +This will install the necessary CDK, then this example's dependencies, and then build your TypeScript files and your CloudFormation template. + +## Deploy + +Run `cdk deploy --context prefix=PREFIX`. This will deploy / redeploy your Stack to your AWS Account. + +## Example + +```shell +$ cdk synth -j +{ + "Resources": { + "MyTopic86869434": { + "Type": "AWS::SNS::Topic" + }, + "MyBucketF68F3FF0": { + "Type": "AWS::S3::Bucket" + } + } +} +``` + +Now with prefix: + +```shell +$ cdk synth -j -c prefix="MyTeam" +{ + "Resources": { + "MyTeamMyTopic86869434": { + "Type": "AWS::SNS::Topic" + }, + "MyTeamMyBucketF68F3FF0": { + "Type": "AWS::S3::Bucket" + } + } +} +``` \ No newline at end of file diff --git a/typescript/custom-logical-names/base-stack.ts b/typescript/custom-logical-names/base-stack.ts new file mode 100644 index 000000000..5dab9d585 --- /dev/null +++ b/typescript/custom-logical-names/base-stack.ts @@ -0,0 +1,16 @@ +import { Stack, CfnElement } from '@aws-cdk/core'; + +/** + * A base stack class that implements custom logical name + * allocation. Adds a prefix if it is defined in the "prefix" + * context key. + * + * Use `cdk --context prefix=PREFIX` to set the prefix. + */ +export class BaseStack extends Stack { + public allocateLogicalId(element: CfnElement) { + const orig = super.allocateLogicalId(element); + const prefix = this.node.tryGetContext('prefix'); + return prefix ? prefix + orig : orig; + } +} \ No newline at end of file diff --git a/typescript/custom-logical-names/cdk.json b/typescript/custom-logical-names/cdk.json new file mode 100644 index 000000000..bc47f5984 --- /dev/null +++ b/typescript/custom-logical-names/cdk.json @@ -0,0 +1,3 @@ +{ + "app": "npx ts-node index.ts" +} diff --git a/typescript/custom-logical-names/index.ts b/typescript/custom-logical-names/index.ts new file mode 100644 index 000000000..69cabc8f9 --- /dev/null +++ b/typescript/custom-logical-names/index.ts @@ -0,0 +1,18 @@ +#!/usr/bin/env node +import { BaseStack } from './base-stack'; +import { App, Construct, StackProps } from '@aws-cdk/core'; +import s3 = require('@aws-cdk/aws-s3'); +import sns = require('@aws-cdk/aws-sns'); + +class MyStack extends BaseStack { + constructor(scope: Construct, id: string, props?: StackProps) { + super(scope, id, props); + + new sns.Topic(this, 'MyTopic'); + new s3.Bucket(this, 'MyBucket'); + } +} + +const app = new App(); +new MyStack(app, 'MyStack'); +app.synth(); \ No newline at end of file diff --git a/typescript/custom-logical-names/package.json b/typescript/custom-logical-names/package.json new file mode 100644 index 000000000..fa45b97fb --- /dev/null +++ b/typescript/custom-logical-names/package.json @@ -0,0 +1,23 @@ +{ + "name": "custom-logical-names", + "version": "0.1.0", + "bin": { + "custom-logical-names": "bin/custom-logical-names.js" + }, + "scripts": { + "build": "tsc", + "watch": "tsc -w", + "cdk": "cdk" + }, + "devDependencies": { + "aws-cdk": "*", + "ts-node": "^8.1.0", + "typescript": "~3.7.2" + }, + "dependencies": { + "@aws-cdk/aws-s3": "*", + "@aws-cdk/aws-sns": "*", + "@aws-cdk/core": "*", + "source-map-support": "^0.5.9" + } +} diff --git a/typescript/custom-logical-names/tsconfig.json b/typescript/custom-logical-names/tsconfig.json new file mode 100644 index 000000000..3f61627ac --- /dev/null +++ b/typescript/custom-logical-names/tsconfig.json @@ -0,0 +1,23 @@ +{ + "compilerOptions": { + "target":"ES2018", + "module": "commonjs", + "lib": ["es2016", "es2017.object", "es2017.string"], + "declaration": true, + "strict": true, + "noImplicitAny": true, + "strictNullChecks": true, + "noImplicitThis": true, + "alwaysStrict": true, + "noUnusedLocals": false, + "noUnusedParameters": false, + "noImplicitReturns": true, + "noFallthroughCasesInSwitch": false, + "inlineSourceMap": true, + "inlineSources": true, + "experimentalDecorators": true, + "strictPropertyInitialization":false, + "typeRoots": ["./node_modules/@types"] + }, + "exclude": ["cdk.out"] +}