AWS CloudFormation
User Guide (API Version 2010-05-15)
« 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.Did this page help you?  Yes | No |  Tell us about it...

AWS::CloudFormation::CustomResource

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 a template, a custom resource is represented by either AWS::CloudFormation::CustomResource or Custom::String.

Syntax

{
   "Type" : "AWS::CloudFormation::CustomResource",
   "Version" : "1.0",
   "Properties" : {
      "ServiceToken" : String,
      ... provider-defined properties ...
   }
} 
      

or

{
   "Type" : "Custom::String",
   "Version" : "1.0",
   "Properties" : {
      "ServiceToken" : String,
      ... provider-defined properties ...
   }
} 

Note

Only one property is defined by AWS for a custom resource: ServiceToken. All other properties are defined by the service provider.

Custom Resource Type Name

For custom resources, you can specify AWS::CloudFormation::CustomResource as the resource type, or you can specify your own resource type name. For example, instead of using AWS::CloudFormation::CustomResource, you can use Custom::String. Custom resource type names must be alphanumeric and can have a maximum length of 60 characters.

Using your own resource type names helps you quickly differentiate the types of custom resources in your stack. For example, if you had two custom resources that conduct two types of tests, you could name the custom resource types as Custom::PingTester to make them easily identifiable (instead of using AWS::CloudFormation::CustomResource).

Note

You cannot change the Type during an update.

Properties

ServiceToken

The service token that was given to the template developer by the service provider to access the service.

Required: Yes

Type: String

Return Values

For a custom resource, return values are defined by the custom resource provider, and are retrieved by calling Fn::GetAtt on the provider-defined attributes.

Examples

Creating a custom resource definition in a template

The following example demonstrates how to create a custom resource definition in a template.

{
   "AWSTemplateFormatVersion" : "2010-09-09",
   "Resources" : {
      "MyFrontEndTest" : {
         "Type": "AWS::CloudFormation::CustomResource",
         "Version" : "1.0",
         "Properties" : {
            "ServiceToken": "arn:aws:sns:us-east-1:84969EXAMPLE:CRTest",
            "key1" : "string",
            "key2" : [ "list" ],
            "key3" : { "key4" : "map" }
         }
      }
   },
   "Outputs" : {
      "CustomResourceAttribute1" : {
         "Value" : { "Fn::GetAtt" : ["MyFrontEndTest", "responseKey1"] }
      },
      "CustomResourceAttribute2" : {
         "Value" : { "Fn::GetAtt" : ["MyFrontEndTest", "responseKey2"] }
      }
   }
}     

All properties other than ServiceToken, and all Fn::GetAtt resource attributes, are defined by the custom resource provider.

Creating a user-defined resource type for a custom resource

The following example demonstrates how to create a type name for a custom resource.

{
   "AWSTemplateFormatVersion" : "2010-09-09",
   "Resources" : {
      "MyFrontEndTest" : {
         "Type": "Custom::PingTester",
         "Version" : "1.0",
         "Properties" : {
            "ServiceToken": "arn:aws:sns:us-east-1:84969EXAMPLE:CRTest",
            "key1" : "string",
            "key2" : [ "list" ],
            "key3" : { "key4" : "map" }
         }
      }
   },
   "Outputs" : {
      "CustomResourceAttribute1" : {
         "Value" : { "Fn::GetAtt" : ["MyFrontEndTest", "responseKey1"] }
      },
      "CustomResourceAttribute2" : {
         "Value" : { "Fn::GetAtt" : ["MyFrontEndTest", "responseKey2"] }
      }
   }
}     

Replacing a Custom Resource During an Update

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 the 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. For a step-by-step walkthrough of this process, see Stack Updates.

Note the following: