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

cfn-signal

Description

You can use the cfn-signal helper script to pause the stack creation process. Use the cfn-signal script in conjunction with two AWS CloudFormation resources:

For more information about how to use wait conditions in your template, see Creating Wait Conditions in a Template.

Syntax

cfn-signal --success|-s signal.to.send \
        --reason|-r resource.status.reason \
        --data|-d data \
        --id|-i unique.id \
        --exit-code|-e exit.code \
        waitconditionhandle.url 

Options

NameDescriptionRequired

-s, --success

if true, signal SUCCESS, else FAILURE.

Type: Boolean

Default: true

No

-r, --reason

A status reason for the resource event (currently only used on failure) - defaults to 'Configuration failed' if success is false.

Type: String

No

-d, --data

Data to send back with the waitConditionHandle. Defaults to blank.

Type: String

Default: blank

No

-i, --id

The unique id to send back with the WaitConditionHandle.

Type: String

Default: The ID of the Amazon EC2 instance. If the ID cannot be resolved, the machine's Fully Qualified Domain Name (FQDN) is returned.

No

-e, --exit-code

The error code from a process that can be used to determine success or failure. If specified, the --success option is ignored.

Type: String

Examples: -e $? (for Linux), -e %ERRORCODE% (for Windows)

No

waitconditionhandle.url

A pre-signed URL that you can use to signal success or failure to an associated WaitCondition

Type: String

Yes

Examples

Example 1

A common usage pattern is to use cfn-init and cfn-signal together. The cfn-signal call uses the return status of the call to cfn-init (using the $? shell construct). If the application fails to install, the WaitCondition will fail to create and the stack will rollback.

"MyInstance": {
   "Type": "AWS::EC2::Instance",
   "Metadata": {
      :
   },
   "Properties": {
      "ImageId" : "ami-12345678",
      "UserData" : {
         "Fn::Base64" : {
            "Fn::Join" : ["", [
               "#!/bin/bash\n",
               "/opt/aws/bin/cfn-init -s ", { "Ref" : "AWS::StackName" },
               "         -r MyInstance ",
               "         --region ", { "Ref" : "AWS::Region" },
               "\n",
               "/opt/aws/bin/cfn-signal -e $? '", { "Ref" : "MyHandle" }, "'\n",
            ] ]
         }
      }
   }
},

Example 2

The following snippet shows another common usage pattern in which a function calls cfn-signal. Wrapping cfn-signal in a function makes it easier to call cfn-signal from multiple places. For Windows stacks, you must base64 encode the wait condition handle URL again. For an example, see Bootstrapping AWS CloudFormation Windows Stacks.

"# Helper function\n",
          "function error_exit\n",
          "{\n",
          "  /opt/aws/bin/cfn-signal -e 1 -r \"$1\" '", { "Ref" : "WaitHandle" }, "'\n",
          "  exit 1\n",
          "}\n",

The following snippet shows the error_exit function called in two commands.

"# Setup MySQL, create a user and a database\n",
"mysqladmin -u root password '", { "Ref" : "DBRootPassword" },
"' || error_exit 'Failed to initialize root password'\n",

"mysql -u root --password='", { "Ref" : "DBRootPassword" },
"' < /tmp/setup.mysql || error_exit 'Failed to initialize database'\n",

Examples in Sample Templates

Several AWS CloudFormation sample templates use cfn-signal, including the following templates.