使用公用擴充功能 CloudFormation - AWS CloudFormation
啟用公有擴充功能

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

使用公用擴充功能 CloudFormation

公用擴充 CloudFormation 功能是擴充功能 (例如資源類型或模組)，會公開發佈在登錄中供所有使用 CloudFormation者使用。這包括所有由 AWS. 第三方也可以發佈公有擴充功能。

有兩種公有擴充功能：

  • AWS 公開擴充功能 — 由發佈的擴充功能永遠 AWS 是公開的，且預設為啟用，因此您不需要採取任何動作，才能在帳戶中使用這些擴充功能。此外， AWS 控制擴充功能的版本控制，因此您將始終使用最新的可用版本。

  • 第三方公開擴充功能 — 這些擴充功能可供發佈者以外的其他發行者一般使用 AWS。若要使用公有擴充功能，您必須先在帳戶和區域中啟用它。

    您可以發佈自己的第三方擴充功能，讓一般 CloudFormation 使用者可以使用它們。若要取得更多資訊，請參閱《指CloudFormation 令行介面使用者指南》中的〈發佈擴充

注意

與私有擴充功能一樣，來自第三方發佈者的公有擴充功能可實作在資源建立、讀取、更新、列出和刪除堆疊操作期間執行的事件處理常式。因此，在 CloudFormation堆疊中使用這些擴充功能可能會向您的帳戶產生費用。這是在因建立資源所產生任何費用之外的額外費用。如需詳細資訊，請參閱 AWS CloudFormation 定價。

啟用公用擴充功能以供您使用 AWS 帳戶

若要在範本中使用公有第三方擴充功能，您必須先為要在其中使用它的帳戶和區域啟用該擴充功能。啟用擴充功能以便用於啟用該擴充功能之帳戶和區域中的堆疊操作。當您啟用公開的第三方擴充功能時， CloudFormation 會在帳戶的擴充功能登錄中建立已啟用的擴充功能的項目，做為私人擴充功能。這允許您透過以下方式在帳戶中啟用擴充功能時對其進行自訂：

  • 指定要使用的別名，而不是公有第三方擴充功能名稱。這有助於避免第三方擴充功能之間的命名衝突。

  • 指定新的次要或修補程式版本可用時是否自動更新擴充功能。

  • 指定 CloudFormation 用於啟動擴充功能的執行角色，以及設定擴充功能的記錄。

啟用公有第三方擴充功能時，您也可以設定擴充功能包含的任何組態屬性。組態屬性定義如何為指定帳戶和區域設定擴充功能。有關組態的詳細資訊，請參閱以下內容：

設定 CloudFormation 為自動使用新版本的擴充功能

啟用擴充功能時，您也可以指定要使用最新次要版本的擴充功能類型。發佈者在已啟用的擴充功能上發佈新版本時，擴充功能類型就會更新次要版本。

例如，下次您使用包含該擴充功能的範本執行堆疊作業 (例如建立或更新堆疊) 時， CloudFormation 會使用新的次要版本。

自動或手動更新為新的擴充功能版本，不會影響堆疊中已佈建的任何擴充功能執行個體。

CloudFormation 將擴充功能的主要版本更新視為可能包含中斷變更，因此需要您手動更新為擴充功能的新主要版本。

根據 AWS 預設，所有可用帳戶和地區的擴充功能預設都會啟用，而且每個擴充功能都會使用各個可用的最新版本 AWS 區域。

重要

由於您可以控制擴充功能是否以及何時更新為帳戶中的最新版本，最終可能會在不同帳戶和區域部署相同擴充功能的不同版本。

在這些帳戶和區域中使用包含該擴充功能的相同範本時，這可能會產生未預期的結果。

指定要用來稱呼擴充功能的別名

您無法在指定帳戶和區域中使用指定名稱啟用一個以上的擴充功能。由於不同的發行者可能會提供具有相同副檔名的公用擴充功能，因此可 CloudFormation 讓您為啟用的任何第三方公用擴充功能指定別名。

