feat: Add X-Gu-CDK-Version tag to GuStack

jest.config.js

@@ -3,4 +3,5 @@ module.exports = {
   transform: {
     "^.+\\.tsx?$": "ts-jest",
   },
+  setupFilesAfterEnv: ["./jest.setup.js"],
 };

jest.setup.js

@@ -0,0 +1 @@
+jest.mock("./src/constants/library-info");

src/constants/__mocks__/library-info.ts

@@ -0,0 +1,8 @@
+export const LibraryInfo = {
+  VERSION: "TEST",
+};
+
+export const TrackingTag = {
+  Key: "X-Gu-CDK-Version",
+  Value: LibraryInfo.VERSION,
+};

src/constants/library-info.ts

@@ -0,0 +1,10 @@
+import { version } from "../../package.json";
+
+export const LibraryInfo = {
+  VERSION: version,
+};
+
+export const TrackingTag = {
+  Key: "X-Gu-CDK-Version",
+  Value: LibraryInfo.VERSION,
+};

src/constructs/cloudwatch/__snapshots__/lambda-alarms.test.ts.snap

@@ -55,6 +55,10 @@ Object {
               "Ref": "Stage",
             },
           },
+          Object {
+            "Key": "X-Gu-CDK-Version",
+            "Value": "TEST",
+          },
         ],
         "Timeout": 30,
       },
@@ -105,6 +109,10 @@ Object {
               "Ref": "Stage",
             },
           },
+          Object {
+            "Key": "X-Gu-CDK-Version",
+            "Value": "TEST",
+          },
         ],
       },
       "Type": "AWS::IAM::Role",

src/constructs/core/stack.test.ts

@@ -3,9 +3,10 @@ import "@aws-cdk/assert/jest";
 import { SynthUtils } from "@aws-cdk/assert";
 import { Role, ServicePrincipal } from "@aws-cdk/aws-iam";
 import { App } from "@aws-cdk/core";
-import { simpleGuStackForTesting } from "../../../test/utils/simple-gu-stack";
-import type { SynthedStack } from "../../../test/utils/synthed-stack";
+import { simpleGuStackForTesting } from "../../../test/utils";
+import type { SynthedStack } from "../../../test/utils";
 import { Stage, Stages } from "../../constants";
+import { TrackingTag } from "../../constants/library-info";
 import { GuStack } from "./stack";
 
 describe("The GuStack construct", () => {
@@ -54,6 +55,7 @@ describe("The GuStack construct", () => {
             Ref: "Stage",
           },
         },
+        TrackingTag,
       ],
     });
   });

src/constructs/core/stack.ts

@@ -1,5 +1,6 @@
 import type { App, StackProps } from "@aws-cdk/core";
 import { Stack, Tags } from "@aws-cdk/core";
+import { TrackingTag } from "../../constants/library-info";
 import { GuStackParameter, GuStageParameter } from "./parameters";
 
 export interface GuStackProps extends StackProps {
@@ -9,6 +10,33 @@ export interface GuStackProps extends StackProps {
   migratedFromCloudFormation?: boolean;
 }
 
+/**
+ * GuStack provides the `stack` and `stage` parameters to a template.
+ * It also takes the `app` in the constructor.
+ *
+ * GuStack will add the Stack, Stage and App tags to all resources.
+ *
+ * GuStack also adds the tag `X-Gu-CDK-Version`.
+ * This tag allows us to measure adoption of this library.
+ * It's value is the version of guardian/cdk being used, as defined in `package.json`.
+ * As a result, the change sets between version numbers will be fairly noisy,
+ * as all resources receive a tag update.
+ * It is recommended to upgrade the version of @guardian/cdk being used in two steps:
+ *   1. Bump the library, apply the tag updates
+ *   2. Make any other stack changes
+ *
+ * Typical usage is to extend GuStack:
+ *
+ * ```typescript
+ * class MyStack extends GuStack {
+ *   constructor(scope: App, id: string, props: GuStackProps) {
+ *     super(scope, id, props)
+ *   }
+ *
+ *   // add resources here
+ * }
+ * ```
+ */
 export class GuStack extends Stack {
   private readonly _stage: GuStageParameter;
   private readonly _stack: GuStackParameter;
@@ -28,6 +56,13 @@ export class GuStack extends Stack {
 
   migratedFromCloudFormation: boolean;
 
+  /**
+   * A helper function to add a tag to all resources in a stack.
+   * @param key the tag name
+   * @param value the value of the tag
+   * @param applyToLaunchedInstances whether or not to apply the tag to instances launched in an ASG.
+   * @protected
+   */
   protected addTag(key: string, value: string, applyToLaunchedInstances: boolean = true): void {
     Tags.of(this).add(key, value, { applyToLaunchedInstances });
   }
@@ -42,6 +77,8 @@ export class GuStack extends Stack {
     this._stack = new GuStackParameter(this);
     this._app = props.app;
 
+    this.addTag(TrackingTag.Key, TrackingTag.Value);
+
     this.addTag("Stack", this.stack);
     this.addTag("Stage", this.stage);
     this.addTag("App", props.app);

src/constructs/iam/policies/__snapshots__/ses.test.ts.snap

@@ -104,6 +104,10 @@ Object {
               "Ref": "Stage",
             },
           },
+          Object {
+            "Key": "X-Gu-CDK-Version",
+            "Value": "TEST",
+          },
         ],
       },
       "Type": "AWS::IAM::Role",

src/constructs/iam/roles/__snapshots__/instance-role.test.ts.snap

@@ -145,6 +145,10 @@ Object {
               "Ref": "Stage",
             },
           },
