在 CloudFormation 範本中建立等待條件 - AWS CloudFormation
在您的範本中建立等待條件等待條件訊號語法存取訊號資料

在 CloudFormation 範本中建立等待條件

此主題解釋了如何在範本中建立等待條件可協調堆疊資源的建立，或追蹤組態程序的進度。例如，您可以在應用程式組態完成一部分後，開始建立另一個資源，或是在安裝和組態程序期間傳送訊號來追蹤其進度。

在 CloudFormation 建立包含等待條件的堆疊時：

  • 它像任何其他資源一樣建立等待條件，並將等待條件的狀態設定為 CREATE_IN_PROGRESS。

  • CloudFormation 會等待，直到收到所需數量的成功訊號，或等待條件的逾時時間到期。

  • 若在逾時時間到期前收到所需數量的成功訊號：

    • 等待條件狀態變更為 CREATE_COMPLETE

    • 堆疊建立繼續

  • 如果逾時過期，或收到失敗訊號：

    • 等待條件狀態變更為 CREATE_FAILED

    • 堆疊復原

重要

針對 Amazon EC2 和 Auto Scaling 資源，我們建議您使用 CreationPolicy 屬性，而非等待條件。請將 CreationPolicy 屬性新增至這類資源，並使用 cfn-signal 的 helper 指令碼在執行個體建立流程成功完成後發出訊號。

如需詳細資訊，請參閱 CreationPolicy 屬性。

注意

若您使用 AWS PrivateLink，則 VPC 中回應等待條件的資源必須能夠存取 CloudFormation 限定的 Amazon Simple Storage Service (Amazon S3) 儲存貯體。資源必須傳送等待條件回應至預先簽章的 Amazon S3 URL。若無法將回應傳送至 Amazon S3，CloudFormation 便不會收到回應，而堆疊操作則會失敗。如需詳細資訊，請參閱 使用介面端點存取 CloudFormation (AWS PrivateLink) 和使用儲存貯體政策控制 VPC 端點的存取。

在您的範本中建立等待條件

1. 等待條件控點

首先在堆疊的範本中定義 AWS::CloudFormation::WaitConditionHandle 資源。此資源會產生傳送訊號所需的預先簽章 URL。這可讓您傳送訊號，無需提供您的 AWS 憑證。例如：

Resources:
  MyWaitHandle:
    Type: AWS::CloudFormation::WaitConditionHandle
2. 等待條件

接下來，您可在堆疊的範本中定義 AWS::CloudFormation::WaitCondition 資源。AWS::CloudFormation::WaitCondition 的基本結構如下所示：

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

AWS::CloudFormation::WaitCondition 資源有兩個必要屬性和一個選用屬性。

  • Handle (必要) – 範本中所宣告 WaitConditionHandle 的參考。

  • Timeout (必要) – CloudFormation 等待收到必要訊號數的秒數。Timeout 是最小限制屬性，表示逾時不會早於您指定的時間，但會在之後不久發生。您可以指定的時間上限是 43200 秒 (12 小時)。

  • Count (選用) – CloudFormation 在將等待條件的狀態設定為 CREATE_COMPLETE 之前，必須接收的成功訊號數量，並繼續建立堆疊。如果未指定，預設值為 1。

通常，您會希望等待條件在特定資源建立完成後立即開始。若要執行此作業，請將 DependsOn 屬性新增至等待條件。向等待條件新增 DependsOn 屬性後，CloudFormation 會先建立 DependsOn 屬性中指定的資源，再建立等待條件。如需詳細資訊，請參閱 DependsOn 屬性。

下列範例示範的等待條件如下：

  • 在成功建立 MyEC2Instance 資源後開始

  • 將 MyWaitHandle 資源用作 WaitConditionHandle

  • 逾時時間為 4500 秒

  • 預設 Count 為 1 (因為未指定 Count 屬性)

  MyWaitCondition:
    Type: AWS::CloudFormation::WaitCondition
    DependsOn: MyEC2Instance
    Properties:
      Handle: !Ref MyWaitHandle
      Timeout: '4500'
