aws-cdk-lib 2.137.0__py3-none-any.whl → 2.138.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
@@ -778,25 +850,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 +1130,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 +1388,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 +1404,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 +1417,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 +1446,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 +1461,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 +1544,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 +1624,128 @@ class AwsSdkCall:
         )
 
 
+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",
@@ -2115,6 +2327,8 @@ __all__ = [
     "AwsCustomResourcePolicy",
     "AwsCustomResourceProps",
     "AwsSdkCall",
+    "Logging",
+    "LoggingProps",
     "PhysicalResourceId",
     "PhysicalResourceIdReference",
     "Provider",
@@ -2191,6 +2405,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 +2414,13 @@ def _typecheckingstub__af7bb124668b93c6ce7d641df2daeabfe424e271742385a76e7e56ec9
     """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:

{aws_cdk_lib-2.137.0.dist-info → aws_cdk_lib-2.138.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: aws-cdk-lib
-Version: 2.137.0
+Version: 2.138.0
 Summary: Version 2 of the AWS Cloud Development Kit library
 Home-page: https://github.com/aws/aws-cdk
 Author: Amazon Web Services
@@ -23,9 +23,9 @@ License-File: LICENSE
 License-File: NOTICE
 Requires-Dist: aws-cdk.asset-awscli-v1 <3.0.0,>=2.2.202
 Requires-Dist: aws-cdk.asset-kubectl-v20 <3.0.0,>=2.1.2
-Requires-Dist: aws-cdk.asset-node-proxy-agent-v6 <3.0.0,>=2.0.1
+Requires-Dist: aws-cdk.asset-node-proxy-agent-v6 <3.0.0,>=2.0.3
 Requires-Dist: constructs <11.0.0,>=10.0.0
-Requires-Dist: jsii <2.0.0,>=1.96.0
+Requires-Dist: jsii <2.0.0,>=1.97.0
 Requires-Dist: publication >=0.0.3
 Requires-Dist: typeguard ~=2.13.3