本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # CloudFormation StackSets 部署動作參考 CodePipeline 可讓您在 CI/CD 程序中執行 CloudFormation StackSets 操作。您可以使用堆疊集，透過使用單一 CloudFormation 範本在跨 AWS 區域的 AWS 帳戶中建立堆疊。每個堆疊中包含的所有資源都由堆疊集的 CloudFormation 範本定義。建立堆疊集時，您可以指定要使用的範本，以及範本所需的任何參數和功能。 如需 for CloudFormation StackSets 概念的詳細資訊，請參閱*AWS CloudFormation 《 使用者指南*》中的 [StackSets 概念](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-concepts.html)。 您可以將管道與 CloudFormation StackSets 透過兩種不同的動作類型整合在一起： + `CloudFormationStackSet` 動作會從存放在管道來源位置的範本建立或更新堆疊集或堆疊執行個體。每次建立或更新堆疊集時，都會啟動對指定執行個體進行這些變更的部署。在 主控台中，您可以在建立或編輯管道時選擇 **CloudFormation 堆疊集**動作提供者。 + `CloudFormationStackInstances` 動作會將變更從`CloudFormationStackSet`動作部署到指定的執行個體、建立新的堆疊執行個體，以及定義參數覆寫到指定的執行個體。在 主控台中，您可以在編輯現有管道時選擇 **CloudFormation Stack Instances** 動作提供者。 您可以使用這些動作來部署到目標 AWS 帳戶或目標 AWS Organizations 組織單位 IDs。 **注意** 若要部署至目標 AWS Organizations 帳戶或組織單位 IDs，並使用服務受管許可模型，您必須在 AWS CloudFormation StackSets 和 AWS Organizations 之間啟用受信任的存取。如需詳細資訊，請參閱[使用 Stacksets AWS CloudFormation 啟用受信任存取](https://docs.aws.amazon.com/organizations/latest/userguide/services-that-can-integrate-cloudformation.html#integrate-enable-ta-cloudformation)。 **Topics** + [How CloudFormation StackSets 動作的運作方式](#action-reference-StackSets-concepts) + [如何在管道中建構 StackSets 動作](#action-reference-StackSets-bestpractices) + [`CloudFormationStackSet` 動作](#action-reference-StackSet) + [CloudFormationStackInstances 動作](#action-reference-StackInstances) + [服務角色許可：`CloudFormationStackSet`動作](#edit-role-cfn-stackset) + [服務角色許可：`CloudFormationStackInstances`動作](#edit-role-cfn-stackinstances) + [堆疊集操作的許可模型](#action-reference-StackSets-permissions) + [範本參數資料類型](#action-reference-StackSets-datatypes) + [另請參閱](#action-reference-CloudFormation-links) ## How CloudFormation StackSets 動作的運作方式 `CloudFormationStackSet` 動作會根據動作是否第一次執行來建立或更新資源。 `CloudFormationStackSet` 動作會*建立*或*更新*堆疊集，並將這些變更部署到指定的執行個體。 **注意** 如果您使用此動作進行包含新增堆疊執行個體的更新，則會先部署新的執行個體，最後完成更新。新執行個體會先收到舊版本，然後將更新套用至所有執行個體。 + *建立*：未指定執行個體且堆疊集不存在時，**CloudFormationStackSet** 動作會在不建立任何執行個體的情況下建立堆疊集。 + *更新*：針對已建立的堆疊集執行 **CloudFormationStackSet** 動作時，動作會更新堆疊集。如果未指定執行個體且堆疊集已存在，則會更新所有執行個體。如果使用此動作更新特定執行個體，則所有剩餘的執行個體都會移至 OUTDATED 狀態。 您可以使用 **CloudFormationStackSet** 動作，以下列方式更新堆疊集。 + 更新部分或所有執行個體上的範本。 + 更新部分或全部執行個體上的參數。 + 更新堆疊集的執行角色 （這必須符合管理員角色中指定的執行角色）。 + 變更許可模型 （只有在未建立執行個體時）。 + `AutoDeployment` 如果堆疊集許可模型為 ，請啟用/停用 `Service Managed`。 + 如果堆疊集許可模型為 ，則擔任成員帳戶中的委派管理員`Service Managed`。 + 更新管理員角色。 + 更新堆疊集上的描述。 + 將部署目標新增至堆疊集更新，以建立新的堆疊執行個體。 `CloudFormationStackInstances` 動作會建立新的堆疊執行個體或更新過時的堆疊執行個體。當堆疊集更新時，執行個體會變得過時，但並非所有執行個體都會更新。 + *建立*：如果堆疊已存在，則`CloudFormationStackInstances`動作只會更新執行個體，而不會建立堆疊執行個體。 + *更新*：執行`CloudFormationStackSet`動作後，如果範本或參數僅在部分執行個體中更新，則其餘項目將標示為 `OUTDATED`。在稍後的管道階段中， 會以波浪`CloudFormationStackInstances`更新堆疊集中的其餘執行個體，以便所有執行個體都標示為 `CURRENT`。此動作也可以用來在新的或現有的執行個體上新增其他執行個體或覆寫參數。 在更新過程中， `CloudFormationStackSet`和 `CloudFormationStackInstances`動作可以指定新的部署目標，以建立新的堆疊執行個體。 在更新過程中， `CloudFormationStackSet`和 `CloudFormationStackInstances`動作不會刪除堆疊集、執行個體或資源。當動作更新堆疊但未指定要更新的所有執行個體時，未指定進行更新的執行個體會從更新中移除，並設為 狀態`OUTDATED`。 在部署期間，`OUTDATED`如果部署到執行個體失敗，堆疊執行個體也可以顯示 的狀態。 ## 如何在管道中建構 StackSets 動作 根據最佳實務，您應該建構管道，以便建立堆疊集，並最初部署到子集或單一執行個體。在您測試部署並檢視產生的堆疊集之後，請新增 `CloudFormationStackInstances`動作，以建立和更新剩餘的執行個體。 使用 主控台或 CLI 建立建議的管道結構，如下所示： 1. 使用來源動作 （必要） 和 `CloudFormationStackSet`動作做為部署動作來建立管道。執行您的管道。 1. 當您的管道第一次執行時，`CloudFormationStackSet`動作會*建立*堆疊集和至少一個初始執行個體。驗證堆疊集建立，並檢閱初始執行個體的部署。例如，對於帳戶 Account-A 的初始堆疊集建立，其中 `us-east-1`是指定的區域，則會使用堆疊集建立堆疊執行個體： **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/codepipeline/latest/userguide/action-reference-StackSets.html) 1. 編輯管道以新增 `CloudFormationStackInstances`做為第二個部署動作，為您指定的目標建立/更新堆疊執行個體。例如，針對指定 `Account-A` `us-east-2`和 `eu-central-1`區域的帳戶建立堆疊執行個體時，會建立剩餘的堆疊執行個體，且初始執行個體會保持更新，如下所示： **** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/codepipeline/latest/userguide/action-reference-StackSets.html) 1. 視需要執行管道，以更新堆疊集，並更新或建立堆疊執行個體。 當您啟動堆疊更新，其中您已從動作組態中移除部署目標，則未指定進行更新的堆疊執行個體會從部署中移除，並移至 OUTDATED 狀態。例如，針對從動作組態中移除`us-east-2`區域`Account-A`之帳戶的堆疊執行個體更新，會建立剩餘的堆疊執行個體，並將移除的執行個體設定為 OUTDATED，如下所示： **** | 堆疊執行個體 | 區域 | 狀態 | | --- | --- | --- | | StackInstanceID-1 | us-east-1 | CURRENT | | StackInstanceID-2 | us-east-2 | 過期 | | StackInstanceID-3 | eu-central-1 | CURRENT | 如需部署堆疊集的最佳實務的詳細資訊，請參閱《 *AWS CloudFormation 使用者指南*》中的 StackSets 的[最佳實務](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-bestpractices.html)。 ## `CloudFormationStackSet` 動作 此動作會從存放在管道來源位置的範本建立或更新堆疊集。 定義堆疊集之後，您可以在組態參數中指定的目標帳戶和區域中建立、更新或刪除堆疊。建立、更新和刪除堆疊時，您可以指定其他偏好設定，例如要執行操作的區域順序、堆疊操作停止的容錯能力百分比，以及同時在堆疊上執行操作的帳戶數量。 堆疊集是區域性資源。如果您在一個 AWS 區域中建立堆疊集，則無法從其他區域存取它。 當此動作用作堆疊集的更新動作時，如果沒有部署到至少一個堆疊執行個體，則不允許更新堆疊。 **Topics** + [動作類型](#action-reference-StackSet-type) + [組態參數](#action-reference-StackSet-config) + [Input artifacts (輸入成品)](#action-reference-StackSet-input) + [輸出成品](#action-reference-StackSet-output) + [輸出變數](#action-reference-StackSet-variables) + [**CloudFormationStackSet** 動作組態範例](#action-reference-StackSet-example) ### 動作類型 + 類別：`Deploy` + 擁有者：`AWS` + 提供者：`CloudFormationStackSet` + 版本：`1` ### 組態參數 **StackSetName** 必要：是 要與堆疊集相關聯的名稱。此名稱在建立該名稱的區域中必須是唯一的。 名稱只能包含英數字元和連字號字元。它必須以字母字元開頭，且不超過 128 個字元。 **Description** 必要：否 堆疊集的描述。您可以使用此描述堆疊集的目的或其他相關資訊。 **TemplatePath** 必要：是 定義堆疊集中資源的範本位置。這必須指向大小上限為 460，800 個位元組的範本。 輸入來源成品名稱和範本檔案的路徑，格式為 `"InputArtifactName::TemplateFileName"`，如下列範例所示。 ``` SourceArtifact::template.txt ``` **Parameters** 必要：否 部署期間更新之堆疊集的範本參數清單。 您可以提供參數做為常值清單或檔案路徑： + 您可以輸入下列速記語法格式的參數：`ParameterKey=string,ParameterValue=string,UsePreviousValue=boolean,ResolvedValue=string ParameterKey=string,ParameterValue=string,UsePreviousValue=boolean,ResolvedValue=string`。如需這些資料類型的詳細資訊，請參閱 [範本參數資料類型](#action-reference-StackSets-datatypes)。 下列範例顯示名為 `BucketName`的參數，其值為 `amzn-s3-demo-source-bucket`。 ``` ParameterKey=BucketName,ParameterValue=amzn-s3-demo-source-bucket ``` 下列範例顯示具有多個參數的項目： ``` ParameterKey=BucketName,ParameterValue=amzn-s3-demo-source-bucket ParameterKey=Asset1,ParameterValue=true ParameterKey=Asset2,ParameterValue=true ``` + 您可以輸入檔案的位置，其中包含以 格式輸入的範本參數覆寫清單`"InputArtifactName::ParametersFileName"`，如下列範例所示。 ``` SourceArtifact::parameters.txt ``` 下列範例顯示 的檔案內容`parameters.txt`。 ``` [ { "ParameterKey": "KeyName", "ParameterValue": "true" }, { "ParameterKey": "KeyName", "ParameterValue": "true" } ] ``` **功能** 必要：否 表示範本可以建立和更新資源，具體取決於範本中的資源類型。 如果您在堆疊範本中有 IAM 資源，或直接從包含巨集的範本建立堆疊，則必須使用此屬性。若要讓 CloudFormation 動作以這種方式成功運作，您必須使用下列其中一項功能： + `CAPABILITY_IAM` + `CAPABILITY_NAMED_IAM` 您可以使用逗號指定多個功能，而且功能之間沒有空格。中的範例[**CloudFormationStackSet** 動作組態範例](#action-reference-StackSet-example)顯示具有多個功能的項目。 **PermissionModel** 必要：否 決定如何建立和管理 IAM 角色。如果未指定 欄位，則會使用預設值。如需相關資訊，請參閱[堆疊集操作的許可模型](#action-reference-StackSets-permissions)。 有效的值如下： + `SELF_MANAGED` （預設）：您必須建立管理員和執行角色，才能部署到目標帳戶。 + `SERVICE_MANAGED`： CloudFormation StackSets 會自動建立部署到 AWS Organizations 管理的帳戶所需的 IAM 角色。這需要 帳戶成為 組織的成員。 只有在堆疊集中沒有堆疊執行個體時，才能變更此參數。 ****AdministrationRoleArn**** 由於 CloudFormation StackSets 跨多個帳戶執行操作，您必須先在這些帳戶中定義必要的許可，才能建立堆疊集。 必要：否 此參數對於 SELF\$1MANAGED 許可模型是選用的，不用於 SERVICE\$1MANAGED 許可模型。 管理員帳戶中用於執行堆疊集操作的 IAM 角色 ARN。 名稱可包含英數字元，以下任一個字元：\$1\$1=、.@- 且不含空格。名稱不區分大小寫。此角色名稱的長度下限為 20 個字元，上限為 2048 個字元。角色名稱在帳戶中必須是唯一的。此處指定的角色名稱必須是現有的角色名稱。如果您未指定角色名稱，則會將其設定為 AWSCloudFormationStackSetAdministrationRole。如果您指定 ServiceManaged，則不得定義角色名稱。 ****ExecutionRoleName**** 由於 CloudFormation StackSets 跨多個帳戶執行操作，您必須先在這些帳戶中定義必要的許可，才能建立堆疊集。 必要：否 此參數對於 SELF\$1MANAGED 許可模型是選用的，不用於 SERVICE\$1MANAGED 許可模型。 用於執行堆疊集操作的目標帳戶中的 IAM 角色名稱。名稱可包含英數字元，以下任一個字元：\$1\$1=、.@- 且不含空格。名稱不區分大小寫。此角色名稱的長度下限為 1 個字元，上限為 64 個字元。角色名稱在帳戶中必須是唯一的。此處指定的角色名稱必須是現有的角色名稱。如果您使用的是自訂執行角色，請勿指定此角色。如果您未指定角色名稱，則會將其設定為 `AWSCloudFormationStackSetExecutionRole`。如果您將 Service\$1Managed 設定為 true，則不得定義角色名稱。 ****OrganizationsAutoDeployment**** 必要：否 此參數是 SERVICE\$1MANAGED 許可模型的選用參數，不會用於 SELF\$1MANAGED 許可模型。 描述 CloudFormation StackSets 是否自動部署到 AWS 新增至目標組織或組織單位 (OU) 的 Organizations 帳戶。如果已指定 `OrganizationsAutoDeployment` ，請勿指定 `DeploymentTargets`和 `Regions`。 如果未提供 的輸入`OrganizationsAutoDeployment`，則預設值為 `Disabled`。 有效的值如下： + `Enabled`。 必要：否。 StackSets 會自動將額外的堆疊執行個體部署到新增至指定區域中目標組織或組織單位 (OU) 的 AWS Organizations 帳戶。如果帳戶已從目標組織或 OU 中移除， CloudFormation StackSets 會從指定區域中的帳戶刪除堆疊執行個體。 + `Disabled`。 必要：否。 StackSets 不會自動將其他堆疊執行個體部署到新增至指定區域中目標組織或組織單位 (OU) 的 AWS Organizations 帳戶。 + `EnabledWithStackRetention`。 必要：否。 從目標組織或 OU 移除帳戶時，會保留堆疊資源。 ****DeploymentTargets**** 必要：否 對於 SERVICE\$1MANAGED 許可模型，您可以為部署目標提供組織根 ID 或組織單位 IDs。對於 SELF\$1MANAGED 許可模型，您只能提供帳戶。 選取此參數時，您還必須選取**區域**。 應建立/更新堆疊集執行個體 AWS 的帳戶或組織單位 IDs 清單。 + **帳戶**： 您可以將帳戶做為常值清單或檔案路徑提供： + *文字*：以速記語法格式 輸入參數`account_ID,account_ID`，如下列範例所示。 ``` 111111222222,333333444444 ``` + *檔案路徑：*檔案的位置，其中包含應建立/更新堆疊集執行個體 AWS 的帳戶清單，格式為 `InputArtifactName::AccountsFileName`。如果您使用檔案路徑來指定**帳戶**或 **OrganizationalUnitIds**，檔案格式必須是 JSON，如下列範例所示。 ``` SourceArtifact::accounts.txt ``` 下列範例顯示 的檔案內容`accounts.txt`。 ``` [ "111111222222" ] ``` 下列範例顯示列出多個帳戶`accounts.txt`時 的檔案內容： ``` [ "111111222222","333333444444" ] ``` + **OrganizationalUnitIds**： **注意** 此參數是 SERVICE\$1MANAGED 許可模型的選用參數，不會用於 SELF\$1MANAGED 許可模型。如果您選擇 **OrganizationsAutoDeployment**，請勿使用此項目。 更新相關聯堆疊執行個體 AWS 的組織單位。 您可以提供組織單位 IDs 做為常值清單或檔案路徑： + *文字*：輸入以逗號分隔的字串陣列，如下列範例所示。 ``` ou-examplerootid111-exampleouid111,ou-examplerootid222-exampleouid222 ``` + *檔案路徑：*檔案的位置，其中包含要在其中建立或更新堆疊集執行個體的 OrganizationalUnitIds清單。如果您使用檔案路徑來指定**帳戶**或 **OrganizationalUnitIds**，檔案格式必須是 JSON，如下列範例所示。 輸入檔案的路徑，格式為 `InputArtifactName::OrganizationalUnitIdsFileName`。 ``` SourceArtifact::OU-IDs.txt ``` 下列範例顯示 的檔案內容`OU-IDs.txt`： ``` [ "ou-examplerootid111-exampleouid111","ou-examplerootid222-exampleouid222" ] ``` ****區域**** 必要：否 選取此參數時，您還必須選取 **DeploymentTargets**。 建立或更新堆疊集執行個體 AWS 的區域清單。區域會依輸入順序更新。 輸入格式為 的有效 AWS 區域清單`Region1,Region2`，如下列範例所示。 ``` us-west-2,us-east-1 ``` ****FailureTolerancePercentage**** 必要：否 在 CloudFormation 停止該區域中的操作之前，此堆疊操作可能失敗的每個區域的帳戶百分比。如果在區域中停止操作， CloudFormation 不會在後續區域中嘗試操作。根據指定的百分比計算帳戶數量時， 會*向下* CloudFormation 四捨五入到下一個整數。 ****MaxConcurrentPercentage**** 必要：否 執行此操作時，一次可用的帳戶百分比上限。根據指定的百分比計算帳戶數量時， 會*向下* CloudFormation 四捨五入到下一個整數。如果四捨五入會導致零， 會改為將數字 CloudFormation 設定為 1。雖然您使用此設定來指定*最大值*，但對於大型部署，由於服務限流，同時執行的帳戶實際數量可能會較低。 **RegionConcurrencyType** 必要：否 您可以設定區域並行部署參數，指定堆疊集是否應依序或平行部署到 AWS 區域 。指定區域並行在多個 之間 AWS 區域 平行部署堆疊時，這可能會導致更快的整體部署時間。 + *平行*：只要區域的部署失敗不超過指定的容錯能力，就會同時執行堆疊集部署。 + *循序*：只要區域的部署失敗不超過指定的容錯能力，就會一次執行一個堆疊集部署。順序部署是預設選項。 **ConcurrencyMode** 必要：否 並行模式可讓您選擇並行層級在堆疊集操作期間的行為，無論是嚴格或軟容錯能力。**嚴格容錯能力**會降低部署速度，由於每次故障會使並行值減少，因此堆疊集操作會發生故障。**軟性容錯能力**會優先考慮部署速度，同時仍利用 CloudFormation 安全功能。 + `STRICT_FAILURE_TOLERANCE`：此選項會動態降低並行層級，以確保失敗的帳戶數目永遠不會超過特定的容錯能力。這是預設行為。 + `SOFT_FAILURE_TOLERANCE`：此選項會將容錯能力與實際並行分離。這可讓堆疊集操作在設定的並行層級執行，無論失敗次數為何。 **CallAs** 必要：否 此參數是`SERVICE_MANAGED`許可模型的選用參數，不會用於`SELF_MANAGED`許可模型。 指定您是擔任組織的管理帳戶，還是成員帳戶中的委派管理員。 如果此參數設定為 `DELEGATED_ADMIN`，請確定管道 IAM 角色具有 `organizations:ListDelegatedAdministrators` 許可。否則，在執行 時發生類似下列的錯誤時，動作將會失敗：`Account used is not a delegated administrator`。 + `SELF`：堆疊集部署將在登入管理帳戶時使用服務受管許可。 + `DELEGATED_ADMIN`：堆疊集部署將在登入委派管理員帳戶時使用服務受管許可。 ### Input artifacts (輸入成品) 您必須在`CloudFormationStackSet`動作中包含至少一個包含堆疊集範本的輸入成品。您可以為部署目標、帳戶和參數的清單包含更多輸入成品。 + **成品數量：** `1 to 3` + **描述：**您可以包含要提供的成品： + 堆疊範本檔案。(請參閱 `TemplatePath` 參數。) + 參數檔案。(請參閱 `Parameters` 參數。) + 帳戶檔案。(請參閱 `DeploymentTargets` 參數。) ### 輸出成品 + **成品數量：** `0` + **描述：**輸出成品不適用於此動作類型。 ### 輸出變數 如果您設定此動作，它會產生變數，可供管道中下游動作的動作組態參考。您可以設定動作的命名空間，讓這些變數可供下游動作的組態使用。 + **StackSetId**：堆疊集的 ID。 + **OperationId**：堆疊集操作的 ID。 如需詳細資訊，請參閱[變數參考](reference-variables.md)。 ### **CloudFormationStackSet** 動作組態範例 下列範例顯示 **CloudFormationStackSet** 動作的動作組態。 #### 自我管理許可模型的範例 下列範例顯示 **CloudFormationStackSet** 動作，其中輸入的部署目標為 AWS 帳戶 ID。 ------ #### [ YAML ] ``` Name: CreateStackSet ActionTypeId: Category: Deploy Owner: AWS Provider: CloudFormationStackSet Version: '1' RunOrder: 1 Configuration: DeploymentTargets: '111111222222' FailureTolerancePercentage: '20' MaxConcurrentPercentage: '25' PermissionModel: SELF_MANAGED Regions: us-east-1 StackSetName: my-stackset TemplatePath: 'SourceArtifact::template.json' OutputArtifacts: [] InputArtifacts: - Name: SourceArtifact Region: us-west-2 Namespace: DeployVariables ``` ------ #### [ JSON ] ``` { "Name": "CreateStackSet", "ActionTypeId": { "Category": "Deploy", "Owner": "AWS", "Provider": "CloudFormationStackSet", "Version": "1" }, "RunOrder": 1, "Configuration": { "DeploymentTargets": "111111222222", "FailureTolerancePercentage": "20", "MaxConcurrentPercentage": "25", "PermissionModel": "SELF_MANAGED", "Regions": "us-east-1", "StackSetName": "my-stackset", "TemplatePath": "SourceArtifact::template.json" }, "OutputArtifacts": [], "InputArtifacts": [ { "Name": "SourceArtifact" } ], "Region": "us-west-2", "Namespace": "DeployVariables" } ``` ------ #### 服務受管許可模型的範例 下列範例顯示服務受管許可模型的 **CloudFormationStackSet** 動作，其中自動部署至 AWS Organizations 的選項已啟用堆疊保留。 ------ #### [ YAML ] ``` Name: Deploy ActionTypeId: Category: Deploy Owner: AWS Provider: CloudFormationStackSet Version: '1' RunOrder: 1 Configuration: Capabilities: 'CAPABILITY_IAM,CAPABILITY_NAMED_IAM' OrganizationsAutoDeployment: EnabledWithStackRetention PermissionModel: SERVICE_MANAGED StackSetName: stacks-orgs TemplatePath: 'SourceArtifact::template.json' OutputArtifacts: [] InputArtifacts: - Name: SourceArtifact Region: eu-central-1 Namespace: DeployVariables ``` ------ #### [ JSON ] ``` { "Name": "Deploy", "ActionTypeId": { "Category": "Deploy", "Owner": "AWS", "Provider": "CloudFormationStackSet", "Version": "1" }, "RunOrder": 1, "Configuration": { "Capabilities": "CAPABILITY_IAM,CAPABILITY_NAMED_IAM", "OrganizationsAutoDeployment": "EnabledWithStackRetention", "PermissionModel": "SERVICE_MANAGED", "StackSetName": "stacks-orgs", "TemplatePath": "SourceArtifact::template.json" }, "OutputArtifacts": [], "InputArtifacts": [ { "Name": "SourceArtifact" } ], "Region": "eu-central-1", "Namespace": "DeployVariables" } ``` ------ ## CloudFormationStackInstances 動作 此動作會建立新的執行個體，並將堆疊集部署至指定的執行個體。「堆疊執行個體」是針對區域內某個目標帳戶中的堆疊所做的參考。堆疊執行個體可以在沒有堆疊的情況下存在；例如，如果堆疊建立不成功，堆疊執行個體會顯示堆疊建立失敗的原因。堆疊執行個體僅與一個堆疊集相關聯。 在初始建立堆疊集之後，您可以使用 新增堆疊執行個體`CloudFormationStackInstances`。在建立或更新堆疊集執行個體操作期間，可以在堆疊執行個體層級覆寫範本參數值。 每個堆疊集都有一個範本和一組範本參數。當您更新範本或範本參數時，您可以更新整個集的參數。然後，所有執行個體狀態都會設為 ，`OUTDATED`直到變更部署到該執行個體為止。 若要覆寫特定執行個體上的參數值，例如，如果範本包含 的參數`stage`，其值為 `prod`，您可以覆寫該參數的值為 `beta`或 `gamma`。 **Topics** + [動作類型](#action-reference-StackInstances-type) + [組態參數](#action-reference-StackInstances-config) + [Input artifacts (輸入成品)](#action-reference-StackInstances-input) + [輸出成品](#action-reference-StackInstances-output) + [輸出變數](#action-reference-StackInstances-variables) + [動作組態範例](#action-reference-StackInstances-example) ### 動作類型 + 類別：`Deploy` + 擁有者：`AWS` + 提供者：`CloudFormationStackInstances` + 版本：`1` ### 組態參數 **StackSetName** 必要：是 要與堆疊集相關聯的名稱。此名稱在建立該名稱的區域中必須是唯一的。 名稱只能包含英數字元和連字號字元。它必須以字母字元開頭，且不超過 128 個字元。 ****DeploymentTargets**** 必要：否 對於 SERVICE\$1MANAGED 許可模型，您可以為部署目標提供組織根 ID 或組織單位 IDs。對於 SELF\$1MANAGED 許可模型，您只能提供帳戶。 選取此參數時，您還必須選取**區域**。 應建立/更新堆疊集執行個體 AWS 的帳戶或組織單位 IDs 清單。 + **帳戶**： 您可以將帳戶做為常值清單或檔案路徑提供： + *文字*：以速記語法格式 輸入參數`account_ID,account_ID`，如下列範例所示。 ``` 111111222222,333333444444 ``` + *檔案路徑：*檔案的位置，其中包含應建立/更新堆疊集執行個體 AWS 的帳戶清單，格式為 `InputArtifactName::AccountsFileName`。如果您使用檔案路徑來指定**帳戶**或 **OrganizationalUnitIds**，檔案格式必須是 JSON，如下列範例所示。 ``` SourceArtifact::accounts.txt ``` 下列範例顯示 的檔案內容`accounts.txt`： ``` [ "111111222222" ] ``` 下列範例顯示列出多個帳戶`accounts.txt`時 的檔案內容： ``` [ "111111222222","333333444444" ] ``` + **OrganizationalUnitIds**： **注意** 此參數是 SERVICE\$1MANAGED 許可模型的選用參數，不會用於 SELF\$1MANAGED 許可模型。如果您選擇 **OrganizationsAutoDeployment**，請勿使用此項目。 更新相關聯堆疊執行個體 AWS 的組織單位。 您可以提供組織單位 IDs 做為常值清單或檔案路徑。 + *文字*：輸入以逗號分隔的字串陣列，如下列範例所示。 ``` ou-examplerootid111-exampleouid111,ou-examplerootid222-exampleouid222 ``` + *檔案路徑：*檔案的位置，其中包含要在其中建立或更新堆疊集執行個體的 OrganizationalUnitIds清單。如果您使用檔案路徑來指定**帳戶**或 **OrganizationalUnitIds**，檔案格式必須是 JSON，如下列範例所示。 輸入檔案的路徑，格式為 `InputArtifactName::OrganizationalUnitIdsFileName`。 ``` SourceArtifact::OU-IDs.txt ``` 下列範例顯示 的檔案內容`OU-IDs.txt`： ``` [ "ou-examplerootid111-exampleouid111","ou-examplerootid222-exampleouid222" ] ``` ****區域**** 必要：是 選取此參數時，您還必須選取 **DeploymentTargets**。 建立或更新堆疊集執行個體 AWS 的區域清單。區域會依輸入順序更新。 輸入有效 AWS 區域的清單，格式為：`Region1,Region2`，如下列範例所示。 ``` us-west-2,us-east-1 ``` **ParameterOverrides** 必要：否 您要在所選堆疊執行個體中覆寫的堆疊集參數清單。覆寫的參數值會套用至指定帳戶和區域中的所有堆疊執行個體。 您可以提供參數做為常值清單或檔案路徑： + 您可以輸入下列速記語法格式的參數：`ParameterKey=string,ParameterValue=string,UsePreviousValue=boolean,ResolvedValue=string ParameterKey=string,ParameterValue=string,UsePreviousValue=boolean,ResolvedValue=string`。如需這些資料類型的詳細資訊，請參閱 [範本參數資料類型](#action-reference-StackSets-datatypes)。 下列範例顯示名為 `BucketName`的參數，其值為 `amzn-s3-demo-source-bucket`。 ``` ParameterKey=BucketName,ParameterValue=amzn-s3-demo-source-bucket ``` 下列範例顯示具有多個參數的項目。 ``` ParameterKey=BucketName,ParameterValue=amzn-s3-demo-source-bucket ParameterKey=Asset1,ParameterValue=true ParameterKey=Asset2,ParameterValue=true ``` + 您可以輸入檔案的位置，其中包含以 格式輸入的範本參數覆寫清單`InputArtifactName::ParameterOverridessFileName`，如下列範例所示。 ``` SourceArtifact::parameter-overrides.txt ``` 下列範例顯示 的檔案內容`parameter-overrides.txt`。 ``` [ { "ParameterKey": "KeyName", "ParameterValue": "true" }, { "ParameterKey": "KeyName", "ParameterValue": "true" } ] ``` ****FailureTolerancePercentage**** 必要：否 在 CloudFormation 停止該區域中的操作之前，此堆疊操作可能失敗的每個區域的帳戶百分比。如果在區域中停止操作， CloudFormation 不會在後續區域中嘗試操作。根據指定的百分比計算帳戶數量時， 會*向下* CloudFormation 四捨五入到下一個整數。 ****MaxConcurrentPercentage**** 必要：否 一次執行此操作的帳戶百分比上限。根據指定的百分比計算帳戶數量時， 會*向下* CloudFormation 四捨五入到下一個整數。如果四捨五入會導致零， 會改為將數字 CloudFormation 設定為 1。雖然您指定*上限*，但對於大型部署，由於服務限流，同時處理的實際帳戶數量可能會較低。 **RegionConcurrencyType** 必要：否 您可以設定區域並行部署參數，指定堆疊集是否應依序或平行部署到 AWS 區域 。指定區域並行在多個 之間 AWS 區域 平行部署堆疊時，這可能會導致更快的整體部署時間。 + *平行*：只要區域的部署失敗不超過指定的容錯能力，就會同時執行堆疊集部署。 + *循序*：只要區域的部署失敗不超過指定的容錯能力，就會一次執行一個堆疊集部署。順序部署是預設選項。 **ConcurrencyMode** 必要：否 並行模式可讓您選擇並行層級在堆疊集操作期間的行為，無論是嚴格或軟容錯能力。**嚴格容錯能力**會降低部署速度，由於每次故障會使並行值減少，因此堆疊集操作會發生故障。**軟性容錯能力**會優先考慮部署速度，同時仍利用 CloudFormation 安全功能。 + `STRICT_FAILURE_TOLERANCE`：此選項會動態降低並行層級，以確保失敗的帳戶數目永遠不會超過特定的容錯能力。這是預設行為。 + `SOFT_FAILURE_TOLERANCE`：此選項會將容錯能力與實際並行分離。這可讓堆疊集操作在設定的並行層級執行，無論失敗次數為何。 **CallAs** 必要：否 此參數是`SERVICE_MANAGED`許可模型的選用參數，不會用於`SELF_MANAGED`許可模型。 指定您是擔任組織的管理帳戶，還是成員帳戶中的委派管理員。 如果此參數設定為 `DELEGATED_ADMIN`，請確定管道 IAM 角色具有 `organizations:ListDelegatedAdministrators` 許可。否則，在執行 時發生類似下列的錯誤時，動作將會失敗：`Account used is not a delegated administrator`。 + `SELF`：堆疊集部署將在登入管理帳戶時使用服務受管許可。 + `DELEGATED_ADMIN`：堆疊集部署將在登入委派管理員帳戶時使用服務受管許可。 ### Input artifacts (輸入成品) `CloudFormationStackInstances` 可以包含列出部署目標和參數的成品。 + **成品數量：** `0 to 2` + **描述：**作為輸入，堆疊集動作可選擇性地接受用於這些目的的成品： + 提供要使用的參數檔案。(請參閱 `ParameterOverrides` 參數。) + 提供要使用的目標帳戶檔案。(請參閱 `DeploymentTargets` 參數。) ### 輸出成品 + **成品數量：** `0` + **描述：**輸出成品不適用於此動作類型。 ### 輸出變數 設定時，此動作會產生變數，供管道中的下游動作的動作組態所參考。您可以設定動作的命名空間，讓這些變數可供下游動作的組態使用。 + **StackSetId**：堆疊集的 ID。 + **OperationId**：堆疊集操作的 ID。 如需詳細資訊，請參閱[變數參考](reference-variables.md)。 ### 動作組態範例 下列範例顯示 **CloudFormationStackInstances** 動作的動作組態。 #### 自我管理許可模型的範例 下列範例顯示 **CloudFormationStackInstances** 動作，其中輸入的部署目標為 AWS 帳戶 ID `111111222222`。 ------ #### [ YAML ] ``` Name: my-instances ActionTypeId: Category: Deploy Owner: AWS Provider: CloudFormationStackInstances Version: '1' RunOrder: 2 Configuration: DeploymentTargets: '111111222222' Regions: 'us-east-1,us-east-2,us-west-1,us-west-2' StackSetName: my-stackset OutputArtifacts: [] InputArtifacts: - Name: SourceArtifact Region: us-west-2 ``` ------ #### [ JSON ] ``` { "Name": "my-instances", "ActionTypeId": { "Category": "Deploy", "Owner": "AWS", "Provider": "CloudFormationStackInstances", "Version": "1" }, "RunOrder": 2, "Configuration": { "DeploymentTargets": "111111222222", "Regions": "us-east-1,us-east-2,us-west-1,us-west-2", "StackSetName": "my-stackset" }, "OutputArtifacts": [], "InputArtifacts": [ { "Name": "SourceArtifact" } ], "Region": "us-west-2" } ``` ------ #### 服務受管許可模型的範例 下列範例顯示服務受管許可模型的 **CloudFormationStackInstances** 動作，其中部署目標為 AWS Organizations 組織單位 ID `ou-1111-1example`。 ------ #### [ YAML ] ``` Name: Instances ActionTypeId: Category: Deploy Owner: AWS Provider: CloudFormationStackInstances Version: '1' RunOrder: 2 Configuration: DeploymentTargets: ou-1111-1example Regions: us-east-1 StackSetName: my-stackset OutputArtifacts: [] InputArtifacts: - Name: SourceArtifact Region: eu-central-1 ``` ------ #### [ JSON ] ``` { "Name": "Instances", "ActionTypeId": { "Category": "Deploy", "Owner": "AWS", "Provider": "CloudFormationStackInstances", "Version": "1" }, "RunOrder": 2, "Configuration": { "DeploymentTargets": "ou-1111-1example", "Regions": "us-east-1", "StackSetName": "my-stackset" }, "OutputArtifacts": [], "InputArtifacts": [ { "Name": "SourceArtifact" } ], "Region": "eu-central-1" } ``` ------ ## 服務角色許可：`CloudFormationStackSet`動作 For CloudFormation StackSets 動作需要下列最低許可。 針對 `CloudFormationStackSet`動作，請將下列項目新增至您的政策陳述式： ``` { "Effect": "Allow", "Action": [ "cloudformation:CreateStackSet", "cloudformation:UpdateStackSet", "cloudformation:CreateStackInstances", "cloudformation:DescribeStackSetOperation", "cloudformation:DescribeStackSet", "cloudformation:ListStackInstances" ], "Resource": "resource_ARN" }, ``` ## 服務角色許可：`CloudFormationStackInstances`動作 針對 `CloudFormationStackInstances`動作，請將下列項目新增至您的政策陳述式： ``` { "Effect": "Allow", "Action": [ "cloudformation:CreateStackInstances", "cloudformation:DescribeStackSetOperation" ], "Resource": "resource_ARN" }, ``` ## 堆疊集操作的許可模型 由於 CloudFormation StackSets 跨多個帳戶執行操作，您必須先在這些帳戶中定義必要的許可，才能建立堆疊集。您可以透過自我管理的許可或服務管理的許可來定義許可。 使用自我管理許可，您可以在您定義堆疊集的帳戶中建立 StackSets 所需的兩個 IAM 角色 - 管理員角色，例如 AWSCloudFormationStackSetAdministrationRole，以及您在部署堆疊集執行個體的每個帳戶中建立執行角色，例如 AWSCloudFormationStackSetExecutionRole。使用此許可模型，StackSets 可以部署到使用者具有建立 IAM 角色許可的任何 AWS 帳戶。如需詳細資訊，請參閱*AWS CloudFormation 《 使用者指南*》中的[授予自我管理許可](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-prereqs-self-managed.html)。 **注意** 由於 CloudFormation StackSets 跨多個帳戶執行操作，您必須先在這些帳戶中定義必要的許可，才能建立堆疊集。 透過服務受管許可，您可以將堆疊執行個體部署至 AWS Organizations 管理的帳戶。使用此許可模型，您不需要建立必要的 IAM 角色，因為 StackSets 會代表您建立 IAM 角色。使用此模型，您也可以啟用未來新增至組織的帳戶的自動部署。請參閱*AWS CloudFormation 《 使用者指南*》中的[使用 AWS Organizations 啟用受信任存取](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-orgs-enable-trusted-access.html)。 ## 範本參數資料類型 堆疊集操作中使用的範本參數包括下列資料類型。如需詳細資訊，請參閱 [DescribeStackSet](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_Parameter.html)。 ParameterKey + 描述：與 參數相關聯的金鑰。如果您未指定特定參數的索引鍵和值， AWS CloudFormation 會使用範本中指定的預設值。 + 範例： ``` "ParameterKey=BucketName,ParameterValue=amzn-s3-demo-source-bucket" ``` ParameterValue + 描述：與 參數相關聯的輸入值。 + 範例： ``` "ParameterKey=BucketName,ParameterValue=amzn-s3-demo-source-bucket" ``` UsePreviousValue + 在堆疊更新期間，使用堆疊用於指定參數金鑰的現有參數值。如果您指定 `true`，請勿指定參數值。 + 範例： ``` "ParameterKey=Asset1,UsePreviousValue=true" ``` 每個堆疊集都有一個範本和一組範本參數。當您更新範本或範本參數時，您可以更新整個集的參數。然後，所有執行個體狀態都會設為 OUTDATED，直到變更部署到該執行個體為止。 若要覆寫特定執行個體上的參數值，例如，如果範本包含 的參數`stage`，其值為 `prod`，您可以覆寫該參數的值為 `beta`或 `gamma`。 ## 另請參閱 以下相關資源可協助您使用此動作。 + [參數類型](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html#parameters-section-structure-properties-type) – *AWS CloudFormation 使用者指南*中的此參考章節提供 CloudFormation 範本參數的更多說明和範例。 + 最佳實務 – 如需部署堆疊集最佳實務的詳細資訊，請參閱*AWS CloudFormation 《 使用者指南*[https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-bestpractices.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-bestpractices.html)》中的 。 + [AWS CloudFormation API 參考](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/) – 您可以在 *AWS CloudFormation API 參考*中參考下列 CloudFormation 動作，以取得堆疊集操作中使用的參數詳細資訊： + [CreateStackSet](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStackSet.html) 動作會建立堆疊集。 + [UpdateStackSet](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_UpdateStackSet.html) 動作會更新指定帳戶和區域中的堆疊集和相關聯的堆疊執行個體。即使更新堆疊集所建立的堆疊集操作失敗 （完全或部分、低於或高於指定的容錯能力），堆疊集也會隨著這些變更而更新。後續對指定堆疊集的 CreateStackInstances 呼叫會使用更新的堆疊集。 + [CreateStackInstances](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStackInstances.html) 動作會在自我管理許可模型上的所有指定帳戶內，或在服務受管許可模型上的所有指定部署目標內，建立所有指定區域的堆疊執行個體。您可以覆寫此動作所建立執行個體的參數。如果執行個體已存在，CreateStackInstances 會使用相同的輸入參數呼叫 UpdateStackInstances。當您使用此動作建立執行個體時，不會變更其他堆疊執行個體的狀態。 + [UpdateStackInstances](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_UpdateStackInstances.html) 動作會在自我管理許可模型的所有指定帳戶內，或在服務管理許可模型的所有指定部署目標內，針對所有指定的區域設定堆疊執行個體，讓堆疊執行個體保持最新狀態。您可以覆寫此動作更新之執行個體的參數。當您使用此動作更新執行個體子集時，不會變更其他堆疊執行個體的狀態。 + [DescribeStackSetOperation](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_DescribeStackSetOperation.html) 動作會傳回指定堆疊集操作的描述。 + [DescribeStackSet](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_DescribeStackSet.html) 動作會傳回指定堆疊集的描述。