本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# CloudFormation StackSets 部署操作参考
CodePipeline 提供了在 CI/CD 流程中执行 CloudFormation StackSets 操作的能力。您可以使用堆栈集通过单个 CloudFormation 模板在跨 AWS 区域的 AWS 账户中创建堆栈。每个堆栈中包含的所有资源均由堆栈集的 CloudFormation 模板定义。在创建堆栈集时，您可指定要使用的模板以及模板所需的任何参数和功能。
有关概念的更多信息 CloudFormation StackSets，请参阅《*AWS CloudFormation 用户指南*》中的[StackSets 概念](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-concepts.html)。
您可以 CloudFormation StackSets 通过两种不同的操作类型将您的管道与之集成，这两种操作类型可以一起使用：
+ `CloudFormationStackSet` 操作会通过存储在管道源位置的模板，创建或更新堆栈集或堆栈实例。每次创建或更新堆栈集时，它都会开始向指定的实例部署这些更改。在控制台中，您可以在创建或编辑管道时选择 **CloudFormation Stack Set** 操作提供者。
+ `CloudFormationStackInstances` 操作会将 `CloudFormationStackSet` 操作的更改部署到指定的实例，创建新的堆栈实例，并定义对指定实例的参数覆盖。在控制台中，编辑现有管道时，您可以选择**CloudFormation 堆栈实例**操作提供者。
您可以使用这些操作部署到目标 AWS 客户或目标 Organizati AWS ons 组织单位 IDs。
**注意**
要部署到目标 AWS Organizations 账户或组织单位 IDs 并使用服务管理权限模型，必须启用 AWS CloudFormation StackSets 和 AWS 组织之间的可信访问权限。有关更多信息，请参阅使用[AWS CloudFormation 堆栈集启用可信访问](https://docs.aws.amazon.com/organizations/latest/userguide/services-that-can-integrate-cloudformation.html#integrate-enable-ta-cloudformation)。
**Topics**
+ [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)
## CloudFormation StackSets 动作是如何运作的
`CloudFormationStackSet` 操作会根据操作是否是首次运行，创建或更新资源。
`CloudFormationStackSet` 操作会*创建* 或*更新* 堆栈集，并将这些更改部署到指定的实例。
**注意**
如果您使用此操作进行更新，包括添加堆栈实例，则会先部署新实例，最后完成更新。新实例会先收到旧版本，然后更新将应用于所有实例。
+ *创建*：如果未指定实例且堆栈集不存在，则该**CloudFormationStackSet**操作将创建堆栈集而不创建任何实例。
+ *更新*：对已创建的堆栈集运行**CloudFormationStackSet**操作时，该操作会更新堆栈集。如果不指定实例且堆栈集已存在，则会更新所有实例。如果使用此操作来更新特定实例，则所有剩余的实例都将变为已过时状态。
您可以使用该**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_cn/codepipeline/latest/userguide/action-reference-StackSets.html)
1. 编辑您的管道，将其`CloudFormationStackInstances`作为第二个部署操作添加到您指定目标的 create/update 堆栈实例中。例如，为账户 `Account-A` 创建堆栈实例，其中指定 `us-east-2` 和 `eu-central-1` 区域，将会创建剩余的堆栈实例，并且初始实例仍会进行更新，如下所示：
****
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/codepipeline/latest/userguide/action-reference-StackSets.html)
1. 根据需要运行管道以更新您的堆栈集，并更新或创建堆栈实例。
在已经从操作配置中移除部署目标的情况下，当您启动堆栈更新时，未指定进行更新的堆栈实例将从部署中移除，并且变为已过时状态。例如，为账户 `Account-A` 更新堆栈实例，其中 `us-east-2` 区域从操作配置中移除，则会创建剩余的堆栈实例，并将移除的实例设置为已过时，如下所示：
****
| 堆栈实例 | Region | Status |
| --- | --- | --- |
| StackInstanceID-1 | us-east-1 | CURRENT |
| StackInstanceID-2 | us-east-2 | OUTDATED |
| 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)
+ [输入构件](#action-reference-StackSet-input)
+ [输出构件](#action-reference-StackSet-output)
+ [输出变量](#action-reference-StackSet-variables)
+ [**CloudFormationStackSet**操作配置示例](#action-reference-StackSet-example)
### 操作类型
+ 类别：`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`。有关这些数据类型的更多信息，请参阅[模板参数数据类型](#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 自动创建部署到 Organizations 管理的账户所需的 AWS 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 自动将其他堆栈实例部署到指定区域的目标 AWS 组织或组织单位 (OU) 的 Organizations 账户。如果账户已从目标组织或 OU 中移除，则会从指定区域的账户中 CloudFormation StackSets 删除堆栈实例。
+ `Disabled`。必需：否。
StackSets 不会自动将其他堆栈实例部署到指定区域的目标 AWS 组织或组织单位 (OU) 的 Organizations 账户。
+ `EnabledWithStackRetention`。必需：否。
从目标组织或 OU 中移除账户时，会保留堆栈资源。
****DeploymentTargets****
必需：否
对于 SERVICE\$1MANAGED 权限模型，您可以 IDs 为部署目标提供组织根 ID 或组织单位。对于 SELF\$1MANAGED 权限模型，您只能提供账户。
选择此参数后，还必须选择**区域**。
应 IDs 在其中创建/更新堆栈集实例的 AWS 账户或组织单位列表。
+ **Accounts**：
您可以通过文本列表或文件路径的形式提供账户：
+ *文本*：使用简写语法格式 `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 区域列表。区域将按照输入顺序进行更新。
按照以下示例所示的格式`Region1,Region2`输入有效 AWS 区域列表。
```
us-west-2,us-east-1
```
****FailureTolerancePercentage****
必需：否
在该区域 CloudFormation 停止该堆栈操作之前，每个区域中该堆栈操作可能失败的账户百分比。如果操作在某个区域中停止，则 CloudFormation 不会在后续区域中尝试该操作。根据指定的百分比计算账户数量时，*向下 CloudFormation *舍入到下一个整数。
****MaxConcurrentPercentage****
必需：否
一次执行此操作的账户数的最大百分比。根据指定的百分比计算账户数量时，*向下 CloudFormation *舍入到下一个整数。如果向下舍入结果为零，则改为将数字 CloudFormation 设置为一。尽管您使用此设置来指定*最大值*，但对于大型部署，并行执行的实际账户的数量可能会因服务节流而减少。
**RegionConcurrencyType**
必需：否
您可以通过配置区域并发部署参数，指定堆栈集应该按照顺序方式还是并行方式跨 AWS 区域 进行部署。如果将区域并发性指定为 AWS 区域 并行部署多个堆栈，则可以缩短总体部署时间。
+ *并行*：只要区域的部署失败次数不超过指定的容错值，就会同时执行堆栈集部署。
+ *顺序*：只要区域的部署失败次数不超过指定的容错值，就会一次执行一个堆栈集部署。顺序部署是默认选项。
**ConcurrencyMode**
必需：否
并发模式允许您选择并发级别在堆栈集操作期间的行为方式，无论是严格容错还是软容错。**严格容错**会降低堆栈集操作失败时的部署速度，因为每次失败都会降低并发数。S@@ **oft Fail** ure Tolerance 优先考虑部署速度，同时仍能利用 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`：在登录到委派管理员账户时，堆栈集部署将使用服务托管式权限。
### 输入构件
您必须至少包括一个输入构件，其中包含 `CloudFormationStackSet` 操作中堆栈集的模板。对于部署目标、账户和参数列表，您可以包含更多输入构件。
+ **构件数：**`1 to 3`
+ **描述：**您可以包含构件以提供：
+ 堆栈模板文件。（请参阅 `TemplatePath` 参数。）
+ 参数文件。（请参阅 `Parameters` 参数。）
+ 账户文件。（请参阅 `DeploymentTargets` 参数。）
### 输出构件
+ **构件数：**`0`
+ **描述：**输出构件不适用于此操作类型。
### 输出变量
如果配置此操作，它会生成一些变量，可供管道中下游操作的操作配置引用。您可以使用命名空间配置操作，以使这些变量可用于下游操作的配置。
+ **StackSetId**: 堆栈集的 ID。
+ **OperationId**: 堆栈集操作的 ID。
有关更多信息，请参阅 [变量参考](reference-variables.md)。
### **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**操作，其中启用了自动部署到 Organizations AWS 的选项，同时保留堆栈。
------
#### [ 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`，直到将更改部署到该实例为止。
要覆盖特定实例上的参数值，例如，如果模板包含一个值为 `prod` 的 `stage` 参数，则可以将该参数的值覆盖为 `beta` 或 `gamma`。
**Topics**
+ [操作类型](#action-reference-StackInstances-type)
+ [配置参数](#action-reference-StackInstances-config)
+ [输入构件](#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 权限模型，您可以 IDs 为部署目标提供组织根 ID 或组织单位。对于 SELF\$1MANAGED 权限模型，您只能提供账户。
选择此参数后，还必须选择**区域**。
应 IDs 在其中创建/更新堆栈集实例的 AWS 账户或组织单位列表。
+ **Accounts**：
您可以通过文本列表或文件路径的形式提供账户：
+ *文本*：使用简写语法格式 `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 设置为一。尽管您指定*最大值*，但对于大型部署，并行执行的实际账户的数量可能会因服务节流而减少。
**RegionConcurrencyType**
必需：否
您可以通过配置区域并发部署参数，指定堆栈集应该按照顺序方式还是并行方式跨 AWS 区域 进行部署。如果将区域并发性指定为 AWS 区域 并行部署多个堆栈，则可以缩短总体部署时间。
+ *并行*：只要区域的部署失败次数不超过指定的容错值，就会同时执行堆栈集部署。
+ *顺序*：只要区域的部署失败次数不超过指定的容错值，就会一次执行一个堆栈集部署。顺序部署是默认选项。
**ConcurrencyMode**
必需：否
并发模式允许您选择并发级别在堆栈集操作期间的行为方式，无论是严格容错还是软容错。**严格容错**会降低堆栈集操作失败时的部署速度，因为每次失败都会降低并发数。S@@ **oft Fail** ure Tolerance 优先考虑部署速度，同时仍能利用 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`：在登录到委派管理员账户时，堆栈集部署将使用服务托管式权限。
### 输入构件
`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**操作，其中部署目标是 Organizations AWS 组织单位 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` 操作
对于 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 执行操作，因此必须先在这些账户中定义必要的权限，然后才能创建堆栈集。您可以通过自管理权限或服务管理权限来定义权限。
使用自我管理权限，您可以创建所需的两个 IAM 角色：一个是管理员角色，例如定义堆栈集的账户 AWSCloudFormationStackSetAdministrationRole 中的，另一个是执行角色，例如部署堆栈集实例的每个账户 AWSCloudFormationStackSetExecutionRole 中的。 StackSets 使用此权限模型， StackSets 可以部署到用户有权创建 IAM 角色的任何 AWS 账户。有关更多信息，请参阅 *AWS CloudFormation 用户指南* 中的[创建自管理权限](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/stacksets-prereqs-self-managed.html)。
**注意**
由于跨多个账户 CloudFormation StackSets 执行操作，因此必须先在这些账户中定义必要的权限，然后才能创建堆栈集。
借助服务管理权限，您可以将堆栈实例部署到由 Organizations 管理的账户 AWS 。使用此权限模型，您无需创建必要的 IAM 角色，因为您可以代表您 StackSets 创建 IAM 角色。使用此模型，您还可以启用向将来添加到组织的账户自动部署的功能。请参阅《*AWS CloudFormation 用户指南》*中的 “[通过 Org AWS anizations 启用可信访问](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，直到将更改部署到该实例为止。
要覆盖特定实例上的参数值，例如，如果模板包含一个值为 `prod` 的 `stage` 参数，则可以将该参数的值覆盖为 `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)操作在自行管理的权限模型上为所有指定账户中的所有指定区域创建堆栈实例，或者在服务管理的权限模型上为所有指定部署目标中的所有指定区域创建堆栈实例。您可以覆盖通过此操作创建的实例的参数。如果实例已经存在，则使用相同的输入参数 UpdateStackInstances 进行 CreateStackInstances 调用。当您使用此操作创建实例时，不会更改其他堆栈实例的状态。
+ 该[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)操作返回指定堆栈集的描述。