Sign In to the Console
AWS CloudFormation
User Guide (API Version 2010-05-15)

AWS Documentation » AWS CloudFormation » User Guide » Template Reference » AWS Resource and Property Types Reference » AWS CloudFormation Resource Types Reference » AWS::CloudFormation::CustomResource

AWS::CloudFormation::CustomResource

In an AWS CloudFormation template, you use the AWS::CloudFormation::CustomResource or Custom::String resource type to specify custom resources.

Custom resources provide a way for you to write custom provisioning logic in AWS CloudFormation template and have AWS CloudFormation run it during a stack operation, such as when you create, update or delete a stack. For more information, see Custom Resources.

Note

If you use the VPC endpoint feature, custom resources in the VPC must have access to AWS CloudFormation-specific Amazon Simple Storage Service (Amazon S3) buckets. Custom resources must send responses to a pre-signed Amazon S3 URL. If they can't send responses to Amazon S3, AWS CloudFormation won't receive a response and the stack operation fails. For more information, see Setting Up VPC Endpoints for AWS CloudFormation.

Syntax

To declare this entity in your AWS CloudFormation template, use the following syntax:

JSON


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

YAML

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

Custom::String

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::MyCustomResourceTypeName.

Custom resource type names can include alphanumeric characters and the following characters: _@-. You can specify a custom resource type name up to a maximum length of 60 characters. You cannot change the type during an update.

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 different ping tests, you could name their type as Custom::PingTester to make them easily identifiable as ping testers (instead of using AWS::CloudFormation::CustomResource).

Properties

Note

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

ServiceToken

The service token that was given to the template developer by the service provider to access the service, such as an Amazon SNS topic ARN or Lambda function ARN. The service token must be from the same region in which you are creating the stack.

Required: Yes

Type: String

Update requires: Updates are not supported.

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.

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

JSON

{
   "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"] }
      }
   }
}

YAML

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

Using an AWS Lambda function in a custom resource

With Lambda functions and custom resources, you can run custom code in response to stack events (create, update, and delete). The following custom resource invokes a Lambda function and sends it the StackName property as input. The function uses this property to get outputs from the appropriate stack.

JSON

"MyCustomResource" : {
  "Type" : "Custom::TestLambdaCrossStackRef",
  "Properties" : {
    "ServiceToken": { "Fn::Join": [ "", [ "arn:aws:lambda:", { "Ref": "AWS::Region" }, ":", { "Ref": "AWS::AccountId" }, ":function:", {"Ref" : "LambdaFunctionName"} ] ] },
    "StackName": {
      "Ref": "NetworkStackName"
    }
  }
}

YAML

MyCustomResource: 
  Type: "Custom::TestLambdaCrossStackRef"
  Properties: 
    ServiceToken:
      !Sub |
        arn:aws:lambda:${AWS::Region}:${AWS::AccountId}:function:${LambdaFunctionName}
    StackName: 
      Ref: "NetworkStackName"

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: