建立 CloudFormation 巨集定義 - AWS CloudFormation
事件映射回應格式建立巨集定義巨集的範本範圍巨集評估順序

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

建立 CloudFormation 巨集定義

當您建立巨集定義時，巨集定義會在指定的帳戶中提供基礎 Lambda 函式，供 CloudFormation 調用以處理範本。

事件映射

當 CloudFormation 調用巨集的 Lambda 函式時，會傳送 JSON 格式的請求，其結構如下：

{
    "region" : "us-east-1",
    "accountId" : "$ACCOUNT_ID",
    "fragment" : { ... },
    "transformId" : "$TRANSFORM_ID",
    "params" : { ... },
    "requestId" : "$REQUEST_ID",
    "templateParameterValues" : { ... }
}

  • region

    巨集所在的區域。

  • accountId

    供巨集用來叫用 Lambda 函數的帳戶的帳戶 ID。

  • fragment

    可供自訂處理的範本內容 (JSON 格式)。

    • 對於 Transform 範本區段包含的巨集，這是整個範本 (Transform 區段除外)。

    • 對於 Fn::Transform 內部函數呼叫包含的巨集，這包括以內部函數 (Fn::Transform 函數除外) 在範本內的位置為基礎的所有同級節點 (及其子系)。如需更多詳細資訊，請參閱 巨集的範本範圍。

  • transformId

    叫用此函數的巨集的名稱。

  • params

    若為 Fn::Transform 函數呼叫，則為該函數指定的任何參數。CloudFormation 不會在將這些參數傳遞至 函數之前對其進行評估。

    對於 Transform 範本區段包含的巨集，這個區段是空的。

  • requestId

    叫用此函數的請求的 ID。

  • templateParameterValues

    範本 Parameters 區段中指定的任何參數。CloudFormation 會在將這些參數傳遞至函數之前對其進行評估。

回應格式

CloudFormation 期望 Lambda 函式傳回的回應是下列 JSON 格式：

{
    "requestId" : "$REQUEST_ID",
    "status" : "$STATUS",
    "fragment" : { ... },
    "errorMessage": "optional error message for failures"
}

  • requestId

    叫用此函數的請求的 ID。這必須符合 CloudFormation 在調用函數時提供的請求 ID。

  • status

    請求的狀態 (不區分大小寫)。應設為 success。CloudFormation 會將任何其他回應視為失敗。

  • fragment

    供 CloudFormation 納入處理後範本的已處理範本內容，含同級項目。CloudFormation 會將傳遞給 Lambda 函式的範本內容取代為在 Lambda 回應中收到的範本片段。

    處理過的範本內容必須是有效的 JSON，而納入所處理的範本中之後必須形成有效的範本。

    如果您的函數不實際變更 CloudFormation 傳來的範本內容，但您仍然需要將該內容納入所處理的範本中，則函數必須在其回應中將該範本內容傳回給 CloudFormation。

  • errorMessage

    說明轉換失敗原因的錯誤訊息。CloudFormation 會在堆疊 Stack details (堆疊詳細資訊) 頁面的 Events (事件) 窗格中顯示此錯誤訊息。

    例如：

    Error creating change set: Transform
                            AWS 帳戶 account
                            number::macro name failed with:
                            error message string.

建立巨集定義

建立 CloudFormation 巨集定義

  1. 建置 Lambda 函式，用於處理範本內容的處理。它可以處理範本的任何部分，甚至整個範本。

  2. 建立包含 AWS::CloudFormation::Macro 資源類型的 CloudFormation 範本，並指定 Name 和 FunctionName 屬性。FunctionName 屬性必須包含當 CloudFormation 執行巨集時調用的 Lambda 函式的 ARN。

  3. (選用) 為了協助除錯，當您為巨集建立 AWS::CloudFormation::Macro 資源類型時，您也可以指定 LogGroupName 和 LogRoleArn 屬性。這些屬性可讓您指定 CloudWatch Logs 日誌群組，供 CloudFormation 在調用巨集的基礎 Lambda 函式時傳送錯誤日誌記錄資訊，也可指定 CloudFormation 將日誌項目傳送到這些日誌時應該擔任的角色。

  4. 在您要使用它的帳戶中，使用具有巨集的範本建立堆疊。或者，在管理員帳戶中使用包含該巨集的範本，建立具有自我管理許可的堆疊集，然後在目標帳戶中建立堆疊執行個體。

  5. 當 CloudFormation 成功建立包含巨集定義的堆疊之後，即可在這些帳戶內使用巨集。在範本中，請在您要處理的範本內容的相對適當位置上參考巨集，以此來使用巨集。

巨集的範本範圍

範本的 Transform 區段中參考的巨集可以處理該範本的整個內容。

Fn::Transform 函數中參考的巨集可以處理該 Fn::Transform 函數在範本中的任何同級元素 (包括子系) 的內容。

例如，在以下範本範例中，AWS::Include 可以根據其所在 MyBucket 函數的位置，而處理所有 Fn::Transform 屬性。MyMacro 可以處理整個範本的內容，因為它已納入 Transform 區段中。

# Start of processable content for MyMacro
AWSTemplateFormatVersion: 2010-09-09 
 Transform: [MyMacro]
 Resources:
    WaitCondition:
      Type: AWS::CloudFormation::WaitCondition
    MyBucket:
      Type: AWS::S3::Bucket
      # Start of processable content for AWS::Include
      Properties:
        BucketName: amzn-s3-demo-bucket1
        Tags: [{"key":"value"}] 
        'Fn::Transform':
          - Name: 'AWS::Include'
              Parameters:
                Location: s3://amzn-s3-demo-bucket2/MyFileName.yaml
        CorsConfiguration: []
        # End of processable content for AWS::Include
    MyEc2Instance:
      Type: AWS::EC2::Instance
      Properties:
        ImageID: ami-1234567890abcdef0
# End of processable content for MyMacro

巨集評估順序

您可以在給定的範本中參考多個巨集，包括由 CloudFormation 託管的轉換，例如 AWS::Include 和 AWS::Serverless。

巨集是根據在範本中的位置而依序評估，從最深巢狀往外到最通用。範本中同一位置的巨集是根據它們所列順序而按順序評估。

在動作順序和範圍方面，轉換 (例如 AWS::Include 和 AWS::Transform) 與任何其他巨集視為相同。

例如，在以下範本範例中，CloudFormation 會先評估 PolicyAdder 巨集，因為它是範本中最深層巢狀的巨集。然後，CloudFormation 會評估 MyMacro，再評估 AWS::Serverless，因為它在 Transform 區段中列在 AWS::Serverless 前面。

AWSTemplateFormatVersion: 2010-09-09
 Transform: [MyMacro, AWS::Serverless]
 Resources:
    WaitCondition:
      Type: AWS::CloudFormation::WaitCondition
    MyBucket:
      Type: AWS::S3::Bucket
      Properties:
        BucketName: amzn-s3-demo-bucket
        Tags: [{"key":"value"}]
        'Fn::Transform':
          - Name: PolicyAdder
        CorsConfiguration: []
    MyEc2Instance:
      Type: AWS::EC2::Instance
      Properties:
        ImageID: ami-1234567890abcdef0