Amazon CloudFormation StackSets 部署操作参考 - Amazon CodePipeline
Amazon CloudFormation StackSets 操作是如何运作的 如何在管道中构造 StackSets操作CloudFormationStackSet 操作动 CloudFormationStackInstances作堆栈集操作的权限模型模板参数数据类型另请参阅
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

Amazon CloudFormation StackSets 部署操作参考

CodePipeline 提供了在 CI/CD 流程中执行 Amazon CloudFormation StackSets 操作的能力。您可以使用堆栈集通过单个 Amazon CloudFormation 模板在跨 Amazon 区域的 Amazon 账户中创建堆栈。每个堆栈中包含的所有资源均由堆栈集的 Amazon CloudFormation 模板定义。在创建堆栈集时，您可指定要使用的模板以及模板所需的任何参数和功能。

有关概念的更多信息 Amazon CloudFormation StackSets，请参阅《Amazon CloudFormation 用户指南》中的StackSets 概念。

您可以 Amazon CloudFormation StackSets 通过两种不同的操作类型将您的管道与之集成，这两种操作类型可以一起使用：

  • CloudFormationStackSet 操作会通过存储在管道源位置的模板，创建或更新堆栈集或堆栈实例。每次创建或更新堆栈集时，它都会开始向指定的实例部署这些更改。在控制台中，您可以在创建或编辑管道时选择 CloudFormation Stack Set 操作提供者。

  • CloudFormationStackInstances 操作会将 CloudFormationStackSet 操作的更改部署到指定的实例，创建新的堆栈实例，并定义对指定实例的参数覆盖。在控制台中，编辑现有管道时，您可以选择CloudFormation 堆栈实例操作提供者。

这些操作不适用于中国（北京）和中国（宁夏）区域。要参考其他可用操作，请参阅 产品和服务与 CodePipeline。

您可以使用这些操作部署到目标 Amazon 客户或目标 Organizati Amazon ons 组织单位IDs。

注意

要部署到目标 Amazon Organizations 账户或组织单位IDs并使用服务管理权限模型，必须启用 Amazon CloudFormation StackSets 和 Amazon 组织之间的可信访问权限。有关更多信息，请参阅使用Amazon CloudFormation 堆栈集启用可信访问。

Amazon 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
    StackInstanceID-1 us-east-1 CURRENT

  3. 编辑您的管道，将 CloudFormationStackInstances 添加为第二个部署操作，以便为您指定的目标创建/更新堆栈实例。例如，为账户 Account-A 创建堆栈实例，其中指定 us-east-2 和 eu-central-1 区域，将会创建剩余的堆栈实例，并且初始实例仍会进行更新，如下所示：

    堆栈实例 区域 Status
    StackInstanceID-1 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
StackInstanceID-1 us-east-1 CURRENT
StackInstanceID-2 us-east-2 OUTDATED
StackInstanceID-3 eu-central-1 CURRENT

有关部署堆栈集的最佳实践的更多信息，请参阅《Amazon CloudFormation 用户指南》 StackSets 中的最佳实践。

CloudFormationStackSet 操作

此操作会通过存储在管道源位置的模板，创建或更新堆栈集。

在定义堆栈集后，您可以在配置参数中指定的目标账户和区域，创建、更新或删除堆栈。在创建、更新或删除堆栈时，您可以指定其他首选项，如执行操作的区域顺序、容错百分比（超过之后会导致堆栈操作停止），以及在其中对堆栈并行执行操作的账户的数量。

堆栈集是一种区域性资源。如果您在一个 Amazon 区域中创建堆栈集，则无法从其他区域访问该堆栈集。

当此操作用作对堆栈集的更新操作时，如果不部署到至少一个堆栈实例，则不允许对堆栈进行更新。

操作类型

  • 类别：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资源，或者直接从包含宏的模板创建堆栈，则必须使用此属性。要使 Amazon CloudFormation 操作以这种方式成功运行，必须使用以下功能之一：

  • CAPABILITY_IAM

  • CAPABILITY_NAMED_IAM

您可以使用逗号指定多项功能，各项功能之间不留空格。CloudFormationStackSet操作配置示例中的示例展示了一个具有多项功能的条目。

PermissionModel

必需：否

确定如何创建和管理IAM角色。如果未指定该字段，则使用默认值。有关信息，请参阅堆栈集操作的权限模型。

有效值为：

  • SELF_MANAGED（默认）：您必须创建管理员角色和执行角色才能向目标账户进行部署。

  • SERVICE_MANAGED： Amazon CloudFormation StackSets 自动创建部署到 Organizations 管理的账户所需的IAM Amazon 角色。这要求账户必须是组织的成员。

注意

只有当堆栈集中不存在任何堆栈实例时，才能更改此参数。