3. 傳送訊號

若要向 CloudFormation 傳出成功或失敗訊號，您通常會執行一些程式碼或指令碼。例如，在 EC2 執行個體上執行的應用程式可能會執行一些額外的組態工作，然後向 CloudFormation 傳送訊號以表示完成。

訊號必須傳送至等待條件控制代碼產生的預先簽章 URL。使用預先簽章的 URL 傳送成功或失敗訊號。

傳送訊號

  1. 要擷取範本中的預先簽章 URL，請使用 Ref 內建函數搭配等待條件控點的邏輯名稱。

    如以下範例所示，您的範本可以宣告 Amazon EC2 執行個體，並透過 Amazon EC2 UserData 屬性將預先簽章的 URL 傳遞至 Amazon EC2 執行個體。這讓在這些執行個體上執行的指令碼或應用程式能向 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" }

    這導致 UserData 輸出結果類似以下內容：

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

    注意：在 AWS 管理主控台 或命令列工具中，預先簽章的 URL 會作為等待條件控點資源的實體 ID 顯示。

  2. (選用) 若要偵測堆疊何時進入等待條件，您可以使用下列其中一種方法：

    • 如果您建立堆疊並啟用通知，CloudFormation 會針對每個堆疊事件發佈通知到指定的主題。如果您或您的應用程式訂閱該主題，您可以監控等待條件控點建立事件的通知，並從通知訊息擷取預先簽章的 URL。

    • 您也可以使用 AWS 管理主控台、AWS CLI 或 SDK 來監控堆疊的事件。

  3. 若要傳送訊號，您可以使用預先簽章的 URL 傳送 HTTP 請求訊息。請求方法必須是 PUT，而且 Content-Type 標頭必須是空白字串或予以省略。請求訊息必須是 等待條件訊號語法 中指定格式的 JSON 結構。

    您必須傳送 Count 屬性指定的成功訊號數目，CloudFormation 才能繼續建立堆疊。如果您的 Count 大於 1，在傳送至特定等待條件的所有訊號之間，每個訊號的 UniqueId 值必須都是不重複的。UniqueId 是任意英數字串。

    curl 命令是傳送訊號的一種方式。下列範例示範將成功訊號傳送至等待條件的 curl 命令列。

    $ 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"

    其中 /tmp/a 檔案包含下列 JSON 結構：

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

    此範例示範傳送同一個成功訊號的 curl 命令列，差別在於在命令列中以參數的形式傳送 JSON 結構。

    $ 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"

等待條件訊號語法

當您向等候條件控點所產生的 URL 傳送訊號時，您必須使用下列 JSON 格式：

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

屬性

Status 欄位可以是以下其中一個值：

  • SUCCESS

  • FAILURE

UniqueId 欄位用於識別 CloudFormation 的訊號。如果等待條件的 Count 屬性大於 1，UniqueId 值在傳送給特定等待條件的所有訊號之間必須是唯一的；否則，CloudFormation 會認為是使用先前傳送過 UniqueId 相同之訊號重新傳輸的訊號，而忽略該訊號。

Data 欄位可包含您想要隨訊號傳回的任何資訊。在範本內使用 Fn::GetAtt 函數就可存取 Data 值。

Reason 欄位是字串，內容除了需要符合 JSON 規定以外，沒有其他限制。

存取訊號資料

要存取有效訊號傳送的資料，您可在 CloudFormation 範本中建立等待條件的輸出值。例如：

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

然後，您可使用 describe-stacks 命令或 CloudFormation 主控台的輸出索引標籤來檢視此資料。

Fn::GetAtt 函數會在 JSON 結構內以名稱/值對的形式傳回 UniqueId 和 Data。例如：

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