feat(ecs): add support for ecs service hook details field

packages/@aws-cdk-testing/framework-integ/test/aws-ecs/test/base/integ.blue-green-deployment-strategy.js.snapshot/aws-ecs-blue-green-deployment.template.json

@@ -742,6 +742,7 @@
     "DeploymentConfiguration": {
      "LifecycleHooks": [
       {
+       "HookDetails": "{\"stringKey\":\"stringValue\",\"intKey\":1,\"boolKey\":true,\"listKey\":[\"stringValue1\",\"stringValue2\"]}",
        "HookTargetArn": {
         "Fn::GetAtt": [
          "LambdaHookBF1BC8B4",

packages/@aws-cdk-testing/framework-integ/test/aws-ecs/test/base/integ.blue-green-deployment-strategy.ts

@@ -125,6 +125,12 @@ const service = new ecs.FargateService(stack, 'Service', {
 
 service.addLifecycleHook(new ecs.DeploymentLifecycleLambdaTarget(lambdaHook, 'PreScaleUp', {
   lifecycleStages: [ecs.DeploymentLifecycleStage.PRE_SCALE_UP],
+  hookDetails: {
+    stringKey: 'stringValue',
+    intKey: 1,
+    boolKey: true,
+    listKey: ['stringValue1', 'stringValue2'],
+  },
 }));
 
 const target = service.loadBalancerTarget({

packages/aws-cdk-lib/aws-ecs/README.md

@@ -2200,6 +2200,7 @@ const service = new ecs.FargateService(this, 'Service', {
 
 service.addLifecycleHook(new ecs.DeploymentLifecycleLambdaTarget(lambdaHook, 'PreScaleHook', {
   lifecycleStages: [ecs.DeploymentLifecycleStage.PRE_SCALE_UP],
+  hookDetails: {'stringKey':'stringValue', 'intKey':1, 'boolKey':true, "list": ["abc",1,true]},
 }));
 
 const target = service.loadBalancerTarget({

packages/aws-cdk-lib/aws-ecs/lib/base/base-service.ts

@@ -879,6 +879,7 @@ export abstract class BaseService extends Resource
         hookTargetArn: config.targetArn,
         roleArn: config.role!.roleArn,
         lifecycleStages: config.lifecycleStages.map(stage => stage.toString()),
+        hookDetails: config.hookDetails,
       };
     });
   }

packages/aws-cdk-lib/aws-ecs/lib/deployment-lifecycle-hook-target.ts

@@ -1,6 +1,7 @@
 import { IConstruct } from 'constructs';
 import * as iam from '../../aws-iam';
 import * as lambda from '../../aws-lambda';
+import { Fn, ValidationError } from '../../core';
 
 /**
  * Deployment lifecycle stages where hooks can be executed
@@ -55,6 +56,12 @@ export interface DeploymentLifecycleHookTargetConfig {
    * The lifecycle stages when this hook should be executed
    */
   readonly lifecycleStages: DeploymentLifecycleStage[];
+
+  /**
+   * Use this field to specify custom parameters that Amazon ECS will pass to your hook target invocations (such as a Lambda function).
+   * @default - No custom parameters will be passed
+   */
+  readonly hookDetails?: string;
 }
 
 /**
@@ -65,7 +72,6 @@ export interface IDeploymentLifecycleHookTarget {
    * Bind this target to a deployment lifecycle hook
    *
    * @param scope The construct scope
-   * @param id A unique identifier for this binding
    */
   bind(scope: IConstruct): DeploymentLifecycleHookTargetConfig;
 }
@@ -84,6 +90,18 @@ export interface DeploymentLifecycleLambdaTargetProps {
    * The lifecycle stages when this hook should be executed
    */
   readonly lifecycleStages: DeploymentLifecycleStage[];
+
+  /**
+   * Use this field to specify custom parameters that Amazon ECS will pass to your hook target invocations (such as a Lambda function).
+   *
+   * This field accepts JSON objects only
+   *
+   * @example
+   * {environment:"production",timeout:300};
+   *
+   * @default - No custom parameters will be passed
+   */
+  readonly hookDetails?: { [key: string]: any };
 }
 
 /**
@@ -118,10 +136,16 @@ export class DeploymentLifecycleLambdaTarget implements IDeploymentLifecycleHook
       this.handler.grantInvoke(this._role);
     }
 
+    // Reject arrays
+    if (Array.isArray(this.props.hookDetails)) {
+      throw new ValidationError('hookDetails must be a JSON object, got: array', scope);
+    }
+
     return {
       targetArn: this.handler.functionArn,
       role: this._role,
       lifecycleStages: this.props.lifecycleStages,
+      hookDetails: this.props.hookDetails ? Fn.toJsonString(this.props.hookDetails) : undefined,
     };
   }
 }

packages/aws-cdk-lib/aws-ecs/test/deployment-lifecycle-hook-target.test.ts

@@ -282,4 +282,59 @@ describe('DeploymentLifecycleHookTarget', () => {
       service.addLifecycleHook(hookTarget);
     }).toThrow(/Deployment lifecycle hooks requires the ECS deployment controller/);
   });
+
+  describe('hookDetails validation', () => {
+    test('validates valid JSON object hookDetails', () => {
+      // GIVEN
+      const service = new ecs.FargateService(stack, 'FargateService', {
+        cluster,
+        taskDefinition,
+      });
+
+      // WHEN
+      const hookTarget = new ecs.DeploymentLifecycleLambdaTarget(lambdaFunction, 'PreScaleUpHook', {
+        lifecycleStages: [ecs.DeploymentLifecycleStage.PRE_SCALE_UP],
+        hookDetails: { environment: 'production', timeout: 300 },
+      });
+      service.addLifecycleHook(hookTarget);
+
+      // THEN
+      Template.fromStack(stack).hasResourceProperties('AWS::ECS::Service', {
+        DeploymentConfiguration: {
+          LifecycleHooks: [
+            {
+              LifecycleStages: ['PRE_SCALE_UP'],
+              HookTargetArn: {
+                'Fn::GetAtt': [
+                  Match.stringLikeRegexp('TestFunction'),
+                  'Arn',
+                ],
+              },
+              HookDetails: '{\"environment\":\"production\",\"timeout\":300}',
+            },
+          ],
+        },
+      });
+    });
+
+    test('throws error for JSON array hookDetails', () => {
+      // GIVEN
+      const service = new ecs.FargateService(stack, 'FargateService', {
+        cluster,
+        taskDefinition,
+      });
+
+      // WHEN
+      const hookTarget = new ecs.DeploymentLifecycleLambdaTarget(lambdaFunction, 'PreScaleUpHook', {
+        lifecycleStages: [ecs.DeploymentLifecycleStage.PRE_SCALE_UP],
+        hookDetails: ['param1', 'param2', 1, true],
+      });
+      service.addLifecycleHook(hookTarget);
+
+      // GIVEN & WHEN & THEN
+      expect(() => {
+        Template.fromStack(stack);
+      }).toThrow(/hookDetails must be a JSON object, got: array/);
+    });
+  });
 });