AWS CloudFormation
User Guide (API Version 2010-05-15)
Did this page help you?  Yes | No |  Tell us about it...
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.

AWS CloudFormation Custom Resource Walkthrough

What is a Custom Resource?

Custom resources are special AWS CloudFormation resources that provide a way for a template developer to include non-AWS resources in an AWS CloudFormation stack. The custom resource provider can be either a template developer or a separate third-party resource provider.

In an AWS CloudFormation template, custom resources are specified by the AWS::CloudFormation::CustomResource type or Custom::String.

How Custom Resources Work

Any action taken for a custom resource involves three parties: the template developer, AWS CloudFormation, and the custom resource provider. The template developer and custom resource provider may be the same person or entity, but the process will be the same. The following steps describe the general process:

  1. The template developer creates, updates, or deletes a stack that contains a custom resource. The template includes a service token and any input/output data parameters for the custom resource.

  2. AWS CloudFormation communicates with the custom resource provider using an SNS topic, sending it the type of request (create, update, or delete) and any input data stored in the stack template. AWS CloudFormation provides the custom resource provider with an S3 URL for the response.

  3. The custom resource provider processes the message and returns a response of SUCCESS or FAILED. The custom resource provider can also send the names and values of resource attributes that can be accessed by the template developer if the request succeeded (output data), or send a string that provides detail about the failure if the request failed.

  4. AWS CloudFormation sets the stack status according to the response received and provides the values of any custom resource output data to the template developer with Fn::GetAtt.

The following figure illustrates the relationships between the template developer, AWS CloudFormation, and the custom resource provider:


What's in this Walkthrough?

This walkthrough will step through the custom resource process, explaining the sequence of events and messages sent and received as a result of custom resource stack creation, updates, and deletion.

It is divided into three parts:

Part 1: Stack Creation

  1. The template developer creates an AWS CloudFormation stack that contains a custom resource; in the template example below, we use the custom resource type name Custom::SeleniumTester for the custom resource MySeleniumTest.

    The custom resource type name is declared with a service token, optional provider-specific properties, and optional Fn::GetAtt attributes that are defined by the custom resource provider. These properties and attributes can be used to pass information from the template developer to the custom resource provider and vice-versa. Custom resource type names must be alphanumeric and can have a maximum length of 60 characters.

    The following example shows a template that has both custom properties and return attributes:

    {
       "AWSTemplateFormatVersion" : "2010-09-09",
       "Resources" : {
          "MySeleniumTest" : {
             "Type": "Custom::SeleniumTester",
             "Version" : "1.0",
             "Properties" : {
                "ServiceToken": "arn:aws:sns:us-east-1:84969EXAMPLE:CRTest",
                "seleniumTester" : "SeleniumTest()",
                "endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com" ],
                "frequencyOfTestsPerHour" : [ "3", "2", "4" ]
             }
          }
       },
       "Outputs" : {
          "topItem" : {
             "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "resultsPage"] }
          },
          "numRespondents" : {
             "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "lastUpdate"] }
          }
       }
    }           

    Note

    The names and values of the data accessed with Fn::GetAtt are returned by the custom resource provider during the provider's response to AWS CloudFormation. If the custom resource provider is a third-party, then the template developer must obtain the names of these return values from the custom resource provider.

  2. AWS CloudFormation sends an Amazon SNS notification to the resource provider with a "RequestType" : "Create" that contains information about the stack, the custom resource properties from the stack template, and an S3 URL for the response.

    The SNS topic that is used to send the notification is embedded in the template in the ServiceToken property. To avoid using a hard-coded value, a template developer can use a template parameter so that the value is entered at the time the stack is launched.

    The following example shows a custom resource Create request which includes a custom resource type name, Custom::SeleniumTester, created with a LogicalResourceId of MySeleniumTester:

    {
       "RequestType" : "Create",
       "ResponseURL" : "http://pre-signed-S3-url-for-response",
       "StackId" : "arn:aws:cloudformation:us-east-1:EXAMPLE/stack-name/guid",
       "RequestId" : "unique id for this create request",
       "ResourceType" : "Custom::SeleniumTester",
       "LogicalResourceId" : "MySeleniumTester",
       "ResourceProperties" : {
          "seleniumTester" : "SeleniumTest()",
          "endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com" ],
          "frequencyOfTestsPerHour" : [ "3", "2", "4" ]
       }
    }                 
                
  3. The custom resource provider processes the data sent by the template developer and determines whether the Create request was successful. The resource provider then uses the S3 URL sent by AWS CloudFormation to send a response of either SUCCESS or FAILED.

    Depending on the response type, different response fields will be expected by AWS CloudFormation. Refer to the Responses section in the reference topic for the RequestType that is being processed.

    In response to a create or update request, the custom resource provider can return data elements in the Data field of the response. These are name/value pairs, and the names correspond to the Fn::GetAtt attributes used with the custom resource in the stack template. The values are the data that is returned when the template developer calls Fn::GetAtt on the resource with the attribute name.

    The following is an example of a custom resource response:

    {
       "Status" : "SUCCESS",
       "PhysicalResourceId" : "Tester1",
       "StackId" : "arn:aws:cloudformation:us-east-1:EXAMPLE:stack/stack-name/guid",
       "RequestId" : "unique id for this create request",
       "LogicalResourceId" : "MySeleniumTester",
       "Data" : {
          "resultsPage" : "http://www.myexampledomain/test-results/guid",
          "lastUpdate" : "2012-11-14T03:30Z",
       }
    }           

    The StackId, RequestId, and LogicalResourceId fields must be copied verbatim from the request.

  4. AWS CloudFormation declares the stack status as CREATE_COMPLETE or CREATE_FAILED. If the stack was successfully created, the template developer can use the output values of the created custom resource by accessing them with Fn::GetAtt.

    For example, the custom resource template used for illustration used Fn::GetAtt to copy resource outputs into the stack outputs:

    "Outputs" : {
       "topItem" : {
          "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "resultsPage"] }
       },
       "numRespondents" : {
          "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "lastUpdate"] }
       }
    }           

