@guardian/cdk 49.4.1 → 49.5.0

package/lib/bin/commands/new-project/index.js

@@ -101,30 +101,30 @@ const newCdkProject = async (props) => {
     });
     const commands = (0, utils_1.getCommands)(config.packageManager, config.cdkDir);
     if (config.init) {
-        core_1.CliUx.ux.action.start(chalk_1.default.yellow("Installing dependencies. This may take a while..."));
+        core_1.ux.action.start(chalk_1.default.yellow("Installing dependencies. This may take a while..."));
         await commands.installDependencies();
-        core_1.CliUx.ux.action.stop();
+        core_1.ux.action.stop();
     }
     // Run `eslint --fix` on the generated files instead of trying to generate code that completely satisfies the linter
     await (0, exec_1.execute)("./node_modules/.bin/eslint", ["lib/** bin/**", "--ext .ts", "--no-error-on-unmatched-pattern", "--fix"], {
         cwd: config.cdkDir,
     });
-    core_1.CliUx.ux.action.start(chalk_1.default.yellow("Running lint check..."));
+    core_1.ux.action.start(chalk_1.default.yellow("Running lint check..."));
     await commands.lint();
-    core_1.CliUx.ux.action.stop();
-    core_1.CliUx.ux.action.start(chalk_1.default.yellow("Running tests..."));
+    core_1.ux.action.stop();
+    core_1.ux.action.start(chalk_1.default.yellow("Running tests..."));
     await commands.test();
-    core_1.CliUx.ux.action.stop();
-    core_1.CliUx.ux.action.start(chalk_1.default.yellow("Running initial synthesis..."));
+    core_1.ux.action.stop();
+    core_1.ux.action.start(chalk_1.default.yellow("Running initial synthesis..."));
     await commands.synth();
-    core_1.CliUx.ux.action.stop();
+    core_1.ux.action.stop();
     console.log(chalk_1.default.green("Success! Here's a summary of the created files:"));
     const tree = await (0, exec_1.execute)("tree", ["-I 'node_modules|cdk.out'"], {
         cwd: config.cdkDir,
     });
     console.log(tree);
     const docsUrl = "https://github.com/guardian/cdk/tree/main/docs";
-    core_1.CliUx.ux.url(chalk_1.default.green(`Please see the docs (${docsUrl}) for next steps.`), docsUrl);
+    core_1.ux.url(chalk_1.default.green(`Please see the docs (${docsUrl}) for next steps.`), docsUrl);
     return Promise.resolve(0);
 };
 exports.newCdkProject = newCdkProject;

package/lib/bin/commands/new-project/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/bin/commands/new-project/index.ts"],"names":[],"mappings":"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","sourcesContent":["import { existsSync } from \"fs\";\nimport { basename, dirname, join } from \"path\";\nimport { CliUx } from \"@oclif/core\";\nimport chalk from \"chalk\";\nimport kebabCase from \"lodash.kebabcase\";\nimport type { CliCommandResponse } from \"../../../types/cli\";\nimport { execute } from \"../../../utils/exec\";\nimport { gitRootOrCwd } from \"../../../utils/git\";\nimport { constructApp } from \"./utils/app\";\nimport { Imports } from \"./utils/imports\";\nimport { buildDirectory } from \"./utils/init\";\nimport { constructTest } from \"./utils/snapshot\";\nimport { constructStack } from \"./utils/stack\";\nimport type { Name } from \"./utils/utils\";\nimport { getCommands, pascalCase } from \"./utils/utils\";\n\nexport type PackageManager = \"npm\" | \"yarn\";\n\ninterface NewProjectProps {\n  init: boolean;\n  app: string;\n  stack: string;\n  stages: string[];\n  yamlTemplateLocation?: string;\n  packageManager: PackageManager;\n}\n\ninterface NewProjectConfig extends Omit<NewProjectProps, \"stack\" | \"app\"> {\n  cdkDir: string;\n  appPath: string;\n  appName: Name;\n  stackPath: string;\n  stackName: Name;\n  testPath: string;\n}\n\nconst checkPathExists = (path: string): void => {\n  if (!existsSync(path)) {\n    throw new Error(`File not found - ${path}`);\n  }\n};\n\nconst checkPathDoesNotExist = (path: string): void => {\n  if (existsSync(path)) {\n    throw new Error(`There is already a file at - ${path}`);\n  }\n};\n\nfunction validateConfig(config: NewProjectConfig): void {\n  if (!config.init) {\n    checkPathExists(config.cdkDir);\n  }\n  checkPathDoesNotExist(config.appPath); // TODO: Update the app file if it already exists\n  checkPathDoesNotExist(config.stackPath);\n\n  if (config.yamlTemplateLocation) {\n    checkPathExists(config.yamlTemplateLocation);\n  }\n}\n\nfunction getConfig(props: NewProjectProps): NewProjectConfig {\n  const { init, app, stack, stages, yamlTemplateLocation, packageManager } = props;\n\n  const rootDir = gitRootOrCwd();\n  const cdkDir = join(rootDir, \"/cdk\");\n\n  const appName = pascalCase(app);\n  const kebabAppName = kebabCase(appName);\n  const stackName = pascalCase(stack);\n  const kebabStackName = kebabCase(stackName);\n\n  const config: NewProjectConfig = {\n    init,\n    yamlTemplateLocation,\n    stages,\n    cdkDir,\n    appName: {\n      kebab: kebabAppName,\n      pascal: appName,\n    },\n    appPath: `${cdkDir}/bin/${kebabAppName}.ts`,\n    stackName: {\n      kebab: kebabStackName,\n      pascal: stackName,\n    },\n    stackPath: `${cdkDir}/lib/${kebabAppName}.ts`,\n    testPath: `${cdkDir}/lib/${kebabAppName}.test.ts`,\n    packageManager,\n  };\n\n  validateConfig(config);\n\n  return config;\n}\n\nexport const newCdkProject = async (props: NewProjectProps): CliCommandResponse => {\n  console.log(\"Starting CDK generator\");\n\n  const config = getConfig(props);\n\n  if (config.init) {\n    buildDirectory({ outputDir: config.cdkDir });\n  }\n\n  console.log(`New app ${config.appName.pascal} will be written to ${config.appPath}`);\n  console.log(`New stack ${config.stackName.pascal} will be written to ${config.stackPath}`);\n\n  // bin directory\n  await constructApp({\n    appName: config.appName,\n    outputFile: \"cdk.ts\",\n    outputDir: dirname(config.appPath),\n    stack: config.stackName,\n    imports: Imports.newAppImports(config.appName),\n    stages: config.stages,\n  });\n\n  // lib directory\n  await constructStack({\n    imports: Imports.newStackImports(),\n    appName: config.appName,\n    outputFile: basename(config.stackPath),\n    outputDir: dirname(config.stackPath),\n    yamlTemplateLocation: config.yamlTemplateLocation,\n  });\n\n  // lib directory\n  await constructTest({\n    imports: Imports.newTestImports(config.appName),\n    stackName: config.stackName,\n    appName: config.appName,\n    outputFile: basename(config.testPath),\n    outputDir: dirname(config.stackPath),\n  });\n\n  const commands = getCommands(config.packageManager, config.cdkDir);\n\n  if (config.init) {\n    CliUx.ux.action.start(chalk.yellow(\"Installing dependencies. This may take a while...\"));\n    await commands.installDependencies();\n    CliUx.ux.action.stop();\n  }\n\n  // Run `eslint --fix` on the generated files instead of trying to generate code that completely satisfies the linter\n  await execute(\n    \"./node_modules/.bin/eslint\",\n    [\"lib/** bin/**\", \"--ext .ts\", \"--no-error-on-unmatched-pattern\", \"--fix\"],\n    {\n      cwd: config.cdkDir,\n    }\n  );\n\n  CliUx.ux.action.start(chalk.yellow(\"Running lint check...\"));\n  await commands.lint();\n  CliUx.ux.action.stop();\n\n  CliUx.ux.action.start(chalk.yellow(\"Running tests...\"));\n  await commands.test();\n  CliUx.ux.action.stop();\n\n  CliUx.ux.action.start(chalk.yellow(\"Running initial synthesis...\"));\n  await commands.synth();\n  CliUx.ux.action.stop();\n\n  console.log(chalk.green(\"Success! Here's a summary of the created files:\"));\n  const tree = await execute(\"tree\", [\"-I 'node_modules|cdk.out'\"], {\n    cwd: config.cdkDir,\n  });\n  console.log(tree);\n\n  const docsUrl = \"https://github.com/guardian/cdk/tree/main/docs\";\n  CliUx.ux.url(chalk.green(`Please see the docs (${docsUrl}) for next steps.`), docsUrl);\n\n  return Promise.resolve(0);\n};\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/bin/commands/new-project/index.ts"],"names":[],"mappings":"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","sourcesContent":["import { existsSync } from \"fs\";\nimport { basename, dirname, join } from \"path\";\nimport { ux } from \"@oclif/core\";\nimport chalk from \"chalk\";\nimport kebabCase from \"lodash.kebabcase\";\nimport type { CliCommandResponse } from \"../../../types/cli\";\nimport { execute } from \"../../../utils/exec\";\nimport { gitRootOrCwd } from \"../../../utils/git\";\nimport { constructApp } from \"./utils/app\";\nimport { Imports } from \"./utils/imports\";\nimport { buildDirectory } from \"./utils/init\";\nimport { constructTest } from \"./utils/snapshot\";\nimport { constructStack } from \"./utils/stack\";\nimport type { Name } from \"./utils/utils\";\nimport { getCommands, pascalCase } from \"./utils/utils\";\n\nexport type PackageManager = \"npm\" | \"yarn\";\n\ninterface NewProjectProps {\n  init: boolean;\n  app: string;\n  stack: string;\n  stages: string[];\n  yamlTemplateLocation?: string;\n  packageManager: PackageManager;\n}\n\ninterface NewProjectConfig extends Omit<NewProjectProps, \"stack\" | \"app\"> {\n  cdkDir: string;\n  appPath: string;\n  appName: Name;\n  stackPath: string;\n  stackName: Name;\n  testPath: string;\n}\n\nconst checkPathExists = (path: string): void => {\n  if (!existsSync(path)) {\n    throw new Error(`File not found - ${path}`);\n  }\n};\n\nconst checkPathDoesNotExist = (path: string): void => {\n  if (existsSync(path)) {\n    throw new Error(`There is already a file at - ${path}`);\n  }\n};\n\nfunction validateConfig(config: NewProjectConfig): void {\n  if (!config.init) {\n    checkPathExists(config.cdkDir);\n  }\n  checkPathDoesNotExist(config.appPath); // TODO: Update the app file if it already exists\n  checkPathDoesNotExist(config.stackPath);\n\n  if (config.yamlTemplateLocation) {\n    checkPathExists(config.yamlTemplateLocation);\n  }\n}\n\nfunction getConfig(props: NewProjectProps): NewProjectConfig {\n  const { init, app, stack, stages, yamlTemplateLocation, packageManager } = props;\n\n  const rootDir = gitRootOrCwd();\n  const cdkDir = join(rootDir, \"/cdk\");\n\n  const appName = pascalCase(app);\n  const kebabAppName = kebabCase(appName);\n  const stackName = pascalCase(stack);\n  const kebabStackName = kebabCase(stackName);\n\n  const config: NewProjectConfig = {\n    init,\n    yamlTemplateLocation,\n    stages,\n    cdkDir,\n    appName: {\n      kebab: kebabAppName,\n      pascal: appName,\n    },\n    appPath: `${cdkDir}/bin/${kebabAppName}.ts`,\n    stackName: {\n      kebab: kebabStackName,\n      pascal: stackName,\n    },\n    stackPath: `${cdkDir}/lib/${kebabAppName}.ts`,\n    testPath: `${cdkDir}/lib/${kebabAppName}.test.ts`,\n    packageManager,\n  };\n\n  validateConfig(config);\n\n  return config;\n}\n\nexport const newCdkProject = async (props: NewProjectProps): CliCommandResponse => {\n  console.log(\"Starting CDK generator\");\n\n  const config = getConfig(props);\n\n  if (config.init) {\n    buildDirectory({ outputDir: config.cdkDir });\n  }\n\n  console.log(`New app ${config.appName.pascal} will be written to ${config.appPath}`);\n  console.log(`New stack ${config.stackName.pascal} will be written to ${config.stackPath}`);\n\n  // bin directory\n  await constructApp({\n    appName: config.appName,\n    outputFile: \"cdk.ts\",\n    outputDir: dirname(config.appPath),\n    stack: config.stackName,\n    imports: Imports.newAppImports(config.appName),\n    stages: config.stages,\n  });\n\n  // lib directory\n  await constructStack({\n    imports: Imports.newStackImports(),\n    appName: config.appName,\n    outputFile: basename(config.stackPath),\n    outputDir: dirname(config.stackPath),\n    yamlTemplateLocation: config.yamlTemplateLocation,\n  });\n\n  // lib directory\n  await constructTest({\n    imports: Imports.newTestImports(config.appName),\n    stackName: config.stackName,\n    appName: config.appName,\n    outputFile: basename(config.testPath),\n    outputDir: dirname(config.stackPath),\n  });\n\n  const commands = getCommands(config.packageManager, config.cdkDir);\n\n  if (config.init) {\n    ux.action.start(chalk.yellow(\"Installing dependencies. This may take a while...\"));\n    await commands.installDependencies();\n    ux.action.stop();\n  }\n\n  // Run `eslint --fix` on the generated files instead of trying to generate code that completely satisfies the linter\n  await execute(\n    \"./node_modules/.bin/eslint\",\n    [\"lib/** bin/**\", \"--ext .ts\", \"--no-error-on-unmatched-pattern\", \"--fix\"],\n    {\n      cwd: config.cdkDir,\n    }\n  );\n\n  ux.action.start(chalk.yellow(\"Running lint check...\"));\n  await commands.lint();\n  ux.action.stop();\n\n  ux.action.start(chalk.yellow(\"Running tests...\"));\n  await commands.test();\n  ux.action.stop();\n\n  ux.action.start(chalk.yellow(\"Running initial synthesis...\"));\n  await commands.synth();\n  ux.action.stop();\n\n  console.log(chalk.green(\"Success! Here's a summary of the created files:\"));\n  const tree = await execute(\"tree\", [\"-I 'node_modules|cdk.out'\"], {\n    cwd: config.cdkDir,\n  });\n  console.log(tree);\n\n  const docsUrl = \"https://github.com/guardian/cdk/tree/main/docs\";\n  ux.url(chalk.green(`Please see the docs (${docsUrl}) for next steps.`), docsUrl);\n\n  return Promise.resolve(0);\n};\n"]}