AdministrationRoleArn
注意

由于跨多个账户 Amazon CloudFormation StackSets 执行操作，因此必须先在这些账户中定义必要的权限，然后才能创建堆栈集。

必需：否

注意

此参数对于 SELF _ MANAGED 权限模型是可选的，不用于 SERVICE _ MANAGED 权限模型。

管理员帐户中用于执行堆栈集操作的IAM角色。ARN

名称中可以包含字母数字字符，以及以下任意字符：_+=,.@-，不能含有空格。名称不区分大小写。此角色名称的最小长度必须为 20 个字符，最大长度为 2048 个字符。角色名称在账户中必须是唯一的。此处指定的角色名称必须是现有的角色名称。如果未指定角色名称，则将其设置为 AWSCloudFormationStackSetAdministrationRole。如果指定 ServiceManaged，则不得定义角色名称。

ExecutionRoleName
注意

由于跨多个账户 Amazon CloudFormation StackSets 执行操作，因此必须先在这些账户中定义必要的权限，然后才能创建堆栈集。

必需：否

注意

此参数对于 SELF _ MANAGED 权限模型是可选的，不用于 SERVICE _ MANAGED 权限模型。

目标账户中用于执行堆栈集操作的IAM角色名称。名称中可以包含字母数字字符，以及以下任意字符：_+=,.@-，不能含有空格。名称不区分大小写。此角色名称的最小长度必须为 1 个字符，最大长度为 64 个字符。角色名称在账户中必须是唯一的。此处指定的角色名称必须是现有的角色名称。如果要使用自定义执行角色，请不要指定此角色。如果不指定角色名称，则它将被设置为 AWSCloudFormationStackSetExecutionRole。如果将 Service_Managed 设置为 true，则不得定义角色名称。

OrganizationsAutoDeployment

必需：否

注意

此参数对于 SERVICE _ MANAGED 权限模型是可选的，不用于 SELF _ MANAGED 权限模型。

描述是否 Amazon CloudFormation StackSets 自动部署到已添加到目标 Amazon 组织或组织单位 (OU) 的 Organizations 帐户。如果指定 OrganizationsAutoDeployment，则请勿指定 DeploymentTargets 和 Regions。

注意

如果不为 OrganizationsAutoDeployment 提供输入，则默认值为 Disabled。

有效值为：

  • Enabled。必需：否。

    StackSets 自动将其他堆栈实例部署到指定区域的目标 Amazon 组织或组织单位 (OU) 的 Organizations 账户。如果账户已从目标组织或 OU 中移除，则会从指定区域的账户中 Amazon CloudFormation StackSets 删除堆栈实例。

  • Disabled。必需：否。

    StackSets 不会自动将其他堆栈实例部署到指定区域的目标 Amazon 组织或组织单位 (OU) 的 Organizations 账户。

  • EnabledWithStackRetention。必需：否。

    从目标组织或 OU 中移除账户时，会保留堆栈资源。

DeploymentTargets

必需：否

注意

对于 SERVICE _ MANAGED 权限模型，您可以IDs为部署目标提供组织根 ID 或组织单位。对于 SELF _ MANAGED 权限模型，您只能提供账户。

注意

选择此参数后，还必须选择区域。

应IDs在其中创建/更新堆栈集实例的 Amazon 账户或组织单位列表。

  • Accounts：

    您可以通过文本列表或文件路径的形式提供账户：

    • 文本：使用简写语法格式 account_ID,account_ID 输入参数，如以下示例所示。

      111111222222,333333444444

    • 文件路径：文件的位置，其中包含应在其中创建/更新堆栈集实例的 Amazon 账户列表，格式为。InputArtifactName::AccountsFileName如果您使用文件路径来指定账户或 OrganizationalUnitIds，则文件格式必须为JSON，如以下示例所示。

      SourceArtifact::accounts.txt

      以下示例显示 accounts.txt 的文件内容。

      [
    "111111222222"
]

      以下示例显示了列出多个账户时 accounts.txt 的文件内容：

      [
    "111111222222","333333444444"
]

  • OrganizationalUnitIds:

    注意

    此参数对于 SERVICE _ MANAGED 权限模型是可选的，不用于 SELF _ MANAGED 权限模型。如果您选择，请不要使用此选项OrganizationsAutoDeployment。

    更新关联堆栈实例的 Amazon 组织单位。

    您可以以文字列表或文件路径的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。

创建或更新堆栈集实例的 Amazon 区域列表。区域将按照输入顺序进行更新。

按照以下示例所示的格式Region1,Region2输入有效 Amazon 区域列表。

us-west-2,us-east-1
FailureTolerancePercentage

必需：否

