@infoxchange/make-it-so 2.18.0 → 2.19.0-internal-testing-add-tag-setup-4d301bb.1

package/README.md

@@ -57,6 +57,55 @@ console.log(getDeployConfig());
 | smtpHost          | SMTP host for the app to use           | string                             | string                 |
 | smtpPort          | SMTP port for the app to use           | number                             | number \| undefined    |
 | clamAVUrl         | ClamAV instance url for the app to use | string                             | string                 |
+| vpcHttpProxy      | HTTP proxy URL for the VPC             | string                             | string                 |
+| alarmSnsTopic     | SNS topic ARN for CloudWatch alarms    | string                             | string                 |
+| tags              | Tags to apply to AWS resources         | Record<string, string>             | Record<string, string> |
+
+</details>
+
+### setupTags
+
+Automatically applies various AWS tags to CDK constructs in your stack and can be customized with your own tagging
+logic. Default behaviour:
+
+- Applies tags from `deployConfig.tags` to the root construct
+- Adds `guardduty-suppress: true` tag to SST "live lambda" Functions (to prevent false positive GuardDuty alerts)
+
+```typescript
+import { setupTags } from "@infoxchange/make-it-so/lib/tags";
+
+// Basic usage - automatically applies tags from deployConfig
+setupTags(app);
+
+// Advanced usage - customize tags based on construct properties
+setupTags(app, {
+  modifyTags: ({ node, isLeafNode, isRootNode, currentTags }) => {
+    // Add custom tags for specific construct types
+    if (node instanceof IxNextjsSite) {
+      return [...currentTags, { key: "ResourceType", value: "NextjsSite" }];
+    }
+    return currentTags;
+  },
+});
+```
+
+<details>
+<summary><strong>Options</strong></summary>
+
+| Prop               | Type                                                            | Description                                                               |
+| ------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| scope              | IConstruct                                                      | The CDK construct to apply tags to (usually your app or stack)            |
+| options            | SetupTagsOptions                                                | (optional) Configuration options                                          |
+| options.modifyTags | (props: ModifyTagsProps) => Array<{key: string, value: string}> | (optional) Function to customize tags based on the construct being tagged |
+
+#### ModifyTagsProps:
+
+| Property    | Type                                | Description                              |
+| ----------- | ----------------------------------- | ---------------------------------------- |
+| node        | IConstruct                          | The current construct being tagged       |
+| isLeafNode  | boolean                             | Whether this construct has no children   |
+| isRootNode  | boolean                             | Whether this is the root scope construct |
+| currentTags | Array<{key: string, value: string}> | The tags that have already been applied  |
 
 </details>
 