For detailed information about the request and response objects involved in Create requests, see Create in the Custom Resource Reference.

Part 2: Stack Updates

To update an existing stack, you must submit a template that specifies updates for the properties of resources in the stack, as shown in the example below. AWS CloudFormation updates only the resources that have changes specified in the template. For more information about updating stacks, see AWS CloudFormation Stacks Updates.

You can update custom resources that require a replacement of the underlying physical resource. When you update a custom resource in an AWS CloudFormation template, AWS CloudFormation sends an update request to that custom resource. If a custom resource requires a replacement, the new custom resource must send a response with the new physical ID. When AWS CloudFormation receives the response, it compares the PhysicalResourceId between the old and new custom resources. If they are different, AWS CloudFormation recognizes the update as a replacement and sends a delete request to the old resource, as shown in Part 3: Stack Deletion.

  1. The template developer initiates an update to the stack that contains a custom resource. During an update, the template developer can specify new Properties in the stack template.

    The following is an example of an Update to the stack template using a custom resource type:

    {
       "AWSTemplateFormatVersion" : "2010-09-09",
       "Resources" : {
          "MySeleniumTest" : {
             "Type": "Custom::SeleniumTester",
             "Version" : "1.0",
             "Properties" : {
                "ServiceToken": "arn:aws:sns:us-east-1:84969EXAMPLE:CRTest",
                "seleniumTester" : "SeleniumTest()",
                "endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com",
                   "http://mynewsite.com" ],
                "frequencyOfTestsPerHour" : [ "3", "2", "4", "3" ]
             }
          }
       },
       "Outputs" : {
          "topItem" : {
             "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "resultsPage"] }
          },
          "numRespondents" : {
             "Value" : { "Fn::GetAtt" : ["MySeleniumTest", "lastUpdate"] }
          }
       }
    }           
  2. AWS CloudFormation sends an Amazon SNS notification to the resource provider with a "RequestType" : "Update" that contains similar information to the Create call, except that the OldResourceProperties field contains the old resource properties, and ResourceProperties contains the updated (if any) resource properties.

    The following is an example of an Update request:

    {
       "RequestType" : "Update",
       "ResponseURL" : "http://pre-signed-S3-url-for-response",
       "StackId" : "arn:aws:cloudformation:us-east-1:EXAMPLE:stack/stack-name/guid",
       "RequestId" : "uniqueid for this update request",
       "LogicalResourceId" : "MySeleniumTester",
       "ResourceType" : "Custom::SeleniumTester"  
       "PhysicalResourceId" : "Tester1",
       "ResourceProperties" : {
          "seleniumTester" : "SeleniumTest()",
          "endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com",
             "http://mynewsite.com" ],
          "frequencyOfTestsPerHour" : [ "3", "2", "4", "3" ]
       }
       "OldResourceProperties" : {
          "seleniumTester" : "SeleniumTest()",
          "endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com" ],
          "frequencyOfTestsPerHour" : [ "3", "2", "4" ]
       }
    }          
  3. The custom resource provider processes the data sent by AWS CloudFormation. The custom resource performs the update and sends a response of either SUCCESS or FAILED to the S3 URL. AWS CloudFormation then compares the PhysicalResourceIDs of old and new custom resources. If they are different, AWS CloudFormation recognizes that the update requires a replacement and sends a delete request to the old resource. The following example demonstrates the custom resource provider response to an Update request.

    {
       "Status" : "SUCCESS",
       "StackId" : "arn:aws:cloudformation:us-east-1:EXAMPLE:stack/stack-name/guid",
       "RequestId" : "uniqueid for this update request",
       "LogicalResourceId" : "MySeleniumTester",
       "PhysicalResourceId" : "Tester2"
    }           

    The StackId, RequestId, and LogicalResourceId fields must be copied verbatim from the request.

  4. AWS CloudFormation declares the stack status as UPDATE_COMPLETE or UPDATE_FAILED. If the update fails, the stack rolls back. If the stack was successfully updated, the template developer can access any new output values of the created custom resource with Fn::GetAtt.

