AWS CloudFormation StackSets 部署動作參考 - AWS CodePipeline
AWS CloudFormation StackSets 動作如何運作 如何在管道中建構 StackSets動作CloudFormationStackSet 動作該 CloudFormationStackInstances動作堆疊集作業的權限模型模板參數數據類型另請參閱

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

AWS CloudFormation StackSets 部署動作參考

CodePipeline 提供了作為 CI/CD 過程的一部分執行 AWS CloudFormation StackSets 操作的能力。您可以使用堆疊集，透過使用單一 AWS CloudFormation 範本在跨 AWS 區域的 AWS 帳戶中建立堆疊。每個堆棧中包含的所有資源均由堆棧集的 AWS CloudFormation 模板定義。建立堆疊集時，您可以指定要使用的範本，以及範本需要的任何參數和功能。

若要取得有關概念的更多資訊 AWS CloudFormation StackSets，請參閱《AWS CloudFormation 使用指南》中的StackSets 概念。

您可以 AWS CloudFormation StackSets 透過兩種不同的動作類型一起使用來整合管道：

  • 此CloudFormationStackSet動作會從儲存在管線來源位置的範本建立或更新堆疊集或堆疊執行個體。每次建立或更新堆疊集時，都會對指定的執行個體啟動這些變更的部署。在主控台中，您可以在建立或編輯管道時選擇「CloudFormation 堆疊集合」動作提供者。

  • 此CloudFormationStackInstances動作會將動作的變更部署到指定的執CloudFormationStackSet行個體、建立新的堆疊執行個體，以及定義指定執行個體的參數覆寫。在主控台中，您可以在編輯現有管道時選擇「CloudFormation 堆疊執行個體」動作提供者。

您可以使用這些動作來部署到目標 AWS 帳戶或目標組 Organ AWS izations 單位IDs。

注意

若要部署到目標組 Organ AWS izations 帳戶或組織單位，IDs並使用服務管理的權限模型，您必須啟用 AWS CloudFormation StackSets 和組 Organ AWS izations 之間的信任存取。如需詳細資訊，請參閱使用 AWS CloudFormation Stackset 啟用受信任存取。

AWS 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動作來建立管道。執行您的管道。

  2. 當您的管道第一次執行時，CloudFormationStackSet動作會建立您的堆疊集和至少一個初始執行個體。驗證堆疊集的建立，並檢閱初始執行個體的部署。例如，對於帳戶 Account-A 的初始堆疊集建立，其中us-east-1是指定的區域，會使用堆疊集建立堆疊執行個體：

    堆棧實例 區域 Status
    StackInstance一号 us-east-1 CURRENT

  3. 編輯管道以新增CloudFormationStackInstances為第二個部署動作，以針對您指定的目標建立/更新堆疊執行個體。例如，針對指定和 Region 的帳戶建立堆疊執行Account-A個體us-east-2，eu-central-1則會建立剩餘的堆疊執行個體，並且初始執行個體會保持更新，如下所示：

    堆棧實例 區域 Status
    StackInstance一号 us-east-1 CURRENT
    StackInstanceID-2 us-east-2 CURRENT
    StackInstanceID-3 eu-central-1 CURRENT

  4. 視需要執行管道以更新堆疊集並更新或建立堆疊執行個體。

當您起始堆疊更新 (其中您已從動作組態中移除部署目標) 時，未指定用於更新的堆疊執行個體會從部署中移除，並移至某個OUTDATED狀態。例如，對於從動作配置中移除us-east-2區域的帳戶Account-A的堆疊執行個體更新，則會建立剩餘的堆疊執行個體，並將移除的執行個體設定OUTDATED為如下：

堆棧實例 區域 Status
StackInstance一号 us-east-1 CURRENT
StackInstanceID-2 us-east-2 OUTDATED
StackInstanceID-3 eu-central-1 CURRENT

如需有關部署堆疊集的最佳作法的詳細資訊，請參閱《AWS CloudFormation 使用者指南》 StackSets 中的最佳作法。

CloudFormationStackSet 動作

此動作會從儲存在管線來源位置的範本建立或更新堆疊集。

定義堆疊集之後，您可以在組態參數中指定的目標帳戶和區域中建立、更新或刪除堆疊。建立、更新和刪除堆疊時，您可以指定其他偏好設定，例如要執行作業的區域順序、堆疊作業停止的失敗容錯百分比，以及在堆疊上同時執行作業的帳戶數目。

堆疊集是區域性資源。如果您在一個 AWS 區域中建立堆疊組合，則無法從其他區域存取該堆疊集。

使用此動作做為堆疊集的更新動作時，如果沒有部署至少一個堆疊執行個體，則不允許對堆疊進行更新。

動作類型

  • 類別：Deploy

  • 擁有者：AWS

  • 提供者：CloudFormationStackSet

  • 版本：1

組態參數

StackSetName

必要：是

要與堆疊集相關聯的名稱。此名稱在建立該名稱的區域中必須是唯一的。

名稱只能包含英數字元和連字號字元。它必須以字母字元開頭，且不得超過 128 個字元。

描述

必要：否

堆疊集的描述。您可以使用它來描述堆棧集的目的或其他相關信息。

TemplatePath

必要：是

定義堆疊集中資源的範本位置。這必須指向具有 460,800 字節的最大大小的模板。

以格式輸入來源人工因素名稱和範本檔案的路徑"InputArtifactName::TemplateFileName"，如下列範例所示。

SourceArtifact::template.txt
參數

必要：否

部署期間更新之堆疊集的範本參數清單。

您可以將參數提供為常值清單或檔案路徑：

  • 您可以使用下列速記語法格式輸入參數：. ParameterKey=string,ParameterValue=string,UsePreviousValue=boolean,ResolvedValue=string ParameterKey=string,ParameterValue=string,UsePreviousValue=boolean,ResolvedValue=string 如需這些資料類型的詳細資訊，請參閱模板參數數據類型。

    下列範例顯示以值命名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資源，或者直接從包含宏的模板創建堆棧，則必須使用此屬性。若要讓 AWS CloudFormation 動作以這種方式成功運作，您必須使用下列其中一項功能：

  • CAPABILITY_IAM

  • CAPABILITY_NAMED_IAM

您可以使用逗號指定多個功能，而且權能之間不能使用空格。中的範例示例CloudFormationStackSet操作配置顯示具有多個權能的項目。

PermissionModel

必要：否

決定建立和管理IAM角色的方式。如果未指定欄位，則使用預設值。如需相關資訊，請參閱 堆疊集作業的權限模型。

有效的 值如下：

  • SELF_MANAGED(預設值)：您必須建立管理員和執行角色，才能部署到目標帳戶。

  • SERVICE_MANAGED： AWS CloudFormation StackSets 自動建立部署至由 Organ AWS izations 管理的帳戶所需的IAM角色。這需要一個帳戶是組織的成員。

注意

只有當堆疊集中沒有堆疊執行個體時，才能變更此參數。

AdministrationRoleArn
注意

由於跨多個帳戶 AWS CloudFormation StackSets 執行作業，因此您必須先在這些帳戶中定義必要的權限，才能建立堆疊集。

必要：否

注意

此參數對於 SELF _ MANAGED 權限模型是可選的，並且不用於 SERVICE _ MANAGED 權限模型。

管理員帳戶中IAM用來執行堆疊集作業ARN的角色。

名稱可以包含字母數字字元，以及下列任何字元：_+=、.@-，且不可包含空格。名稱不區分大小寫。此角色名稱的長度下限必須為 20 個字元，長度上限為 2048 個字元。角色名稱在帳戶中必須是唯一的。此處指定的角色名稱必須是現有的角色名稱。如果您未指定角色名稱，則會將其設定為 AWSCloudFormationStackSetAdministrationRole。如果您指定 ServiceManaged，則不能定義角色名稱。

ExecutionRoleName
注意

由於跨多個帳戶 AWS CloudFormation StackSets 執行作業，因此您必須先在這些帳戶中定義必要的權限，才能建立堆疊集。

必要：否

注意

此參數對於 SELF _ MANAGED 權限模型是可選的，並且不用於 SERVICE _ MANAGED 權限模型。

