Registry / aws / aws-cdk-custom-resources

aws-cdk-custom-resources

JSON →
library1.204.0pypypi✓ verified 85d ago

The `aws-cdk-custom-resources` library, currently at version `1.204.0`, provides constructs within the AWS Cloud Development Kit (CDK) for implementing custom resources in CloudFormation. These resources extend CloudFormation capabilities by integrating with other AWS services or even third-party APIs. This package is part of the CDK v1 ecosystem, which is now in maintenance mode, receiving only critical updates. Users are encouraged to migrate to AWS CDK v2 for new development.

pip install aws-cdk-custom-resources
INSTALL
IMPORT
SIG · AWS-CDK-CUSTOM-RES
A
aws-cdk-custom-resources
awspythonv1.204.0
Install
7.1s avg
Import
Disk
58MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 56.5MB
glibc
py 3.103.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.
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`).
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.
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.
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.
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.
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.
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.
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.
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'
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.)
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.
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.
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.
Agent activity
17 hits · last 30 days
node
14
OpenAI (training)
2
Resources
aws-cdk-custom-resources — pip install aws-cdk-custom-resources · libregistry