skuba 12.1.0-main-20250810101347 → 12.1.0-main-20250812041011

package/template/koa-rest-api/.gantry/prod.yml

@@ -1,8 +1,8 @@
-environment: prod
+deployment: prod
+env: production
 
 maxInstanceCount: 10
 minInstanceCount: 3
 
 openTelemetry:
-  datadogEnvironmentName: production
-  enabled: false
+  enabled: true

package/template/koa-rest-api/README.md

@@ -29,7 +29,7 @@ It uses the [Koa] middleware framework and common SEEK packages.
 Resource APIs enable synchronous interactions and serve as the backbone of SEEK's general service architecture.
 
 The `koa-rest-api` template is modelled after a hypothetical service for posting and retrieving job advertisements.
-It's stubbed out with in-memory [storage](src/storage) which can observed by standing up an environment with multiple instances.
+It's stubbed out with in-memory [storage](src/storage) which can observed by standing up a deployment with multiple instances.
 Storage is local to each instance, so load balancing across the instances may render a read inconsistent with a previous write.
 This would be replaced with an external data store in production.
 
@@ -75,19 +75,19 @@ pnpm start:debug
 
 This project is deployed through a [Buildkite pipeline](.buildkite/pipeline.yml).
 
-- Commits to a feature branch can be deployed to the dev environment by unblocking a step in the Buildkite UI
-- Commits to the default branch are automatically deployed to the dev and prod environments in sequence
+- Commits to a feature branch can be deployed to the development environment by unblocking a step in the Buildkite UI
+- Commits to the default branch are automatically deployed to the development and production environments in sequence
 
 To rapidly roll back a change,
 retry an individual deployment step from the previous build in Buildkite.
-Note that this will introduce drift between the head of the default Git branch and the live environment;
+Note that this will introduce drift between the head of the default Git branch and the live deployment;
 use with caution and always follow up with a proper revert or fix in Git history.
 
 ## Support
 
 ### Dev
 
-TODO: add support links for the dev environment.
+TODO: add support links for the dev deployment.
 
 <!--
 - CloudWatch dashboard
@@ -97,7 +97,7 @@ TODO: add support links for the dev environment.
 
 ### Prod
 
-TODO: add support links for the prod environment.
+TODO: add support links for the prod deployment.
 
 <!--
 - CloudWatch dashboard

package/template/koa-rest-api/gantry.apply.yml

@@ -9,10 +9,14 @@ owner: '{{values "owner"}}'
 image: '{{values "image"}}'
 
 env:
-  ENVIRONMENT: '{{values "environment"}}'
-  OPENTELEMETRY_ENABLED: '{{.Values.openTelemetry.enabled | default false}}'
+  DEPLOYMENT: '{{values "deployment"}}'
   SERVICE: '{{values "service"}}'
 
+  DD_ENV: '{{values "env"}}'
+  DD_SERVICE: '{{values "service"}}'
+
+  OPENTELEMETRY_ENABLED: '{{values "openTelemetry.enabled"}}'
+
 {{if .Values.cloudwatchDashboardDisabled}}
 cloudwatchDashboardDisabled: {{values "cloudwatchDashboardDisabled"}}
 {{end}}
@@ -21,9 +25,17 @@ cloudwatchDashboardDisabled: {{values "cloudwatchDashboardDisabled"}}
 datadogSecretId: '{{values "datadogSecretId"}}'
 {{end}}
 
+# Uncomment if the `tin` tier is acceptable for your SEEK Auth Sidecar logs
+# The eeeoh log forwarder bypasses Amazon CloudWatch for cost savings
+# logSink:
+#   forwarder: eeeoh
+#   splunkIndex: '{{values "logSink.splunkIndex"}}'
+
 openTelemetry:
-  datadogEnvironmentName: '{{values "openTelemetry.datadogEnvironmentName"}}'
+  datadogEnvironmentName: '{{values "env"}}'
   enabled: {{values "openTelemetry.enabled"}}
+  useGantryServiceName: true
+
 {{if .Values.pagerDutyEndpoint}}
 pagerDutyEndpoint: '{{values "pagerDutyEndpoint"}}'
 {{end}}

package/template/koa-rest-api/package.json

