Registry / aws / crhelper

crhelper

JSON →
library2.0.12pypypiunverified

crhelper simplifies authoring CloudFormation Custom Resources, implementing best practices for handling responses to CloudFormation, exception and timeout trapping, and detailed configurable logging. It is an open-source project actively maintained by AWS CloudFormation. The current version is 2.0.12, with regular updates to its PyPI package.

pip install crhelper
INSTALL
IMPORT
SIG · CRHELPER
C
crhelper
awspythonv2.0.12
Install
1.5s avg
Import
Disk
65MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.0.12 · 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.940 runs
installs and imports cleanly · install 0.0s · import 0.000s · 65.6MB
glibc
py 3.103.940 runs
installs and imports cleanly · install 1.5s · import 0.000s · 18MB
65MB installed
● package 65MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

CfnResource
from crhelper import CfnResource
from crhelper import CfnResource

This quickstart demonstrates a typical `crhelper` integration in an AWS Lambda function. It initializes `CfnResource` and defines handler functions for `Create`, `Update`, and `Delete` events using decorators. It also includes a basic local test setup.

import logging import os from crhelper import CfnResource logger = logging.getLogger(__name__) # Initialise the helper, all inputs are optional helper = CfnResource(json_logging=True, log_level='INFO', boto_level='CRITICAL') # Example function to be called by the helper @helper.create @helper.update def create_update_resource(event, context): logger.info("Got Create/Update event") # Access properties from the CloudFormation event my_property = event['ResourceProperties'].get('MyProperty', 'default') logger.info(f"MyProperty: {my_property}") # Simulate creating/updating a resource physical_resource_id = f"my-custom-resource-{my_property}" # Optionally return an ID that will be used for the PhysicalResourceId # if None is returned, an ID will be generated. The value is used in subsequent Update/Delete events. helper.Data['Result'] = 'Success' return physical_resource_id @helper.delete def delete_resource(event, context): logger.info("Got Delete event") # Access the PhysicalResourceId of the resource to be deleted physical_resource_id = event.get('PhysicalResourceId') logger.info(f"Deleting resource: {physical_resource_id}") # Simulate deleting the resource # No return value needed for delete def handler(event, context): logger.info("Lambda handler invoked") helper(event, context) # Example of how to run this locally for testing purposes (outside Lambda) if __name__ == '__main__': # Mock event and context for local testing mock_event = { 'RequestType': 'Create', 'ResponseURL': 'http://example.com/', 'StackId': 'arn:aws:cloudformation:us-east-1:123456789012:stack/MyStack/UUID', 'RequestId': 'uniqueid123', 'LogicalResourceId': 'MyCustomResource', 'ResourceType': 'Custom::MyResource', 'ResourceProperties': { 'ServiceToken': 'arn:aws:lambda:us-east-1:123456789012:function:my-cr-lambda', 'MyProperty': 'test-value' } } mock_context = type('Context', (object,), { 'function_name': 'test-func', 'invoked_function_arn': 'arn:aws:lambda:us-east-1:123456789012:function:test-func', 'aws_request_id': 'reqid123', 'log_group_name': '/aws/lambda/test-func', 'log_stream_name': '2026/04/14/[$LATEST]uuid', 'memory_limit_in_mb': '128', 'get_remaining_time_in_millis': lambda: 60000 # Mock 60 seconds remaining })() print("--- Simulating Create Event ---") # In a real scenario, helper would send response to ResponseURL # For local test, we just call the handler and check logs handler(mock_event, mock_context) print("\n--- Simulating Update Event ---") mock_event['RequestType'] = 'Update' mock_event['PhysicalResourceId'] = 'my-custom-resource-test-value' # Must be present for Update/Delete handler(mock_event, mock_context) print("\n--- Simulating Delete Event ---") mock_event['RequestType'] = 'Delete' handler(mock_event, mock_context)
Debug
Known issues
gotchacrhelper is explicitly not intended for use with AWS CDK's `Provider` construct. Using it this way can lead to unexpected behavior or conflicts.
fix
When using AWS CDK, define custom resources directly using `CustomResource` and pass the Lambda function's ARN as the `ServiceToken` instead of relying on the `Provider` construct.
affects: 2.0.0+
gotchaWhen testing locally (e.g., with `sam local`), `crhelper` attempts to send a response to CloudFormation, which fails if no actual stack or pre-signed URL exists. This can obscure actual business logic errors.
fix
Mock the `crhelper._send_response` method during local testing to prevent external calls. Alternatively, ensure the `AWS_SAM_LOCAL` environment variable is set to enable internal `crhelper` logic that may prevent actual network calls for responses.
affects: All versions
gotchaIf a `create` event handler fails (e.g., due to `helper.init_failure`), `crhelper` might not generate or propagate a `PhysicalResourceId` correctly, which can lead to CloudFormation rollback issues (e.g., attempting a `delete` on a non-existent resource).
fix
Ensure that if `init_failure` is called during a `create` event, the `PhysicalResourceId` is explicitly set to `None` if no resource was truly created, or provide a meaningful, idempotent `PhysicalResourceId` if a partial creation occurred that needs cleanup.
affects: All versions
gotchaEnabling the polling feature for long-running custom resources requires additional IAM permissions for the Lambda function's execution role to manage Lambda permissions and EventBridge rules. Failing to provide these will cause polling to fail.
fix
Attach the necessary IAM policy to the Lambda function's role as described in the `crhelper` documentation, including actions like `lambda:AddPermission`, `events:PutRule`, `events:DeleteRule`, `events:PutTargets`, and `events:RemoveTargets` on `*` resources.
affects: All versions
Upgrade
Version history
2.0.12latest on PyPI · released Oct 29, 2024
Audit
Dependencies
boto3requiredcrhelper leverages boto3 internally for AWS service interactions, and most custom resource logic will require it for resource management.
Agent activity
13 hits · last 30 days
node
12
Resources
crhelper — pip install crhelper · libregistry