fix(custom-resources): cannot set logging for state machine generated in CompleteHandler

packages/aws-cdk-lib/custom-resources/lib/provider-framework/provider.ts

@@ -2,7 +2,7 @@ import * as path from 'path';
 import { Construct } from 'constructs';
 import * as consts from './runtime/consts';
 import { calculateRetryPolicy } from './util';
-import { WaiterStateMachine } from './waiter-state-machine';
+import { LogOptions, WaiterStateMachine } from './waiter-state-machine';
 import { CustomResourceProviderConfig, ICustomResourceProvider } from '../../../aws-cloudformation';
 import * as ec2 from '../../../aws-ec2';
 import * as iam from '../../../aws-iam';
@@ -126,6 +126,20 @@ export interface ProviderProps {
    * @default -  AWS Lambda creates and uses an AWS managed customer master key (CMK)
    */
   readonly providerFunctionEnvEncryption?: kms.IKey;
+
+  /**
+   * Defines what execution history events of the waiter state machine are logged and where they are logged.
+   *
+   * @default - A default log group will be created if logging for the waiter state machine is enabled.
+   */
+  readonly waiterStateMachineLogOptions?: LogOptions;
+
+  /**
+   * Whether logging for the waiter state machine is disabled.
+   *
+   * @default - false
+   */
+  readonly disableWaiterStateMachineLogging?: boolean;
 }
 
 /**
@@ -162,9 +176,17 @@ export class Provider extends Construct implements ICustomResourceProvider {
   constructor(scope: Construct, id: string, props: ProviderProps) {
     super(scope, id);
 
-    if (!props.isCompleteHandler && (props.queryInterval || props.totalTimeout)) {
-      throw new Error('"queryInterval" and "totalTimeout" can only be configured if "isCompleteHandler" is specified. '
-        + 'Otherwise, they have no meaning');
+    if (!props.isCompleteHandler) {
+      if (
+        props.queryInterval
+        || props.totalTimeout
+        || props.waiterStateMachineLogOptions
+        || props.disableWaiterStateMachineLogging !== undefined
+      ) {
+        throw new Error('"queryInterval", "totalTimeout", "waiterStateMachineLogOptions", and "disableWaiterStateMachineLogging" '
+          + 'can only be configured if "isCompleteHandler" is specified. '
+          + 'Otherwise, they have no meaning');
+      }
     }
 
     this.onEventHandler = props.onEventHandler;
@@ -191,6 +213,8 @@ export class Provider extends Construct implements ICustomResourceProvider {
         backoffRate: retry.backoffRate,
         interval: retry.interval,
         maxAttempts: retry.maxAttempts,
+        logOptions: props.waiterStateMachineLogOptions,
+        disableLogging: props.disableWaiterStateMachineLogging,
       });
       // the on-event entrypoint is going to start the execution of the waiter
       onEventFunction.addEnvironment(consts.WAITER_STATE_MACHINE_ARN_ENV, waiterStateMachine.stateMachineArn);

packages/aws-cdk-lib/custom-resources/lib/provider-framework/waiter-state-machine.ts

@@ -1,8 +1,39 @@
 import { Construct } from 'constructs';
-import { Grant, IGrantable, Role, ServicePrincipal } from '../../../aws-iam';
+import { Grant, IGrantable, PolicyStatement, Role, ServicePrincipal } from '../../../aws-iam';
 import { IFunction } from '../../../aws-lambda';
-import { CfnResource, Duration, Stack } from '../../../core';
+import { ILogGroup, LogGroup } from '../../../aws-logs';
+import { CfnStateMachine, LogLevel } from '../../../aws-stepfunctions';
+import { Duration, Stack } from '../../../core';
 
+/**
+ * Log Options for the state machine.
+ */
+export interface LogOptions {
+  /**
+   * The log group where the execution history events will be logged.
+   *
+   * @default - a new log group will be created
+   */
+  readonly destination?: ILogGroup;
+
+  /**
+   * Determines whether execution data is included in your log.
+   *
+   * @default - false
+   */
+  readonly includeExecutionData?: boolean;
+
+  /**
+   * Defines which category of execution history events are logged.
+   *
+   * @default - ERROR
+   */
+  readonly level?: LogLevel;
+}
+
+/**
+ * Initialization properties for the `WaiterStateMachine` construct.
+ */
 export interface WaiterStateMachineProps {
   /**
    * The main handler that notifies if the waiter to decide 'complete' or 'incomplete'.
@@ -28,17 +59,36 @@ export interface WaiterStateMachineProps {
    * Backoff between attempts.
    */
   readonly backoffRate: number;
+
+  /**
+   * Defines what execution history events are logged and where they are logged.
+   *
+   * @default - A default log group will be created if logging is enabled.
+   */
+  readonly logOptions?: LogOptions;
+
+  /**
+   * Whether logging for the state machine is disabled.
+   *
+   * @default - false
+   */
+  readonly disableLogging?: boolean;
 }
 
 /**
  * A very simple StateMachine construct highly customized to the provider framework.
- * This is so that this package does not need to depend on aws-stepfunctions module.
+ * We previously used `CfnResource` instead of `CfnStateMachine` to avoid depending
+ * on `aws-stepfunctions` module, but now it is okay.
  *
  * The state machine continuously calls the isCompleteHandler, until it succeeds or times out.
  * The handler is called `maxAttempts` times with an `interval` duration and a `backoffRate` rate.
  */
 export class WaiterStateMachine extends Construct {
+  /**
+   * The ARN of the state machine.
+   */
   public readonly stateMachineArn: string;
+  private readonly isCompleteHandler: IFunction;
 
   constructor(scope: Construct, id: string, props: WaiterStateMachineProps) {
     super(scope, id);
@@ -75,23 +125,73 @@ export class WaiterStateMachine extends Construct {
       },
     });
 
-    const resource = new CfnResource(this, 'Resource', {
-      type: 'AWS::StepFunctions::StateMachine',
-      properties: {
-        DefinitionString: definition,
-        RoleArn: role.roleArn,
-      },
+    this.isCompleteHandler = props.isCompleteHandler;
+    const resource = new CfnStateMachine(this, 'Resource', {
+      definitionString: definition,
+      roleArn: role.roleArn,
+      loggingConfiguration: this.renderLoggingConfiguration(role, props.logOptions, props.disableLogging),
     });
     resource.node.addDependency(role);
 
     this.stateMachineArn = resource.ref;
   }
 
+  /**
+   * Grant the given identity permissions on StartExecution of the state machine.
+   */
   public grantStartExecution(identity: IGrantable) {
     return Grant.addToPrincipal({
       grantee: identity,
       actions: ['states:StartExecution'],
       resourceArns: [this.stateMachineArn],
     });
   }
+
+  private renderLoggingConfiguration(
+    role: Role,
+    logOptions?: LogOptions,
+    disableLogging?: boolean,
+  ): CfnStateMachine.LoggingConfigurationProperty | undefined {
+    if (disableLogging) return undefined;
+
+    // You need to specify `*` in the Resource field because CloudWatch API actions, such as
+    // CreateLogDelivery and DescribeLogGroups, don't support Resource types defined by Amazon
+    // CloudWatch Logs.
+    // https://docs.aws.amazon.com/step-functions/latest/dg/cw-logs.html#cloudwatch-iam-policy
+    role.addToPrincipalPolicy(new PolicyStatement({
+      actions: [
+        'logs:CreateLogDelivery',
+        'logs:CreateLogStream',
+        'logs:GetLogDelivery',
+        'logs:UpdateLogDelivery',
+        'logs:DeleteLogDelivery',
+        'logs:ListLogDeliveries',
+        'logs:PutLogEvents',
+        'logs:PutResourcePolicy',
+        'logs:DescribeResourcePolicies',
+        'logs:DescribeLogGroups',
+      ],
+      resources: ['*'],
+    }));
+
+    const logGroup = logOptions?.destination ?? new LogGroup(this, 'LogGroup', {
+      // By using the auto-generated name of the Lambda created in the `Provider` that calls this
+      // `WaiterStateMachine` construct, even if the `Provider` (or its parent) is deleted and then
+      // created again, the log group name will not duplicate previously created one with removal
+      // policy `RETAIN`. This is because that the Lambda will be re-created again with auto-generated name.
+      // The `node.addr` is also used to prevent duplicate names no matter how many times this construct
+      // is created in the stack. It will not duplicate if called on other stacks.
+      logGroupName: `/aws/vendedlogs/states/waiter-state-machine-${this.isCompleteHandler.functionName}-${this.node.addr}`,
+    });
+
+    return {
+      destinations: [{
+        cloudWatchLogsLogGroup: {
+          logGroupArn: logGroup.logGroupArn,
+        },
+      }],
+      includeExecutionData: logOptions?.includeExecutionData ?? false,
+      level: logOptions?.level ?? LogLevel.ERROR,
+    };
+  }
 }

packages/aws-cdk-lib/custom-resources/test/provider-framework/provider.test.ts

@@ -1,9 +1,10 @@
-import { Template } from '../../../assertions';
+import { Match, Template } from '../../../assertions';
 import * as ec2 from '../../../aws-ec2';
 import * as iam from '../../../aws-iam';
 import * as kms from '../../../aws-kms';
 import * as lambda from '../../../aws-lambda';
 import * as logs from '../../../aws-logs';
+import { LogLevel } from '../../../aws-stepfunctions';
 import { Duration, Stack } from '../../../core';
 import * as cr from '../../lib';
 import * as util from '../../lib/provider-framework/util';
@@ -180,6 +181,10 @@ test('if isComplete is specified, the isComplete framework handler is also inclu
   new cr.Provider(stack, 'MyProvider', {
     onEventHandler: handler,
     isCompleteHandler: handler,
+    waiterStateMachineLogOptions: {
+      includeExecutionData: true,
+      level: LogLevel.ALL,
+    },
   });
 
   // THEN
@@ -238,10 +243,84 @@ test('if isComplete is specified, the isComplete framework handler is also inclu
         ],
       ],
     },
+    LoggingConfiguration: {
+      Destinations: [
+        {
+          CloudWatchLogsLogGroup: {
+            LogGroupArn: {
+              'Fn::GetAtt': [
+                'MyProviderwaiterstatemachineLogGroupD43CA868',
+                'Arn',
+              ],
+            },
+          },
+        },
+      ],
+      IncludeExecutionData: true,
+      Level: 'ALL',
+    },
   });
 });
 
-test('fails if "queryInterval" and/or "totalTimeout" are set without "isCompleteHandler"', () => {
+test('a default LoggingConfiguration will be created even if waiterStateMachineLogOptions is not specified', () => {
+  // GIVEN
+  const stack = new Stack();
+  const handler = new lambda.Function(stack, 'MyHandler', {
+    code: new lambda.InlineCode('foo'),
+    handler: 'index.onEvent',
+    runtime: lambda.Runtime.NODEJS_LATEST,
+  });
+
+  // WHEN
+  new cr.Provider(stack, 'MyProvider', {
+    onEventHandler: handler,
+    isCompleteHandler: handler,
+  });
+
+  // THEN
+  Template.fromStack(stack).hasResourceProperties('AWS::StepFunctions::StateMachine', {
+    LoggingConfiguration: {
+      Destinations: [
+        {
+          CloudWatchLogsLogGroup: {
+            LogGroupArn: {
+              'Fn::GetAtt': [
+                'MyProviderwaiterstatemachineLogGroupD43CA868',
+                'Arn',
+              ],
+            },
+          },
+        },
+      ],
+      IncludeExecutionData: false,
+      Level: 'ERROR',
+    },
+  });
+});
+
+test('a default LoggingConfiguration will not be created if disableWaiterStateMachineLogging is true', () => {
+  // GIVEN
+  const stack = new Stack();
+  const handler = new lambda.Function(stack, 'MyHandler', {
+    code: new lambda.InlineCode('foo'),
+    handler: 'index.onEvent',
+    runtime: lambda.Runtime.NODEJS_LATEST,
+  });
+
+  // WHEN
+  new cr.Provider(stack, 'MyProvider', {
+    onEventHandler: handler,
+    isCompleteHandler: handler,
+    disableWaiterStateMachineLogging: true,
+  });
+
+  // THEN
+  Template.fromStack(stack).hasResourceProperties('AWS::StepFunctions::StateMachine', {
+    LoggingConfiguration: Match.absent(),
+  });
+});
+
+test('fails if "queryInterval" or "totalTimeout" or "waiterStateMachineLogOptions" or "disableWaiterStateMachineLogging" are set without "isCompleteHandler"', () => {
   // GIVEN
   const stack = new Stack();
   const handler = new lambda.Function(stack, 'MyHandler', {
@@ -254,12 +333,25 @@ test('fails if "queryInterval" and/or "totalTimeout" are set without "isComplete
   expect(() => new cr.Provider(stack, 'provider1', {
     onEventHandler: handler,
     queryInterval: Duration.seconds(10),
-  })).toThrow(/\"queryInterval\" and \"totalTimeout\" can only be configured if \"isCompleteHandler\" is specified. Otherwise, they have no meaning/);
+  })).toThrow(/\"queryInterval\", \"totalTimeout\", \"waiterStateMachineLogOptions\", and \"disableWaiterStateMachineLogging\" can only be configured if \"isCompleteHandler\" is specified. Otherwise, they have no meaning/);
 
   expect(() => new cr.Provider(stack, 'provider2', {
     onEventHandler: handler,
     totalTimeout: Duration.seconds(100),
-  })).toThrow(/\"queryInterval\" and \"totalTimeout\" can only be configured if \"isCompleteHandler\" is specified. Otherwise, they have no meaning/);
+  })).toThrow(/\"queryInterval\", \"totalTimeout\", \"waiterStateMachineLogOptions\", and \"disableWaiterStateMachineLogging\" can only be configured if \"isCompleteHandler\" is specified. Otherwise, they have no meaning/);
+
+  expect(() => new cr.Provider(stack, 'provider3', {
+    onEventHandler: handler,
+    waiterStateMachineLogOptions: {
+      includeExecutionData: true,
+      level: LogLevel.ALL,
+    },
+  })).toThrow(/\"queryInterval\", \"totalTimeout\", \"waiterStateMachineLogOptions\", and \"disableWaiterStateMachineLogging\" can only be configured if \"isCompleteHandler\" is specified. Otherwise, they have no meaning/);
+
+  expect(() => new cr.Provider(stack, 'provider4', {
+    onEventHandler: handler,
+    disableWaiterStateMachineLogging: false,
+  })).toThrow(/\"queryInterval\", \"totalTimeout\", \"waiterStateMachineLogOptions\", and \"disableWaiterStateMachineLogging\" can only be configured if \"isCompleteHandler\" is specified. Otherwise, they have no meaning/);
 });
 
 describe('retry policy', () => {
@@ -448,4 +540,4 @@ describe('environment encryption', () => {
       },
     });
   });
-});
+});