+          Object {
+            "Key": "X-Gu-CDK-Version",
+            "Value": "TEST",
+          },
         ],
       },
       "Type": "AWS::IAM::Role",
@@ -404,6 +408,10 @@ Object {
               "Ref": "Stage",
             },
           },
+          Object {
+            "Key": "X-Gu-CDK-Version",
+            "Value": "TEST",
+          },
         ],
       },
       "Type": "AWS::IAM::Role",
@@ -616,6 +624,10 @@ Object {
               "Ref": "Stage",
             },
           },
+          Object {
+            "Key": "X-Gu-CDK-Version",
+            "Value": "TEST",
+          },
         ],
       },
       "Type": "AWS::IAM::Role",

src/constructs/lambda/__snapshots__/lambda.test.ts.snap

@@ -109,6 +109,10 @@ Object {
               "Ref": "Stage",
             },
           },
+          Object {
+            "Key": "X-Gu-CDK-Version",
+            "Value": "TEST",
+          },
         ],
         "Timeout": 30,
       },
@@ -159,6 +163,10 @@ Object {
               "Ref": "Stage",
             },
           },
+          Object {
+            "Key": "X-Gu-CDK-Version",
+            "Value": "TEST",
+          },
         ],
       },
       "Type": "AWS::IAM::Role",
@@ -234,6 +242,10 @@ Object {
               "Ref": "Stage",
             },
           },
+          Object {
+            "Key": "X-Gu-CDK-Version",
+            "Value": "TEST",
+          },
         ],
       },
       "Type": "AWS::ApiGateway::RestApi",
@@ -418,11 +430,15 @@ Object {
               "Ref": "Stage",
             },
           },
+          Object {
+            "Key": "X-Gu-CDK-Version",
+            "Value": "TEST",
+          },
         ],
       },
       "Type": "AWS::IAM::Role",
     },
-    "lambdaapi2Deployment4ECB93738ba48d7cb88b4c2b9ec5c442ee1c99e9": Object {
+    "lambdaapi2Deployment4ECB937340ba28821c4d87686bb600192997b7b2": Object {
       "DependsOn": Array [
         "lambdaapi2proxyANY3F8E1D36",
         "lambdaapi2proxyE68FDFBC",
@@ -439,7 +455,7 @@ Object {
     "lambdaapi2DeploymentStageprodCC9E3016": Object {
       "Properties": Object {
         "DeploymentId": Object {
-          "Ref": "lambdaapi2Deployment4ECB93738ba48d7cb88b4c2b9ec5c442ee1c99e9",
+          "Ref": "lambdaapi2Deployment4ECB937340ba28821c4d87686bb600192997b7b2",
         },
         "RestApiId": Object {
           "Ref": "lambdaapi239350ECC",
@@ -462,6 +478,10 @@ Object {
               "Ref": "Stage",
             },
           },
+          Object {
+            "Key": "X-Gu-CDK-Version",
+            "Value": "TEST",
+          },
         ],
       },
       "Type": "AWS::ApiGateway::Stage",
@@ -755,6 +775,10 @@ Object {
               "Ref": "Stage",
             },
           },
+          Object {
+            "Key": "X-Gu-CDK-Version",
+            "Value": "TEST",
+          },
         ],
       },
       "Type": "AWS::ApiGateway::RestApi",
@@ -804,11 +828,15 @@ Object {
               "Ref": "Stage",
             },
           },