在该区域 Amazon CloudFormation 停止该堆栈操作之前，每个区域中该堆栈操作可能失败的账户百分比。如果操作在某个区域中停止，则 Amazon CloudFormation 不会在后续区域中尝试该操作。根据指定的百分比计算账户数量时，向下 Amazon CloudFormation 舍入到下一个整数。

MaxConcurrentPercentage

必需：否

一次执行此操作的账户数的最大百分比。根据指定的百分比计算账户数量时，向下 Amazon CloudFormation 舍入到下一个整数。如果向下舍入结果为零，则改为将数字 Amazon CloudFormation 设置为一。尽管您使用此设置来指定最大值，但对于大型部署，并行执行的实际账户的数量可能会因服务节流而减少。

RegionConcurrencyType

必需：否

您可以通过配置区域并发部署参数，指定堆栈集应该按照顺序方式还是并行方式跨 Amazon Web Services 区域 进行部署。如果将区域并发性指定为 Amazon Web Services 区域 并行部署多个堆栈，则可以缩短总体部署时间。

  • 并行：只要区域的部署失败次数不超过指定的容错值，就会同时执行堆栈集部署。

  • 顺序：只要区域的部署失败次数不超过指定的容错值，就会一次执行一个堆栈集部署。顺序部署是默认选项。

ConcurrencyMode

必需：否

并发模式允许您选择并发级别在堆栈集操作期间的行为方式，无论是严格容错还是软容错。严格容错会降低堆栈集操作失败时的部署速度，因为每次失败都会降低并发数。S@@ oft Fail ure Tolerance 优先考虑部署速度，同时仍能利用 Amazon 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。

有关更多信息，请参阅 变量参考。

CloudFormationStackSet操作配置示例

以下示例显示了操作的CloudFormationStackSet操作配置。

自行管理权限模型的示例

以下示例显示了输入的部署目标为 Amazon 账户 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 Amazon 的选项，同时保留堆栈。

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。

操作类型

  • 类别：Deploy

  • 拥有者：AWS

  • 提供方：CloudFormationStackInstances

  • 版本：1

配置参数

StackSetName

必需：是

要与堆栈集关联的名称。此名称在创建它的区域中必须唯一。

名称中只能包含字母数字字符和连字符。它必须以字母字符开头，且不得超过 128 个字符。

DeploymentTargets

必需：否

注意

对于 SERVICE _ MANAGED 权限模型，您可以IDs为部署目标提供组织根 ID 或组织单位。对于 SELF _ MANAGED 权限模型，您只能提供账户。

注意

选择此参数后，还必须选择区域。

应IDs在其中创建/更新堆栈集实例的 Amazon 账户或组织单位列表。

  • Accounts：

    您可以通过文本列表或文件路径的形式提供账户：

    • 文本：使用简写语法格式 account_ID,account_ID 输入参数，如以下示例所示。

      111111222222,333333444444

    • 文件路径：文件的位置，其中包含应在其中创建/更新堆栈集实例的 Amazon 账户列表，格式为。InputArtifactName::AccountsFileName如果您使用文件路径来指定账户或 OrganizationalUnitIds，则文件格式必须为JSON，如以下示例所示。

      SourceArtifact::accounts.txt

      以下示例显示 accounts.txt 的文件内容：

      [
    "111111222222"
]

      以下示例显示了列出多个账户时 accounts.txt 的文件内容：

      [
    "111111222222","333333444444"
]

  • OrganizationalUnitIds:

    注意

    此参数对于 SERVICE _ MANAGED 权限模型是可选的，不用于 SELF _ MANAGED 权限模型。如果您选择，请不要使用此选项OrganizationsAutoDeployment。

    更新关联堆栈实例的 Amazon 组织单位。

    您可以以文字列表或文件路径的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。

创建或更新堆栈集实例的 Amazon 区域列表。区域将按照输入顺序进行更新。

以:的格式输入有效 Amazon 区域列表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

必需：否

在该区域 Amazon CloudFormation 停止该堆栈操作之前，每个区域中该堆栈操作可能失败的账户百分比。如果操作在某个区域中停止，则 Amazon CloudFormation 不会在后续区域中尝试该操作。根据指定的百分比计算账户数量时，向下 Amazon CloudFormation 舍入到下一个整数。

MaxConcurrentPercentage

必需：否

一次执行此操作的账户数的最大百分比。根据指定的百分比计算账户数量时，向下 Amazon CloudFormation 舍入到下一个整数。如果向下舍入结果为零，则改为将数字 Amazon CloudFormation 设置为一。尽管您指定最大值，但对于大型部署，并行执行的实际账户的数量可能会因服务节流而减少。

RegionConcurrencyType

必需：否