@@ -22,11 +22,11 @@
     "@opentelemetry/instrumentation-http": "^0.203.0",
     "@opentelemetry/propagator-b3": "^2.0.0",
     "@opentelemetry/sdk-node": "^0.203.0",
-    "@seek/logger": "master",
+    "@seek/logger": "11.0.0",
     "hot-shots": "^11.0.0",
     "koa": "^3.0.1",
     "koa-compose": "^4.1.0",
-    "seek-datadog-custom-metrics": "^5.0.0",
+    "seek-datadog-custom-metrics": "^6.0.0",
     "seek-koala": "^7.1.0",
     "skuba-dive": "^2.0.0",
     "zod": "^4.0.0"
@@ -39,7 +39,6 @@
     "@types/node": "^22.13.10",
     "@types/supertest": "^6.0.0",
     "chance": "^1.1.8",
-    "mime": "^4.0.1",
     "pino-pretty": "^13.0.0",
     "skuba": "*",
     "supertest": "^7.0.0"

package/template/koa-rest-api/src/api/healthCheck.ts

@@ -3,8 +3,8 @@ import type { Middleware } from 'src/types/koa.js';
 /**
  * Signifies that the API is available to serve requests.
  *
- * The deployment environment calls this endpoint to see if the container is
- * unhealthy and needs to be recycled.
+ * The workload hosting environment calls this endpoint to see if the container
+ * is unhealthy and needs to be recycled.
  */
 export const healthCheckHandler: Middleware = (ctx) => {
   ctx.state.skipRequestLogging = true;

package/template/koa-rest-api/src/config.ts

@@ -1,7 +1,7 @@
 import { Env } from 'skuba-dive';
 
 interface Config {
-  environment: Environment;
+  deployment: Deployment;
 
   logLevel: string;
   name: string;
@@ -11,17 +11,17 @@ interface Config {
   port: number | null;
 }
 
-type Environment = (typeof environments)[number];
+type Deployment = (typeof deployments)[number];
 
 const dev = '<%- devGantryEnvironmentName %>';
 const prod = '<%- prodGantryEnvironmentName %>';
 
-const environments = ['local', 'test', dev, prod] as const;
+const deployments = ['local', 'test', dev, prod] as const;
 
-const environment = Env.oneOf(environments)('ENVIRONMENT');
+const deployment = Env.oneOf(deployments)('DEPLOYMENT');
 
 /* istanbul ignore next: config verification makes more sense in a smoke test */
-const configs: Record<Environment, () => Omit<Config, 'environment'>> = {
+const configs: Record<Deployment, () => Omit<Config, 'deployment'>> = {
   local: () => ({
     logLevel: 'debug',
     name: '<%- serviceName %>',
@@ -62,6 +62,6 @@ const configs: Record<Environment, () => Omit<Config, 'environment'>> = {
 };
 
 export const config: Config = {
-  ...configs[environment](),
-  environment,
+  ...configs[deployment](),
+  deployment,
 };

package/template/koa-rest-api/src/framework/logging.ts

@@ -1,4 +1,4 @@
-import createLogger, { createDestination } from '@seek/logger';
+import { createDestination, createLogger } from '@seek/logger';
 import { RequestLogging } from 'seek-koala';
 
 import { config } from 'src/config.js';
@@ -9,26 +9,30 @@ const { createContextMiddleware, mixin } =
 export const contextMiddleware = createContextMiddleware();
 
 const { destination, stdoutMock } = createDestination({
-  mock: config.environment === 'test',
+  mock: config.deployment === 'test',
 });
 
 export { stdoutMock };
 
 export const logger = createLogger(
   {
-    base: {
-      environment: config.environment,
-      version: config.version,
+    eeeoh: {
+      /**
+       * TODO: choose an appropriate Datadog log tier.
+       *
+       * https://github.com/seek-oss/logger/blob/master/docs/eeeoh.md#datadog-log-tiers
+       */
+      datadog: 'tin',
+      team: '<%- teamName %>',
+      use: 'environment',
     },
 
     mixin,
 
     level: config.logLevel,
 
-    name: config.name,
-
     transport:
-      config.environment === 'local' ? { target: 'pino-pretty' } : undefined,
+      config.deployment === 'local' ? { target: 'pino-pretty' } : undefined,
   },
   destination,
 );

package/template/koa-rest-api/src/framework/metrics.ts

@@ -7,5 +7,5 @@ import { logger } from './logging.js';
 
 /* istanbul ignore next: StatsD client is not our responsibility */
 export const metricsClient = createStatsDClient(StatsD, config, (err) =>
-  logger.error({ err }, 'StatsD error'),
+  logger.error(err, 'StatsD error'),
 );

package/template/koa-rest-api/src/framework/server.test.ts

@@ -132,7 +132,7 @@ describe('createApp', () => {
 
     expect(stdoutMock.calls).toMatchObject([
       {
-        err: {
+        error: {
           statusCode: 400,
           type: 'BadRequestError',
         },
@@ -166,7 +166,7 @@ describe('createApp', () => {
 
     expect(stdoutMock.calls).toMatchObject([
       {
-        err: {
+        error: {
           statusCode: 500,
           type: 'InternalServerError',
         },
@@ -202,7 +202,7 @@ describe('createApp', () => {
 
     expect(stdoutMock.calls).toMatchObject([
       {
-        err: {
+        error: {
           message: err.message,
           type: 'Error',
         },
@@ -236,7 +236,7 @@ describe('createApp', () => {
 
     expect(stdoutMock.calls).toMatchObject([
       {
-        err: null,
+        error: null,
         level: 50,
         method: 'GET',
         msg: 'Server error',
@@ -255,10 +255,10 @@ describe('createApp', () => {
   });
 
   it('handles string error', async () => {
-    const err = chance.sentence();
+    const error = chance.sentence();
 
     middleware.mockImplementation(() => {
-      throw err;
+      throw error;
     });
 
     await agent
@@ -269,7 +269,7 @@ describe('createApp', () => {
 
     expect(stdoutMock.calls).toMatchObject([
       {
-        err,
+        error,
         level: 50,
         method: 'GET',
         msg: 'Server error',

package/template/koa-rest-api/src/framework/server.ts

@@ -30,10 +30,7 @@ const requestLogging = RequestLogging.createMiddleware((ctx, fields, err) => {
     : logger.error(fields, 'Server error');
 });
 
-const version = VersionMiddleware.create({
-  name: config.name,
-  version: config.version,
-});
+const version = VersionMiddleware.create(config);
 
 export const createApp = <State, Context>(
   ...middleware: Array<Koa.Middleware<State, Context>>

package/template/lambda-sqs-worker-cdk/.buildkite/pipeline.yml

@@ -81,7 +81,9 @@ steps:
     agents:
       queue: <%- devBuildkiteQueueName %>
     env:
-      ENVIRONMENT: dev
+      DD_DEPLOYMENT_ENVIRONMENT: development
+      DD_DEPLOYMENT_SERVICE: <%- serviceName %>
+      DEPLOYMENT: dev
       GET_NPM_TOKEN: please
     label: 🤞 Deploy Dev
     concurrency_group: '<%- repoName %>/deploy/dev'
@@ -89,7 +91,9 @@ steps:
 
   - <<: *deploy
     env:
-      ENVIRONMENT: prod
+      DD_DEPLOYMENT_ENVIRONMENT: production
+      DD_DEPLOYMENT_SERVICE: <%- serviceName %>
+      DEPLOYMENT: prod
       GET_NPM_TOKEN: please
     label: 🚀 Deploy Prod
     branches: ${BUILDKITE_PIPELINE_DEFAULT_BRANCH}

package/template/lambda-sqs-worker-cdk/.env

@@ -1 +1 @@
-ENVIRONMENT=local
+DEPLOYMENT=local

package/template/lambda-sqs-worker-cdk/README.md

@@ -54,7 +54,7 @@ pnpm test
 awsauth
 
 # Run smoke test against deployed application
-ENVIRONMENT=dev pnpm smoke
+DEPLOYMENT=dev pnpm smoke
 ```
 
 ### Lint
@@ -88,8 +88,8 @@ curl --data '[{}, {"awsRequestId": "local"}]' --include localhost:<%- port %>
 
 This project is deployed through a [Buildkite pipeline](.buildkite/pipeline.yml).
 
-- Commits to a feature branch can be deployed to the dev environment by unblocking a step in the Buildkite UI
-- Commits to the default branch are automatically deployed to the dev and prod environments in sequence
+- Commits to a feature branch can be deployed to the development environment by unblocking a step in the Buildkite UI
+- Commits to the default branch are automatically deployed to the development and production environments in sequence
 
 To deploy locally:
 
@@ -97,7 +97,7 @@ To deploy locally:
 # Authenticate to dev account
 awsauth
 
-ENVIRONMENT=dev pnpm run deploy
+DEPLOYMENT=dev pnpm run deploy
 ```
 
 A hotswap deploy enables faster deployment but come with caveats such as requiring a Lambda to be rebuilt with every build.
@@ -108,19 +108,19 @@ To deploy a [hotswap]:
 # Authenticate to dev account
 awsauth
 
-ENVIRONMENT=dev pnpm run deploy:hotswap
+DEPLOYMENT=dev pnpm run deploy:hotswap
 ```
 
 To rapidly roll back a change,
 retry an individual deployment step from the previous build in Buildkite.
-Note that this will introduce drift between the head of the default Git branch and the live environment;
+Note that this will introduce drift between the head of the default Git branch and the live deployment;
 use with caution and always follow up with a proper revert or fix in Git history.
 
 ## Support
 
 ### Dev
 
-TODO: add support links for the dev environment.
+TODO: add support links for the dev deployment.
 
 <!--
 - CloudWatch dashboard
@@ -130,7 +130,7 @@ TODO: add support links for the dev environment.
 
 ### Prod
 
-TODO: add support links for the prod environment.
+TODO: add support links for the prod deployment.
 
 <!--
 - CloudWatch dashboard

package/template/lambda-sqs-worker-cdk/infra/__snapshots__/appStack.test.ts.snap

@@ -180,28 +180,29 @@ exports[`returns expected CloudFormation stack for dev 1`] = `
               "Ref": "datadogapikeysecret046FEF06",
             },
             "DD_CAPTURE_LAMBDA_PAYLOAD": "false",
+            "DD_ENV": "development",
             "DD_FLUSH_TO_LOG": "false",
             "DD_LAMBDA_HANDLER": "index.handler",
             "DD_LOGS_INJECTION": "false",
             "DD_MERGE_XRAY_TRACES": "false",
             "DD_SERVERLESS_APPSEC_ENABLED": "false",
             "DD_SERVERLESS_LOGS_ENABLED": "false",
+            "DD_SERVICE": "serviceName",
             "DD_SITE": "datadoghq.com",
             "DD_TRACE_CLOUD_REQUEST_PAYLOAD_TAGGING": "$.*",
             "DD_TRACE_CLOUD_RESPONSE_PAYLOAD_TAGGING": "$.*",
             "DD_TRACE_ENABLED": "true",
+            "DD_VERSION": "local",
+            "DEPLOYMENT": "dev",
             "DESTINATION_SNS_TOPIC_ARN": {
               "Ref": "destinationtopicDCE2E0B8",
             },
-            "ENVIRONMENT": "dev",
             "NODE_ENV": "production",
             "NODE_OPTIONS": "--enable-source-maps",
-            "SERVICE": "serviceName",
-            "VERSION": "local",
           },
         },
         "FunctionName": "serviceName",
-        "Handler": "node_modules/datadog-lambda-js/dist/handler.handler",
+        "Handler": "/opt/nodejs/node_modules/datadog-lambda-js/handler.handler",
         "KmsKeyArn": {
           "Fn::GetAtt": [
             "kmskey49FBC3B3",
@@ -209,6 +210,18 @@ exports[`returns expected CloudFormation stack for dev 1`] = `
           ],
         },
         "Layers": [
+          {
+            "Fn::Join": [
+              "",
+              [
+                "arn:aws:lambda:",
+                {
+                  "Ref": "AWS::Region",
+                },
+                ":464622532012:layer:Datadog-Node22-x:x",
+              ],
+            ],
+          },
           {
             "Fn::Join": [
               "",
@@ -920,28 +933,29 @@ exports[`returns expected CloudFormation stack for prod 1`] = `
               "Ref": "datadogapikeysecret046FEF06",
             },
             "DD_CAPTURE_LAMBDA_PAYLOAD": "false",
+            "DD_ENV": "production",
             "DD_FLUSH_TO_LOG": "false",
             "DD_LAMBDA_HANDLER": "index.handler",
             "DD_LOGS_INJECTION": "false",
             "DD_MERGE_XRAY_TRACES": "false",
             "DD_SERVERLESS_APPSEC_ENABLED": "false",
             "DD_SERVERLESS_LOGS_ENABLED": "false",
+            "DD_SERVICE": "serviceName",
             "DD_SITE": "datadoghq.com",
             "DD_TRACE_CLOUD_REQUEST_PAYLOAD_TAGGING": "$.*",
             "DD_TRACE_CLOUD_RESPONSE_PAYLOAD_TAGGING": "$.*",
             "DD_TRACE_ENABLED": "true",
+            "DD_VERSION": "local",
+            "DEPLOYMENT": "prod",
             "DESTINATION_SNS_TOPIC_ARN": {
               "Ref": "destinationtopicDCE2E0B8",
             },
-            "ENVIRONMENT": "prod",
             "NODE_ENV": "production",
             "NODE_OPTIONS": "--enable-source-maps",
-            "SERVICE": "serviceName",
-            "VERSION": "local",
           },
         },
         "FunctionName": "serviceName",
-        "Handler": "node_modules/datadog-lambda-js/dist/handler.handler",
+        "Handler": "/opt/nodejs/node_modules/datadog-lambda-js/handler.handler",
         "KmsKeyArn": {
           "Fn::GetAtt": [
             "kmskey49FBC3B3",
@@ -949,6 +963,18 @@ exports[`returns expected CloudFormation stack for prod 1`] = `
           ],
         },
         "Layers": [
+          {
+            "Fn::Join": [
+              "",
+              [
+                "arn:aws:lambda:",
+                {
+                  "Ref": "AWS::Region",
+                },
+                ":464622532012:layer:Datadog-Node22-x:x",
+              ],
+            ],
+          },
           {
             "Fn::Join": [
               "",

package/template/lambda-sqs-worker-cdk/infra/appStack.test.ts

@@ -15,11 +15,11 @@ jest.useFakeTimers({
   now: new Date(currentDate),
 });
 
-const originalEnv = process.env.ENVIRONMENT;
+const originalDeployment = process.env.DEPLOYMENT;
 const originalVersion = process.env.VERSION;
 
 afterAll(() => {
-  process.env.ENVIRONMENT = originalEnv;
+  process.env.DEPLOYMENT = originalDeployment;
   process.env.VERSION = originalVersion;
 });
 
@@ -29,8 +29,8 @@ afterEach(() => {
 
 it.each(['dev', 'prod'])(
   'returns expected CloudFormation stack for %s',
-  async (env) => {
-    process.env.ENVIRONMENT = env;
+  async (deployment) => {
+    process.env.DEPLOYMENT = deployment;
     process.env.VERSION = 'local';
 
     const { AppStack } = await import('./appStack.js');
@@ -69,10 +69,7 @@ it.each(['dev', 'prod'])(
         /"DD_TAGS":"git.commit.sha:([0-9a-f]+),git.repository_url:([^\"]+)",/g,
         '',
       )
-      .replaceAll(
-        /(layer:Datadog-Extension-.+?:)\d+/g,
-        (_, layer) => `${layer}x`,
-      );
+      .replaceAll(/(layer:Datadog-[^-]+-.+?:)\d+/g, (_, layer) => `${layer}x`);
     expect(JSON.parse(json)).toMatchSnapshot();
   },
 );

package/template/lambda-sqs-worker-cdk/infra/appStack.ts

@@ -19,7 +19,10 @@ import { DatadogLambda } from 'datadog-cdk-constructs-v2';
 import { config } from './config.js';
 
 // Updated by https://github.com/seek-oss/rynovate
-const DATADOG_EXTENSION_LAYER_VERSION = 64;
+const DATADOG_EXTENSION_LAYER_VERSION = 84;
+
+// Updated by https://github.com/seek-oss/rynovate
+const DATADOG_NODE_LAYER_VERSION = 126;
 
 export class AppStack extends Stack {
   constructor(scope: Construct, id: string, props?: StackProps) {
@@ -95,7 +98,6 @@ export class AppStack extends Stack {
         target: 'node22',
         // aws-sdk-v3 is set as an external module by default, but we want it to be bundled with the function
         externalModules: [],
-        nodeModules: ['datadog-lambda-js', 'dd-trace'],
       },
       functionName: '<%- serviceName %>',
       environment: {
@@ -127,11 +129,15 @@ export class AppStack extends Stack {
     );
 
     const datadog = new DatadogLambda(this, 'datadog', {
+      env: config.env,
+      service: config.service,
+      version: config.version,
+
       apiKeySecret: datadogSecret,
-      addLayers: false,
       enableDatadogLogs: false,
-      flushMetricsToLogs: false,
       extensionLayerVersion: DATADOG_EXTENSION_LAYER_VERSION,
+      flushMetricsToLogs: false,
+      nodeLayerVersion: DATADOG_NODE_LAYER_VERSION,
     });
 
     datadog.addLambdaFunctions([worker]);
@@ -142,8 +148,8 @@ export class AppStack extends Stack {
 
     workerDeployment.alias.addEventSource(
       new aws_lambda_event_sources.SqsEventSource(queue, {
-        maxConcurrency: config.workerLambda.reservedConcurrency - 1, // Ensure we have capacity reserved for our blue/green deployment
         batchSize: config.workerLambda.batchSize,
+        maxConcurrency: config.workerLambda.reservedConcurrency - 1, // Ensure we have capacity reserved for our blue/green deployment
         reportBatchItemFailures: true,
       }),
     );

package/template/lambda-sqs-worker-cdk/infra/config.ts

@@ -1,55 +1,64 @@
 import { Env } from 'skuba-dive';
 
-const ENVIRONMENTS = ['dev', 'prod'] as const;
+type Deployment = (typeof deployments)[number];
 
-type Environment = (typeof ENVIRONMENTS)[number];
+const deployments = ['dev', 'prod'] as const;
 
-const environment = Env.oneOf(ENVIRONMENTS)('ENVIRONMENT');
+const deployment = Env.oneOf(deployments)('DEPLOYMENT');
 
 interface Config {
-  appName: string;
+  env: 'development' | 'production';
+  service: string;
+  version: string;
+
   workerLambda: {
     batchSize: number;
     reservedConcurrency: number;
     environment: {
-      ENVIRONMENT: Environment;
-      SERVICE: string;
-      VERSION: string;
+      DEPLOYMENT: Deployment;
     };
   };
+
   datadogApiKeySecretArn: string;
   sourceSnsTopicArn: string;
 }
 
-const configs: Record<Environment, Config> = {
+const service = '<%- serviceName %>';
+const version = Env.string('VERSION');
+
+const configs: Record<Deployment, Config> = {
   dev: {
-    appName: '<%- serviceName %>',
+    env: 'development',
+    service,
+    version,
+
     workerLambda: {
       batchSize: 10,
       reservedConcurrency: 3,
       environment: {
-        ENVIRONMENT: 'dev',
-        SERVICE: '<%- serviceName %>',
-        VERSION: Env.string('VERSION', { default: 'local' }),
+        DEPLOYMENT: 'dev',
       },
     },
+
     datadogApiKeySecretArn: 'TODO: datadogApiKeySecretArn',
     sourceSnsTopicArn: 'TODO: sourceSnsTopicArn',
   },
   prod: {
-    appName: '<%- serviceName %>',
+    env: 'production',
+    service,
+    version,
+
     workerLambda: {
       batchSize: 10,
       reservedConcurrency: 20,
       environment: {
-        ENVIRONMENT: 'prod',
-        SERVICE: '<%- serviceName %>',
-        VERSION: Env.string('VERSION', { default: 'local' }),
+        DEPLOYMENT: 'prod',
       },
     },
+
     datadogApiKeySecretArn: 'TODO: datadogApiKeySecretArn',
     sourceSnsTopicArn: 'TODO: sourceSnsTopicArn',
   },
 };
 
-export const config: Config = configs[environment];
+export const config: Config = configs[deployment];

package/template/lambda-sqs-worker-cdk/infra/index.ts

@@ -7,7 +7,7 @@ import { config } from './config.js';
 const app = new App();
 
 const appStack = new AppStack(app, 'appStack', {
-  stackName: config.appName,
+  stackName: config.service,
   tags: {
     'seek:source:url': 'https://github.com/SEEK-Jobs/<%- repoName %>',
     // 'seek:system:name': 'TODO: https://rfc.skinfra.xyz/RFC051-AWS-Tagging-Standard.html#tagging-schema',