用於執行堆疊集作業之目標帳戶中IAM角色的名稱。名稱可以包含字母數字字元，以及下列任何字元：_+=、.@-，且不可包含空格。名稱不區分大小寫。此角色名稱的長度下限必須為 1 個字元，且長度上限為 64 個字元。角色名稱在帳戶中必須是唯一的。此處指定的角色名稱必須是現有的角色名稱。如果您使用自訂的執行角色，請勿指定此角色。如果您未指定角色名稱，則會將其設定為AWSCloudFormationStackSetExecutionRole。如果您將服務 _ 託管設置為真，則不能定義角色名稱。

OrganizationsAutoDeployment

必要：否

注意

此參數對於 SERVICE _ MANAGED 權限模型是可選的，並且不用於 SELF _ MANAGED 權限模型。

描述是否 AWS CloudFormation StackSets 自動部署至 AWS 新增至目標組織或組織單位 (OU) 的組織帳戶。如果OrganizationsAutoDeployment已指定，請勿指定DeploymentTargets和Regions。

注意

如果未提供任何輸入OrganizationsAutoDeployment，則預設值為Disabled。

有效的 值如下：

  • Enabled。 需要：否

    StackSets 自動將其他堆疊執行個體部署到 AWS 新增至指定區域中目標組織或組織單位 (OU) 的組織帳戶。如果帳戶從目標組織或 OU 中移 AWS CloudFormation StackSets 除，請從指定區域中的帳戶中刪除堆疊執行個體。

  • Disabled。 需要：否

    StackSets 不會自動將其他堆疊執行個體部署到 AWS 新增至指定區域中目標組織或組織單位 (OU) 的組織帳戶。

  • EnabledWithStackRetention。 需要：否

    從目標組織或 OU 移除帳號時，會保留堆疊資源。

DeploymentTargets

必要：否

注意

對於 SERVICE _ MANAGED 權限模型，您可以為部署目標提供組織根 ID 或組織單位IDs。對於 SELF _ MANAGED 權限模型，您只能提供帳戶。

注意

選取此參數時，您還必須選取「區域」(Region)。

應IDs在其中建立/更新堆疊集執行個體的 AWS 帳戶或組織單位清單。

  • 帳戶：

    您可以將帳戶提供為常值清單或檔案路徑：

    • 常值：以速記語法格式輸入參數account_ID,account_ID，如下列範例所示。

      111111222222,333333444444

    • 檔案路徑：包含應在其中建立/更新堆疊集實例的 AWS 帳戶清單的檔案位置，並以格式輸入。InputArtifactName::AccountsFileName如果您使用檔案路徑來指定帳戶或 OrganizationalUnitIds，檔案格式必須是JSON，如下列範例所示。

      SourceArtifact::accounts.txt

      下列範例顯示的檔案內容accounts.txt。

      [
    "111111222222"
]

      下列範例顯示列出多個帳號accounts.txt時的檔案內容：

      [
    "111111222222","333333444444"
]

  • OrganizationalUnitIds:

    注意

    此參數對於 SERVICE _ MANAGED 權限模型是可選的，並且不用於 SELF _ MANAGED 權限模型。如果您選取，請勿使用此選項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

必要：否

在 AWS CloudFormation 停止該區域的作業之前，此堆疊作業可能會失敗的每個區域的帳戶百分比。如果「區域」中的作業已停止，則 AWS CloudFormation 不會在後續「區域」中嘗試該作業。根據指定的百分比計算帳戶數時，會 AWS CloudFormation 捨入至下一個整數。

MaxConcurrentPercentage

必要：否

執行此操作時，一次可用的帳戶百分比上限。根據指定的百分比計算帳戶數時，會 AWS CloudFormation 捨入至下一個整數。如果向下舍入會導致零，則將數字 AWS CloudFormation 設置為一。雖然您使用此設定來指定最大值，但對於大型部署，由於服務節流，實際並行處理的帳戶數目可能會降低。

RegionConcurrencyType

必要：否

您可以設定 Region 並行部署參數，指定堆疊集應 AWS 區域 依序或 parallel 部署。如果指定區域 parallel 部署多 AWS 區域 個堆疊，可以加快整體部署時間。

  • 並行：只要區域的部署失敗不超過指定的故障容忍，就會同時執行堆疊集合部署。

  • 循序：只要區域的部署失敗不超過指定的故障容忍，就會一次執行一個堆疊集部署。順序部署是預設選項。

ConcurrencyMode

必要：否