如果您指定擴充功能的別名，則 CloudFormation 會將別名視為帳戶和區域內的擴充功能類型名稱。您必須使用別名來參照範本、API呼叫和 CloudFormation主控台中的擴充功能。

在指定帳戶和區域中的擴充功能別名必須是唯一的。您可以使用不同類型名稱別名，在同一帳戶和區域中多次啟用相同的公有資源。

重要

雖然擴充功能別名只需要在指定帳戶和區域中為唯一，但我們強烈建議使用者不要為跨帳戶和區域的不同第三方公有擴充功能指派相同的別名。使用包含跨多個帳戶或區域之擴充功能別名的範本時，這樣做可能會產生未預期的結果。

啟動擴充功能時指定執行角色

啟動資源時，您可以指定在帳戶和區域中呼叫該擴充程式時 CloudFormation 要承擔的IAM執行角色。

CloudFormation 若要擔任執行角色，角色必須具有使用定義的信任原則 CloudFormation。此外，透過建立IAM原則並附加至執行角色，授與執行作業的權限。在擴充功能結構描述的處理常式區段中定義必要許可。

以下是資源類型延伸模組的IAM角色信任原則範例：

{
    "Version": "2012-10-17",
    "Statement":[
        {
            "Effect": "Allow",
            "Principal":{
                "Service": "resources.cloudformation.amazonaws.com"
            },
            "Action":"sts:AssumeRole",
            "Condition":{
                "StringEquals":{
                    "aws:SourceAccount":"123456789012"
                },
                "StringLike":{
                    "aws:SourceArn":"arn:aws:cloudformation:us-east-1:123456789012:type/resource/Organization-Service-Resource/*"
                }
            }
        }
    ]
}

以下是勾點延伸模組的IAM角色信任原則範例：

{
    "Version":"2012-10-17",
    "Statement":[
        {
            "Effect":"Allow",
            "Principal": {
                "Service": [
                    "resources.cloudformation.amazonaws.com",
                    "hooks.cloudformation.amazonaws.com"
                ]
            },
            "Action":"sts:AssumeRole",
            "Condition":{
                "StringEquals":{
                    "aws:SourceAccount":"123456789012"
                },
                "StringLike":{
                     "aws:SourceArn":"arn:aws:cloudformation:us-east-1:123456789012:type/hook/Organization-Service-Hook/*"
                }
            }
        }
    ]
}

如需詳細資訊，請參閱《AWS Identity and Access Management 使用者指南》中的修改角色信任政策。

啟用登錄檔中的公有擴充功能

在 AWS CloudFormation 登錄中啟用您的擴充功能，以便可供使用。

使用 CloudFormation主控台啟用您帳戶中使用的公用擴充功能

  1. 請登入 AWS Management Console 並開啟 AWS CloudFormation 主控台，網址為 https://console.aws.amazon.com/cloudformation。

  2. 從CloudFormation瀏覽窗格的CloudFormation 登錄下，選取 [公用擴充功能]。

  3. 使用 Filter (篩選條件) 選取擴充功能類型，然後選取 Third party (第三方)。(依預設， AWS 會啟用由發佈的延伸功能。)

  4. 選取擴充功能，然後選取 Activate (啟用)。

    注意

    如果擴充功能有多個版本，您可以使用 Version (版本) 選單選取要啟用的擴充功能版本。預設為最新版本。

  5. 使用 Activate extension (啟用擴充功能) 頁面上的選項，以自訂在此帳戶中啟用擴充功能的方式。

    • 若要使用擴充功能類型別名啟用擴充功能：

      1. 選取 Override default (覆寫預設值)

      2. 輸入要搭配此擴充功能使用的擴充功能類型別名。別名必須遵循擴充功能類型的推薦格式。

      如需詳細資訊，請參閱指定要用來稱呼擴充功能的別名。

    • 如果您要啟用私有資源，則可以指定呼叫擴充功能時 CloudFormation 要承擔的IAM角色。如需詳細資訊，請參閱在啟用擴充功能時指定執行角色。

    • 在 Logging config (記錄設定) 下，指定擴充功能的記錄組態資訊 (若需要)。例如：

      {
    "logRoleArn": "arn:aws:iam::account:role/rolename",
    "logGroupName": "log-group-name"
}

      記錄組態資訊不是必需的，但建議作為除錯用途使用。若要使用帶掛鉤的記錄組態，請新增與指定執行角色相同的信任政策，以便日誌角色可以將日誌寫入您的日誌群組。

      logRoleArn和logGroupName密鑰名稱是區分大小寫的。

    • 在 Versioning (版本控制) 下，指定接收更新的方式。

      • On (打開) – 自動更新為最新次要版本。主要版本需手動更新。

      • Off (關閉) – 永不自動更新為最新版本。所有版本需手動更新。

      如需詳細資訊，請參閱自動 CloudFormation 使用新版擴充功能的設定。

  6. 指定組態資料。

    注意

    掛鉤需要此步驟。您必須為 TargetStack 屬性指定 ALL。此操作將啟用掛鉤結構描述屬性區段中定義的掛鉤屬性。

    如果擴充功能需要帳戶和區域層級的其他設定， CloudFormation 請在 [啟用擴充功能] 頁面上加入 [組態] 區段。您可以選擇現在指定組態資料,或在啟用擴充功能之後指定。如果擴充功能不需要組態，您將不會看見 Configuration (組態) 區段。

    • 若在啟用擴充功能時指定組態資料：

      1. 選取 Configure now (立即設定)，然後選取 Activate extension (啟用擴充功能)。

        CloudFormation 顯示 [設定擴充功能] 頁面。若要檢視擴充功能的目前組態結構描述，請確保已啟用 View configuration schema (檢視組態結構描述)。

      2. 在「組態」JSON 文字方塊中，輸入JSON字串，代表您要為此延伸模組指定的組態結構描述。

      3. 選取 Configure extension (設定擴充功能)。

    • 若要稍後指定組態資料：

      • 選取 Configure later (稍後設定)，然後選取 Activate extension (啟用擴充功能)。

      若要為已啟用的擴充功能指定組態資料，請造訪已啟用擴充功能的詳細資訊頁面。

    成功啟用擴充功能後， CloudFormation 會顯示該擴充功能的詳細資訊頁面。

使用 CloudFormation主控台更新帳戶中已啟用的公開擴充功能

在 AWS CloudFormation 登錄中更新您的擴充功能，以便可供使用。

在帳戶和區域中啟用擴充功能後，您可以在啟用該擴充功能時更新下列屬性，包括：

  • 組態結構描述。

  • 是否啟用自動版本更新。

  • 私有已註冊擴充功能要使用的執行角色。

  • 記錄組態資訊。

  1. 請登入 AWS Management Console 並開啟 AWS CloudFormation 主控台，網址為 https://console.aws.amazon.com/cloudformation。

  2. 從CloudFormation瀏覽窗格的CloudFormation 登錄下，選取 [公用擴充功能]。

  3. 在 Actions (動作) 選單中，選取 Edit (編輯)，然後選取適當的編輯選項：

    • 若要更新組態結構描述，請參閱若要在 CloudFormation 主控台中指定擴充功能的組態特性

    • 若要啟用或停用自動更新：

      1. 選取 Edit automatic updates (編輯自動更新)。

      2. 選取 On (打開) 或者 Off (關閉)，然後選取 Save (儲存)。

    • 若要更新執行角色：

      1. 選取 Edit execution role (編輯執行角色)。

      2. 指定呼叫此延伸模ARN組時 CloudFormation 要使用的IAM角色，然後選取 [儲存]。

    • 若要更新記錄組態：

      1. 選取 Edit logging config (編輯記錄組態)。

      2. 編輯記錄日誌組態JSON，然後選取儲存。

若要啟用公用擴充功能，以便在您的帳戶中使用 AWS CLI

