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.