Create wait conditions in a CloudFormation template (original) (raw)

This topic explains how to create a wait condition in a template to coordinate the creation of stack resources or track the progress of a configuration process. For example, you can start the creation of another resource after an application configuration is partially complete, or you can send signals during an installation and configuration process to track its progress.

When CloudFormation creates a stack that includes a wait condition:

Important

For Amazon EC2 and Auto Scaling resources, we recommend that you use a CreationPolicy attribute instead of wait conditions. Add a CreationPolicy attribute to those resources, and use the cfn-signal helper script to signal when an instance creation process has completed successfully.

For more information, see CreationPolicy attribute or Deploy applications on Amazon EC2.

Topics

Creating a wait condition in your template

1. Wait condition handle

You start by defining a AWS::CloudFormation::WaitConditionHandle resource in the stack's template. This resource generates the presigned URL needed for sending signals. This allows you to send a signal without having to supply your AWS credentials. For example: 

Resources:
  MyWaitHandle:
    Type: AWS::CloudFormation::WaitConditionHandle
2. Wait condition

Next, you define an AWS::CloudFormation::WaitCondition resource in the stack's template. The basic structure of aAWS::CloudFormation::WaitCondition looks like this: 

  MyWaitCondition:
    Type: AWS::CloudFormation::WaitCondition
    Properties:
      Handle: String
      Timeout: String
      Count: Integer

The AWS::CloudFormation::WaitCondition resource has two required properties and one optional property.

Typically, you want a wait condition to begin immediately after the creation of a specific resource. You do this by adding the DependsOn attribute to a wait condition. When you add aDependsOn attribute to a wait condition, CloudFormation creates the resource in the DependsOn attribute first, and then creates the wait condition.

The following example demonstrates a wait condition that: 

  MyWaitCondition:
    Type: AWS::CloudFormation::WaitCondition
    DependsOn: MyEC2Instance
    Properties:
      Handle: !Ref MyWaitHandle
      Timeout: '4500'
3. Sending a signal

To signal success or failure to CloudFormation, you typically run some code or script. For example, an application running on an EC2 instance might perform some additional configuration tasks and then send a signal to CloudFormation to indicate completion.

The signal must be sent to the presigned URL generated by the wait condition handle. You use that presigned URL to signal success or failure.

To send a signal
  1. To retrieve the presigned URL within the template, use the Ref intrinsic function with the logical name of the wait condition handle.
    As shown in the following example, your template can declare an Amazon EC2 instance and pass the presigned URL to EC2 instances using the Amazon EC2UserData property. This allows scripts or applications running on those instances to signal success or failure to CloudFormation.
  MyEC2Instance:  
    Type: AWS::EC2::Instance  
    Properties:  
    InstanceType: t2.micro  # Example instance type  
    ImageId: ami-055e3d4f0bbeb5878  # Change this as needed (Amazon Linux 2023 in us-west-2)  
    UserData:  
      Fn::Base64:  
        Fn::Join:  
          - ""  
          - - "SignalURL="  
            - { "Ref": "MyWaitHandle" }

This results in UserData output similar to: 

SignalURL=https://amzn-s3-demo-bucket.s3.amazonaws.com/....

Note: In the AWS Management Console and the command line tools, the presigned URL is displayed as the physical ID of the wait condition handle resource. 2. (Optional) To detect when the stack enters the wait condition, you can use one of the following methods:

  1. To send a signal, you send an HTTP request message using the presigned URL. The request method must be PUT and the Content-Type header must be an empty string or omitted. The request message must be a JSON structure of the form specified in Wait condition signal syntax.
    You must send the number of success signals specified by theCount property in order for CloudFormation to continue stack creation. If you have a Count that is greater than 1, theUniqueId value for each signal must be unique across all signals sent to a particular wait condition. The UniqueId is an arbitrary alphanumerical string.
    A curl command is one way to send a signal. The following example shows a curl command line that signals success to a wait condition.
$ curl -T /tmp/a \  
  "https://amzn-s3-demo-bucket.s3.amazonaws.com/arn%3Aaws%3Acloudformation%3Aus-west-2%3A034017226601%3Astack%2Fstack-gosar-20110427004224-test-stack-with-WaitCondition--VEYW%2Fe498ce60-70a1-11e0-81a7-5081d0136786%2FmyWaitConditionHandle?Expires=1303976584&AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE&Signature=ik1twT6hpS4cgNAw7wyOoRejVoo%3D"

where the file `/tmp/a` contains the following JSON structure: 

{  
   "Status" : "SUCCESS",  
   "Reason" : "Configuration Complete",  
   "UniqueId" : "ID1234",  
   "Data" : "Application has completed configuration."  
}

This example shows a curl command line that sends the same success signal except it sends the JSON structure as a parameter on the command line. 

$ curl -X PUT \  
  -H 'Content-Type:' --data-binary '{"Status" : "SUCCESS","Reason" : "Configuration Complete","UniqueId" : "ID1234","Data" : "Application has completed configuration."}' \  
  "https://amzn-s3-demo-bucket.s3.amazonaws.com/arn%3Aaws%3Acloudformation%3Aus-west-2%3A034017226601%3Astack%2Fstack-gosar-20110427004224-test-stack-with-WaitCondition--VEYW%2Fe498ce60-70a1-11e0-81a7-5081d0136786%2FmyWaitConditionHandle?Expires=1303976584&AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE&Signature=ik1twT6hpS4cgNAw7wyOoRejVoo%3D"

Wait condition signal syntax

When you send signals to the URL generated by the wait condition handle, you must use the following JSON format:

{
  "Status" : "StatusValue",
  "UniqueId" : "Some UniqueId",
  "Data" : "Some Data",
  "Reason" : "Some Reason"
}

Properties

The Status field must be one of the following values:

The UniqueId field identifies the signal to CloudFormation. If theCount property of the wait condition is greater than 1, theUniqueId value must be unique across all signals sent for a particular wait condition; otherwise, CloudFormation will consider the signal a retransmission of the previously sent signal with the same UniqueId and ignore it.

The Data field can contain any information you want to send back with the signal. You can access the Data value by using the Fn::GetAtt function within the template.

The Reason field is a string with no other restrictions on its content besides JSON compliance.

Accessing signal data

To access the data sent by valid signals, you can create an output value for the wait condition in your CloudFormation template. For example:

Outputs:
  WaitConditionData:
    Description: The data passed back as part of signalling the WaitCondition
    Value: !GetAtt MyWaitCondition.Data

You can then view this data using the describe-stacks command, or theOutputs tab of the CloudFormation console.

The Fn::GetAtt function returns the UniqueId andData as a name/value pair within a JSON structure. For example:

{"Signal1":"Application has completed configuration."}