在 AWS CloudFormation 登錄中啟用您的擴充功能，透過 AWS CLI.

啟用掛鉤

開發並註冊掛鉤後，您可以 AWS 帳戶 通過將其發佈到註冊表來激活鉤子。

  • 若要啟用帳戶中的掛鉤，請使用 SetTypeConfiguration 操作。此操作將啟用掛鉤結構描述 properties 區段中定義的掛鉤屬性。

    注意

    透過在您的帳戶中啟用勾點，即表示您授權鉤子使用您 AWS 帳戶的. CloudFormation 在將權限傳遞給勾點之前，會移除非必要的權限。 CloudFormation 建議客戶或掛鉤使用者檢閱勾點權限，並瞭解允許掛接的權限，然後再啟用帳戶中的勾點。

    在同一帳戶和 AWS 區域中指定已註冊掛鉤擴充功能的組態資料。

    aws cloudformation --region us-west-2 set-type-configuration \
  --configuration "{"CloudFormationConfiguration":{"HookConfiguration":{"TargetStacks": "ALL", "FailureMode": "FAIL", "Properties":{}}}}" \
  --type-arn $HOOK_TYPE_ARN
    重要

    若要讓掛鉤主動檢查堆疊的組態，您必須在 HookConfiguration 區段中將 TargetStacks 設定為 ALL。

啟用資源類型和模組
使用 AWS CLI啟用公有擴充功能，以便在帳戶中使用

  • 使用 activate-type 啟用擴充功能，並指定是否在發佈擴充功能的新次要版本時自動更新擴充功能。

    以下範例指定要為此帳戶啟用的公用擴充功能的公用 Amazon 資源名稱 (ARN)。此外，它還指定每當發佈新的次要版本時 CloudFormation 更新擴充功能。

    aws cloudformation activate-type \
  --public-type-arn public_extension_ARN \
  --auto-update true

    此命令會傳回已啟動ARN的擴充功能，特定於此帳戶和區域。

    {
    "Arn": "624af370-311a-11e8-b6b7-500cexample"
}
若要使用更新公用擴充功能的版本 AWS CLI

使用 activate-type 再次啟用擴充功能。

使用 --version-bump 參數指定是否將擴充功能更新為最新 MAJOR 版本、最新 MINOR 版本。

aws cloudformation activate-type \
    --region us-west-2 \
    --type RESOURCE \
    --type-name Example::Test::1234567890abcdef0 \
    --type-name-alias Example::Test::Alias \
    --version-bump MAJOR

停用帳戶中的公有擴充功能

下列章節說明如何停用帳戶中的公有擴充功能。

使用 CloudFormation 主控台停用帳戶中的公用擴充功能

  1. 使用 CloudFormation 登錄來尋找擴充功能。

  2. 在 Actions (動作) 選單中，選取 Deactivate (停用)。

  3. 選取 Deactivate (停用)。

若要停用帳戶中的公用分機，請使用 AWS CLI

若要停用帳戶中的公有擴充功能，請指定 deactivate-type。以下是 AWS CLI 停用命令的範例。

aws cloudformation deactivate-type \
    --region us-west-2 \
    --type MODULE \
    --type-name Example::Test::Type::MODULE

若要停用帳戶中的掛鉤，請使用 AWS CLI

停用掛鉤可以防止掛鉤執行 AWS 帳戶。

TargetStacks 設定為 NONE 會關閉帳戶中的掛鉤，因此其不適用於堆疊操作。

使用 set-type-configuration 操作並將 TargetStacks 指定為 NONE 以停用掛鉤。

下列範例指定要停用的掛接的 AWS 區域 和 Amazon 資源名稱 (ARN)。

aws cloudformation set-type-configuration \
  --region us-west-2 \
  --configuration "{"CloudFormationConfiguration":{"HookConfiguration":{"TargetStacks": "NONE", "FailureMode": "FAIL", "Properties":{}}}}" \
  --type-arn HOOK_TYPE_ARN