aws-cdk-lib 2.137.0__py3-none-any.whl → 2.139.0__py3-none-any.whl

aws_cdk/custom_resources/__init__.py

@@ -613,6 +613,78 @@ cr.AwsCustomResource(self, "ListObjects",
 Note that even if you restrict the output of your custom resource you can still use any
 path in `PhysicalResourceId.fromResponse()`.
 
+### Custom Resource Logging for SDK Calls
+
+By default, logging occurs during execution of the singleton Lambda used by a custom resource. The data being logged includes:
+
+* The event object that is received by the Lambda handler
+* The response received after making an API call
+* The response object that the Lambda handler will return
+* SDK versioning information
+* Caught and uncaught errors
+
+The `logging` property defined on the `AwsSdkCall` interface allows control over what data is being logged on a per SDK call basis. This is configurable via an instance of the `Logging` class. The `Logging` class exposes two options that can be used to configure logging:
+
+1. `Logging.all()` which enables logging of all data. This is the default `logging` configuration.
+2. `Logging.withDataHidden()` which prevents logging of all data associated with the API call response, including logging the raw API call response and the `Data` field on the Lambda handler response object. This configuration option is particularly useful for situations where the API call response may contain sensitive information.
+
+For further context about `Logging.withDataHidden()`, consider a user who might be making an API call that is returning sensitive information that they may want to keep hidden. To do this, they would configure `logging` with `Logging.withDataHidden()`:
+
+```python
+get_parameter = cr.AwsCustomResource(self, "GetParameter",
+    on_update=cr.AwsSdkCall(
+        service="SSM",
+        action="GetParameter",
+        parameters={
+            "Name": "my-parameter",
+            "WithDecryption": True
+        },
+        physical_resource_id=cr.PhysicalResourceId.of(Date.now().to_string()),
+        logging=cr.Logging.with_data_hidden()
+    ),
+    policy=cr.AwsCustomResourcePolicy.from_sdk_calls(
+        resources=cr.AwsCustomResourcePolicy.ANY_RESOURCE
+    )
+)
+```
+
+With this configuration option set, the raw API call response would not be logged and the `Data` field of the response object would be hidden:
+
+```
+{
+  "Status": "SUCCESS",
+  "Reason": "OK",
+  "PhysicalResourceId": "1234567890123",
+  "StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/Test/043tyub2-194e-4cy2-a969-9891ghj6cd0d",
+  "RequestId": "a16y677a-a8b6-41a6-bf7b-7644586861a5",
+  "LogicalResourceId": "Sercret",
+  "NoEcho": false,
+}
+```
+
+For comparison, configuring `logging` with `Logging.all()` would result in the raw API call response being logged, as well as the full response object:
+
+```
+{
+  "Status": "SUCCESS",
+  "Reason": "OK",
+  "PhysicalResourceId": "1234567890123",
+  "StackId": "arn:aws:cloudformation:us-west-2:123456789012:stack/Test/043tyub2-194e-4cy2-a969-9891ghj6cd0d",
+  "RequestId": "a16y677a-a8b6-41a6-bf7b-7644586861a5",
+  "LogicalResourceId": "Sercret",
+  "NoEcho": false,
+  "Data": {
+    "region": "us-west-2",
+    "Parameter.ARN": "arn:aws:ssm:us-west-2:123456789012:parameter/Test/Parameter",
+    "Parameter.DataType": "text",
+    "Parameter.Name": "/Test/Parameter",
+    "Parameter.Type": "SecureString",
+    "Parameter.Value": "ThisIsSecret!123",
+    "Parameter.Version": 1
+  }
+}
+```
+
 ### Custom Resource Examples
 
 #### Get the latest version of a secure SSM parameter
@@ -748,6 +820,7 @@ from ..aws_ec2 import (
     SubnetSelection as _SubnetSelection_e57d76df,
 )
 from ..aws_iam import (
+    Grant as _Grant_a7ae64f8,
     IGrantable as _IGrantable_71c4f5de,
     IPrincipal as _IPrincipal_539bb2fd,
     IRole as _IRole_235f5d8e,
@@ -758,6 +831,7 @@ from ..aws_lambda import IFunction as _IFunction_6adb0ab8
 from ..aws_logs import (
     ILogGroup as _ILogGroup_3c4fa718, RetentionDays as _RetentionDays_070f99f0
 )
+from ..aws_stepfunctions import LogLevel as _LogLevel_be1990fe
 
 
 @jsii.implements(_IGrantable_71c4f5de)
@@ -778,25 +852,22 @@ class AwsCustomResource(
 
     Example::
 
-        get_parameter = cr.AwsCustomResource(self, "AssociateVPCWithHostedZone",
-            on_create=cr.AwsSdkCall(
-                assumed_role_arn="arn:aws:iam::OTHERACCOUNT:role/CrossAccount/ManageHostedZoneConnections",
-                service="Route53",
-                action="AssociateVPCWithHostedZone",
+        get_parameter = cr.AwsCustomResource(self, "GetParameter",
+            on_update=cr.AwsSdkCall( # will also be called for a CREATE event
+                service="SSM",
+                action="GetParameter",
                 parameters={
-                    "HostedZoneId": "hz-123",
-                    "VPC": {
-                        "VPCId": "vpc-123",
-                        "VPCRegion": "region-for-vpc"
-                    }
+                    "Name": "my-parameter",
+                    "WithDecryption": True
                 },
-                physical_resource_id=cr.PhysicalResourceId.of("${vpcStack.SharedVpc.VpcId}-${vpcStack.Region}-${PrivateHostedZone.HostedZoneId}")
-            ),
-            # Will ignore any resource and use the assumedRoleArn as resource and 'sts:AssumeRole' for service:action
+                physical_resource_id=cr.PhysicalResourceId.of(Date.now().to_string())),
             policy=cr.AwsCustomResourcePolicy.from_sdk_calls(
                 resources=cr.AwsCustomResourcePolicy.ANY_RESOURCE
             )
         )
+        
+        # Use the value in another construct with
+        get_parameter.get_response_field("Parameter.Value")
     '''
 
     def __init__(
@@ -1061,25 +1132,22 @@ class AwsCustomResourceProps:
 
         Example::
 
-            get_parameter = cr.AwsCustomResource(self, "AssociateVPCWithHostedZone",
-                on_create=cr.AwsSdkCall(
-                    assumed_role_arn="arn:aws:iam::OTHERACCOUNT:role/CrossAccount/ManageHostedZoneConnections",
-                    service="Route53",
-                    action="AssociateVPCWithHostedZone",
+            get_parameter = cr.AwsCustomResource(self, "GetParameter",
+                on_update=cr.AwsSdkCall( # will also be called for a CREATE event
+                    service="SSM",
+                    action="GetParameter",
                     parameters={
-                        "HostedZoneId": "hz-123",
-                        "VPC": {
-                            "VPCId": "vpc-123",
-                            "VPCRegion": "region-for-vpc"
-                        }
+                        "Name": "my-parameter",
+                        "WithDecryption": True
                     },
-                    physical_resource_id=cr.PhysicalResourceId.of("${vpcStack.SharedVpc.VpcId}-${vpcStack.Region}-${PrivateHostedZone.HostedZoneId}")
-                ),
-                # Will ignore any resource and use the assumedRoleArn as resource and 'sts:AssumeRole' for service:action
+                    physical_resource_id=cr.PhysicalResourceId.of(Date.now().to_string())),
                 policy=cr.AwsCustomResourcePolicy.from_sdk_calls(
                     resources=cr.AwsCustomResourcePolicy.ANY_RESOURCE
                 )
             )
+            
+            # Use the value in another construct with
+            get_parameter.get_response_field("Parameter.Value")
         '''
         if isinstance(on_create, dict):
             on_create = AwsSdkCall(**on_create)
@@ -1322,6 +1390,7 @@ class AwsCustomResourceProps:
         "api_version": "apiVersion",
         "assumed_role_arn": "assumedRoleArn",
         "ignore_error_codes_matching": "ignoreErrorCodesMatching",
+        "logging": "logging",
         "output_paths": "outputPaths",
         "parameters": "parameters",
         "physical_resource_id": "physicalResourceId",
@@ -1337,6 +1406,7 @@ class AwsSdkCall:
         api_version: typing.Optional[builtins.str] = None,
         assumed_role_arn: typing.Optional[builtins.str] = None,
         ignore_error_codes_matching: typing.Optional[builtins.str] = None,
+        logging: typing.Optional["Logging"] = None,
         output_paths: typing.Optional[typing.Sequence[builtins.str]] = None,
         parameters: typing.Any = None,
         physical_resource_id: typing.Optional["PhysicalResourceId"] = None,
@@ -1349,6 +1419,7 @@ class AwsSdkCall:
         :param api_version: API version to use for the service. Default: - use latest available API version
         :param assumed_role_arn: Used for running the SDK calls in underlying lambda with a different role. Can be used primarily for cross-account requests to for example connect hostedzone with a shared vpc. Region controls where assumeRole call is made. Example for Route53 / associateVPCWithHostedZone Default: - run without assuming role
         :param ignore_error_codes_matching: The regex pattern to use to catch API errors. The ``code`` property of the ``Error`` object will be tested against this pattern. If there is a match an error will not be thrown. Default: - do not catch errors
+        :param logging: A property used to configure logging during lambda function execution. Note: The default Logging configuration is all. This configuration will enable logging on all logged data in the lambda handler. This includes: - The event object that is received by the lambda handler - The response received after making a API call - The response object that the lambda handler will return - SDK versioning information - Caught and uncaught errors Default: Logging.all()
         :param output_paths: Restrict the data returned by the custom resource to specific paths in the API response. Use this to limit the data returned by the custom resource if working with API calls that could potentially result in custom response objects exceeding the hard limit of 4096 bytes. Example for ECS / updateService: ['service.deploymentConfiguration.maximumPercent'] Default: - return all data
         :param parameters: The parameters for the service action. Default: - no parameters
         :param physical_resource_id: The physical resource id of the custom resource for this call. Mandatory for onCreate call. In onUpdate, you can omit this to passthrough it from request. Default: - no physical resource id
@@ -1377,6 +1448,7 @@ class AwsSdkCall:
             check_type(argname="argument api_version", value=api_version, expected_type=type_hints["api_version"])
             check_type(argname="argument assumed_role_arn", value=assumed_role_arn, expected_type=type_hints["assumed_role_arn"])
             check_type(argname="argument ignore_error_codes_matching", value=ignore_error_codes_matching, expected_type=type_hints["ignore_error_codes_matching"])
+            check_type(argname="argument logging", value=logging, expected_type=type_hints["logging"])
             check_type(argname="argument output_paths", value=output_paths, expected_type=type_hints["output_paths"])
             check_type(argname="argument parameters", value=parameters, expected_type=type_hints["parameters"])
             check_type(argname="argument physical_resource_id", value=physical_resource_id, expected_type=type_hints["physical_resource_id"])
@@ -1391,6 +1463,8 @@ class AwsSdkCall:
             self._values["assumed_role_arn"] = assumed_role_arn
         if ignore_error_codes_matching is not None:
             self._values["ignore_error_codes_matching"] = ignore_error_codes_matching
+        if logging is not None:
+            self._values["logging"] = logging
         if output_paths is not None:
             self._values["output_paths"] = output_paths
         if parameters is not None:
@@ -1472,6 +1546,24 @@ class AwsSdkCall:
         result = self._values.get("ignore_error_codes_matching")
         return typing.cast(typing.Optional[builtins.str], result)
 
+    @builtins.property
+    def logging(self) -> typing.Optional["Logging"]:
+        '''A property used to configure logging during lambda function execution.
+
+        Note: The default Logging configuration is all. This configuration will enable logging on all logged data
+        in the lambda handler. This includes:
+
+        - The event object that is received by the lambda handler
+        - The response received after making a API call
+        - The response object that the lambda handler will return
+        - SDK versioning information
+        - Caught and uncaught errors
+
+        :default: Logging.all()
+        '''
+        result = self._values.get("logging")
+        return typing.cast(typing.Optional["Logging"], result)
+
     @builtins.property
     def output_paths(self) -> typing.Optional[typing.List[builtins.str]]:
         '''Restrict the data returned by the custom resource to specific paths in the API response.
@@ -1534,6 +1626,221 @@ class AwsSdkCall:
         )
 
 
+@jsii.data_type(
+    jsii_type="aws-cdk-lib.custom_resources.LogOptions",
+    jsii_struct_bases=[],
+    name_mapping={
+        "destination": "destination",
+        "include_execution_data": "includeExecutionData",
+        "level": "level",
+    },
+)
+class LogOptions:
+    def __init__(
+        self,
+        *,
+        destination: typing.Optional[_ILogGroup_3c4fa718] = None,
+        include_execution_data: typing.Optional[builtins.bool] = None,
+        level: typing.Optional[_LogLevel_be1990fe] = None,
+    ) -> None:
+        '''Log Options for the state machine.
+
+        :param destination: The log group where the execution history events will be logged. Default: - a new log group will be created
+        :param include_execution_data: Determines whether execution data is included in your log. Default: - false
+        :param level: Defines which category of execution history events are logged. Default: - ERROR
+
+        :exampleMetadata: fixture=_generated
+
+        Example::
+
+            # The code below shows an example of how to instantiate this type.
+            # The values are placeholders you should change.
+            from aws_cdk import aws_logs as logs
+            from aws_cdk import aws_stepfunctions as stepfunctions
+            from aws_cdk import custom_resources
+            
+            # log_group: logs.LogGroup
+            
+            log_options = custom_resources.LogOptions(
+                destination=log_group,
+                include_execution_data=False,
+                level=stepfunctions.LogLevel.OFF
+            )
+        '''
+        if __debug__:
+            type_hints = typing.get_type_hints(_typecheckingstub__2622296f61199d2b10825c21d976c0578e9488ad1b2b7635565f604c598734b7)
+            check_type(argname="argument destination", value=destination, expected_type=type_hints["destination"])
+            check_type(argname="argument include_execution_data", value=include_execution_data, expected_type=type_hints["include_execution_data"])
+            check_type(argname="argument level", value=level, expected_type=type_hints["level"])
+        self._values: typing.Dict[builtins.str, typing.Any] = {}
+        if destination is not None:
+            self._values["destination"] = destination
+        if include_execution_data is not None:
+            self._values["include_execution_data"] = include_execution_data
+        if level is not None:
+            self._values["level"] = level
+
+    @builtins.property
+    def destination(self) -> typing.Optional[_ILogGroup_3c4fa718]:
+        '''The log group where the execution history events will be logged.
+
+        :default: - a new log group will be created
+        '''
+        result = self._values.get("destination")
+        return typing.cast(typing.Optional[_ILogGroup_3c4fa718], result)
+
+    @builtins.property
+    def include_execution_data(self) -> typing.Optional[builtins.bool]:
+        '''Determines whether execution data is included in your log.
+
+        :default: - false
+        '''
+        result = self._values.get("include_execution_data")
+        return typing.cast(typing.Optional[builtins.bool], result)
+
+    @builtins.property
+    def level(self) -> typing.Optional[_LogLevel_be1990fe]:
+        '''Defines which category of execution history events are logged.
+
+        :default: - ERROR
+        '''
+        result = self._values.get("level")
+        return typing.cast(typing.Optional[_LogLevel_be1990fe], result)
+
+    def __eq__(self, rhs: typing.Any) -> builtins.bool:
+        return isinstance(rhs, self.__class__) and rhs._values == self._values
+
+    def __ne__(self, rhs: typing.Any) -> builtins.bool:
+        return not (rhs == self)
+
+    def __repr__(self) -> str:
+        return "LogOptions(%s)" % ", ".join(
+            k + "=" + repr(v) for k, v in self._values.items()
+        )
+
+
+class Logging(
+    metaclass=jsii.JSIIAbstractClass,
+    jsii_type="aws-cdk-lib.custom_resources.Logging",
+):
+    '''A class used to configure Logging during AwsCustomResource SDK calls.
+
+    :exampleMetadata: infused
+
+    Example::
+
+        get_parameter = cr.AwsCustomResource(self, "GetParameter",
+            on_update=cr.AwsSdkCall(
+                service="SSM",
+                action="GetParameter",
+                parameters={
+                    "Name": "my-parameter",
+                    "WithDecryption": True
+                },
+                physical_resource_id=cr.PhysicalResourceId.of(Date.now().to_string()),
+                logging=cr.Logging.with_data_hidden()
+            ),
+            policy=cr.AwsCustomResourcePolicy.from_sdk_calls(
+                resources=cr.AwsCustomResourcePolicy.ANY_RESOURCE
+            )
+        )
+    '''
+
+    def __init__(
+        self,
+        *,
+        log_api_response_data: typing.Optional[builtins.bool] = None,
+    ) -> None:
+        '''
+        :param log_api_response_data: Whether or not to log data associated with the API call response. Default: true
+        '''
+        props = LoggingProps(log_api_response_data=log_api_response_data)
+
+        jsii.create(self.__class__, self, [props])
+
+    @jsii.member(jsii_name="all")
+    @builtins.classmethod
+    def all(cls) -> "Logging":
+        '''Enables logging of all logged data in the lambda handler.
+
+        This includes the event object, the API call response, all fields in the response object
+        returned by the lambda, and any errors encountered.
+        '''
+        return typing.cast("Logging", jsii.sinvoke(cls, "all", []))
+
+    @jsii.member(jsii_name="withDataHidden")
+    @builtins.classmethod
+    def with_data_hidden(cls) -> "Logging":
+        '''Hides logging of data associated with the API call response.
+
+        This includes hiding the raw API
+        call response and the ``Data`` field associated with the lambda handler response.
+        '''
+        return typing.cast("Logging", jsii.sinvoke(cls, "withDataHidden", []))
+
+
+class _LoggingProxy(Logging):
+    pass
+
+# Adding a "__jsii_proxy_class__(): typing.Type" function to the abstract class
+typing.cast(typing.Any, Logging).__jsii_proxy_class__ = lambda : _LoggingProxy
+
+
+@jsii.data_type(
+    jsii_type="aws-cdk-lib.custom_resources.LoggingProps",
+    jsii_struct_bases=[],
+    name_mapping={"log_api_response_data": "logApiResponseData"},
+)
+class LoggingProps:
+    def __init__(
+        self,
+        *,
+        log_api_response_data: typing.Optional[builtins.bool] = None,
+    ) -> None:
+        '''Properties used to initialize Logging.
+
+        :param log_api_response_data: Whether or not to log data associated with the API call response. Default: true
+
+        :exampleMetadata: fixture=_generated
+
+        Example::
+
+            # The code below shows an example of how to instantiate this type.
+            # The values are placeholders you should change.
+            from aws_cdk import custom_resources
+            
+            logging_props = custom_resources.LoggingProps(
+                log_api_response_data=False
+            )
+        '''
+        if __debug__:
+            type_hints = typing.get_type_hints(_typecheckingstub__da0d46a1eb4b059395d06daee7dcb9417dffd0b4cf8e8942cbe0a6549f0faf4b)
+            check_type(argname="argument log_api_response_data", value=log_api_response_data, expected_type=type_hints["log_api_response_data"])
+        self._values: typing.Dict[builtins.str, typing.Any] = {}
+        if log_api_response_data is not None:
+            self._values["log_api_response_data"] = log_api_response_data
+
+    @builtins.property
+    def log_api_response_data(self) -> typing.Optional[builtins.bool]:
+        '''Whether or not to log data associated with the API call response.
+
+        :default: true
+        '''
+        result = self._values.get("log_api_response_data")
+        return typing.cast(typing.Optional[builtins.bool], result)
+
+    def __eq__(self, rhs: typing.Any) -> builtins.bool:
+        return isinstance(rhs, self.__class__) and rhs._values == self._values
+
+    def __ne__(self, rhs: typing.Any) -> builtins.bool:
+        return not (rhs == self)
+
+    def __repr__(self) -> str:
+        return "LoggingProps(%s)" % ", ".join(
+            k + "=" + repr(v) for k, v in self._values.items()
+        )
+
+
 class PhysicalResourceId(
     metaclass=jsii.JSIIMeta,
     jsii_type="aws-cdk-lib.custom_resources.PhysicalResourceId",
@@ -1706,6 +2013,7 @@ class Provider(
         id: builtins.str,
         *,
         on_event_handler: _IFunction_6adb0ab8,
+        disable_waiter_state_machine_logging: typing.Optional[builtins.bool] = None,
         is_complete_handler: typing.Optional[_IFunction_6adb0ab8] = None,
         log_group: typing.Optional[_ILogGroup_3c4fa718] = None,
         log_retention: typing.Optional[_RetentionDays_070f99f0] = None,
@@ -1717,11 +2025,13 @@ class Provider(
         total_timeout: typing.Optional[_Duration_4839e8c3] = None,
         vpc: typing.Optional[_IVpc_f30d5663] = None,
         vpc_subnets: typing.Optional[typing.Union[_SubnetSelection_e57d76df, typing.Dict[builtins.str, typing.Any]]] = None,
+        waiter_state_machine_log_options: typing.Optional[typing.Union[LogOptions, typing.Dict[builtins.str, typing.Any]]] = None,
     ) -> None:
         '''
         :param scope: -
         :param id: -
         :param on_event_handler: The AWS Lambda function to invoke for all resource lifecycle operations (CREATE/UPDATE/DELETE). This function is responsible to begin the requested resource operation (CREATE/UPDATE/DELETE) and return any additional properties to add to the event, which will later be passed to ``isComplete``. The ``PhysicalResourceId`` property must be included in the response.
+        :param disable_waiter_state_machine_logging: Whether logging for the waiter state machine is disabled. Default: - false
         :param is_complete_handler: The AWS Lambda function to invoke in order to determine if the operation is complete. This function will be called immediately after ``onEvent`` and then periodically based on the configured query interval as long as it returns ``false``. If the function still returns ``false`` and the alloted timeout has passed, the operation will fail. Default: - provider is synchronous. This means that the ``onEvent`` handler is expected to finish all lifecycle operations within the initial invocation.
         :param log_group: The Log Group used for logging of events emitted by the custom resource's lambda function. Providing a user-controlled log group was rolled out to commercial regions on 2023-11-16. If you are deploying to another type of region, please check regional availability first. Default: - a default log group created by AWS Lambda
         :param log_retention: The number of days framework log events are kept in CloudWatch Logs. When updating this property, unsetting it doesn't remove the log retention policy. To remove the retention policy, set the value to ``INFINITE``. This is a legacy API and we strongly recommend you migrate to ``logGroup`` if you can. ``logGroup`` allows you to create a fully customizable log group and instruct the Lambda function to send logs to it. Default: logs.RetentionDays.INFINITE
@@ -1733,6 +2043,7 @@ class Provider(
         :param total_timeout: Total timeout for the entire operation. The maximum timeout is 1 hour (yes, it can exceed the AWS Lambda 15 minutes) Default: Duration.minutes(30)
         :param vpc: The vpc to provision the lambda functions in. Default: - functions are not provisioned inside a vpc.
         :param vpc_subnets: Which subnets from the VPC to place the lambda functions in. Only used if 'vpc' is supplied. Note: internet access for Lambdas requires a NAT gateway, so picking Public subnets is not allowed. Default: - the Vpc default strategy if not specified
+        :param waiter_state_machine_log_options: 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.
         '''
         if __debug__:
             type_hints = typing.get_type_hints(_typecheckingstub__29415d7bf7977fcf110b77ce69cec309dcf0404601944735020770ddfe2b01a8)
@@ -1740,6 +2051,7 @@ class Provider(
             check_type(argname="argument id", value=id, expected_type=type_hints["id"])
         props = ProviderProps(
             on_event_handler=on_event_handler,
+            disable_waiter_state_machine_logging=disable_waiter_state_machine_logging,
             is_complete_handler=is_complete_handler,
             log_group=log_group,
             log_retention=log_retention,
@@ -1751,6 +2063,7 @@ class Provider(
             total_timeout=total_timeout,
             vpc=vpc,
             vpc_subnets=vpc_subnets,
+            waiter_state_machine_log_options=waiter_state_machine_log_options,
         )
 
         jsii.create(self.__class__, self, [scope, id, props])
@@ -1779,6 +2092,7 @@ class Provider(
     jsii_struct_bases=[],
     name_mapping={
         "on_event_handler": "onEventHandler",
+        "disable_waiter_state_machine_logging": "disableWaiterStateMachineLogging",
         "is_complete_handler": "isCompleteHandler",
         "log_group": "logGroup",
         "log_retention": "logRetention",
@@ -1790,6 +2104,7 @@ class Provider(
         "total_timeout": "totalTimeout",
         "vpc": "vpc",
         "vpc_subnets": "vpcSubnets",
+        "waiter_state_machine_log_options": "waiterStateMachineLogOptions",
     },
 )
 class ProviderProps:
@@ -1797,6 +2112,7 @@ class ProviderProps:
         self,
         *,
         on_event_handler: _IFunction_6adb0ab8,
+        disable_waiter_state_machine_logging: typing.Optional[builtins.bool] = None,
         is_complete_handler: typing.Optional[_IFunction_6adb0ab8] = None,
         log_group: typing.Optional[_ILogGroup_3c4fa718] = None,
         log_retention: typing.Optional[_RetentionDays_070f99f0] = None,
@@ -1808,10 +2124,12 @@ class ProviderProps:
         total_timeout: typing.Optional[_Duration_4839e8c3] = None,
         vpc: typing.Optional[_IVpc_f30d5663] = None,
         vpc_subnets: typing.Optional[typing.Union[_SubnetSelection_e57d76df, typing.Dict[builtins.str, typing.Any]]] = None,
+        waiter_state_machine_log_options: typing.Optional[typing.Union[LogOptions, typing.Dict[builtins.str, typing.Any]]] = None,
     ) -> None:
         '''Initialization properties for the ``Provider`` construct.
 
         :param on_event_handler: The AWS Lambda function to invoke for all resource lifecycle operations (CREATE/UPDATE/DELETE). This function is responsible to begin the requested resource operation (CREATE/UPDATE/DELETE) and return any additional properties to add to the event, which will later be passed to ``isComplete``. The ``PhysicalResourceId`` property must be included in the response.
+        :param disable_waiter_state_machine_logging: Whether logging for the waiter state machine is disabled. Default: - false
         :param is_complete_handler: The AWS Lambda function to invoke in order to determine if the operation is complete. This function will be called immediately after ``onEvent`` and then periodically based on the configured query interval as long as it returns ``false``. If the function still returns ``false`` and the alloted timeout has passed, the operation will fail. Default: - provider is synchronous. This means that the ``onEvent`` handler is expected to finish all lifecycle operations within the initial invocation.
         :param log_group: The Log Group used for logging of events emitted by the custom resource's lambda function. Providing a user-controlled log group was rolled out to commercial regions on 2023-11-16. If you are deploying to another type of region, please check regional availability first. Default: - a default log group created by AWS Lambda
         :param log_retention: The number of days framework log events are kept in CloudWatch Logs. When updating this property, unsetting it doesn't remove the log retention policy. To remove the retention policy, set the value to ``INFINITE``. This is a legacy API and we strongly recommend you migrate to ``logGroup`` if you can. ``logGroup`` allows you to create a fully customizable log group and instruct the Lambda function to send logs to it. Default: logs.RetentionDays.INFINITE
@@ -1823,6 +2141,7 @@ class ProviderProps:
         :param total_timeout: Total timeout for the entire operation. The maximum timeout is 1 hour (yes, it can exceed the AWS Lambda 15 minutes) Default: Duration.minutes(30)
         :param vpc: The vpc to provision the lambda functions in. Default: - functions are not provisioned inside a vpc.
         :param vpc_subnets: Which subnets from the VPC to place the lambda functions in. Only used if 'vpc' is supplied. Note: internet access for Lambdas requires a NAT gateway, so picking Public subnets is not allowed. Default: - the Vpc default strategy if not specified
+        :param waiter_state_machine_log_options: 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.
 
         :exampleMetadata: infused
 
@@ -1844,9 +2163,12 @@ class ProviderProps:
         '''
         if isinstance(vpc_subnets, dict):
             vpc_subnets = _SubnetSelection_e57d76df(**vpc_subnets)
+        if isinstance(waiter_state_machine_log_options, dict):
+            waiter_state_machine_log_options = LogOptions(**waiter_state_machine_log_options)
         if __debug__:
             type_hints = typing.get_type_hints(_typecheckingstub__32b03803ee02437d8d83814282c700ede5633030e4d9f7ebdaf3b9d075b0cbdb)
             check_type(argname="argument on_event_handler", value=on_event_handler, expected_type=type_hints["on_event_handler"])
+            check_type(argname="argument disable_waiter_state_machine_logging", value=disable_waiter_state_machine_logging, expected_type=type_hints["disable_waiter_state_machine_logging"])
             check_type(argname="argument is_complete_handler", value=is_complete_handler, expected_type=type_hints["is_complete_handler"])
             check_type(argname="argument log_group", value=log_group, expected_type=type_hints["log_group"])
             check_type(argname="argument log_retention", value=log_retention, expected_type=type_hints["log_retention"])
@@ -1858,9 +2180,12 @@ class ProviderProps:
             check_type(argname="argument total_timeout", value=total_timeout, expected_type=type_hints["total_timeout"])
             check_type(argname="argument vpc", value=vpc, expected_type=type_hints["vpc"])
             check_type(argname="argument vpc_subnets", value=vpc_subnets, expected_type=type_hints["vpc_subnets"])
+            check_type(argname="argument waiter_state_machine_log_options", value=waiter_state_machine_log_options, expected_type=type_hints["waiter_state_machine_log_options"])
         self._values: typing.Dict[builtins.str, typing.Any] = {
             "on_event_handler": on_event_handler,
         }
+        if disable_waiter_state_machine_logging is not None:
+            self._values["disable_waiter_state_machine_logging"] = disable_waiter_state_machine_logging
         if is_complete_handler is not None:
             self._values["is_complete_handler"] = is_complete_handler
         if log_group is not None:
@@ -1883,6 +2208,8 @@ class ProviderProps:
             self._values["vpc"] = vpc
         if vpc_subnets is not None:
             self._values["vpc_subnets"] = vpc_subnets
+        if waiter_state_machine_log_options is not None:
+            self._values["waiter_state_machine_log_options"] = waiter_state_machine_log_options
 
     @builtins.property
     def on_event_handler(self) -> _IFunction_6adb0ab8:
@@ -1897,6 +2224,15 @@ class ProviderProps:
         assert result is not None, "Required property 'on_event_handler' is missing"
         return typing.cast(_IFunction_6adb0ab8, result)
 
+    @builtins.property
+    def disable_waiter_state_machine_logging(self) -> typing.Optional[builtins.bool]:
+        '''Whether logging for the waiter state machine is disabled.
+
+        :default: - false
+        '''
+        result = self._values.get("disable_waiter_state_machine_logging")
+        return typing.cast(typing.Optional[builtins.bool], result)
+
     @builtins.property
     def is_complete_handler(self) -> typing.Optional[_IFunction_6adb0ab8]:
         '''The AWS Lambda function to invoke in order to determine if the operation is complete.
@@ -2033,6 +2369,15 @@ class ProviderProps:
         result = self._values.get("vpc_subnets")
         return typing.cast(typing.Optional[_SubnetSelection_e57d76df], result)
 
+    @builtins.property
+    def waiter_state_machine_log_options(self) -> typing.Optional[LogOptions]:
+        '''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.
+        '''
+        result = self._values.get("waiter_state_machine_log_options")
+        return typing.cast(typing.Optional[LogOptions], result)
+
     def __eq__(self, rhs: typing.Any) -> builtins.bool:
         return isinstance(rhs, self.__class__) and rhs._values == self._values
 
@@ -2110,16 +2455,278 @@ class SdkCallsPolicyOptions:
         )
 
 
+class WaiterStateMachine(
+    _constructs_77d1e7e8.Construct,
+    metaclass=jsii.JSIIMeta,
+    jsii_type="aws-cdk-lib.custom_resources.WaiterStateMachine",
+):
+    '''A very simple StateMachine construct highly customized to the provider framework.
+
+    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.
+
+    :exampleMetadata: fixture=_generated
+
+    Example::
+
+        # The code below shows an example of how to instantiate this type.
+        # The values are placeholders you should change.
+        import aws_cdk as cdk
+        from aws_cdk import aws_lambda as lambda_
+        from aws_cdk import aws_logs as logs
+        from aws_cdk import aws_stepfunctions as stepfunctions
+        from aws_cdk import custom_resources
+        
+        # function_: lambda.Function
+        # log_group: logs.LogGroup
+        
+        waiter_state_machine = custom_resources.WaiterStateMachine(self, "MyWaiterStateMachine",
+            backoff_rate=123,
+            interval=cdk.Duration.minutes(30),
+            is_complete_handler=function_,
+            max_attempts=123,
+            timeout_handler=function_,
+        
+            # the properties below are optional
+            disable_logging=False,
+            log_options=custom_resources.LogOptions(
+                destination=log_group,
+                include_execution_data=False,
+                level=stepfunctions.LogLevel.OFF
+            )
+        )
+    '''
+
+    def __init__(
+        self,
+        scope: _constructs_77d1e7e8.Construct,
+        id: builtins.str,
+        *,
+        backoff_rate: jsii.Number,
+        interval: _Duration_4839e8c3,
+        is_complete_handler: _IFunction_6adb0ab8,
+        max_attempts: jsii.Number,
+        timeout_handler: _IFunction_6adb0ab8,
+        disable_logging: typing.Optional[builtins.bool] = None,
+        log_options: typing.Optional[typing.Union[LogOptions, typing.Dict[builtins.str, typing.Any]]] = None,
+    ) -> None:
+        '''
+        :param scope: -
+        :param id: -
+        :param backoff_rate: Backoff between attempts.
+        :param interval: The interval to wait between attempts.
+        :param is_complete_handler: The main handler that notifies if the waiter to decide 'complete' or 'incomplete'.
+        :param max_attempts: Number of attempts.
+        :param timeout_handler: The handler to call if the waiter times out and is incomplete.
+        :param disable_logging: Whether logging for the state machine is disabled. Default: - false
+        :param log_options: Defines what execution history events are logged and where they are logged. Default: - A default log group will be created if logging is enabled.
+        '''
+        if __debug__:
+            type_hints = typing.get_type_hints(_typecheckingstub__12427b739f326cdb535d2aaf4a70f10977eec5711902d4e5e395f0b8c9bb184e)
+            check_type(argname="argument scope", value=scope, expected_type=type_hints["scope"])
+            check_type(argname="argument id", value=id, expected_type=type_hints["id"])
+        props = WaiterStateMachineProps(
+            backoff_rate=backoff_rate,
+            interval=interval,
+            is_complete_handler=is_complete_handler,
+            max_attempts=max_attempts,
+            timeout_handler=timeout_handler,
+            disable_logging=disable_logging,
+            log_options=log_options,
+        )
+
+        jsii.create(self.__class__, self, [scope, id, props])
+
+    @jsii.member(jsii_name="grantStartExecution")
+    def grant_start_execution(self, identity: _IGrantable_71c4f5de) -> _Grant_a7ae64f8:
+        '''Grant the given identity permissions on StartExecution of the state machine.
+
+        :param identity: -
+        '''
+        if __debug__:
+            type_hints = typing.get_type_hints(_typecheckingstub__2c3d1c306ca04ebd1194ce4f97bed6aa9510a02067654b39f43a1ecef601e3db)
+            check_type(argname="argument identity", value=identity, expected_type=type_hints["identity"])
+        return typing.cast(_Grant_a7ae64f8, jsii.invoke(self, "grantStartExecution", [identity]))
+
+    @builtins.property
+    @jsii.member(jsii_name="stateMachineArn")
+    def state_machine_arn(self) -> builtins.str:
+        '''The ARN of the state machine.'''
+        return typing.cast(builtins.str, jsii.get(self, "stateMachineArn"))
+
+
+@jsii.data_type(
+    jsii_type="aws-cdk-lib.custom_resources.WaiterStateMachineProps",
+    jsii_struct_bases=[],
+    name_mapping={
+        "backoff_rate": "backoffRate",
+        "interval": "interval",
+        "is_complete_handler": "isCompleteHandler",
+        "max_attempts": "maxAttempts",
+        "timeout_handler": "timeoutHandler",
+        "disable_logging": "disableLogging",
+        "log_options": "logOptions",
+    },
+)
+class WaiterStateMachineProps:
+    def __init__(
+        self,
+        *,
+        backoff_rate: jsii.Number,
+        interval: _Duration_4839e8c3,
+        is_complete_handler: _IFunction_6adb0ab8,
+        max_attempts: jsii.Number,
+        timeout_handler: _IFunction_6adb0ab8,
+        disable_logging: typing.Optional[builtins.bool] = None,
+        log_options: typing.Optional[typing.Union[LogOptions, typing.Dict[builtins.str, typing.Any]]] = None,
+    ) -> None:
+        '''Initialization properties for the ``WaiterStateMachine`` construct.
+
+        :param backoff_rate: Backoff between attempts.
+        :param interval: The interval to wait between attempts.
+        :param is_complete_handler: The main handler that notifies if the waiter to decide 'complete' or 'incomplete'.
+        :param max_attempts: Number of attempts.
+        :param timeout_handler: The handler to call if the waiter times out and is incomplete.
+        :param disable_logging: Whether logging for the state machine is disabled. Default: - false
+        :param log_options: Defines what execution history events are logged and where they are logged. Default: - A default log group will be created if logging is enabled.
+
+        :exampleMetadata: fixture=_generated
+
+        Example::
+
+            # The code below shows an example of how to instantiate this type.
+            # The values are placeholders you should change.
+            import aws_cdk as cdk
+            from aws_cdk import aws_lambda as lambda_
+            from aws_cdk import aws_logs as logs
+            from aws_cdk import aws_stepfunctions as stepfunctions
+            from aws_cdk import custom_resources
+            
+            # function_: lambda.Function
+            # log_group: logs.LogGroup
+            
+            waiter_state_machine_props = custom_resources.WaiterStateMachineProps(
+                backoff_rate=123,
+                interval=cdk.Duration.minutes(30),
+                is_complete_handler=function_,
+                max_attempts=123,
+                timeout_handler=function_,
+            
+                # the properties below are optional
+                disable_logging=False,
+                log_options=custom_resources.LogOptions(
+                    destination=log_group,
+                    include_execution_data=False,
+                    level=stepfunctions.LogLevel.OFF
+                )
+            )
+        '''
+        if isinstance(log_options, dict):
+            log_options = LogOptions(**log_options)
+        if __debug__:
+            type_hints = typing.get_type_hints(_typecheckingstub__569ff1333551048ad82f7261bcf43cbefe118e974cba179165c355fc9347fc13)
+            check_type(argname="argument backoff_rate", value=backoff_rate, expected_type=type_hints["backoff_rate"])
+            check_type(argname="argument interval", value=interval, expected_type=type_hints["interval"])
+            check_type(argname="argument is_complete_handler", value=is_complete_handler, expected_type=type_hints["is_complete_handler"])
+            check_type(argname="argument max_attempts", value=max_attempts, expected_type=type_hints["max_attempts"])
+            check_type(argname="argument timeout_handler", value=timeout_handler, expected_type=type_hints["timeout_handler"])
+            check_type(argname="argument disable_logging", value=disable_logging, expected_type=type_hints["disable_logging"])
+            check_type(argname="argument log_options", value=log_options, expected_type=type_hints["log_options"])
+        self._values: typing.Dict[builtins.str, typing.Any] = {
+            "backoff_rate": backoff_rate,
+            "interval": interval,
+            "is_complete_handler": is_complete_handler,
+            "max_attempts": max_attempts,
+            "timeout_handler": timeout_handler,
+        }
+        if disable_logging is not None:
+            self._values["disable_logging"] = disable_logging
+        if log_options is not None:
+            self._values["log_options"] = log_options
+
+    @builtins.property
+    def backoff_rate(self) -> jsii.Number:
+        '''Backoff between attempts.'''
+        result = self._values.get("backoff_rate")
+        assert result is not None, "Required property 'backoff_rate' is missing"
+        return typing.cast(jsii.Number, result)
+
+    @builtins.property
+    def interval(self) -> _Duration_4839e8c3:
+        '''The interval to wait between attempts.'''
+        result = self._values.get("interval")
+        assert result is not None, "Required property 'interval' is missing"
+        return typing.cast(_Duration_4839e8c3, result)
+
+    @builtins.property
+    def is_complete_handler(self) -> _IFunction_6adb0ab8:
+        '''The main handler that notifies if the waiter to decide 'complete' or 'incomplete'.'''
+        result = self._values.get("is_complete_handler")
+        assert result is not None, "Required property 'is_complete_handler' is missing"
+        return typing.cast(_IFunction_6adb0ab8, result)
+
+    @builtins.property
+    def max_attempts(self) -> jsii.Number:
+        '''Number of attempts.'''
+        result = self._values.get("max_attempts")
+        assert result is not None, "Required property 'max_attempts' is missing"
+        return typing.cast(jsii.Number, result)
+
+    @builtins.property
+    def timeout_handler(self) -> _IFunction_6adb0ab8:
+        '''The handler to call if the waiter times out and is incomplete.'''
+        result = self._values.get("timeout_handler")
+        assert result is not None, "Required property 'timeout_handler' is missing"
+        return typing.cast(_IFunction_6adb0ab8, result)
+
+    @builtins.property
+    def disable_logging(self) -> typing.Optional[builtins.bool]:
+        '''Whether logging for the state machine is disabled.
+
+        :default: - false
+        '''
+        result = self._values.get("disable_logging")
+        return typing.cast(typing.Optional[builtins.bool], result)
+
+    @builtins.property
+    def log_options(self) -> typing.Optional[LogOptions]:
+        '''Defines what execution history events are logged and where they are logged.
+
+        :default: - A default log group will be created if logging is enabled.
+        '''
+        result = self._values.get("log_options")
+        return typing.cast(typing.Optional[LogOptions], result)
+
+    def __eq__(self, rhs: typing.Any) -> builtins.bool:
+        return isinstance(rhs, self.__class__) and rhs._values == self._values
+
+    def __ne__(self, rhs: typing.Any) -> builtins.bool:
+        return not (rhs == self)
+
+    def __repr__(self) -> str:
+        return "WaiterStateMachineProps(%s)" % ", ".join(
+            k + "=" + repr(v) for k, v in self._values.items()
+        )
+
+
 __all__ = [
     "AwsCustomResource",
     "AwsCustomResourcePolicy",
     "AwsCustomResourceProps",
     "AwsSdkCall",
+    "LogOptions",
+    "Logging",
+    "LoggingProps",
     "PhysicalResourceId",
     "PhysicalResourceIdReference",
     "Provider",
     "ProviderProps",
     "SdkCallsPolicyOptions",
+    "WaiterStateMachine",
+    "WaiterStateMachineProps",
 ]
 
 publication.publish()
@@ -2191,6 +2798,7 @@ def _typecheckingstub__af7bb124668b93c6ce7d641df2daeabfe424e271742385a76e7e56ec9
     api_version: typing.Optional[builtins.str] = None,
     assumed_role_arn: typing.Optional[builtins.str] = None,
     ignore_error_codes_matching: typing.Optional[builtins.str] = None,
+    logging: typing.Optional[Logging] = None,
     output_paths: typing.Optional[typing.Sequence[builtins.str]] = None,
     parameters: typing.Any = None,
     physical_resource_id: typing.Optional[PhysicalResourceId] = None,
@@ -2199,6 +2807,22 @@ def _typecheckingstub__af7bb124668b93c6ce7d641df2daeabfe424e271742385a76e7e56ec9
     """Type checking stubs"""
     pass
 
+def _typecheckingstub__2622296f61199d2b10825c21d976c0578e9488ad1b2b7635565f604c598734b7(
+    *,
+    destination: typing.Optional[_ILogGroup_3c4fa718] = None,
+    include_execution_data: typing.Optional[builtins.bool] = None,
+    level: typing.Optional[_LogLevel_be1990fe] = None,
+) -> None:
+    """Type checking stubs"""
+    pass
+
+def _typecheckingstub__da0d46a1eb4b059395d06daee7dcb9417dffd0b4cf8e8942cbe0a6549f0faf4b(
+    *,
+    log_api_response_data: typing.Optional[builtins.bool] = None,
+) -> None:
+    """Type checking stubs"""
+    pass
+
 def _typecheckingstub__6baa8764ccdf77f11bd8f80af9fafec69f56b719c1a237caae55c7f988e174b6(
     response_path: builtins.str,
 ) -> None:
@@ -2222,6 +2846,7 @@ def _typecheckingstub__29415d7bf7977fcf110b77ce69cec309dcf0404601944735020770ddf
     id: builtins.str,
     *,
     on_event_handler: _IFunction_6adb0ab8,
+    disable_waiter_state_machine_logging: typing.Optional[builtins.bool] = None,
     is_complete_handler: typing.Optional[_IFunction_6adb0ab8] = None,
     log_group: typing.Optional[_ILogGroup_3c4fa718] = None,
     log_retention: typing.Optional[_RetentionDays_070f99f0] = None,
@@ -2233,6 +2858,7 @@ def _typecheckingstub__29415d7bf7977fcf110b77ce69cec309dcf0404601944735020770ddf
     total_timeout: typing.Optional[_Duration_4839e8c3] = None,
     vpc: typing.Optional[_IVpc_f30d5663] = None,
     vpc_subnets: typing.Optional[typing.Union[_SubnetSelection_e57d76df, typing.Dict[builtins.str, typing.Any]]] = None,
+    waiter_state_machine_log_options: typing.Optional[typing.Union[LogOptions, typing.Dict[builtins.str, typing.Any]]] = None,
 ) -> None:
     """Type checking stubs"""
     pass
@@ -2240,6 +2866,7 @@ def _typecheckingstub__29415d7bf7977fcf110b77ce69cec309dcf0404601944735020770ddf
 def _typecheckingstub__32b03803ee02437d8d83814282c700ede5633030e4d9f7ebdaf3b9d075b0cbdb(
     *,
     on_event_handler: _IFunction_6adb0ab8,
+    disable_waiter_state_machine_logging: typing.Optional[builtins.bool] = None,
     is_complete_handler: typing.Optional[_IFunction_6adb0ab8] = None,
     log_group: typing.Optional[_ILogGroup_3c4fa718] = None,
     log_retention: typing.Optional[_RetentionDays_070f99f0] = None,
@@ -2251,6 +2878,7 @@ def _typecheckingstub__32b03803ee02437d8d83814282c700ede5633030e4d9f7ebdaf3b9d07
     total_timeout: typing.Optional[_Duration_4839e8c3] = None,
     vpc: typing.Optional[_IVpc_f30d5663] = None,
     vpc_subnets: typing.Optional[typing.Union[_SubnetSelection_e57d76df, typing.Dict[builtins.str, typing.Any]]] = None,
+    waiter_state_machine_log_options: typing.Optional[typing.Union[LogOptions, typing.Dict[builtins.str, typing.Any]]] = None,
 ) -> None:
     """Type checking stubs"""
     pass
@@ -2261,3 +2889,37 @@ def _typecheckingstub__0cd00e8add38e42b6c4d7db0390a899ccaf5bbe0367bfb387986125da
 ) -> None:
     """Type checking stubs"""
     pass
+
+def _typecheckingstub__12427b739f326cdb535d2aaf4a70f10977eec5711902d4e5e395f0b8c9bb184e(
+    scope: _constructs_77d1e7e8.Construct,
+    id: builtins.str,
+    *,
+    backoff_rate: jsii.Number,
+    interval: _Duration_4839e8c3,
+    is_complete_handler: _IFunction_6adb0ab8,
+    max_attempts: jsii.Number,
+    timeout_handler: _IFunction_6adb0ab8,
+    disable_logging: typing.Optional[builtins.bool] = None,
+    log_options: typing.Optional[typing.Union[LogOptions, typing.Dict[builtins.str, typing.Any]]] = None,
+) -> None:
+    """Type checking stubs"""
+    pass
+
+def _typecheckingstub__2c3d1c306ca04ebd1194ce4f97bed6aa9510a02067654b39f43a1ecef601e3db(
+    identity: _IGrantable_71c4f5de,
+) -> None:
+    """Type checking stubs"""
+    pass
+
+def _typecheckingstub__569ff1333551048ad82f7261bcf43cbefe118e974cba179165c355fc9347fc13(
+    *,
+    backoff_rate: jsii.Number,
+    interval: _Duration_4839e8c3,
+    is_complete_handler: _IFunction_6adb0ab8,
+    max_attempts: jsii.Number,
+    timeout_handler: _IFunction_6adb0ab8,
+    disable_logging: typing.Optional[builtins.bool] = None,
+    log_options: typing.Optional[typing.Union[LogOptions, typing.Dict[builtins.str, typing.Any]]] = None,
+) -> None:
+    """Type checking stubs"""
+    pass