您可以通过配置区域并发部署参数，指定堆栈集应该按照顺序方式还是并行方式跨 Amazon Web Services 区域 进行部署。如果将区域并发性指定为 Amazon Web Services 区域 并行部署多个堆栈，则可以缩短总体部署时间。

  • 并行：只要区域的部署失败次数不超过指定的容错值，就会同时执行堆栈集部署。

  • 顺序：只要区域的部署失败次数不超过指定的容错值，就会一次执行一个堆栈集部署。顺序部署是默认选项。

ConcurrencyMode

必需：否

并发模式允许您选择并发级别在堆栈集操作期间的行为方式，无论是严格容错还是软容错。严格容错会降低堆栈集操作失败时的部署速度，因为每次失败都会降低并发数。S@@ oft Fail ure Tolerance 优先考虑部署速度，同时仍能利用 Amazon 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。

有关更多信息，请参阅 变量参考。

操作配置示例

以下示例显示了操作的CloudFormationStackInstances操作配置。

自行管理权限模型的示例

以下示例显示了一个CloudFormationStackInstances操作，其中输入的部署目标是 Amazon Web Services 账户 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 Amazon 组织单位 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"
}

堆栈集操作的权限模型

由于跨多个账户 Amazon CloudFormation StackSets 执行操作，因此必须先在这些账户中定义必要的权限，然后才能创建堆栈集。您可以通过自管理权限或服务管理权限来定义权限。

使用自我管理权限，您可以创建所需的两个IAM角色：一个是管理员角色，例如定义堆栈集的账户 AWSCloudFormationStackSetAdministrationRole 中的，另一个是执行角色，例如部署堆栈集实例的每个账户 AWSCloudFormationStackSetExecutionRole 中的。 StackSets 使用此权限模型， StackSets 可以部署到用户有权创建IAM角色的任何 Amazon 账户。有关更多信息，请参阅 Amazon CloudFormation 用户指南 中的创建自管理权限。

注意

由于跨多个账户 Amazon CloudFormation StackSets 执行操作，因此必须先在这些账户中定义必要的权限，然后才能创建堆栈集。

借助服务管理权限，您可以将堆栈实例部署到由 Organizations 管理的账户 Amazon 。使用此权限模型，您无需创建必要的IAM角色，因为这些IAM角色是代表您 StackSets 创建的。使用此模型，您还可以启用向将来添加到组织的账户自动部署的功能。请参阅《Amazon CloudFormation 用户指南》中的 “通过 Org Amazon anizations 启用可信访问”。

模板参数数据类型

堆栈集操作中使用的模板参数包括以下数据类型。有关更多信息，请参阅DescribeStackSet。

ParameterKey

  • 描述：与参数关联的键。如果您没有为特定参数指定键和值，则 Amazon 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。

下列相关资源在您使用此操作的过程中会有所帮助。

  • 参数类型 —《Amazon CloudFormation 用户指南》中的本参考章节提供了 CloudFormation 模板参数的更多描述和示例。

  • 最佳实践：有关部署堆栈集的最佳实践的更多信息，请参阅 Amazon CloudFormation 用户指南 中的 https://docs.amazonaws.cn/AWSCloudFormation/latest/UserGuide/stacksets-bestpractices.html。

  • Amazon CloudFormation API参考 — 您可以在 “参考” 中Amazon CloudFormation API引用以下 CloudFormation 操作，以了解有关堆栈集操作中使用的参数的更多信息：

    • 该CreateStackSet操作会创建堆栈集。

    • 该UpdateStackSet操作更新了指定账户和区域中的堆栈集和关联堆栈实例。即使通过更新堆栈集创建的堆栈集操作失败（完全失败或部分失败，低于或高于指定的容错值），也会使用这些更改来更新堆栈集。对指定堆栈集的后续 CreateStackInstances 调用使用更新的堆栈集。

    • 该CreateStackInstances操作在自行管理的权限模型上为所有指定账户中的所有指定区域创建堆栈实例，或者在服务管理的权限模型上为所有指定部署目标中的所有指定区域创建堆栈实例。您可以覆盖通过此操作创建的实例的参数。如果实例已经存在，则使用相同的输入参数 UpdateStackInstances 进行 CreateStackInstances 调用。当您使用此操作创建实例时，不会更改其他堆栈实例的状态。

    • 该UpdateStackInstances操作使堆栈实例与在自管理权限模型上所有指定账户中的所有指定区域或服务托管权限模型上的所有指定部署目标中的所有指定部署目标中的堆栈集保持同步。您可以覆盖通过此操作更新的实例的参数。当您使用此操作更新实例子集时，不会更改其他堆栈实例的状态。

    • 该DescribeStackSetOperation操作返回指定堆栈集操作的描述。

    • 该DescribeStackSet操作返回指定堆栈集的描述。