For detailed information about the request and response objects involved in Update requests, see Update in the Custom Resource Reference.

Part 3: Stack Deletion

  1. The template developer deletes a stack that contains a custom resource. AWS CloudFormation gets the current properties specified in the stack template along with the SNS topic, and prepares to make a request to the custom resource provider.

  2. AWS CloudFormation sends an Amazon SNS notification to the resource provider with a "RequestType" : "Delete" that contains current information about the stack, the custom resource properties from the stack template, and an S3 URL for the response.

    Whenever you delete a stack or make an update that removes or replaces the custom resource, AWS CloudFormation compares the PhysicalResourceId between the old and new custom resources. If they are different, AWS CloudFormation recognizes the update as a replacement and sends a delete request for the old resource (OldPhysicalResource), as shown in the following example of a Delete request.

    {
       "RequestType" : "Delete",
       "ResponseURL" : "http://pre-signed-S3-url-for-response",
       "StackId" : "arn:aws:cloudformation:us-east-1:EXAMPLE:stack/stack-name/guid",
       "RequestId" : "unique id for this delete request",
       "ResourceType" : "Custom::SeleniumTester",
       "LogicalResourceId" : "MySeleniumTester",
       "PhysicalResourceId" : "Tester1",
       "ResourceProperties" : {
          "seleniumTester" : "SeleniumTest()",
          "endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com",
             "http://mynewsite.com" ],
          "frequencyOfTestsPerHour" : [ "3", "2", "4", "3" ]
       }
    }    
                

    DescribeStackResource, DescribeStackResources, and ListStackResources display the user-defined name if it has been specified.

  3. The custom resource provider processes the data sent by AWS CloudFormation and determines whether the Delete request was successful. The resource provider then uses the S3 URL sent by AWS CloudFormation to send a response of either SUCCESS or FAILED.

    The following is an example of a custom resource provider response to a Delete request:

    {
       "Status" : "SUCCESS",
       "StackId" : "arn:aws:cloudformation:us-east-1:EXAMPLE:stack/stack-name/guid",
       "RequestId" : "unique id for this delete request",
       "LogicalResourceId" : "MySeleniumTester",
       "PhysicalResourceId" : "Tester1"
    }           
                

    The StackId, RequestId, and LogicalResourceId fields must be copied verbatim from the request.

  4. AWS CloudFormation declares the stack status as DELETE_COMPLETE or DELETE_FAILED.

For detailed information about the request and response objects involved in Delete requests, see Delete in the Custom Resource Reference.