@@ -232,6 +281,71 @@ const domainCert = new IxCertificate(scope, "ExampleDotComCertificate", {
 
 </details>
 
+<details>
+<summary><strong>IxCloudWatchAlarm</strong> - Creates a CloudWatch alarm with IX-specific defaults.</summary>
+
+IxCloudWatchAlarm extends AWS CDK's CloudWatch Alarm functionality with IX-specific defaults and special handling for
+CloudFront alarms (which must be created in us-east-1). If no actions are specified, the alarm will automatically use
+the IX alarm SNS topic which sends alerts to MS Teams. Who is tagged in these alerts can be configured with the
+`toNotify` property.
+
+```typescript
+import { IxCloudWatchAlarm } from "@infoxchange/make-it-so/cdk-constructs";
+
+new IxCloudWatchAlarm(scope, "ApiErrorAlarm", {
+  alarmName: "high-error-rate",
+  alarmDescription: "Alert when API error rate is too high",
+  metric: {
+    namespace: "AWS/ApiGateway",
+    metricName: "5XXError",
+    dimensionsMap: {
+      ApiName: "my-api",
+    },
+    period: (Duration) => Duration.minutes(5),
+    statistic: (Stats) => Stats.AVERAGE,
+  },
+  threshold: 10,
+  evaluationPeriods: 2,
+  comparisonOperator: (ComparisonOperator) =>
+    ComparisonOperator.GREATER_THAN_THRESHOLD,
+  toNotify: ["Receiver Name", "Second Receiver"], // Receivers are defined in aws-gov under components/infra-event-notification
+});
+```
+
+#### Options:
+
+| Prop                       | Type                                                               | Description                                                                                                                                 |
+| -------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| metric                     | object                                                             | Metric configuration                                                                                                                        |
+| metric.namespace           | string                                                             | The namespace of the metric (e.g., "AWS/ApiGateway")                                                                                        |
+| metric.metricName          | string                                                             | The name of the metric                                                                                                                      |
+| metric.dimensionsMap       | Record<string, string>                                             | (optional) Dimensions for the metric                                                                                                        |
+| metric.period              | Duration \| ((Duration) => Duration)                               | (optional) The period over which the statistic is applied. Can be a function for easier access to CDK Duration helpers                      |
+| metric.statistic           | string \| ((Stats) => string)                                      | (optional) The statistic to apply (e.g., "Average", "Sum"). Can be a function for easier access to CloudWatch.Stats helpers                 |
+| comparisonOperator         | ComparisonOperator \| ((ComparisonOperator) => ComparisonOperator) | How to compare the metric to the threshold. Can be a function for easier access to CloudWatch.ComparisonOperator helpers                    |
+| threshold                  | number                                                             | The value to compare the metric against                                                                                                     |
+| evaluationPeriods          | number                                                             | The number of periods over which data is compared to the threshold                                                                          |
+| treatMissingData           | TreatMissingData \| ((TreatMissingData) => TreatMissingData)       | (optional) How to treat missing data points. Can be a function for easier access to CloudWatch.TreatMissingData helpers                     |
+| alarmName                  | string                                                             | (optional) Name of the alarm                                                                                                                |
+| alarmDescription           | string                                                             | (optional) Description of the alarm                                                                                                         |
+| toNotify                   | string[]                                                           | (optional) List receivers to be notified on alarm state changes. Receivers are defined in aws-gov under components/infra-event-notification |
+| actions                    | object                                                             | (optional) Actions to take when alarm state changes. If not provided, defaults to IX alarm SNS topic                                        |
+| actions.onOk               | (string \| IAlarmAction)[]                                         | (optional) Actions to take when alarm goes to OK state                                                                                      |
+| actions.onAlarm            | (string \| IAlarmAction)[]                                         | (optional) Actions to take when alarm goes to ALARM state                                                                                   |
+| actions.onInsufficientData | (string \| IAlarmAction)[]                                         | (optional) Actions to take when alarm goes to INSUFFICIENT_DATA state                                                                       |
+| [...CloudWatch.AlarmProps] |                                                                    | Any other props accepted by [CloudWatch.Alarm](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_cloudwatch.Alarm.html)           |
+
+#### Static Properties:
+
+IxCloudWatchAlarm provides access to various CloudWatch constants:
+
+- `IxCloudWatchAlarm.Stats` - CloudWatch.Stats for metric statistics
+- `IxCloudWatchAlarm.Duration` - CDK.Duration for time periods
+- `IxCloudWatchAlarm.TreatMissingData` - CloudWatch.TreatMissingData for handling missing data
+- `IxCloudWatchAlarm.ComparisonOperator` - CloudWatch.ComparisonOperator for comparison operations
+
+</details>
+
 <details>
 <summary><strong>IxDnsRecord</strong> - Creates a DNS record for a domain managed by IX.</summary>
 

package/dist/deployConfig.d.ts

@@ -16,6 +16,7 @@ declare const _default: {
     clamAVUrl: string;
     vpcHttpProxy: string;
     alarmSnsTopic: string;
+    tags: Record<string, string>;
 } | {
     isIxDeploy: false;
     appName: string;
@@ -32,6 +33,7 @@ declare const _default: {
     clamAVUrl: string;
     vpcHttpProxy: string;
     alarmSnsTopic: string;
+    tags: Record<string, string>;
     isInternalApp?: boolean | undefined;
     smtpPort?: number | undefined;
 };
@@ -54,6 +56,7 @@ export declare const getDeployConfig: () => {
     clamAVUrl: string;
     vpcHttpProxy: string;
     alarmSnsTopic: string;
+    tags: Record<string, string>;
 } | {
     isIxDeploy: false;
     appName: string;
@@ -70,6 +73,7 @@ export declare const getDeployConfig: () => {
     clamAVUrl: string;
     vpcHttpProxy: string;
     alarmSnsTopic: string;
+    tags: Record<string, string>;
     isInternalApp?: boolean | undefined;
     smtpPort?: number | undefined;
 };

package/dist/deployConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deployConfig.d.ts","sourceRoot":"","sources":["../src/deployConfig.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsFA,wBAA0C;AAG1C,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAAmC,CAAC"}
+{"version":3,"file":"deployConfig.d.ts","sourceRoot":"","sources":["../src/deployConfig.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyFA,wBAA0C;AAG1C,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAAmC,CAAC"}

package/dist/deployConfig.js

@@ -17,6 +17,7 @@ const getEnvVars = () => ({
     clamAVUrl: process.env.CLAMAV_URL ?? "",
     vpcHttpProxy: process.env.VPC_HTTP_PROXY ?? "",
     alarmSnsTopic: process.env.IX_ALARM_SNS_TOPIC ?? "",
+    tags: JSON.parse(process.env.IX_TAGS ?? "{}"),
 });
 const ixDeployConfigSchema = z
     .object({
@@ -41,6 +42,7 @@ const ixDeployConfigSchema = z
     clamAVUrl: z.string().url(),
     vpcHttpProxy: z.string().url(),
     alarmSnsTopic: z.string().min(1),
+    tags: z.record(z.string(), z.string()),
 })
     .strip();
 const nonIxDeployConfigSchema = z
@@ -70,6 +72,7 @@ const nonIxDeployConfigSchema = z
     clamAVUrl: z.string(),
     vpcHttpProxy: z.string(),
     alarmSnsTopic: z.string(),
+    tags: z.record(z.string(), z.string()),
 })
     .strip();
 const schema = z.discriminatedUnion("isIxDeploy", [

package/dist/lib/tags/ConditionalTags.d.ts

@@ -0,0 +1,11 @@
+import { IAspect } from "aws-cdk-lib";
+import { IConstruct } from "constructs";
+export declare class ConditionalTags implements IAspect {
+    private getTags;
+    constructor(getTags: (node: IConstruct) => Array<{
+        key: string;
+        value: string;
+    }> | undefined | null);
+    visit(node: IConstruct): void;
+}
+//# sourceMappingURL=ConditionalTags.d.ts.map

package/dist/lib/tags/ConditionalTags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConditionalTags.d.ts","sourceRoot":"","sources":["../../../src/lib/tags/ConditionalTags.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAQ,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,qBAAa,eAAgB,YAAW,OAAO;IAE3C,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE,CACf,IAAI,EAAE,UAAU,KACb,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,SAAS,GAAG,IAAI;IAG/D,KAAK,CAAC,IAAI,EAAE,UAAU;CAKvB"}

package/dist/lib/tags/ConditionalTags.js

@@ -0,0 +1,12 @@
+import { Tags } from "aws-cdk-lib";
+export class ConditionalTags {
+    getTags;
+    constructor(getTags) {
+        this.getTags = getTags;
+    }
+    visit(node) {
+        this.getTags(node)?.forEach(({ key, value }) => {
+            Tags.of(node).add(key, value);
+        });
+    }
+}

package/dist/lib/tags/index.d.ts

@@ -0,0 +1,3 @@
+export { setupTags } from "./setupTags.js";
+export { ConditionalTags } from "./ConditionalTags.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/tags/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/tags/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/lib/tags/index.js

@@ -0,0 +1,2 @@
+export { setupTags } from "./setupTags.js";
+export { ConditionalTags } from "./ConditionalTags.js";

package/dist/lib/tags/setupTags.d.ts

@@ -0,0 +1,18 @@
+import { IConstruct } from "constructs";
+export type ModifyTagsProps = {
+    node: IConstruct;
+    isLeafNode: boolean;
+    isRootNode: boolean;
+    currentTags: Array<{
+        key: string;
+        value: string;
+    }>;
+};
+export type SetupTagsOptions = {
+    modifyTags?: (props: ModifyTagsProps) => Array<{
+        key: string;
+        value: string;
+    }>;
+};
+export declare function setupTags(scope: IConstruct, { modifyTags }?: SetupTagsOptions): void;
+//# sourceMappingURL=setupTags.d.ts.map

package/dist/lib/tags/setupTags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setupTags.d.ts","sourceRoot":"","sources":["../../../src/lib/tags/setupTags.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAKxC,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,UAAU,CAAC;IACjB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,WAAW,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACpD,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,UAAU,CAAC,EAAE,CACX,KAAK,EAAE,eAAe,KACnB,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC5C,CAAC;AAEF,wBAAgB,SAAS,CACvB,KAAK,EAAE,UAAU,EACjB,EAAE,UAAU,EAAE,GAAE,gBAAqB,QAiCtC"}

package/dist/lib/tags/setupTags.js

@@ -0,0 +1,33 @@
+import { Aspects } from "aws-cdk-lib";
+import { Function } from "sst/constructs";
+import { ConditionalTags } from "./ConditionalTags.js";
+import deployConfig from "../../deployConfig.js";
+export function setupTags(scope, { modifyTags } = {}) {
+    const conditionalTags = new ConditionalTags((node) => {
+        let tags = [];
+        const isLeafNode = node.node.children.length === 0;
+        const isRootNode = node === scope;
+        // Add tags from deploy config to all constructs
+        if (isRootNode) {
+            Object.entries(deployConfig.tags).forEach(([key, value]) => {
+                tags.push({ key, value });
+            });
+        }
+        // SST v2's live lambda feature means that the local machine that `sst dev` is run on may use AWS creds that were
+        // setup for a lambda. This triggers a false positive in GuardDuty, so we suppress that finding for any lambda that
+        // has live dev enabled.
+        if (node instanceof Function && node._isLiveDevEnabled) {
+            tags.push({ key: "guardduty-suppress", value: "true" });
+        }
+        tags = modifyTags
+            ? modifyTags({
+                node,
+                isLeafNode,
+                isRootNode,
+                currentTags: tags,
+            })
+            : tags;
+        return tags;
+    });
+    Aspects.of(scope).add(conditionalTags);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@infoxchange/make-it-so",
-  "version": "2.18.0",
+  "version": "2.19.0-internal-testing-add-tag-setup-4d301bb.1",
   "description": "Makes deploying services to IX infra easy",
   "repository": "github:infoxchange/make-it-so",
   "publishConfig": {
@@ -21,7 +21,8 @@
     "./cdk-constructs": "./dist/cdk-constructs/index.js",
     "./deployConfig": "./dist/deployConfig.js",
     "./auth": "./dist/lib/auth/index.js",
-    "./proxy": "./dist/lib/proxy/index.js"
+    "./proxy": "./dist/lib/proxy/index.js",
+    "./tags": "./dist/lib/tags/index.js"
   },
   "lint-staged": {
     "**/*": [

package/src/deployConfig.ts

@@ -19,6 +19,7 @@ const getEnvVars = () =>
     clamAVUrl: process.env.CLAMAV_URL ?? "",
     vpcHttpProxy: process.env.VPC_HTTP_PROXY ?? "",
     alarmSnsTopic: process.env.IX_ALARM_SNS_TOPIC ?? "",
+    tags: JSON.parse(process.env.IX_TAGS ?? "{}"),
   }) satisfies Record<string, string | boolean>;
 
 const ixDeployConfigSchema = z
@@ -44,6 +45,7 @@ const ixDeployConfigSchema = z
     clamAVUrl: z.string().url(),
     vpcHttpProxy: z.string().url(),
     alarmSnsTopic: z.string().min(1),
+    tags: z.record(z.string(), z.string()),
   } satisfies Record<keyof ReturnType<typeof getEnvVars>, unknown>)
   .strip();
 
@@ -76,6 +78,7 @@ const nonIxDeployConfigSchema = z
     clamAVUrl: z.string(),
     vpcHttpProxy: z.string(),
     alarmSnsTopic: z.string(),
+    tags: z.record(z.string(), z.string()),
   } satisfies Record<keyof ReturnType<typeof getEnvVars>, unknown>)
   .strip();
 

package/src/lib/tags/ConditionalTags.ts

@@ -0,0 +1,16 @@
+import { IAspect, Tags } from "aws-cdk-lib";
+import { IConstruct } from "constructs";
+
+export class ConditionalTags implements IAspect {
+  constructor(
+    private getTags: (
+      node: IConstruct,
+    ) => Array<{ key: string; value: string }> | undefined | null,
+  ) {}
+
+  visit(node: IConstruct) {
+    this.getTags(node)?.forEach(({ key, value }) => {
+      Tags.of(node).add(key, value);
+    });
+  }
+}

package/src/lib/tags/index.ts

@@ -0,0 +1,2 @@
+export { setupTags } from "./setupTags.js";
+export { ConditionalTags } from "./ConditionalTags.js";

package/src/lib/tags/setupTags.ts

@@ -0,0 +1,55 @@
+import { Aspects } from "aws-cdk-lib";
+import { IConstruct } from "constructs";
+import { Function } from "sst/constructs";
+import { ConditionalTags } from "./ConditionalTags.js";
+import deployConfig from "../../deployConfig.js";
+
+export type ModifyTagsProps = {
+  node: IConstruct;
+  isLeafNode: boolean;
+  isRootNode: boolean;
+  currentTags: Array<{ key: string; value: string }>;
+};
+
+export type SetupTagsOptions = {
+  modifyTags?: (
+    props: ModifyTagsProps,
+  ) => Array<{ key: string; value: string }>;
+};
+
+export function setupTags(
+  scope: IConstruct,
+  { modifyTags }: SetupTagsOptions = {},
+) {
+  const conditionalTags = new ConditionalTags((node) => {
+    let tags = [];
+    const isLeafNode = node.node.children.length === 0;
+    const isRootNode = node === scope;
+
+    // Add tags from deploy config to all constructs
+    if (isRootNode) {
+      Object.entries(deployConfig.tags).forEach(([key, value]) => {
+        tags.push({ key, value });
+      });
+    }
+
+    // SST v2's live lambda feature means that the local machine that `sst dev` is run on may use AWS creds that were
+    // setup for a lambda. This triggers a false positive in GuardDuty, so we suppress that finding for any lambda that
+    // has live dev enabled.
+    if (node instanceof Function && node._isLiveDevEnabled) {
+      tags.push({ key: "guardduty-suppress", value: "true" });
+    }
+
+    tags = modifyTags
+      ? modifyTags({
+          node,
+          isLeafNode,
+          isRootNode,
+          currentTags: tags,
+        })
+      : tags;
+    return tags;
+  });
+
+  Aspects.of(scope).add(conditionalTags);
+}