Registry /
aws / aws-cdk-custom-resources
Install & Compatibility
Where this runs
tested against v1.204.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 56.5MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 7.1s · import 0.000s · 57MB
58MB installed
● package 58MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AwsCustomResource
✓ from aws_cdk.custom_resources import AwsCustomResource
✗ from aws_cdk.aws_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.
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()
Debug
Known issues
breakingThis 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.fixFor 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`).
affects: All versions of `aws-cdk-custom-resources` (as it's a V1 package).
gotchaCustom 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.fixAlways 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.
affects: All.
gotchaEnsuring 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.fixDesign `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. affects: All.
gotchaLambda-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.fixEnsure 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.
affects: All.
Errors
Common errors & fixes
CloudFormation Custom Resource failed. See details in CloudWatch log group /aws/lambda/...
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.
fixNavigate 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'
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.
fixEnsure `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.)
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.
fixEnsure 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.
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.
fixFor `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. Upgrade
Version history
1.204.0latest on PyPI · released Jun 19, 2023
Audit
Dependencies
aws-cdk.corerequiredCore CDK constructs and app lifecycle, required for all CDK applications.
jsiirequiredRuntime for JSII-generated Python modules.