AWS CloudFormation Custom Resource Walkthrough

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.

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.

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.

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 template developer launches an AWS CloudFormation stack with a template that includes an AWS::CloudFormation::CustomResource.

The CustomResource 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.

The following is an example of a template that has both custom properties and return attributes:

{
   "AWSTemplateFormatVersion" : "2010-09-09",
   "Resources" : {
      "myCustomResource" : {
         "Type": "AWS::CloudFormation::CustomResource",
         "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" : ["myCustomResource", "resultsPage"] }
      },
      "numRespondents" : {
         "Value" : { "Fn::GetAtt" : ["myCustomResource", "lastUpdate"] }
      }
   }
}           

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 is an example of a custom resource Create request:

{
   "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",
   "LogicalResourceId" : "myCustomResource",
   "ResourceProperties" : {
      "seleniumTester" : "SeleniumTest()",
      "endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com" ],
      "frequencyOfTestsPerHour" : [ "3", "2", "4" ]
   }
}           

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" : "required vendor-defined physical id that is unique for that vendor",
   "StackId" : "arn:aws:cloudformation:us-east-1:EXAMPLE:stack/stack-name/guid",
   "RequestId" : "unique id for this create request",
   "LogicalResourceId" : "myCustomResource",
   "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.

AWS CloudFormation declares the stack status as CREATE_SUCCESS 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" : ["myCustomResource", "resultsPage"] }
   },
   "numRespondents" : {
      "Value" : { "Fn::GetAtt" : ["myCustomResource", "lastUpdate"] }
   }
}           

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:

{
   "AWSTemplateFormatVersion" : "2010-09-09",
   "Resources" : {
      "myCustomResource" : {
         "Type": "AWS::CloudFormation::CustomResource",
         "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" : ["myCustomResource", "resultsPage"] }
      },
      "numRespondents" : {
         "Value" : { "Fn::GetAtt" : ["myCustomResource", "lastUpdate"] }
      }
   }
}           

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" : "myCustomResource",
   "PhysicalResourceId" : "vendor-defined physical id",
   "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" ]
   }
}          

The custom resource provider processes the data sent by the template developer and determines whether the Update 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 an Update request:

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

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

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

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.

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.

The following is an 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",
   "LogicalResourceId" : "myCustomResource",
   "PhysicalResourceId" : "vendor-defined physical id",
   "ResourceProperties" : {
      "seleniumTester" : "SeleniumTest()",
      "endpoints" : [ "http://mysite.com", "http://myecommercesite.com/", "http://search.mysite.com",
         "http://mynewsite.com" ],
      "frequencyOfTestsPerHour" : [ "3", "2", "4", "3" ]
   }
}           

The custom resource provider processes the data sent by the template developer 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" : "name of resource in template (copied from request)",
   "PhysicalResourceId" : "vendor-defined physical id"
}           

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

AWS CloudFormation declares the stack status as DELETE_COMPLETE or DELETE_FAILED.