package/lib/constructs/cloudwatch/alarm.d.ts

@@ -3,6 +3,7 @@ import type { AlarmProps } from "aws-cdk-lib/aws-cloudwatch";
 import type { AppIdentity, GuStack } from "../core";
 export interface GuAlarmProps extends AlarmProps, AppIdentity {
     snsTopicName: string;
+    okAction?: boolean;
 }
 export interface Http5xxAlarmProps extends Omit<GuAlarmProps, "snsTopicName" | "evaluationPeriods" | "metric" | "period" | "threshold" | "treatMissingData" | "app"> {
     tolerated5xxPercentage: number;

package/lib/constructs/cloudwatch/alarm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"alarm.d.ts","sourceRoot":"","sources":["../../../src/constructs/cloudwatch/alarm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAI7D,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEpD,MAAM,WAAW,YAAa,SAAQ,UAAU,EAAE,WAAW;IAC3D,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,iBACf,SAAQ,IAAI,CACV,YAAY,EACZ,cAAc,GAAG,mBAAmB,GAAG,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,kBAAkB,GAAG,KAAK,CACtG;IACD,sBAAsB,EAAE,MAAM,CAAC;IAC/B,wCAAwC,CAAC,EAAE,MAAM,CAAC;CACnD;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,OAAQ,SAAQ,KAAK;gBACpB,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY;CAU5D"}
+{"version":3,"file":"alarm.d.ts","sourceRoot":"","sources":["../../../src/constructs/cloudwatch/alarm.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAI7D,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEpD,MAAM,WAAW,YAAa,SAAQ,UAAU,EAAE,WAAW;IAC3D,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,iBACf,SAAQ,IAAI,CACV,YAAY,EACZ,cAAc,GAAG,mBAAmB,GAAG,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,kBAAkB,GAAG,KAAK,CACtG;IACD,sBAAsB,EAAE,MAAM,CAAC;IAC/B,wCAAwC,CAAC,EAAE,MAAM,CAAC;CACnD;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,OAAQ,SAAQ,KAAK;gBACpB,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY;CAa5D"}

package/lib/constructs/cloudwatch/alarm.js

@@ -23,11 +23,14 @@ const aws_sns_1 = require("aws-cdk-lib/aws-sns");
 class GuAlarm extends aws_cloudwatch_1.Alarm {
     constructor(scope, id, props) {
         const { region, account } = scope;
-        const { snsTopicName, actionsEnabled = true } = props;
+        const { snsTopicName, actionsEnabled = true, okAction } = props;
         super(scope, id, { ...props, actionsEnabled });
         const topicArn = `arn:aws:sns:${region}:${account}:${snsTopicName}`;
         const snsTopic = aws_sns_1.Topic.fromTopicArn(scope, `SnsTopicFor${id}`, topicArn);
         this.addAlarmAction(new aws_cloudwatch_actions_1.SnsAction(snsTopic));
+        if (okAction) {
+            this.addOkAction(new aws_cloudwatch_actions_1.SnsAction(snsTopic));
+        }
     }
 }
 exports.GuAlarm = GuAlarm;

package/lib/constructs/cloudwatch/alarm.js.map

@@ -1 +1 @@
-{"version":3,"file":"alarm.js","sourceRoot":"","sources":["../../../src/constructs/cloudwatch/alarm.ts"],"names":[],"mappings":";;;AAAA,+DAAmD;AAEnD,+EAA+D;AAC/D,iDAA4C;AAiB5C;;;;;;;;;;;;;;;GAeG;AACH,MAAa,OAAQ,SAAQ,sBAAK;IAChC,YAAY,KAAc,EAAE,EAAU,EAAE,KAAmB;QACzD,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;QAClC,MAAM,EAAE,YAAY,EAAE,cAAc,GAAG,IAAI,EAAE,GAAG,KAAK,CAAC;QAEtD,KAAK,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE,GAAG,KAAK,EAAE,cAAc,EAAE,CAAC,CAAC;QAE/C,MAAM,QAAQ,GAAW,eAAe,MAAM,IAAI,OAAO,IAAI,YAAY,EAAE,CAAC;QAC5E,MAAM,QAAQ,GAAW,eAAK,CAAC,YAAY,CAAC,KAAK,EAAE,cAAc,EAAE,EAAE,EAAE,QAAQ,CAAC,CAAC;QACjF,IAAI,CAAC,cAAc,CAAC,IAAI,kCAAS,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC/C,CAAC;CACF;AAXD,0BAWC","sourcesContent":["import { Alarm } from \"aws-cdk-lib/aws-cloudwatch\";\nimport type { AlarmProps } from \"aws-cdk-lib/aws-cloudwatch\";\nimport { SnsAction } from \"aws-cdk-lib/aws-cloudwatch-actions\";\nimport { Topic } from \"aws-cdk-lib/aws-sns\";\nimport type { ITopic } from \"aws-cdk-lib/aws-sns\";\nimport type { AppIdentity, GuStack } from \"../core\";\n\nexport interface GuAlarmProps extends AlarmProps, AppIdentity {\n  snsTopicName: string;\n}\n\nexport interface Http5xxAlarmProps\n  extends Omit<\n    GuAlarmProps,\n    \"snsTopicName\" | \"evaluationPeriods\" | \"metric\" | \"period\" | \"threshold\" | \"treatMissingData\" | \"app\"\n  > {\n  tolerated5xxPercentage: number;\n  numberOfMinutesAboveThresholdBeforeAlarm?: number;\n}\n\n/**\n * Creates a CloudWatch alarm which sends notifications to the specified SNS topic.\n *\n * Alarm actions are enabled by default.\n *\n * To enable the alarm only in PROD, use the value of `Stage`:\n * ```typescript\n * new GuAlarm(stack, \"alarm\", {\n *   // other required props\n *   actionsEnabled: this.stage === \"PROD\",\n * });\n * ```\n *\n * This library provides an implementation of some commonly used alarms, which require less boilerplate than this construct,\n * for example the [[`GuAlb5xxPercentageAlarm`]]. Prefer using these more specific implementations where possible.\n */\nexport class GuAlarm extends Alarm {\n  constructor(scope: GuStack, id: string, props: GuAlarmProps) {\n    const { region, account } = scope;\n    const { snsTopicName, actionsEnabled = true } = props;\n\n    super(scope, id, { ...props, actionsEnabled });\n\n    const topicArn: string = `arn:aws:sns:${region}:${account}:${snsTopicName}`;\n    const snsTopic: ITopic = Topic.fromTopicArn(scope, `SnsTopicFor${id}`, topicArn);\n    this.addAlarmAction(new SnsAction(snsTopic));\n  }\n}\n"]}
+{"version":3,"file":"alarm.js","sourceRoot":"","sources":["../../../src/constructs/cloudwatch/alarm.ts"],"names":[],"mappings":";;;AAAA,+DAAmD;AAEnD,+EAA+D;AAC/D,iDAA4C;AAkB5C;;;;;;;;;;;;;;;GAeG;AACH,MAAa,OAAQ,SAAQ,sBAAK;IAChC,YAAY,KAAc,EAAE,EAAU,EAAE,KAAmB;QACzD,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;QAClC,MAAM,EAAE,YAAY,EAAE,cAAc,GAAG,IAAI,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC;QAEhE,KAAK,CAAC,KAAK,EAAE,EAAE,EAAE,EAAE,GAAG,KAAK,EAAE,cAAc,EAAE,CAAC,CAAC;QAE/C,MAAM,QAAQ,GAAW,eAAe,MAAM,IAAI,OAAO,IAAI,YAAY,EAAE,CAAC;QAC5E,MAAM,QAAQ,GAAW,eAAK,CAAC,YAAY,CAAC,KAAK,EAAE,cAAc,EAAE,EAAE,EAAE,QAAQ,CAAC,CAAC;QACjF,IAAI,CAAC,cAAc,CAAC,IAAI,kCAAS,CAAC,QAAQ,CAAC,CAAC,CAAC;QAC7C,IAAI,QAAQ,EAAE;YACZ,IAAI,CAAC,WAAW,CAAC,IAAI,kCAAS,CAAC,QAAQ,CAAC,CAAC,CAAC;SAC3C;IACH,CAAC;CACF;AAdD,0BAcC","sourcesContent":["import { Alarm } from \"aws-cdk-lib/aws-cloudwatch\";\nimport type { AlarmProps } from \"aws-cdk-lib/aws-cloudwatch\";\nimport { SnsAction } from \"aws-cdk-lib/aws-cloudwatch-actions\";\nimport { Topic } from \"aws-cdk-lib/aws-sns\";\nimport type { ITopic } from \"aws-cdk-lib/aws-sns\";\nimport type { AppIdentity, GuStack } from \"../core\";\n\nexport interface GuAlarmProps extends AlarmProps, AppIdentity {\n  snsTopicName: string;\n  okAction?: boolean;\n}\n\nexport interface Http5xxAlarmProps\n  extends Omit<\n    GuAlarmProps,\n    \"snsTopicName\" | \"evaluationPeriods\" | \"metric\" | \"period\" | \"threshold\" | \"treatMissingData\" | \"app\"\n  > {\n  tolerated5xxPercentage: number;\n  numberOfMinutesAboveThresholdBeforeAlarm?: number;\n}\n\n/**\n * Creates a CloudWatch alarm which sends notifications to the specified SNS topic.\n *\n * Alarm actions are enabled by default.\n *\n * To enable the alarm only in PROD, use the value of `Stage`:\n * ```typescript\n * new GuAlarm(stack, \"alarm\", {\n *   // other required props\n *   actionsEnabled: this.stage === \"PROD\",\n * });\n * ```\n *\n * This library provides an implementation of some commonly used alarms, which require less boilerplate than this construct,\n * for example the [[`GuAlb5xxPercentageAlarm`]]. Prefer using these more specific implementations where possible.\n */\nexport class GuAlarm extends Alarm {\n  constructor(scope: GuStack, id: string, props: GuAlarmProps) {\n    const { region, account } = scope;\n    const { snsTopicName, actionsEnabled = true, okAction } = props;\n\n    super(scope, id, { ...props, actionsEnabled });\n\n    const topicArn: string = `arn:aws:sns:${region}:${account}:${snsTopicName}`;\n    const snsTopic: ITopic = Topic.fromTopicArn(scope, `SnsTopicFor${id}`, topicArn);\n    this.addAlarmAction(new SnsAction(snsTopic));\n    if (okAction) {\n      this.addOkAction(new SnsAction(snsTopic));\n    }\n  }\n}\n"]}

package/lib/patterns/ec2-app/base.d.ts

@@ -13,7 +13,19 @@ import { AppAccess } from "../../types";
 import type { GuAsgCapacity, GuDomainName } from "../../types";
 import type { AmigoProps } from "../../types/amigo";
 export interface AccessLoggingProps {
+    /**
+     * Enable (load balancer) access logs.
+     *
+     * Note, you will need to specify a region in your stack declaration to use
+     * this.
+     * See`https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-elasticloadbalancingv2.ApplicationLoadBalancer.html#logwbraccesswbrlogsbucket-prefix`
+     */
     enabled: boolean;
+    /**
+     * S3 prefix for the logs.
+     *
+     * @defaultValue no prefix
+     */
     prefix?: string;
 }
 /**
@@ -29,279 +41,136 @@ export interface AccessLoggingProps {
  * to Kinesis will be configured automatically via the [[`GuEc2App`]] pattern.
  */
 export interface ApplicationLoggingProps {
+    /**
+     * Enables forwarding of application logs to the Guardian ELK stack.
+     *
+     * Note, to work, you will need to also do the following non-CDK things:
+     *
+     * 1. Include the `cdk-base` Amigo role in your AMI.
+     * 2. Log to `journald`. We recommend doing this by logging to `stdout` and
+     *    using `systemd` to start your app
+     * 3. Confirm that your [[`systemdUnitName`]] is configured properly.
+     *
+     * Unless you have explicitly opted-out, appropriate IAM permissions for
+     * logging to Kinesis will be configured automatically via the [[`GuEc2App`]]
+     * pattern.
+     *
+     * @see https://github.com/guardian/amigo/tree/main/roles/cdk-base
+     */
     enabled: boolean;
     /**
-     * Defaults to app name. That is, if your app runs as `<app>.service`
-     * (e.g. `janus.service`), this will 'just work'.
+     * This needs to match the name of your SystemD unit.
+     *
+     * If your systemd unit is not `<app>.service` set this value.
      *
-     * If it runs with a non-standard name, you will need to override the default
-     * behavour. I.e. if your app is running as `some-different-name.service`, then
-     * this prop should be set to `some-different-name`.
+     * @defaultValue `<app>.service`
      */
     systemdUnitName?: string;
 }
+/**
+ * @privateRemarks we should rename this to AlarmsProps.
+ */
 export interface Alarms {
+    /**
+     * Name of the target (SNS Topic) for alarm notifications.
+     */
     snsTopicName: string;
+    /**
+     * Enable the 5xx alarm with settings.
+     */
     http5xxAlarm: false | Http5xxAlarmProps;
+    /**
+     * Enable the unhealthy instances alarm.
+     */
     unhealthyInstancesAlarm: boolean;
+    /**
+     * Internal flag - users of this library should ignore this setting.
+     */
     noMonitoring?: false;
 }
-/**
- * Configuration options for the [[`GuEc2App`]] pattern.
- *
- * To grant EC2 instances additional IAM permissions, use the `roleConfiguration` prop. For example,
- * to allow your app to write to DynamoDB:
- *
- * ```typescript
- * // other props
- * roleConfiguration: {
- *   additionalPolicies: [new GuDynamoDBWritePolicy(stack, "DynamoTable", { tableName: "my-dynamo-table" })],
- * }
- * ```
- *
- * To create alarms (recommended), use:
- * ```typescript
- * // other props
- * monitoringConfiguration: {
- *   snsTopicName: "alerts-topic-for-my-team",
- *   http5xxAlarm: {
- *     tolerated5xxPercentage: 1,
- *   },
- *   unhealthyInstancesAlarm: true,
- * }
- * ```
- *
- * To opt out of creating alarms, use:
- *```typescript
- * // other props
- * monitoringConfiguration: { noMonitoring: true }
- * ```
- *
- * To automatically ship application logs from `stdout` to ELK, use:
- *
- * ```typescript
- * {
- *   // other props
- *   applicationLogging: { enabled: true }
- * }
- * ```
- *
- * For more details on the requirements for application log shipping, see [[`ApplicationLoggingProps`]].
- *
- * To enable access logging for your load balancer, you can specify the prefix to write the logs to.
- * The S3 bucket used to hold these access logs must be specified in SSM at `/account/services/access-logging/bucket`
- * You must specify a region in your stack declaration if you are to use this prop, as specified here:
- * https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-elasticloadbalancingv2.ApplicationLoadBalancer.html#logwbraccesswbrlogsbucket-prefix
- * For example:
- * ```typescript
- * {
- *   // other props
- *   accessLogging: {
- *     enabled: true,
- *     prefix: "my-application-logs"
- *   }
- * }
- *
- * If you would like to enable access logging at the root of the S3 bucket (ie without a prefix), you can omit the prefix
- * For example:
- * ```typescript
- * {
- *   // other props
- *   accessLogging: {
- *     enabled: true,
- *   }
- * }
- * ```
- */
 export interface GuEc2AppProps extends AppIdentity {
+    /**
+     * User data for the autoscaling group.
+     */
     userData: GuUserDataProps | string;
+    /**
+     * Network access restrictions for your load balancer.
+     *
+     * Note, this merely provides defence in depth; you should, for example, limit
+     * access to the VPN and then treat that as sufficient. Instead, use Google
+     * Auth for human access, or a suitable machine auth mechanism.
+     */
     access: AppAccess;
+    /**
+     * The port your application runs on.
+     */
     applicationPort: number;
+    /**
+     * Configure IAM roles for autoscaling group EC2 instances.
+     */
     roleConfiguration?: GuInstanceRoleProps;
+    /**
+     * Enable and configure alarms.
+     */
     monitoringConfiguration: Alarms | NoMonitoring;
+    /**
+     * EC2 instance type. Note, ensure your code is built for the same
+     * architecture family (arm64 - 'Graviton' instances - or x64).
+     */
     instanceType: InstanceType;
+    /**
+     * Enable and configures application logs.
+     */
     applicationLogging?: ApplicationLoggingProps;
+    /**
+     * Enable and configures access logs.
+     */
     accessLogging?: AccessLoggingProps;
+    /**
+     * Add block devices (additional storage).
+     */
     blockDevices?: BlockDevice[];
+    /**
+     * Autoscaling group min and max sizes.
+     */
     scaling: GuAsgCapacity;
+    /**
+     * Specify certificate for the load balancer.
+     */
     certificateProps?: GuDomainName;
+    /**
+     * Disable imdsv2. Most of the time you should not set this.
+     *
+     * @see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html
+     */
     withoutImdsv2?: boolean;
+    /**
+     * Configure Amigo image recipe.
+     */
     imageRecipe?: string | AmigoProps;
+    /**
+     * Specify the VPC to use.
+     *
+     * @see https://github.com/guardian/aws-account-setup
+     */
     vpc?: IVpc;
+    /**
+     * Specify private subnets if using a non-default VPC or (generally
+     * discouraged) to limit to a subset of the available subnets.
+     */
     privateSubnets?: ISubnet[];
+    /**
+     * Specify private subnets if using a non-default VPC or (generally
+     * discouraged) to limit to a subset of the available subnets.
+     */
     publicSubnets?: ISubnet[];
 }
 /**
- * Pattern which creates the resources needed to run an application on EC2 instances.
- * For convenience, you may wish to use [[`GuPlayApp`]] or [[`GuNodeApp`]], which extend this class.
- *
- * This pattern will grant your EC2 instances a number of commonly needed IAM permissions. For more information on
- * this, see [[`GuInstanceRole`]]. To add additional permissions to your EC2 instances, see [[`GuEc2AppProps`]].
- *
- * This pattern will automatically create security groups/rules which allow for:
- * 1. Incoming traffic over HTTPS (from the whole internet or from the specified CIDR ranges, depending on the
- * [[`AppAccess`]] specified).
- * 2. Communication between the load balancer and the EC2 instances over HTTP, via the specified application port.
- * 3. Outbound traffic from your EC2 instances over HTTPS (to enable communication with third-party APIs).
- *
- * Example usage for a public facing app (open to the internet):
- * ```typescript
- * new GuEc2App(stack, {
- *   applicationPort: 1234,
- *   app: "app-name",
- *   access: { scope: AccessScope.PUBLIC },
- *   instanceType: InstanceType.of(InstanceClass.T4G, InstanceSize.MEDIUM),
- *   certificateProps:{
- *     domainName: "domain-name-for-your-application.example",
- *   },
- *   monitoringConfiguration: {
- *     snsTopicName: "alerts-topic-for-my-team",
- *     http5xxAlarm: {
- *       tolerated5xxPercentage: 1,
- *     },
- *     unhealthyInstancesAlarm: true,
- *   },
- *   userData: {
- *     distributable: {
- *       fileName: "app-name.deb",
- *       executionStatement: `dpkg -i /app-name/app-name.deb`,
- *     }
- *   },
- * });
- * ```
- *
- * Example usage for an app which is restricted to specific CIDR ranges:
- * ```typescript
- * new GuEc2App(stack, {
- *   applicationPort: 1234,
- *   app: "app-name",
- *   access: {
- *     scope: AccessScope.RESTRICTED,
- *     cidrRanges: [Peer.ipv4("192.168.1.1/32"), Peer.ipv4("8.8.8.8/32")],
- *   },
- *   instanceType: InstanceType.of(InstanceClass.T4G, InstanceSize.MEDIUM),
- *   certificateProps:{
- *     domainName: "domain-name-for-your-application.example",
- *   },
- *   monitoringConfiguration: {
- *     snsTopicName: "alerts-topic-for-my-team",
- *     http5xxAlarm: {
- *       tolerated5xxPercentage: 1,
- *     },
- *     unhealthyInstancesAlarm: true,
- *   }
- *   userData: {
- *     distributable: {
- *       fileName: "app-name.deb",
- *       executionStatement: `dpkg -i /app-name/app-name.deb`,
- *     }
- *   },
- * });
- * ```
- *
- * ### Varying values by stage
- *
- * There are times when you want a resource's configuration to be stage aware,
- * for example the number of instances in an ASG.
- *
- * To do this, we can use a simple ternary:
- * ```typescript
- * new GuEc2App(this, {
- *   // other required properties
- *   scaling: this.stage === "PROD" ? { minimumInstances: 6 } : { minimumInstances: 1 }
- * });
- * ```
- *
- * If multiple properties need to be stage aware, consider encoding this into the `props` of the calling class:
- *
- * ```typescript
- * export interface MyAppProps extends GuStackProps {
- *   domainName: string;
- *   scaling: GuAsgCapacity;
- *   monitoringConfiguration: Alarms | NoMonitoring;
- * }
- *
- * export class MyApp extends GuStack {
- *   private static app = "cdk-playground";
- *
- *   constructor(scope: App, id: string, props: MyAppProps) {
- *     const { stage, domainName, scaling, monitoringConfiguration } = props;
- *
- *     super(scope, id, props);
- *
- *     new GuPlayApp(this, {
- *       app: "my-app",
- *       instanceType: InstanceType.of(InstanceClass.T4G, InstanceSize.MICRO),
- *       access: { scope: AccessScope.PUBLIC },
- *       userData: {
- *         distributable: {
- *           fileName: `my-app.deb`,
- *           executionStatement: `dpkg -i /my-app/my-app.deb`,
- *         },
- *       },
- *       certificateProps: {
- *         domainName,
- *       },
- *       monitoringConfiguration,
- *       scaling,
- *     });
- *   }
- * }
- *
- * new MyApp(app, "MyApp-CODE", {
- *   stage: "CODE",
- *   domainName: "my-app.code.dev-gutools.co.uk",
- *   scaling: { minimumInstances: 1 },
- *   monitoringConfiguration: { noMonitoring: true },
- * });
- *
- * new MyApp(app, "MyApp-PROD", {
- *   stage: "PROD",
- *   domainName: "my-app.prod.gutools.co.uk",
- *   scaling: { minimumInstances: 6 },
- *   monitoringConfiguration: {
- *     // config to enable alarms in PROD
- *   },
- * });
- * ```
- *
- * If you _must_ support a non-standard VPC setup, it's possible to override the VPC and subnet selection into which
- * instances will be started. You need to set the three props below in order for this to work:
- *  vpc: this must be an IVpc instance indicating the VPC to deploy into (usually obtained from `Vpc.fromVpcAttributes`)
- *  privateSubnets: a list of ISubnet indicating the subnets for the autoscaling group to deploy instances into (usually
- *    obtained from `GuVpc.subnets`)
- *  publicSubnets: a list of ISubnet indicating the subnets for the loadbalancer to use, if the loadbalancer
- *    is intended for public access (usually obtained from `GuVpc.subnets`)
- *    On the other hand, if the access is private, then an "internal" loadbalancer is used in the `privateSubnets` list.
- * Please note that no checking is applied to the subnet lists to ensure that they correspond to the vpc given; as
- * an advanced feature it is assumed that the caller ensures this.  If the subnets are mismatched then the resulting
- * Cloudformation will fail to deploy.
- *
- * ### Customising the infrastructure generated by this pattern
- *
- * Although we allow users to customise many aspects of their infrastructure via [[`GuEc2AppProps`]], it's possible
- * that there are less common use-cases which are currently unsupported via the API. In these circumstances escape
- * hatches can be used to override specific resources in the stack.
- *
- * In order to do this:
+ * Pattern which creates the resources needed to run an application on EC2
+ * behind a load balancer. For convenience, you may wish to use [[`GuPlayApp`]]
+ * or [[`GuNodeApp`]], which extend this class.
  *
- * 1. Create desired resource using Guardian or AWS constructs, for example:
- * ```typescript
- * const sg = new GuSecurityGroup(
- *   // custom parameters
- * );
- * ```
- * 2. Access the CloudFormation version of the resource that you wish to customise, for example:
- * ```typescript
- * const pattern = new GuEc2App(
- *   // all parameters
- * )
- * const cfnLb = pattern.loadBalancer.node.defaultChild as CfnLoadBalancer;
- * ```
- * 3. Replace the resource generated by the pattern with your bespoke resource, for example:
- * ```typescript
- * cfnLb.securityGroups = [sg.securityGroupId];
- * ```
+ * See props for further details.
  */
 export declare class GuEc2App extends Construct {
     readonly vpc: IVpc;

package/lib/patterns/ec2-app/base.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../src/patterns/ec2-app/base.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../src/patterns/ec2-app/base.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAE/D,OAAO,KAAK,EAAE,YAAY,EAAS,OAAO,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAI9E,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,kBAAkB,EAAc,MAAM,8BAA8B,CAAC;AAC9E,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAEnF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAmD,MAAM,uBAAuB,CAAC;AAErG,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAEhE,OAAO,EACL,yBAAyB,EACzB,wBAAwB,EACxB,0BAA0B,EAC3B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,MAAM,WAAW,kBAAkB;IACjC;;;;;;OAMG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;;;;;;;;;;;OAeG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,MAAM;IACrB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB;;OAEG;IACH,YAAY,EAAE,KAAK,GAAG,iBAAiB,CAAC;IACxC;;OAEG;IACH,uBAAuB,EAAE,OAAO,CAAC;IACjC;;OAEG;IACH,YAAY,CAAC,EAAE,KAAK,CAAC;CACtB;AAED,MAAM,WAAW,aAAc,SAAQ,WAAW;IAChD;;OAEG;IACH,QAAQ,EAAE,eAAe,GAAG,MAAM,CAAC;IACnC;;;;;;OAMG;IACH,MAAM,EAAE,SAAS,CAAC;IAClB;;OAEG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB;;OAEG;IACH,iBAAiB,CAAC,EAAE,mBAAmB,CAAC;IACxC;;OAEG;IACH,uBAAuB,EAAE,MAAM,GAAG,YAAY,CAAC;IAC/C;;;OAGG;IACH,YAAY,EAAE,YAAY,CAAC;IAC3B;;OAEG;IACH,kBAAkB,CAAC,EAAE,uBAAuB,CAAC;IAC7C;;OAEG;IACH,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC;;OAEG;IACH,YAAY,CAAC,EAAE,WAAW,EAAE,CAAC;IAC7B;;OAEG;IACH,OAAO,EAAE,aAAa,CAAC;IACvB;;OAEG;IACH,gBAAgB,CAAC,EAAE,YAAY,CAAC;IAChC;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;IAClC;;;;OAIG;IACH,GAAG,CAAC,EAAE,IAAI,CAAC;IACX;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,EAAE,CAAC;IAE3B;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,EAAE,CAAC;CAC3B;AAUD;;;;;;GAMG;AACH,qBAAa,QAAS,SAAQ,SAAS;IASrC,SAAgB,GAAG,EAAE,IAAI,CAAC;IAC1B,SAAgB,WAAW,CAAC,EAAE,aAAa,CAAC;IAC5C,SAAgB,YAAY,EAAE,yBAAyB,CAAC;IACxD,SAAgB,gBAAgB,EAAE,kBAAkB,CAAC;IACrD,SAAgB,QAAQ,EAAE,0BAA0B,CAAC;IACrD,SAAgB,WAAW,EAAE,wBAAwB,CAAC;gBAE1C,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,aAAa;CAyKjD"}

package/lib/patterns/ec2-app/base.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GuEc2App = void 0;
+/* eslint "@guardian/tsdoc-required/tsdoc-required": 2 -- to begin rolling this out for public APIs. */
 const aws_cdk_lib_1 = require("aws-cdk-lib");
 const aws_autoscaling_1 = require("aws-cdk-lib/aws-autoscaling");
 const aws_ec2_1 = require("aws-cdk-lib/aws-ec2");
@@ -24,176 +25,11 @@ function restrictedCidrRanges(ranges) {
     }));
 }
 /**
- * Pattern which creates the resources needed to run an application on EC2 instances.
- * For convenience, you may wish to use [[`GuPlayApp`]] or [[`GuNodeApp`]], which extend this class.
+ * Pattern which creates the resources needed to run an application on EC2
+ * behind a load balancer. For convenience, you may wish to use [[`GuPlayApp`]]
+ * or [[`GuNodeApp`]], which extend this class.
  *
- * This pattern will grant your EC2 instances a number of commonly needed IAM permissions. For more information on
- * this, see [[`GuInstanceRole`]]. To add additional permissions to your EC2 instances, see [[`GuEc2AppProps`]].
- *
- * This pattern will automatically create security groups/rules which allow for:
- * 1. Incoming traffic over HTTPS (from the whole internet or from the specified CIDR ranges, depending on the
- * [[`AppAccess`]] specified).
- * 2. Communication between the load balancer and the EC2 instances over HTTP, via the specified application port.
- * 3. Outbound traffic from your EC2 instances over HTTPS (to enable communication with third-party APIs).
- *
- * Example usage for a public facing app (open to the internet):
- * ```typescript
- * new GuEc2App(stack, {
- *   applicationPort: 1234,
- *   app: "app-name",
- *   access: { scope: AccessScope.PUBLIC },
- *   instanceType: InstanceType.of(InstanceClass.T4G, InstanceSize.MEDIUM),
- *   certificateProps:{
- *     domainName: "domain-name-for-your-application.example",
- *   },
- *   monitoringConfiguration: {
- *     snsTopicName: "alerts-topic-for-my-team",
- *     http5xxAlarm: {
- *       tolerated5xxPercentage: 1,
- *     },
- *     unhealthyInstancesAlarm: true,
- *   },
- *   userData: {
- *     distributable: {
- *       fileName: "app-name.deb",
- *       executionStatement: `dpkg -i /app-name/app-name.deb`,
- *     }
- *   },
- * });
- * ```
- *
- * Example usage for an app which is restricted to specific CIDR ranges:
- * ```typescript
- * new GuEc2App(stack, {
- *   applicationPort: 1234,
- *   app: "app-name",
- *   access: {
- *     scope: AccessScope.RESTRICTED,
- *     cidrRanges: [Peer.ipv4("192.168.1.1/32"), Peer.ipv4("8.8.8.8/32")],
- *   },
- *   instanceType: InstanceType.of(InstanceClass.T4G, InstanceSize.MEDIUM),
- *   certificateProps:{
- *     domainName: "domain-name-for-your-application.example",
- *   },
- *   monitoringConfiguration: {
- *     snsTopicName: "alerts-topic-for-my-team",
- *     http5xxAlarm: {
- *       tolerated5xxPercentage: 1,
- *     },
- *     unhealthyInstancesAlarm: true,
- *   }
- *   userData: {
- *     distributable: {
- *       fileName: "app-name.deb",
- *       executionStatement: `dpkg -i /app-name/app-name.deb`,
- *     }
- *   },
- * });
- * ```
- *
- * ### Varying values by stage
- *
- * There are times when you want a resource's configuration to be stage aware,
- * for example the number of instances in an ASG.
- *
- * To do this, we can use a simple ternary:
- * ```typescript
- * new GuEc2App(this, {
- *   // other required properties
- *   scaling: this.stage === "PROD" ? { minimumInstances: 6 } : { minimumInstances: 1 }
- * });
- * ```
- *
- * If multiple properties need to be stage aware, consider encoding this into the `props` of the calling class:
- *
- * ```typescript
- * export interface MyAppProps extends GuStackProps {
- *   domainName: string;
- *   scaling: GuAsgCapacity;
- *   monitoringConfiguration: Alarms | NoMonitoring;
- * }
- *
- * export class MyApp extends GuStack {
- *   private static app = "cdk-playground";
- *
- *   constructor(scope: App, id: string, props: MyAppProps) {
- *     const { stage, domainName, scaling, monitoringConfiguration } = props;
- *
- *     super(scope, id, props);
- *
- *     new GuPlayApp(this, {
- *       app: "my-app",
- *       instanceType: InstanceType.of(InstanceClass.T4G, InstanceSize.MICRO),
- *       access: { scope: AccessScope.PUBLIC },
- *       userData: {
- *         distributable: {
- *           fileName: `my-app.deb`,
- *           executionStatement: `dpkg -i /my-app/my-app.deb`,
- *         },
- *       },
- *       certificateProps: {
- *         domainName,
- *       },
- *       monitoringConfiguration,
- *       scaling,
- *     });
- *   }
- * }
- *
- * new MyApp(app, "MyApp-CODE", {
- *   stage: "CODE",
- *   domainName: "my-app.code.dev-gutools.co.uk",
- *   scaling: { minimumInstances: 1 },
- *   monitoringConfiguration: { noMonitoring: true },
- * });
- *
- * new MyApp(app, "MyApp-PROD", {
- *   stage: "PROD",
- *   domainName: "my-app.prod.gutools.co.uk",
- *   scaling: { minimumInstances: 6 },
- *   monitoringConfiguration: {
- *     // config to enable alarms in PROD
- *   },
- * });
- * ```
- *
- * If you _must_ support a non-standard VPC setup, it's possible to override the VPC and subnet selection into which
- * instances will be started. You need to set the three props below in order for this to work:
- *  vpc: this must be an IVpc instance indicating the VPC to deploy into (usually obtained from `Vpc.fromVpcAttributes`)
- *  privateSubnets: a list of ISubnet indicating the subnets for the autoscaling group to deploy instances into (usually
- *    obtained from `GuVpc.subnets`)
- *  publicSubnets: a list of ISubnet indicating the subnets for the loadbalancer to use, if the loadbalancer
- *    is intended for public access (usually obtained from `GuVpc.subnets`)
- *    On the other hand, if the access is private, then an "internal" loadbalancer is used in the `privateSubnets` list.
- * Please note that no checking is applied to the subnet lists to ensure that they correspond to the vpc given; as
- * an advanced feature it is assumed that the caller ensures this.  If the subnets are mismatched then the resulting
- * Cloudformation will fail to deploy.
- *
- * ### Customising the infrastructure generated by this pattern
- *
- * Although we allow users to customise many aspects of their infrastructure via [[`GuEc2AppProps`]], it's possible
- * that there are less common use-cases which are currently unsupported via the API. In these circumstances escape
- * hatches can be used to override specific resources in the stack.
- *
- * In order to do this:
- *
- * 1. Create desired resource using Guardian or AWS constructs, for example:
- * ```typescript
- * const sg = new GuSecurityGroup(
- *   // custom parameters
- * );
- * ```
- * 2. Access the CloudFormation version of the resource that you wish to customise, for example:
- * ```typescript
- * const pattern = new GuEc2App(
- *   // all parameters
- * )
- * const cfnLb = pattern.loadBalancer.node.defaultChild as CfnLoadBalancer;
- * ```
- * 3. Replace the resource generated by the pattern with your bespoke resource, for example:
- * ```typescript
- * cfnLb.securityGroups = [sg.securityGroupId];
- * ```
+ * See props for further details.
  */
 class GuEc2App extends constructs_1.Construct {
     constructor(scope, props) {

package/lib/patterns/ec2-app/base.js.map

@@ -1 +1 @@
-{"version":3,"file":"base.js","sourceRoot":"","sources":["../../../src/patterns/ec2-app/base.ts"],"names":[],"mappings":"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","sourcesContent":["import { Duration, Tags } from \"aws-cdk-lib\";\nimport type { BlockDevice } from \"aws-cdk-lib/aws-autoscaling\";\nimport { HealthCheck } from \"aws-cdk-lib/aws-autoscaling\";\nimport type { InstanceType, IPeer, ISubnet, IVpc } from \"aws-cdk-lib/aws-ec2\";\nimport { Port } from \"aws-cdk-lib/aws-ec2\";\nimport { ApplicationProtocol } from \"aws-cdk-lib/aws-elasticloadbalancingv2\";\nimport { Bucket } from \"aws-cdk-lib/aws-s3\";\nimport { Construct } from \"constructs\";\nimport { AccessScope, MetadataKeys, NAMED_SSM_PARAMETER_PATHS } from \"../../constants\";\nimport { GuCertificate } from \"../../constructs/acm\";\nimport type { GuUserDataProps } from \"../../constructs/autoscaling\";\nimport { GuAutoScalingGroup, GuUserData } from \"../../constructs/autoscaling\";\nimport type { Http5xxAlarmProps, NoMonitoring } from \"../../constructs/cloudwatch\";\nimport { GuAlb5xxPercentageAlarm, GuUnhealthyInstancesAlarm } from \"../../constructs/cloudwatch\";\nimport type { GuStack } from \"../../constructs/core\";\nimport { AppIdentity, GuLoggingStreamNameParameter, GuStringParameter } from \"../../constructs/core\";\nimport { GuSecurityGroup, GuVpc, SubnetType } from \"../../constructs/ec2\";\nimport type { GuInstanceRoleProps } from \"../../constructs/iam\";\nimport { GuGetPrivateConfigPolicy, GuInstanceRole } from \"../../constructs/iam\";\nimport {\n  GuApplicationLoadBalancer,\n  GuApplicationTargetGroup,\n  GuHttpsApplicationListener,\n} from \"../../constructs/loadbalancing\";\nimport { AppAccess } from \"../../types\";\nimport type { GuAsgCapacity, GuDomainName } from \"../../types\";\nimport type { AmigoProps } from \"../../types/amigo\";\n\nexport interface AccessLoggingProps {\n  enabled: boolean;\n  prefix?: string;\n}\n\n/**\n * To ship your application logs to ELK automatically, you must:\n *\n * 1. Set the `enabled` flag to true\n * 2. Include the `cdk-base` Amigo role in your AMI\n * 3. Log to `journald`. We recommend doing this by logging to `stdout` and\n * using `systemd` to start your app\n * 4. Confirm that your [[`systemdUnitName`]] is configured properly.\n *\n * Unless you have explicitly opted-out, appropriate IAM permissions for logging\n * to Kinesis will be configured automatically via the [[`GuEc2App`]] pattern.\n */\nexport interface ApplicationLoggingProps {\n  enabled: boolean;\n  /**\n   * Defaults to app name. That is, if your app runs as `<app>.service`\n   * (e.g. `janus.service`), this will 'just work'.\n   *\n   * If it runs with a non-standard name, you will need to override the default\n   * behavour. I.e. if your app is running as `some-different-name.service`, then\n   * this prop should be set to `some-different-name`.\n   */\n  systemdUnitName?: string;\n}\n\nexport interface Alarms {\n  snsTopicName: string;\n  http5xxAlarm: false | Http5xxAlarmProps;\n  unhealthyInstancesAlarm: boolean;\n  noMonitoring?: false;\n}\n\n/**\n * Configuration options for the [[`GuEc2App`]] pattern.\n *\n * To grant EC2 instances additional IAM permissions, use the `roleConfiguration` prop. For example,\n * to allow your app to write to DynamoDB:\n *\n * ```typescript\n * // other props\n * roleConfiguration: {\n *   additionalPolicies: [new GuDynamoDBWritePolicy(stack, \"DynamoTable\", { tableName: \"my-dynamo-table\" })],\n * }\n * ```\n *\n * To create alarms (recommended), use:\n * ```typescript\n * // other props\n * monitoringConfiguration: {\n *   snsTopicName: \"alerts-topic-for-my-team\",\n *   http5xxAlarm: {\n *     tolerated5xxPercentage: 1,\n *   },\n *   unhealthyInstancesAlarm: true,\n * }\n * ```\n *\n * To opt out of creating alarms, use:\n *```typescript\n * // other props\n * monitoringConfiguration: { noMonitoring: true }\n * ```\n *\n * To automatically ship application logs from `stdout` to ELK, use:\n *\n * ```typescript\n * {\n *   // other props\n *   applicationLogging: { enabled: true }\n * }\n * ```\n *\n * For more details on the requirements for application log shipping, see [[`ApplicationLoggingProps`]].\n *\n * To enable access logging for your load balancer, you can specify the prefix to write the logs to.\n * The S3 bucket used to hold these access logs must be specified in SSM at `/account/services/access-logging/bucket`\n * You must specify a region in your stack declaration if you are to use this prop, as specified here:\n * https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-elasticloadbalancingv2.ApplicationLoadBalancer.html#logwbraccesswbrlogsbucket-prefix\n * For example:\n * ```typescript\n * {\n *   // other props\n *   accessLogging: {\n *     enabled: true,\n *     prefix: \"my-application-logs\"\n *   }\n * }\n *\n * If you would like to enable access logging at the root of the S3 bucket (ie without a prefix), you can omit the prefix\n * For example:\n * ```typescript\n * {\n *   // other props\n *   accessLogging: {\n *     enabled: true,\n *   }\n * }\n * ```\n */\nexport interface GuEc2AppProps extends AppIdentity {\n  userData: GuUserDataProps | string;\n  access: AppAccess;\n  applicationPort: number;\n  roleConfiguration?: GuInstanceRoleProps;\n  monitoringConfiguration: Alarms | NoMonitoring;\n  instanceType: InstanceType;\n  applicationLogging?: ApplicationLoggingProps;\n  accessLogging?: AccessLoggingProps;\n  blockDevices?: BlockDevice[];\n  scaling: GuAsgCapacity;\n  certificateProps?: GuDomainName;\n  withoutImdsv2?: boolean;\n  imageRecipe?: string | AmigoProps;\n  vpc?: IVpc;\n  privateSubnets?: ISubnet[];\n  publicSubnets?: ISubnet[];\n}\n\nfunction restrictedCidrRanges(ranges: IPeer[]) {\n  return ranges.map((range) => ({\n    range,\n    port: Port.tcp(443),\n    description: `Allow access on port 443 from ${range.uniqueId}`,\n  }));\n}\n\n/**\n * Pattern which creates the resources needed to run an application on EC2 instances.\n * For convenience, you may wish to use [[`GuPlayApp`]] or [[`GuNodeApp`]], which extend this class.\n *\n * This pattern will grant your EC2 instances a number of commonly needed IAM permissions. For more information on\n * this, see [[`GuInstanceRole`]]. To add additional permissions to your EC2 instances, see [[`GuEc2AppProps`]].\n *\n * This pattern will automatically create security groups/rules which allow for:\n * 1. Incoming traffic over HTTPS (from the whole internet or from the specified CIDR ranges, depending on the\n * [[`AppAccess`]] specified).\n * 2. Communication between the load balancer and the EC2 instances over HTTP, via the specified application port.\n * 3. Outbound traffic from your EC2 instances over HTTPS (to enable communication with third-party APIs).\n *\n * Example usage for a public facing app (open to the internet):\n * ```typescript\n * new GuEc2App(stack, {\n *   applicationPort: 1234,\n *   app: \"app-name\",\n *   access: { scope: AccessScope.PUBLIC },\n *   instanceType: InstanceType.of(InstanceClass.T4G, InstanceSize.MEDIUM),\n *   certificateProps:{\n *     domainName: \"domain-name-for-your-application.example\",\n *   },\n *   monitoringConfiguration: {\n *     snsTopicName: \"alerts-topic-for-my-team\",\n *     http5xxAlarm: {\n *       tolerated5xxPercentage: 1,\n *     },\n *     unhealthyInstancesAlarm: true,\n *   },\n *   userData: {\n *     distributable: {\n *       fileName: \"app-name.deb\",\n *       executionStatement: `dpkg -i /app-name/app-name.deb`,\n *     }\n *   },\n * });\n * ```\n *\n * Example usage for an app which is restricted to specific CIDR ranges:\n * ```typescript\n * new GuEc2App(stack, {\n *   applicationPort: 1234,\n *   app: \"app-name\",\n *   access: {\n *     scope: AccessScope.RESTRICTED,\n *     cidrRanges: [Peer.ipv4(\"192.168.1.1/32\"), Peer.ipv4(\"8.8.8.8/32\")],\n *   },\n *   instanceType: InstanceType.of(InstanceClass.T4G, InstanceSize.MEDIUM),\n *   certificateProps:{\n *     domainName: \"domain-name-for-your-application.example\",\n *   },\n *   monitoringConfiguration: {\n *     snsTopicName: \"alerts-topic-for-my-team\",\n *     http5xxAlarm: {\n *       tolerated5xxPercentage: 1,\n *     },\n *     unhealthyInstancesAlarm: true,\n *   }\n *   userData: {\n *     distributable: {\n *       fileName: \"app-name.deb\",\n *       executionStatement: `dpkg -i /app-name/app-name.deb`,\n *     }\n *   },\n * });\n * ```\n *\n * ### Varying values by stage\n *\n * There are times when you want a resource's configuration to be stage aware,\n * for example the number of instances in an ASG.\n *\n * To do this, we can use a simple ternary:\n * ```typescript\n * new GuEc2App(this, {\n *   // other required properties\n *   scaling: this.stage === \"PROD\" ? { minimumInstances: 6 } : { minimumInstances: 1 }\n * });\n * ```\n *\n * If multiple properties need to be stage aware, consider encoding this into the `props` of the calling class:\n *\n * ```typescript\n * export interface MyAppProps extends GuStackProps {\n *   domainName: string;\n *   scaling: GuAsgCapacity;\n *   monitoringConfiguration: Alarms | NoMonitoring;\n * }\n *\n * export class MyApp extends GuStack {\n *   private static app = \"cdk-playground\";\n *\n *   constructor(scope: App, id: string, props: MyAppProps) {\n *     const { stage, domainName, scaling, monitoringConfiguration } = props;\n *\n *     super(scope, id, props);\n *\n *     new GuPlayApp(this, {\n *       app: \"my-app\",\n *       instanceType: InstanceType.of(InstanceClass.T4G, InstanceSize.MICRO),\n *       access: { scope: AccessScope.PUBLIC },\n *       userData: {\n *         distributable: {\n *           fileName: `my-app.deb`,\n *           executionStatement: `dpkg -i /my-app/my-app.deb`,\n *         },\n *       },\n *       certificateProps: {\n *         domainName,\n *       },\n *       monitoringConfiguration,\n *       scaling,\n *     });\n *   }\n * }\n *\n * new MyApp(app, \"MyApp-CODE\", {\n *   stage: \"CODE\",\n *   domainName: \"my-app.code.dev-gutools.co.uk\",\n *   scaling: { minimumInstances: 1 },\n *   monitoringConfiguration: { noMonitoring: true },\n * });\n *\n * new MyApp(app, \"MyApp-PROD\", {\n *   stage: \"PROD\",\n *   domainName: \"my-app.prod.gutools.co.uk\",\n *   scaling: { minimumInstances: 6 },\n *   monitoringConfiguration: {\n *     // config to enable alarms in PROD\n *   },\n * });\n * ```\n *\n * If you _must_ support a non-standard VPC setup, it's possible to override the VPC and subnet selection into which\n * instances will be started. You need to set the three props below in order for this to work:\n *  vpc: this must be an IVpc instance indicating the VPC to deploy into (usually obtained from `Vpc.fromVpcAttributes`)\n *  privateSubnets: a list of ISubnet indicating the subnets for the autoscaling group to deploy instances into (usually\n *    obtained from `GuVpc.subnets`)\n *  publicSubnets: a list of ISubnet indicating the subnets for the loadbalancer to use, if the loadbalancer\n *    is intended for public access (usually obtained from `GuVpc.subnets`)\n *    On the other hand, if the access is private, then an \"internal\" loadbalancer is used in the `privateSubnets` list.\n * Please note that no checking is applied to the subnet lists to ensure that they correspond to the vpc given; as\n * an advanced feature it is assumed that the caller ensures this.  If the subnets are mismatched then the resulting\n * Cloudformation will fail to deploy.\n *\n * ### Customising the infrastructure generated by this pattern\n *\n * Although we allow users to customise many aspects of their infrastructure via [[`GuEc2AppProps`]], it's possible\n * that there are less common use-cases which are currently unsupported via the API. In these circumstances escape\n * hatches can be used to override specific resources in the stack.\n *\n * In order to do this:\n *\n * 1. Create desired resource using Guardian or AWS constructs, for example:\n * ```typescript\n * const sg = new GuSecurityGroup(\n *   // custom parameters\n * );\n * ```\n * 2. Access the CloudFormation version of the resource that you wish to customise, for example:\n * ```typescript\n * const pattern = new GuEc2App(\n *   // all parameters\n * )\n * const cfnLb = pattern.loadBalancer.node.defaultChild as CfnLoadBalancer;\n * ```\n * 3. Replace the resource generated by the pattern with your bespoke resource, for example:\n * ```typescript\n * cfnLb.securityGroups = [sg.securityGroupId];\n * ```\n */\nexport class GuEc2App extends Construct {\n  /*\n   * These are public for now, as this allows users to\n   * modify these constructs as desired to fit their\n   * specific needs.\n   * In the future, we might build functionality to better enable users\n   * to access in-pattern constructs, but this would allow teams to be unblocked\n   * in the short term.\n   * */\n  public readonly vpc: IVpc;\n  public readonly certificate?: GuCertificate;\n  public readonly loadBalancer: GuApplicationLoadBalancer;\n  public readonly autoScalingGroup: GuAutoScalingGroup;\n  public readonly listener: GuHttpsApplicationListener;\n  public readonly targetGroup: GuApplicationTargetGroup;\n\n  constructor(scope: GuStack, props: GuEc2AppProps) {\n    const {\n      access,\n      accessLogging = { enabled: false },\n      app,\n      // We should update this default once a significant number of apps have migrated to devx-logs\n      applicationLogging = { enabled: false },\n      applicationPort,\n      blockDevices,\n      certificateProps,\n      instanceType,\n      monitoringConfiguration,\n      roleConfiguration = { withoutLogShipping: false, additionalPolicies: [] },\n      scaling: { minimumInstances, maximumInstances = minimumInstances * 2 },\n      userData,\n      withoutImdsv2,\n      imageRecipe,\n      vpc = GuVpc.fromIdParameter(scope, AppIdentity.suffixText({ app }, \"VPC\")),\n      privateSubnets = GuVpc.subnetsFromParameter(scope, { type: SubnetType.PRIVATE, app }),\n      publicSubnets = GuVpc.subnetsFromParameter(scope, { type: SubnetType.PUBLIC, app }),\n    } = props;\n\n    super(scope, app); // The assumption is `app` is unique\n\n    // We should really prevent users from doing this via the type system,\n    // but that requires a breaking change to the API\n    if (applicationLogging.enabled && roleConfiguration.withoutLogShipping) {\n      throw new Error(\n        \"Application logging has been enabled (via the `applicationLogging` prop) but your `roleConfiguration` sets \" +\n          \"`withoutLogShipping` to true. Please turn off application logging or remove `withoutLogShipping`\"\n      );\n    }\n\n    AppAccess.validate(access);\n\n    const certificate =\n      typeof certificateProps !== \"undefined\"\n        ? new GuCertificate(scope, {\n            app,\n            domainName: certificateProps.domainName,\n            hostedZoneId: certificateProps.hostedZoneId,\n          })\n        : undefined;\n\n    const maybePrivateConfigPolicy =\n      typeof userData !== \"string\" && userData.configuration\n        ? [new GuGetPrivateConfigPolicy(scope, \"GetPrivateConfigFromS3Policy\", userData.configuration)]\n        : [];\n\n    const mergedRoleConfiguration: GuInstanceRoleProps = {\n      withoutLogShipping: roleConfiguration.withoutLogShipping,\n      additionalPolicies: maybePrivateConfigPolicy.concat(roleConfiguration.additionalPolicies ?? []),\n    };\n\n    const autoScalingGroup = new GuAutoScalingGroup(scope, \"AutoScalingGroup\", {\n      app,\n      vpc,\n      instanceType,\n      minimumInstances,\n      maximumInstances,\n      withoutImdsv2,\n      role: new GuInstanceRole(scope, { app, ...mergedRoleConfiguration }),\n      healthCheck: HealthCheck.elb({ grace: Duration.minutes(2) }), // should this be defaulted at pattern or construct level?\n      userData: typeof userData !== \"string\" ? new GuUserData(scope, { app, ...userData }).userData : userData,\n      vpcSubnets: { subnets: privateSubnets },\n      ...(blockDevices && { blockDevices }),\n      imageRecipe,\n    });\n\n    // This allows automatic shipping of instance Cloud Init logs when using the\n    // `cdk-base` Amigo role on your AMI.\n    Tags.of(autoScalingGroup).add(\n      MetadataKeys.LOG_KINESIS_STREAM_NAME,\n      GuLoggingStreamNameParameter.getInstance(scope).valueAsString\n    );\n\n    if (applicationLogging.enabled) {\n      // This allows automatic shipping of application logs when using the\n      // `cdk-base` Amigo role on your AMI.\n      Tags.of(autoScalingGroup).add(\n        MetadataKeys.SYSTEMD_UNIT,\n        applicationLogging.systemdUnitName ? `${applicationLogging.systemdUnitName}.service` : `${app}.service`\n      );\n    }\n\n    const loadBalancer = new GuApplicationLoadBalancer(scope, \"LoadBalancer\", {\n      app,\n      vpc,\n      // Setting internetFacing to true does not necessarily allow public access to the load balancer itself. That is handled by the listener's `open` prop.\n      internetFacing: access.scope !== AccessScope.INTERNAL,\n      vpcSubnets: {\n        subnets: access.scope === AccessScope.INTERNAL ? privateSubnets : publicSubnets,\n      },\n    });\n\n    if (accessLogging.enabled) {\n      const accessLoggingBucket = new GuStringParameter(scope, \"AccessLoggingBucket\", {\n        description: NAMED_SSM_PARAMETER_PATHS.AccessLoggingBucket.description,\n        default: NAMED_SSM_PARAMETER_PATHS.AccessLoggingBucket.path,\n        fromSSM: true,\n      });\n\n      loadBalancer.logAccessLogs(\n        Bucket.fromBucketName(\n          scope,\n          AppIdentity.suffixText(props, \"AccessLoggingBucket\"),\n          accessLoggingBucket.valueAsString\n        ),\n        accessLogging.prefix\n      );\n    }\n\n    const targetGroup = new GuApplicationTargetGroup(scope, \"TargetGroup\", {\n      app,\n      vpc,\n      protocol: ApplicationProtocol.HTTP,\n      targets: [autoScalingGroup],\n      port: applicationPort,\n    });\n\n    const listener = new GuHttpsApplicationListener(scope, \"Listener\", {\n      app,\n      loadBalancer,\n      certificate,\n      targetGroup,\n      // When open=true, AWS will create a security group which allows all inbound traffic over HTTPS\n      open: access.scope === AccessScope.PUBLIC && typeof certificate !== \"undefined\",\n    });\n\n    // Since AWS won't create a security group automatically when open=false, we need to add our own\n    if (access.scope !== AccessScope.PUBLIC) {\n      loadBalancer.addSecurityGroup(\n        new GuSecurityGroup(scope, `${access.scope}IngressSecurityGroup`, {\n          app,\n          vpc,\n          description: \"Allow restricted ingress from CIDR ranges\",\n          allowAllOutbound: false,\n          ingresses: restrictedCidrRanges(access.cidrRanges),\n        })\n      );\n    }\n\n    if (!monitoringConfiguration.noMonitoring) {\n      const { http5xxAlarm, snsTopicName, unhealthyInstancesAlarm } = monitoringConfiguration;\n\n      if (http5xxAlarm) {\n        new GuAlb5xxPercentageAlarm(scope, {\n          app,\n          loadBalancer,\n          snsTopicName,\n          ...http5xxAlarm,\n        });\n      }\n      if (unhealthyInstancesAlarm) {\n        new GuUnhealthyInstancesAlarm(scope, {\n          app,\n          targetGroup,\n          snsTopicName,\n        });\n      }\n    }\n\n    this.vpc = vpc;\n    this.certificate = certificate;\n    this.loadBalancer = loadBalancer;\n    this.autoScalingGroup = autoScalingGroup;\n    this.listener = listener;\n    this.targetGroup = targetGroup;\n  }\n}\n"]}
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../../src/patterns/ec2-app/base.ts"],"names":[],"mappings":";;;AAAA,uGAAuG;AACvG,6CAA6C;AAE7C,iEAA0D;AAE1D,iDAA2C;AAC3C,uFAA6E;AAC7E,+CAA4C;AAC5C,2CAAuC;AACvC,+CAAuF;AACvF,8CAAqD;AAErD,8DAA8E;AAE9E,4DAAiG;AAEjG,gDAAqG;AACrG,8CAA0E;AAE1E,8CAAgF;AAChF,kEAIwC;AACxC,uCAAwC;AAkKxC,SAAS,oBAAoB,CAAC,MAAe;IAC3C,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAC5B,KAAK;QACL,IAAI,EAAE,cAAI,CAAC,GAAG,CAAC,GAAG,CAAC;QACnB,WAAW,EAAE,iCAAiC,KAAK,CAAC,QAAQ,EAAE;KAC/D,CAAC,CAAC,CAAC;AACN,CAAC;AAED;;;;;;GAMG;AACH,MAAa,QAAS,SAAQ,sBAAS;IAgBrC,YAAY,KAAc,EAAE,KAAoB;QAC9C,MAAM,EACJ,MAAM,EACN,aAAa,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,EAClC,GAAG;QACH,6FAA6F;QAC7F,kBAAkB,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,EACvC,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,uBAAuB,EACvB,iBAAiB,GAAG,EAAE,kBAAkB,EAAE,KAAK,EAAE,kBAAkB,EAAE,EAAE,EAAE,EACzE,OAAO,EAAE,EAAE,gBAAgB,EAAE,gBAAgB,GAAG,gBAAgB,GAAG,CAAC,EAAE,EACtE,QAAQ,EACR,aAAa,EACb,WAAW,EACX,GAAG,GAAG,WAAK,CAAC,eAAe,CAAC,KAAK,EAAE,kBAAW,CAAC,UAAU,CAAC,EAAE,GAAG,EAAE,EAAE,KAAK,CAAC,CAAC,EAC1E,cAAc,GAAG,WAAK,CAAC,oBAAoB,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,gBAAU,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,EACrF,aAAa,GAAG,WAAK,CAAC,oBAAoB,CAAC,KAAK,EAAE,EAAE,IAAI,EAAE,gBAAU,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,GACpF,GAAG,KAAK,CAAC;QAEV,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,oCAAoC;QAEvD,sEAAsE;QACtE,iDAAiD;QACjD,IAAI,kBAAkB,CAAC,OAAO,IAAI,iBAAiB,CAAC,kBAAkB,EAAE;YACtE,MAAM,IAAI,KAAK,CACb,6GAA6G;gBAC3G,kGAAkG,CACrG,CAAC;SACH;QAED,iBAAS,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAE3B,MAAM,WAAW,GACf,OAAO,gBAAgB,KAAK,WAAW;YACrC,CAAC,CAAC,IAAI,mBAAa,CAAC,KAAK,EAAE;gBACvB,GAAG;gBACH,UAAU,EAAE,gBAAgB,CAAC,UAAU;gBACvC,YAAY,EAAE,gBAAgB,CAAC,YAAY;aAC5C,CAAC;YACJ,CAAC,CAAC,SAAS,CAAC;QAEhB,MAAM,wBAAwB,GAC5B,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,aAAa;YACpD,CAAC,CAAC,CAAC,IAAI,8BAAwB,CAAC,KAAK,EAAE,8BAA8B,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAC;YAC/F,CAAC,CAAC,EAAE,CAAC;QAET,MAAM,uBAAuB,GAAwB;YACnD,kBAAkB,EAAE,iBAAiB,CAAC,kBAAkB;YACxD,kBAAkB,EAAE,wBAAwB,CAAC,MAAM,CAAC,iBAAiB,CAAC,kBAAkB,IAAI,EAAE,CAAC;SAChG,CAAC;QAEF,MAAM,gBAAgB,GAAG,IAAI,gCAAkB,CAAC,KAAK,EAAE,kBAAkB,EAAE;YACzE,GAAG;YACH,GAAG;YACH,YAAY;YACZ,gBAAgB;YAChB,gBAAgB;YAChB,aAAa;YACb,IAAI,EAAE,IAAI,oBAAc,CAAC,KAAK,EAAE,EAAE,GAAG,EAAE,GAAG,uBAAuB,EAAE,CAAC;YACpE,WAAW,EAAE,6BAAW,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,sBAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5D,QAAQ,EAAE,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,wBAAU,CAAC,KAAK,EAAE,EAAE,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ;YACxG,UAAU,EAAE,EAAE,OAAO,EAAE,cAAc,EAAE;YACvC,GAAG,CAAC,YAAY,IAAI,EAAE,YAAY,EAAE,CAAC;YACrC,WAAW;SACZ,CAAC,CAAC;QAEH,4EAA4E;QAC5E,qCAAqC;QACrC,kBAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,CAAC,GAAG,CAC3B,wBAAY,CAAC,uBAAuB,EACpC,mCAA4B,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,aAAa,CAC9D,CAAC;QAEF,IAAI,kBAAkB,CAAC,OAAO,EAAE;YAC9B,oEAAoE;YACpE,qCAAqC;YACrC,kBAAI,CAAC,EAAE,CAAC,gBAAgB,CAAC,CAAC,GAAG,CAC3B,wBAAY,CAAC,YAAY,EACzB,kBAAkB,CAAC,eAAe,CAAC,CAAC,CAAC,GAAG,kBAAkB,CAAC,eAAe,UAAU,CAAC,CAAC,CAAC,GAAG,GAAG,UAAU,CACxG,CAAC;SACH;QAED,MAAM,YAAY,GAAG,IAAI,yCAAyB,CAAC,KAAK,EAAE,cAAc,EAAE;YACxE,GAAG;YACH,GAAG;YACH,sJAAsJ;YACtJ,cAAc,EAAE,MAAM,CAAC,KAAK,KAAK,uBAAW,CAAC,QAAQ;YACrD,UAAU,EAAE;gBACV,OAAO,EAAE,MAAM,CAAC,KAAK,KAAK,uBAAW,CAAC,QAAQ,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,aAAa;aAChF;SACF,CAAC,CAAC;QAEH,IAAI,aAAa,CAAC,OAAO,EAAE;YACzB,MAAM,mBAAmB,GAAG,IAAI,wBAAiB,CAAC,KAAK,EAAE,qBAAqB,EAAE;gBAC9E,WAAW,EAAE,qCAAyB,CAAC,mBAAmB,CAAC,WAAW;gBACtE,OAAO,EAAE,qCAAyB,CAAC,mBAAmB,CAAC,IAAI;gBAC3D,OAAO,EAAE,IAAI;aACd,CAAC,CAAC;YAEH,YAAY,CAAC,aAAa,CACxB,eAAM,CAAC,cAAc,CACnB,KAAK,EACL,kBAAW,CAAC,UAAU,CAAC,KAAK,EAAE,qBAAqB,CAAC,EACpD,mBAAmB,CAAC,aAAa,CAClC,EACD,aAAa,CAAC,MAAM,CACrB,CAAC;SACH;QAED,MAAM,WAAW,GAAG,IAAI,wCAAwB,CAAC,KAAK,EAAE,aAAa,EAAE;YACrE,GAAG;YACH,GAAG;YACH,QAAQ,EAAE,gDAAmB,CAAC,IAAI;YAClC,OAAO,EAAE,CAAC,gBAAgB,CAAC;YAC3B,IAAI,EAAE,eAAe;SACtB,CAAC,CAAC;QAEH,MAAM,QAAQ,GAAG,IAAI,0CAA0B,CAAC,KAAK,EAAE,UAAU,EAAE;YACjE,GAAG;YACH,YAAY;YACZ,WAAW;YACX,WAAW;YACX,+FAA+F;YAC/F,IAAI,EAAE,MAAM,CAAC,KAAK,KAAK,uBAAW,CAAC,MAAM,IAAI,OAAO,WAAW,KAAK,WAAW;SAChF,CAAC,CAAC;QAEH,gGAAgG;QAChG,IAAI,MAAM,CAAC,KAAK,KAAK,uBAAW,CAAC,MAAM,EAAE;YACvC,YAAY,CAAC,gBAAgB,CAC3B,IAAI,qBAAe,CAAC,KAAK,EAAE,GAAG,MAAM,CAAC,KAAK,sBAAsB,EAAE;gBAChE,GAAG;gBACH,GAAG;gBACH,WAAW,EAAE,2CAA2C;gBACxD,gBAAgB,EAAE,KAAK;gBACvB,SAAS,EAAE,oBAAoB,CAAC,MAAM,CAAC,UAAU,CAAC;aACnD,CAAC,CACH,CAAC;SACH;QAED,IAAI,CAAC,uBAAuB,CAAC,YAAY,EAAE;YACzC,MAAM,EAAE,YAAY,EAAE,YAAY,EAAE,uBAAuB,EAAE,GAAG,uBAAuB,CAAC;YAExF,IAAI,YAAY,EAAE;gBAChB,IAAI,oCAAuB,CAAC,KAAK,EAAE;oBACjC,GAAG;oBACH,YAAY;oBACZ,YAAY;oBACZ,GAAG,YAAY;iBAChB,CAAC,CAAC;aACJ;YACD,IAAI,uBAAuB,EAAE;gBAC3B,IAAI,sCAAyB,CAAC,KAAK,EAAE;oBACnC,GAAG;oBACH,WAAW;oBACX,YAAY;iBACb,CAAC,CAAC;aACJ;SACF;QAED,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC/B,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjC,IAAI,CAAC,gBAAgB,GAAG,gBAAgB,CAAC;QACzC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACzB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;CACF;AAzLD,4BAyLC","sourcesContent":["/* eslint \"@guardian/tsdoc-required/tsdoc-required\": 2 -- to begin rolling this out for public APIs. */\nimport { Duration, Tags } from \"aws-cdk-lib\";\nimport type { BlockDevice } from \"aws-cdk-lib/aws-autoscaling\";\nimport { HealthCheck } from \"aws-cdk-lib/aws-autoscaling\";\nimport type { InstanceType, IPeer, ISubnet, IVpc } from \"aws-cdk-lib/aws-ec2\";\nimport { Port } from \"aws-cdk-lib/aws-ec2\";\nimport { ApplicationProtocol } from \"aws-cdk-lib/aws-elasticloadbalancingv2\";\nimport { Bucket } from \"aws-cdk-lib/aws-s3\";\nimport { Construct } from \"constructs\";\nimport { AccessScope, MetadataKeys, NAMED_SSM_PARAMETER_PATHS } from \"../../constants\";\nimport { GuCertificate } from \"../../constructs/acm\";\nimport type { GuUserDataProps } from \"../../constructs/autoscaling\";\nimport { GuAutoScalingGroup, GuUserData } from \"../../constructs/autoscaling\";\nimport type { Http5xxAlarmProps, NoMonitoring } from \"../../constructs/cloudwatch\";\nimport { GuAlb5xxPercentageAlarm, GuUnhealthyInstancesAlarm } from \"../../constructs/cloudwatch\";\nimport type { GuStack } from \"../../constructs/core\";\nimport { AppIdentity, GuLoggingStreamNameParameter, GuStringParameter } from \"../../constructs/core\";\nimport { GuSecurityGroup, GuVpc, SubnetType } from \"../../constructs/ec2\";\nimport type { GuInstanceRoleProps } from \"../../constructs/iam\";\nimport { GuGetPrivateConfigPolicy, GuInstanceRole } from \"../../constructs/iam\";\nimport {\n  GuApplicationLoadBalancer,\n  GuApplicationTargetGroup,\n  GuHttpsApplicationListener,\n} from \"../../constructs/loadbalancing\";\nimport { AppAccess } from \"../../types\";\nimport type { GuAsgCapacity, GuDomainName } from \"../../types\";\nimport type { AmigoProps } from \"../../types/amigo\";\n\nexport interface AccessLoggingProps {\n  /**\n   * Enable (load balancer) access logs.\n   *\n   * Note, you will need to specify a region in your stack declaration to use\n   * this.\n   * See`https://docs.aws.amazon.com/cdk/api/latest/docs/@aws-cdk_aws-elasticloadbalancingv2.ApplicationLoadBalancer.html#logwbraccesswbrlogsbucket-prefix`\n   */\n  enabled: boolean;\n  /**\n   * S3 prefix for the logs.\n   *\n   * @defaultValue no prefix\n   */\n  prefix?: string;\n}\n\n/**\n * To ship your application logs to ELK automatically, you must:\n *\n * 1. Set the `enabled` flag to true\n * 2. Include the `cdk-base` Amigo role in your AMI\n * 3. Log to `journald`. We recommend doing this by logging to `stdout` and\n * using `systemd` to start your app\n * 4. Confirm that your [[`systemdUnitName`]] is configured properly.\n *\n * Unless you have explicitly opted-out, appropriate IAM permissions for logging\n * to Kinesis will be configured automatically via the [[`GuEc2App`]] pattern.\n */\nexport interface ApplicationLoggingProps {\n  /**\n   * Enables forwarding of application logs to the Guardian ELK stack.\n   *\n   * Note, to work, you will need to also do the following non-CDK things:\n   *\n   * 1. Include the `cdk-base` Amigo role in your AMI.\n   * 2. Log to `journald`. We recommend doing this by logging to `stdout` and\n   *    using `systemd` to start your app\n   * 3. Confirm that your [[`systemdUnitName`]] is configured properly.\n   *\n   * Unless you have explicitly opted-out, appropriate IAM permissions for\n   * logging to Kinesis will be configured automatically via the [[`GuEc2App`]]\n   * pattern.\n   *\n   * @see https://github.com/guardian/amigo/tree/main/roles/cdk-base\n   */\n  enabled: boolean;\n  /**\n   * This needs to match the name of your SystemD unit.\n   *\n   * If your systemd unit is not `<app>.service` set this value.\n   *\n   * @defaultValue `<app>.service`\n   */\n  systemdUnitName?: string;\n}\n\n/**\n * @privateRemarks we should rename this to AlarmsProps.\n */\nexport interface Alarms {\n  /**\n   * Name of the target (SNS Topic) for alarm notifications.\n   */\n  snsTopicName: string;\n  /**\n   * Enable the 5xx alarm with settings.\n   */\n  http5xxAlarm: false | Http5xxAlarmProps;\n  /**\n   * Enable the unhealthy instances alarm.\n   */\n  unhealthyInstancesAlarm: boolean;\n  /**\n   * Internal flag - users of this library should ignore this setting.\n   */\n  noMonitoring?: false;\n}\n\nexport interface GuEc2AppProps extends AppIdentity {\n  /**\n   * User data for the autoscaling group.\n   */\n  userData: GuUserDataProps | string;\n  /**\n   * Network access restrictions for your load balancer.\n   *\n   * Note, this merely provides defence in depth; you should, for example, limit\n   * access to the VPN and then treat that as sufficient. Instead, use Google\n   * Auth for human access, or a suitable machine auth mechanism.\n   */\n  access: AppAccess;\n  /**\n   * The port your application runs on.\n   */\n  applicationPort: number;\n  /**\n   * Configure IAM roles for autoscaling group EC2 instances.\n   */\n  roleConfiguration?: GuInstanceRoleProps;\n  /**\n   * Enable and configure alarms.\n   */\n  monitoringConfiguration: Alarms | NoMonitoring;\n  /**\n   * EC2 instance type. Note, ensure your code is built for the same\n   * architecture family (arm64 - 'Graviton' instances - or x64).\n   */\n  instanceType: InstanceType;\n  /**\n   * Enable and configures application logs.\n   */\n  applicationLogging?: ApplicationLoggingProps;\n  /**\n   * Enable and configures access logs.\n   */\n  accessLogging?: AccessLoggingProps;\n  /**\n   * Add block devices (additional storage).\n   */\n  blockDevices?: BlockDevice[];\n  /**\n   * Autoscaling group min and max sizes.\n   */\n  scaling: GuAsgCapacity;\n  /**\n   * Specify certificate for the load balancer.\n   */\n  certificateProps?: GuDomainName;\n  /**\n   * Disable imdsv2. Most of the time you should not set this.\n   *\n   * @see https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html\n   */\n  withoutImdsv2?: boolean;\n  /**\n   * Configure Amigo image recipe.\n   */\n  imageRecipe?: string | AmigoProps;\n  /**\n   * Specify the VPC to use.\n   *\n   * @see https://github.com/guardian/aws-account-setup\n   */\n  vpc?: IVpc;\n  /**\n   * Specify private subnets if using a non-default VPC or (generally\n   * discouraged) to limit to a subset of the available subnets.\n   */\n  privateSubnets?: ISubnet[];\n\n  /**\n   * Specify private subnets if using a non-default VPC or (generally\n   * discouraged) to limit to a subset of the available subnets.\n   */\n  publicSubnets?: ISubnet[];\n}\n\nfunction restrictedCidrRanges(ranges: IPeer[]) {\n  return ranges.map((range) => ({\n    range,\n    port: Port.tcp(443),\n    description: `Allow access on port 443 from ${range.uniqueId}`,\n  }));\n}\n\n/**\n * Pattern which creates the resources needed to run an application on EC2\n * behind a load balancer. For convenience, you may wish to use [[`GuPlayApp`]]\n * or [[`GuNodeApp`]], which extend this class.\n *\n * See props for further details.\n */\nexport class GuEc2App extends Construct {\n  /*\n   * These are public for now, as this allows users to\n   * modify these constructs as desired to fit their\n   * specific needs.\n   * In the future, we might build functionality to better enable users\n   * to access in-pattern constructs, but this would allow teams to be unblocked\n   * in the short term.\n   * */\n  public readonly vpc: IVpc;\n  public readonly certificate?: GuCertificate;\n  public readonly loadBalancer: GuApplicationLoadBalancer;\n  public readonly autoScalingGroup: GuAutoScalingGroup;\n  public readonly listener: GuHttpsApplicationListener;\n  public readonly targetGroup: GuApplicationTargetGroup;\n\n  constructor(scope: GuStack, props: GuEc2AppProps) {\n    const {\n      access,\n      accessLogging = { enabled: false },\n      app,\n      // We should update this default once a significant number of apps have migrated to devx-logs\n      applicationLogging = { enabled: false },\n      applicationPort,\n      blockDevices,\n      certificateProps,\n      instanceType,\n      monitoringConfiguration,\n      roleConfiguration = { withoutLogShipping: false, additionalPolicies: [] },\n      scaling: { minimumInstances, maximumInstances = minimumInstances * 2 },\n      userData,\n      withoutImdsv2,\n      imageRecipe,\n      vpc = GuVpc.fromIdParameter(scope, AppIdentity.suffixText({ app }, \"VPC\")),\n      privateSubnets = GuVpc.subnetsFromParameter(scope, { type: SubnetType.PRIVATE, app }),\n      publicSubnets = GuVpc.subnetsFromParameter(scope, { type: SubnetType.PUBLIC, app }),\n    } = props;\n\n    super(scope, app); // The assumption is `app` is unique\n\n    // We should really prevent users from doing this via the type system,\n    // but that requires a breaking change to the API\n    if (applicationLogging.enabled && roleConfiguration.withoutLogShipping) {\n      throw new Error(\n        \"Application logging has been enabled (via the `applicationLogging` prop) but your `roleConfiguration` sets \" +\n          \"`withoutLogShipping` to true. Please turn off application logging or remove `withoutLogShipping`\"\n      );\n    }\n\n    AppAccess.validate(access);\n\n    const certificate =\n      typeof certificateProps !== \"undefined\"\n        ? new GuCertificate(scope, {\n            app,\n            domainName: certificateProps.domainName,\n            hostedZoneId: certificateProps.hostedZoneId,\n          })\n        : undefined;\n\n    const maybePrivateConfigPolicy =\n      typeof userData !== \"string\" && userData.configuration\n        ? [new GuGetPrivateConfigPolicy(scope, \"GetPrivateConfigFromS3Policy\", userData.configuration)]\n        : [];\n\n    const mergedRoleConfiguration: GuInstanceRoleProps = {\n      withoutLogShipping: roleConfiguration.withoutLogShipping,\n      additionalPolicies: maybePrivateConfigPolicy.concat(roleConfiguration.additionalPolicies ?? []),\n    };\n\n    const autoScalingGroup = new GuAutoScalingGroup(scope, \"AutoScalingGroup\", {\n      app,\n      vpc,\n      instanceType,\n      minimumInstances,\n      maximumInstances,\n      withoutImdsv2,\n      role: new GuInstanceRole(scope, { app, ...mergedRoleConfiguration }),\n      healthCheck: HealthCheck.elb({ grace: Duration.minutes(2) }), // should this be defaulted at pattern or construct level?\n      userData: typeof userData !== \"string\" ? new GuUserData(scope, { app, ...userData }).userData : userData,\n      vpcSubnets: { subnets: privateSubnets },\n      ...(blockDevices && { blockDevices }),\n      imageRecipe,\n    });\n\n    // This allows automatic shipping of instance Cloud Init logs when using the\n    // `cdk-base` Amigo role on your AMI.\n    Tags.of(autoScalingGroup).add(\n      MetadataKeys.LOG_KINESIS_STREAM_NAME,\n      GuLoggingStreamNameParameter.getInstance(scope).valueAsString\n    );\n\n    if (applicationLogging.enabled) {\n      // This allows automatic shipping of application logs when using the\n      // `cdk-base` Amigo role on your AMI.\n      Tags.of(autoScalingGroup).add(\n        MetadataKeys.SYSTEMD_UNIT,\n        applicationLogging.systemdUnitName ? `${applicationLogging.systemdUnitName}.service` : `${app}.service`\n      );\n    }\n\n    const loadBalancer = new GuApplicationLoadBalancer(scope, \"LoadBalancer\", {\n      app,\n      vpc,\n      // Setting internetFacing to true does not necessarily allow public access to the load balancer itself. That is handled by the listener's `open` prop.\n      internetFacing: access.scope !== AccessScope.INTERNAL,\n      vpcSubnets: {\n        subnets: access.scope === AccessScope.INTERNAL ? privateSubnets : publicSubnets,\n      },\n    });\n\n    if (accessLogging.enabled) {\n      const accessLoggingBucket = new GuStringParameter(scope, \"AccessLoggingBucket\", {\n        description: NAMED_SSM_PARAMETER_PATHS.AccessLoggingBucket.description,\n        default: NAMED_SSM_PARAMETER_PATHS.AccessLoggingBucket.path,\n        fromSSM: true,\n      });\n\n      loadBalancer.logAccessLogs(\n        Bucket.fromBucketName(\n          scope,\n          AppIdentity.suffixText(props, \"AccessLoggingBucket\"),\n          accessLoggingBucket.valueAsString\n        ),\n        accessLogging.prefix\n      );\n    }\n\n    const targetGroup = new GuApplicationTargetGroup(scope, \"TargetGroup\", {\n      app,\n      vpc,\n      protocol: ApplicationProtocol.HTTP,\n      targets: [autoScalingGroup],\n      port: applicationPort,\n    });\n\n    const listener = new GuHttpsApplicationListener(scope, \"Listener\", {\n      app,\n      loadBalancer,\n      certificate,\n      targetGroup,\n      // When open=true, AWS will create a security group which allows all inbound traffic over HTTPS\n      open: access.scope === AccessScope.PUBLIC && typeof certificate !== \"undefined\",\n    });\n\n    // Since AWS won't create a security group automatically when open=false, we need to add our own\n    if (access.scope !== AccessScope.PUBLIC) {\n      loadBalancer.addSecurityGroup(\n        new GuSecurityGroup(scope, `${access.scope}IngressSecurityGroup`, {\n          app,\n          vpc,\n          description: \"Allow restricted ingress from CIDR ranges\",\n          allowAllOutbound: false,\n          ingresses: restrictedCidrRanges(access.cidrRanges),\n        })\n      );\n    }\n\n    if (!monitoringConfiguration.noMonitoring) {\n      const { http5xxAlarm, snsTopicName, unhealthyInstancesAlarm } = monitoringConfiguration;\n\n      if (http5xxAlarm) {\n        new GuAlb5xxPercentageAlarm(scope, {\n          app,\n          loadBalancer,\n          snsTopicName,\n          ...http5xxAlarm,\n        });\n      }\n      if (unhealthyInstancesAlarm) {\n        new GuUnhealthyInstancesAlarm(scope, {\n          app,\n          targetGroup,\n          snsTopicName,\n        });\n      }\n    }\n\n    this.vpc = vpc;\n    this.certificate = certificate;\n    this.loadBalancer = loadBalancer;\n    this.autoScalingGroup = autoScalingGroup;\n    this.listener = listener;\n    this.targetGroup = targetGroup;\n  }\n}\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@guardian/cdk",
   "description": "Generic Guardian flavoured AWS CDK components",
-  "version": "49.4.1",
+  "version": "49.5.0",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "files": [
@@ -28,14 +28,15 @@
     "cli:dev": "ts-node src/bin/index.ts"
   },
   "devDependencies": {
-    "@guardian/eslint-config-typescript": "4.0.0",
+    "@guardian/eslint-config-typescript": "5.0.0",
+    "@guardian/eslint-plugin-tsdoc-required": "^0.1.3",
     "@types/git-url-parse": "^9.0.1",
-    "@types/jest": "^29.4.0",
+    "@types/jest": "^29.5.0",
     "@types/js-yaml": "^4.0.5",
     "@types/lodash.camelcase": "^4.3.7",
     "@types/lodash.kebabcase": "^4.1.7",
     "@types/lodash.upperfirst": "^4.3.7",
-    "@types/node": "18.14.6",
+    "@types/node": "18.15.5",
     "@types/yargs": "^17.0.19",
     "aws-cdk": "2.68.0",
     "cz-conventional-changelog": "^3.3.0",
@@ -52,9 +53,9 @@
     "typescript": "~4.9.5"
   },
   "dependencies": {
-    "@oclif/core": "1.24.2",
+    "@oclif/core": "2.6.4",
     "aws-cdk-lib": "2.68.0",
-    "aws-sdk": "^2.1326.0",
+    "aws-sdk": "^2.1339.0",
     "chalk": "^4.1.2",
     "codemaker": "^1.77.0",
     "constructs": "10.1.273",