Using Amazon Lambda with Amazon CloudFormation - Amazon Lambda
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Using Amazon Lambda with Amazon CloudFormation

In an Amazon CloudFormation template, you can specify a Lambda function as the target of a custom resource. Use custom resources to process parameters, retrieve configuration values, or call other Amazon services during stack lifecycle events.

The following example invokes a function that's defined elsewhere in the template.

Example – Custom resource definition
Resources:
  primerinvoke:
    Type: AWS::CloudFormation::CustomResource
    Version: "1.0"
    Properties:
      ServiceToken: !GetAtt primer.Arn
      FunctionName: !Ref randomerror

The service token is the Amazon Resource Name (ARN) of the function that Amazon CloudFormation invokes when you create, update, or delete the stack. You can also include additional properties like FunctionName, which Amazon CloudFormation passes to your function as is.

Amazon CloudFormation invokes your Lambda function asynchronously with an event that includes a callback URL.

Example – Amazon CloudFormation message event
{
    "RequestType": "Create",
    "ServiceToken": "arn:aws-cn:lambda:cn-north-1:123456789012:function:lambda-error-processor-primer-14ROR2T3JKU66",
    "ResponseURL": "https://cloudformation-custom-resource-response-cnnorth1.s3.cn-north-1.amazonaws.com.cn/arn%3Aaws%3Acloudformation%3Acn-north-1%3A123456789012%3Astack/lambda-error-processor/1134083a-2608-1e91-9897-022501a2c456%7Cprimerinvoke%7C5d478078-13e9-baf0-464a-7ef285ecc786?AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE&Expires=1555451971&Signature=28UijZePE5I4dvukKQqM%2F9Rf1o4%3D",
    "StackId": "arn:aws-cn:cloudformation:cn-north-1:123456789012:stack/lambda-error-processor/1134083a-2608-1e91-9897-022501a2c456",
    "RequestId": "5d478078-13e9-baf0-464a-7ef285ecc786",
    "LogicalResourceId": "primerinvoke",
    "ResourceType": "AWS::CloudFormation::CustomResource",
    "ResourceProperties": {
        "ServiceToken": "arn:aws-cn:lambda:cn-north-1:123456789012:function:lambda-error-processor-primer-14ROR2T3JKU66",
        "FunctionName": "lambda-error-processor-randomerror-ZWUC391MQAJK"
    }
}

The function is responsible for returning a response to the callback URL that indicates success or failure. For the full response syntax, see Custom resource response objects.

Example – Amazon CloudFormation custom resource response
{
    "Status": "SUCCESS",
    "PhysicalResourceId": "2019/04/18/[$LATEST]b3d1bfc65f19ec610654e4d9b9de47a0",
    "StackId": "arn:aws-cn:cloudformation:cn-north-1:123456789012:stack/lambda-error-processor/1134083a-2608-1e91-9897-022501a2c456",
    "RequestId": "5d478078-13e9-baf0-464a-7ef285ecc786",
    "LogicalResourceId": "primerinvoke"
}

Amazon CloudFormation provides a library called cfn-response that handles sending the response. If you define your function within a template, you can require the library by name. Amazon CloudFormation then adds the library to the deployment package that it creates for the function.

If your function that a Custom Resource uses has an Elastic Network Interface attached to it, add the following resources to the VPC policy where region is the Region the function is in without the dashes. For example, us-east-1 is useast1. This will allow the Custom Resource to respond to the callback URL that sends a signal back to the Amazon CloudFormation stack.

arn:aws:s3:::cloudformation-custom-resource-response-region",
"arn:aws:s3:::cloudformation-custom-resource-response-region/*",

The following example function invokes a second function. If the call succeeds, the function sends a success response to Amazon CloudFormation, and the stack update continues. The template uses the AWS::Serverless::Function resource type provided by Amazon Serverless Application Model.

Example – Custom resource function
Transform: 'AWS::Serverless-2016-10-31'
Resources:
  primer:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.handler
      Runtime: nodejs16.x
      InlineCode: |
        var aws = require('aws-sdk');
        var response = require('cfn-response');
        exports.handler = function(event, context) {
            // For Delete requests, immediately send a SUCCESS response.
            if (event.RequestType == "Delete") {
                response.send(event, context, "SUCCESS");
                return;
            }
            var responseStatus = "FAILED";
            var responseData = {};
            var functionName = event.ResourceProperties.FunctionName
            var lambda = new aws.Lambda();
            lambda.invoke({ FunctionName: functionName }, function(err, invokeResult) {
                if (err) {
                    responseData = {Error: "Invoke call failed"};
                    console.log(responseData.Error + ":\n", err);
                }
                else responseStatus = "SUCCESS";
                response.send(event, context, responseStatus, responseData);
            });
        };
      Description: Invoke a function to create a log stream.
      MemorySize: 128
      Timeout: 8
      Role: !GetAtt role.Arn
      Tracing: Active

If the function that the custom resource invokes isn't defined in a template, you can get the source code for cfn-response from cfn-response module in the Amazon CloudFormation User Guide.

For more information about custom resources, see Custom resources in the Amazon CloudFormation User Guide.