Before you get started configuring CloudFormation custom resources, it is worthwhile to discuss how they actually work and describe the key components that compose a custom resource.
The following diagram illustrates how CloudFormation custom resources work:
CloudFormation custom resources
In the preceding diagram, the following steps take place when you use custom resources in your CloudFormation templates:
- You need to define custom resources in your CloudFormation templates. A custom resource has the AWS::CloudFormation::CustomResource resource type, or alternatively Custom::<resource-name>. When CloudFormation encounters a custom resource, it looks for a specific property called ServiceToken, which provides the ARN of a Lambda function that should provision the custom resource.
- CloudFormation invokes the Lambda function, and passes a custom resource request to the function in the form of a JSON object. The event has a request type, which defines whether the request is to either create, update, or delete the resource, and includes request properties, which are custom properties you can define in your custom resource definition that will be passed to the Lambda function. Another important property of the request is the response URL, which provides a pre-signed S3 URL where the Lambda function should post a response once provisioning is complete.
- The Lambda function processes the custom resource request and performs appropriate provisioning of the resource, based upon the request type and request properties. Once provisioning is complete, the function posts a success or failure response to the response URL received in the custom resource request, and includes a resource identifier in the event a resource has been created or updated. Assuming the response signals success, the response may include a Data property, which can include useful information about the provisioned custom resource that can be referenced elsewhere in the CloudFormation stack using the standard !Sub ${<resource-name>.<data-property>} syntax, where <data-property> is a property included in the Data property of the response.
- The CloudFormation service polls the response URL for a response. Once a response is received, CloudFormation parses the response and continues stack provisioning (or rolls back the stack in the event the response indicates a failure).