並行模式可讓您選擇並行層級在堆疊集合作業期間的行為方式，無論是具有嚴格或軟式失敗容錯。嚴格容錯能力會降低部署速度，由於每次故障會使並行值減少，因此堆疊集操作會發生故障。軟故障容忍優先考慮部署速度，同時仍然利用 AWS 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：堆疊集合的識別碼。

  • OperationId：堆疊集合作業的識別碼。

如需詳細資訊，請參閱變數參考。

示例CloudFormationStackSet操作配置

下列範例顯示動作的動CloudFormationStackSet作組態。

自我管理權限模型的範例

下列範例顯示輸入的部署目標為 AWS 帳號 ID 的CloudFormationStackSet動作。

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動作，其中啟用堆疊保留功能的 auto 動部署至 Organ AWS izations 的選項。

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直到變更部署至該執行個體為止。

若要覆寫特定執行個體上的參數值，例如，如果範本包含的參數值為 stageprod，您可以將該參數的值覆寫為beta或gamma。

動作類型

  • 類別：Deploy

  • 擁有者：AWS

  • 提供者：CloudFormationStackInstances

  • 版本：1

組態參數

StackSetName

必要：是

要與堆疊集相關聯的名稱。此名稱在建立該名稱的區域中必須是唯一的。

名稱只能包含英數字元和連字號字元。它必須以字母字元開頭，且不得超過 128 個字元。

DeploymentTargets

必要：否

注意

對於 SERVICE _ MANAGED 權限模型，您可以為部署目標提供組織根 ID 或組織單位IDs。對於 SELF _ MANAGED 權限模型，您只能提供帳戶。

注意

選取此參數時，您還必須選取「區域」(Region)。

應IDs在其中建立/更新堆疊集執行個體的 AWS 帳戶或組織單位清單。

  • 帳戶：

    您可以將帳戶提供為常值清單或檔案路徑：

    • 常值：以速記語法格式輸入參數account_ID,account_ID，如下列範例所示。

      111111222222,333333444444

    • 檔案路徑：包含應在其中建立/更新堆疊集實例的 AWS 帳戶清單的檔案位置，並以格式輸入。InputArtifactName::AccountsFileName如果您使用檔案路徑來指定帳戶或 OrganizationalUnitIds，檔案格式必須是JSON，如下列範例所示。

      SourceArtifact::accounts.txt

      下列範例顯示的檔案內容accounts.txt：

      [
    "111111222222"
]

      下列範例顯示列出多個帳號accounts.txt時的檔案內容：

      [
    "111111222222","333333444444"
]

  • OrganizationalUnitIds:

    注意

    此參數對於 SERVICE _ MANAGED 權限模型是可選的，並且不用於 SELF _ MANAGED 權限模型。如果您選取，請勿使用此選項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 如需這些資料類型的詳細資訊，請參閱模板參數數據類型。

    下列範例顯示以值命名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

必要：否

在 AWS CloudFormation 停止該區域的作業之前，此堆疊作業可能會失敗的每個區域的帳戶百分比。如果「區域」中的作業已停止，則 AWS CloudFormation 不會在後續「區域」中嘗試該作業。根據指定的百分比計算帳戶數時，會 AWS CloudFormation 捨入至下一個整數。

MaxConcurrentPercentage

必要：否

一次執行此作業的帳戶百分比上限。根據指定的百分比計算帳戶數時，會 AWS CloudFormation 捨入至下一個整數。如果向下舍入會導致零，則將數字 AWS CloudFormation 設置為一。雖然您指定了最大值，但對於大型部署，由於服務節流，並行處理的實際帳戶數量可能會降低。

RegionConcurrencyType

必要：否

您可以設定區域並行部署參數，指定堆疊集應 AWS 區域 依序或 parallel 部署。如果指定區域 parallel 部署多 AWS 區域 個堆疊，可以加快整體部署時間。

  • 並行：只要區域的部署失敗不超過指定的故障容忍，就會同時執行堆疊集合部署。

  • 循序：只要區域的部署失敗不超過指定的故障容忍，就會一次執行一個堆疊集部署。順序部署是預設選項。

ConcurrencyMode

必要：否

