AWS CDK Custom Resources (v1)

Common errors

• CloudFormation Custom Resource failed. See details in CloudWatch log group /aws/lambda/...

  cause This generic error typically indicates an issue within the custom resource's execution, most commonly insufficient IAM permissions for the underlying SDK calls or an error in the custom resource's handler code.
  fix Navigate to the specified CloudWatch log group in the AWS console. Examine the logs for specific error messages (e.g., `AccessDeniedException`, Python tracebacks) and adjust IAM policies or fix the custom resource's handler code accordingly.

• ModuleNotFoundError: No module named 'aws_cdk.custom_resources'

  cause The `aws-cdk-custom-resources` package (or the monolithic `aws-cdk` for V2 projects) is not installed in the active Python environment, or there's a package version conflict.
  fix Ensure `pip install aws-cdk-custom-resources` has been successfully run within your virtual environment. Verify that the correct virtual environment is active. If migrating to V2, ensure `pip install aws-cdk` is used instead and this V1 package is removed.

• TypeError: Object of type Decimal is not JSON serializable (or similar for datetime, etc.)

  cause A custom resource handler (especially Lambda-backed) attempted to return a non-JSON-serializable object in its response's `Data` field, or an SDK call's parameters were not correctly formatted.
  fix Ensure all data passed in the custom resource's response is JSON serializable. Convert objects like `Decimal` or `datetime` to strings before including them in the response. For `AwsCustomResource`, verify parameters passed to SDK actions adhere to AWS API specifications.

• Custom resource handler did not return a physical resource ID in the response.

  cause CloudFormation requires a unique and stable `PhysicalResourceId` to track custom resources. This error occurs when the custom resource (e.g., a Lambda-backed provider or an `AwsCustomResource` without a `physical_resource_id` parameter) fails to provide this identifier.
  fix For `AwsCustomResource`, always set `physical_resource_id` using `PhysicalResourceId.of('your-stable-unique-id')`. For Lambda-backed `CustomResource`, ensure the Lambda function's response JSON includes a `PhysicalResourceId` field.

Warnings

• breaking This package is part of AWS CDK v1, which is in maintenance mode and no longer receives new features. While the `aws_cdk.custom_resources` module exists in CDK v2, using this V1 package (`aws-cdk-custom-resources`) alongside a CDK v2 project can lead to dependency conflicts and unexpected behavior due to different core libraries and versioning strategies.
  Fix: For new projects, prefer installing `aws-cdk` (the monolithic v2 package) and utilize its bundled `custom_resources` module directly. For existing V1 projects, ensure all `aws-cdk.*` packages are consistently pinned to compatible V1 versions (e.g., all `1.x.y`).
• gotcha Custom Resources, especially `AwsCustomResource`, require careful IAM permissions. If the underlying SDK call fails due to insufficient permissions, CloudFormation deployment will often fail with a generic 'Custom Resource failed' message, and details are only found in CloudWatch logs.
  Fix: Always attach `AwsCustomResourcePolicy.from_sdk_calls()` or a specific `iam.PolicyStatement` to the custom resource's execution role. This policy must grant the *exact* permissions needed for the SDK calls being made. Check CloudWatch logs (usually under `/aws/lambda/`) for precise `AccessDeniedException` messages.
• gotcha Ensuring a stable and unique `PhysicalResourceId` is crucial for custom resources, particularly for `on_update` and `on_delete` operations. A changing `PhysicalResourceId` or one that is not unique across deployments can lead to resource abandonment, orphaned resources, or unintended side effects during updates or rollbacks.
  Fix: Design `on_create`, `on_update`, and `on_delete` handlers to be idempotent. Always use `PhysicalResourceId.of('a-stable-unique-id')` that uniquely identifies the *managed external resource* (not the custom resource itself) and remains constant across deployments for the same logical resource.
• gotcha Lambda-backed custom resources (using `CustomResource` with a `provider`) must return a specific JSON response format to CloudFormation within the specified timeout. Incorrect formats or exceeding the timeout will cause the CloudFormation deployment to fail.
  Fix: Ensure your Lambda provider function returns a valid CloudFormation custom resource response object. For Python, the `cfnresponse` library is commonly used. Monitor Lambda logs for errors and ensure the function completes within the `timeout` specified for the Custom Resource.

Install

• pip install aws-cdk-custom-resources Install AWS CDK Custom Resources v1

Imports

• AwsCustomResource
  wrong:

  from aws_cdk.aws_custom_resources import AwsCustomResource

  correct:

  from aws_cdk.custom_resources import AwsCustomResource

  Common misspelling of the module path.
• AwsCustomResourcePolicy

  from aws_cdk.custom_resources import AwsCustomResourcePolicy

• PhysicalResourceId

  from aws_cdk.custom_resources import PhysicalResourceId

• CustomResource

  from aws_cdk.custom_resources import CustomResource

  Used for Lambda-backed custom resources where you provide the provider function.

Quickstart

This quickstart demonstrates how to use `AwsCustomResource` to make a direct AWS SDK call (listing objects in an S3 bucket) from a CDK stack. This construct simplifies interaction with AWS APIs that don't have direct CloudFormation support. Remember that `aws-cdk-custom-resources` is a V1 package.

import os
from aws_cdk import (
    Stack,
    App,
    Duration,
)
from aws_cdk.aws_s3 import Bucket
from aws_cdk.custom_resources import (
    AwsCustomResource,
    AwsCustomResourcePolicy,
    PhysicalResourceId,
)
from constructs import Construct

class MyCustomResourceStack(Stack):
    def __init__(self, scope: Construct, id: str, **kwargs) -> None:
        super().__init__(scope, id, **kwargs)

        # Create an S3 bucket to interact with
        bucket = Bucket(self, "MyCustomResourceBucket")

        # Use AwsCustomResource to call S3 listObjectsV2 API
        # This construct makes direct SDK calls from CloudFormation
        s3_list_caller = AwsCustomResource(
            self,
            "S3ListCaller",
            on_create={
                "service": "S3",
                "action": "listObjectsV2",
                "parameters": {
                    "Bucket": bucket.bucket_name,
                },
                "physical_resource_id": PhysicalResourceId.of(f"my-s3-lister-{bucket.bucket_name}"),
            },
            on_update={
                "service": "S3",
                "action": "listObjectsV2",
                "parameters": {
                    "Bucket": bucket.bucket_name,
                },
                "physical_resource_id": PhysicalResourceId.of(f"my-s3-lister-{bucket.bucket_name}"),
            },
            # on_delete is optional; here it's not needed for a read-only action
            # For resources that create external entities, on_delete is critical for cleanup.
            policy=AwsCustomResourcePolicy.from_sdk_calls(
                resources=[bucket.bucket_arn, bucket.bucket_arn + "/*"]
            ),
            timeout=Duration.minutes(2)
        )

        # You can retrieve outputs from the SDK call result
        # For listObjectsV2, it returns a list of contents. Here, we just get the Request ID.
        request_id = s3_list_caller.get_response_field("ResponseMetadata.RequestId")
        # In a real application, you might use this output, e.g., CfnOutput(self, "RequestId", value=request_id)

app = App()
MyCustomResourceStack(app, "MyCustomResourceExampleStack")
app.synth()