Skip to main content

crhelper simplifies authoring CloudFormation Custom Resources

Project description

Custom Resource Helper

Simplify best practice Custom Resource creation, sending responses to CloudFormation and providing exception, timeout trapping, and detailed configurable logging.

PyPI Version Python Versions Build Status Test Coverage

Features

  • Dead simple to use, reduces the complexity of writing a CloudFormation custom resource
  • Guarantees that CloudFormation will get a response even if an exception is raised
  • Returns meaningful errors to CloudFormation Stack events in the case of a failure
  • Polling enables run times longer than the lambda 15 minute limit
  • JSON logging that includes request id's, stack id's and request type to assist in tracing logs relevant to a particular CloudFormation event
  • Catches function timeouts and sends CloudFormation a failure response

Installation

Install into the root folder of your lambda function

cd my-lambda-function/
pip install crhelper -t .

Example Usage

from __future__ import print_function
from crhelper import CfnResource
import logging

logger = logging.getLogger(__name__)
# Initialise the helper, all inputs are optional, this example shows the defaults
helper = CfnResource(json_logging=False, log_level='DEBUG', boto_level='CRITICAL')

try:
    ## Init code goes here
    pass
except Exception as e:
    helper.init_failure(e)


@helper.create
def create(event, context):
    logger.info("Got Create")
    # Optionally return an ID that will be used for the resource PhysicalResourceId, 
    # if None is returned an ID will be generated. If a poll_create function is defined 
    # return value is placed into the poll event as event['CrHelperData']['PhysicalResourceId']
    #
    # To add response data update the helper.Data dict
    # If poll is enabled data is placed into poll event as event['CrHelperData']
    helper.Data.update({"test": "testdata"})
    return "MyResourceId"


@helper.update
def update(event, context):
    logger.info("Got Update")
    # If the update resulted in a new resource being created, return an id for the new resource. CloudFormation will send
    # a delete event with the old id when stack update completes


@helper.delete
def delete(event, context):
    logger.info("Got Delete")
    # Delete never returns anything. Should not fail if the underlying resources are already deleted. Desired state.


@helper.poll_create
def poll_create(event, context):
    logger.info("Got create poll")
    # Return a resource id or True to indicate that creation is complete. if True is returned an id will be generated
    return True


def handler(event, context):
    helper(event, context)

Polling

If you need longer than the max runtime of 15 minutes, you can enable polling by adding additional decorators for poll_create, poll_update or poll_delete. When a poll function is defined for create/update/delete the function will not send a response to CloudFormation and instead a CloudWatch Events schedule will be created to re-invoke the lambda function every 2 minutes. When the function is invoked the matching @helper.poll_ function will be called, logic to check for completion should go here, if the function returns None then the schedule will run again in 2 minutes. Once complete either return a PhysicalResourceID or True to have one generated. The schedule will be deleted and a response sent back to CloudFormation. If you use polling the following additional IAM policy must be attached to the function's IAM role:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "lambda:AddPermission",
        "lambda:RemovePermission",
        "events:PutRule",
        "events:DeleteRule",
        "events:PutTargets",
        "events:RemoveTargets"
      ],
      "Resource": "*"
    }
  ]
}

Credits

Decorator implementation inspired by https://github.com/ryansb/cfn-wrapper-python

Log implementation inspired by https://gitlab.com/hadrien/aws_lambda_logging

License

This library is licensed under the Apache 2.0 License.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

crhelper-2.0.3.tar.gz (10.7 kB view details)

Uploaded Source

Built Distribution

crhelper-2.0.3-py3-none-any.whl (15.8 kB view details)

Uploaded Python 3

File details

Details for the file crhelper-2.0.3.tar.gz.

File metadata

  • Download URL: crhelper-2.0.3.tar.gz
  • Upload date:
  • Size: 10.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.13.0 pkginfo/1.5.0.1 requests/2.21.0 setuptools/40.8.0 requests-toolbelt/0.9.1 tqdm/4.32.1 CPython/3.7.3

File hashes

Hashes for crhelper-2.0.3.tar.gz
Algorithm Hash digest
SHA256 cb6f81b503e1fb215aba381d964d484dbd45c2c93950090be3b62f6b37f45a19
MD5 2c831803cc6987ead7f43ae3174308f1
BLAKE2b-256 410ed8ae2b11746348057394f5c12f512e96c997672b872fbbe8aa52cdcfb5f2

See more details on using hashes here.

File details

Details for the file crhelper-2.0.3-py3-none-any.whl.

File metadata

  • Download URL: crhelper-2.0.3-py3-none-any.whl
  • Upload date:
  • Size: 15.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.13.0 pkginfo/1.5.0.1 requests/2.21.0 setuptools/40.8.0 requests-toolbelt/0.9.1 tqdm/4.32.1 CPython/3.7.3

File hashes

Hashes for crhelper-2.0.3-py3-none-any.whl
Algorithm Hash digest
SHA256 66f8c85ef7461615c85f208d1948db386171a199d061503b5bce62552a9c6e21
MD5 fdd5e833562f943db52194dae96959a5
BLAKE2b-256 3630d907569254d94f4009f52f2078f4ba4a46a890494e69ce226d2d38c9739f

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page