並行模式可讓您選擇並行層級在堆疊集合作業期間的行為方式，無論是具有嚴格或軟式失敗容錯。嚴格容錯能力會降低部署速度，由於每次故障會使並行值減少，因此堆疊集操作會發生故障。軟故障容忍優先考慮部署速度，同時仍然利用 AWS 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：堆疊集合的識別碼。

  • OperationId：堆疊集合作業的識別碼。

如需詳細資訊，請參閱變數參考。

動作組態範例

下列範例顯示動作的動CloudFormationStackInstances作組態。

自我管理權限模型的範例

下列範例顯示輸入的部署目標為 AWS 帳戶 ID 的CloudFormationStackInstances動作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動作，其中部署目標是組 Organ AWS izations 組織單位 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"
}

堆疊集作業的權限模型

由於跨多個帳戶 AWS CloudFormation StackSets 執行作業，因此您必須先在這些帳戶中定義必要的權限，才能建立堆疊集。您可以透過自我管理的權限或服務管理的權限來定義權限。

使用自我管理的權限，您可以建立兩個所需的IAM角色 StackSets -管理員角色，例如 AWSCloudFormationStackSetAdministrationRole 在您定義堆疊集的帳戶中，以及執行角色 (例如， AWSCloudFormationStackSetExecutionRole 在您部署堆疊集執行個體的每個帳戶中)。使用此權限模型， StackSets 可以部署到使用者有權建立IAM角色的任何 AWS 帳戶。如需詳細資訊，請參閱AWS CloudFormation 使用指南中的授與自我管理權限。

注意

由於跨多個帳戶 AWS CloudFormation StackSets 執行作業，因此您必須先在這些帳戶中定義必要的權限，才能建立堆疊集。

透過服務管理的權限，您可以將堆疊執行個體部署到由 Organ AWS izations 管理的帳戶。使用此權限模型，您不必建立必要的IAM角色，因為 StackSets 會代表您建立IAM角色。使用此模型，您也可以對 future 新增至組織的帳戶啟用自動部署。請參閱《AWS CloudFormation 使用指南》中的「啟用 Organ AWS izations 信任的存取」。

模板參數數據類型

在堆棧集操作中使用的模板參數包括以下數據類型。如需詳細資訊，請參閱DescribeStackSet。

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直到變更部署至該執行個體為止。

若要覆寫特定執行個體上的參數值，例如，如果範本包含的參數值為 stageprod，您可以將該參數的值覆寫為beta或gamma。

以下相關資源可協助您使用此動作。

  • 參數類型 — AWS CloudFormation 使用者指南中的本參考章節提供範 CloudFormation 本參數的更多說明和範例。

  • 最佳做法 — 如需部署堆疊集的最佳作法的詳細資訊，請參閱《AWS CloudFormation 使用者指南》https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-bestpractices.html中的〈〉。

  • AWS CloudFormation API參照 — 您可以參考「參AWS CloudFormation API考 CloudFormation 」中的下列動作，以取得有關堆疊集合作業中使用之參數的詳細資訊：

    • 此動CreateStackSet作會建立堆疊集。

    • 此UpdateStackSet動作會更新指定帳戶和區域中的堆疊集和關聯的堆疊執行個體。即使透過更新堆疊集建立的堆疊集合作業失敗 (完全或部分、低於或高於指定的失敗容許)，堆疊集也會以這些變更進行更新。指定堆疊集的後續 CreateStackInstances 呼叫會使用更新的堆疊集。

    • 此CreateStackInstances動作會針對自我管理的權限模型上所有指定帳戶內的所有指定區域，或在服務管理權限模型上的所有指定部署目標內建立堆疊執行個體。您可以覆寫由此動作建立之執行個體的參數。如果實例已存在，則使用相同的輸入參數進行 CreateStackInstances 調 UpdateStackInstances 用。使用此動作建立執行個體時，不會變更其他堆疊執行個體的狀態。

    • 此UpdateStackInstances動作會使堆疊執行個體在自我管理的權限模型上，或是服務管理權限模型上所有指定帳戶內所有指定區域的堆疊設定為最新狀態。您可以覆寫由此動作更新之執行個體的參數。當您使用此動作更新執行個體的子集時，不會變更其他堆疊執行個體的狀態。

    • 該DescribeStackSetOperation動作返回指定堆棧集操作的描述。

    • 該DescribeStackSet操作返回指定堆棧集的描述。