+          Object {
+            "Key": "X-Gu-CDK-Version",
+            "Value": "TEST",
+          },
         ],
       },
       "Type": "AWS::IAM::Role",
     },
-    "lambdaapiDeployment8E95B5854e05b687211f19a449136200fabf5846": Object {
+    "lambdaapiDeployment8E95B58515e203156872c143be11756a3c89fbba": Object {
       "DependsOn": Array [
         "lambdaapiproxyANYA94E968A",
         "lambdaapiproxyB573C729",
@@ -825,7 +853,7 @@ Object {
     "lambdaapiDeploymentStageprod9598BC2F": Object {
       "Properties": Object {
         "DeploymentId": Object {
-          "Ref": "lambdaapiDeployment8E95B5854e05b687211f19a449136200fabf5846",
+          "Ref": "lambdaapiDeployment8E95B58515e203156872c143be11756a3c89fbba",
         },
         "RestApiId": Object {
           "Ref": "lambdaapiC1812993",
@@ -848,6 +876,10 @@ Object {
               "Ref": "Stage",
             },
           },
+          Object {
+            "Key": "X-Gu-CDK-Version",
+            "Value": "TEST",
+          },
         ],
       },
       "Type": "AWS::ApiGateway::Stage",

src/constructs/rds/instance.test.ts

@@ -3,8 +3,9 @@ import { SynthUtils } from "@aws-cdk/assert/lib/synth-utils";
 import { Vpc } from "@aws-cdk/aws-ec2";
 import { DatabaseInstanceEngine, ParameterGroup, PostgresEngineVersion } from "@aws-cdk/aws-rds";
 import { Stack } from "@aws-cdk/core";
-import { simpleGuStackForTesting } from "../../../test/utils/simple-gu-stack";
-import type { SynthedStack } from "../../../test/utils/synthed-stack";
+import { simpleGuStackForTesting } from "../../../test/utils";
+import type { SynthedStack } from "../../../test/utils";
+import { TrackingTag } from "../../constants/library-info";
 import { GuDatabaseInstance } from "./instance";
 
 describe("The GuDatabaseInstance class", () => {
@@ -100,6 +101,7 @@ describe("The GuDatabaseInstance class", () => {
             Ref: "Stage",
           },
         },
+        TrackingTag,
       ],
     });
   });

src/patterns/__snapshots__/scheduled-lambda.test.ts.snap

@@ -56,6 +56,10 @@ Object {
               "Ref": "Stage",
             },
           },
+          Object {
+            "Key": "X-Gu-CDK-Version",
+            "Value": "TEST",
+          },
         ],
         "Timeout": 30,
       },
@@ -156,6 +160,10 @@ Object {
               "Ref": "Stage",
             },
           },
+          Object {
+            "Key": "X-Gu-CDK-Version",
+            "Value": "TEST",
+          },
         ],
       },
       "Type": "AWS::IAM::Role",

src/patterns/__snapshots__/sns-lambda.test.ts.snap

@@ -48,6 +48,10 @@ Object {
               "Ref": "Stage",
             },
           },
+          Object {
+            "Key": "X-Gu-CDK-Version",
+            "Value": "TEST",
+          },
         ],
       },
       "Type": "AWS::SNS::Topic",
@@ -89,6 +93,10 @@ Object {
               "Ref": "Stage",
             },
           },
+          Object {
+            "Key": "X-Gu-CDK-Version",
+            "Value": "TEST",
+          },
         ],
         "Timeout": 30,
       },
@@ -205,6 +213,10 @@ Object {
               "Ref": "Stage",
             },
           },
+          Object {
+            "Key": "X-Gu-CDK-Version",
+            "Value": "TEST",
+          },
         ],
       },
       "Type": "AWS::IAM::Role",

tsconfig.json

@@ -14,7 +14,8 @@
     "inlineSources": true,
     "experimentalDecorators": true,
     "typeRoots": ["./node_modules/@types"],
-    "outDir": "lib"
+    "outDir": "lib",
+    "resolveJsonModule": true
   },
   "include": ["src/**/*"],
   "exclude": ["node_modules", "test", "src/**/*.test.ts", "src/**/__snapshots__/**"]