cfn-custom-resource

Cloudformation Custom Resources Helper

Node.js module providing utility functions and constants for AWS CloudFormation Custom Resources.

Supported Runtimes

• NodeJS 10+  

Usage

const cfnCR = require('cfn-custom-resource');
const { configure, sendSuccess, sendFailure, sendResponse, LOG_VERBOSE, SUCCESS } = cfnCR;

/* Increase the logging level */
configure({ logLevel: LOG_VERBOSE });

/**
  Do resource creation
                      **/

/* Resource successfully created! - async/await */
const result = await sendSuccess(id, { ImportantInfo: otherId }, event);
return result;

/* Resource successfully created! - Promises */
return sendSuccess(id, { ImportantInfo: otherId} , event, callback);

/* Resource encountered an error during creation - async/await */
await sendFailure('mistakes were made', event); // Simple form
await sendFailure('mistakes were made', event, null, null, id); //If there's a special resource id to pass

/* Resource encountered an error during creation - Promises */
return sendFailure('mistakes were made', event, callback); // Simple form
return sendFailure('mistakes were made', event, callback, null, id); //If there's a special resource id to pass

/* If you want full control */
await sendResponse({ Status: SUCCESS, PhysicalResourceId: id, Data: { ImportantInfo: otherId } }, event);

Constants

• Responses - SUCCESS and FAILED
• Request Types - CREATE, UPDATE, DELETE
• Logging Levels - LOG_NORMAL, LOG_VERBOSE, LOG_DEBUG
• Default sendFailure text - DEFAULT_PHYSICAL_RESOURCE_ID, DEFAULT_REASON_WITH_CONTEXT, DEFAULT_REASON (no context)  

Functions

configure(options) ⇒ void

Configures the module with the given options

Kind: global function
Returns: void - Void return

Param	Type	Description
options	Object	Options to configure with

sendResponse(responseDetails, event, callback) ⇒ Promise

Sends a response to Cloudformation about the success or failure of a custom resource deploy

Kind: global function
Returns: Promise - Promise for sending the response. If the Lambda callback is provided,returns the provided callback with error/result parameters. If the Lambda callback is not provided, returns the error or result data directly. Errors are returned for FAILED responses as well as for any errors in the send response execution. If Data is provided, it is provided as the callback result or returned directly. Otherwise, null will be provided as the callback result or returned directly.

Param	Type	Description
responseDetails	Object	Contains the properties for the response
responseDetails.Status	string	Status for the response. SUCCESS or FAILED.
responseDetails.Reason	string	Reason for FAILED response. Ignored if SUCCESS.
responseDetails.PhysicalResourceId	string	Physical resource id
responseDetails.Data	string	Additional response to return. Optional.
event	Object	Lambda event that contains passthrough information
callback	function	Optional. Lambda callback.

sendSuccess(physicalResourceId, data, event, callback) ⇒ Promise

Sends a success response to Cloudformation. Wraps sendResponse.

Kind: global function
Returns: Promise - Promise for sending the response If the Lambda callback is provided,returns the provided callback with error/result parameters. If the Lambda callback is not provided, returns the error or result data directly. Errors are returned for FAILED responses as well as for any errors in the send response execution. If Data is provided, it is provided as the callback result or returned directly. Otherwise, null will be provided as the callback result or returned directly.

Param	Type	Description
physicalResourceId	string	Physical Resource Id of the resource
data	*	Optional. Additional data to send. If not an object, it is wrapped in one with a single property, data, assigned to it.
event	Object	Lambda event
callback	function	Lambda callback

sendFailure(reason, event, callback, context, physicalResourceId) ⇒ Promise

Sends a failed response to Cloudformation. Wraps sendResponse.

Kind: global function
Returns: Promise - Promise for sending the responses If the Lambda callback is provided,returns the provided callback with error/result parameters. If the Lambda callback is not provided, returns the error or result data directly. Errors are returned for FAILED responses as well as for any errors in the send response execution. If Data is provided, it is provided as the callback result or returned directly. Otherwise, null will be provided as the callback result or returned directly.

Param	Type	Description
reason	string	Reason for the failure. If not provided, a default is provided.
event	Object	Lambda event
callback	function	Lambda callback
context	Object	Lambda context. Used for providing a useful default reason.
physicalResourceId	string	Physical Resource Id of the resource. If not provided, uses the one from the event. If none in the event, generates one.