AWS CLI 的 cloudformation create-stack-instances 命令实战：为 StackSet 批量创建跨账户、跨区域堆栈实例

AWS CLI 的 cloudformation create-stack-instances 命令实战：为 StackSet 批量创建跨账户、跨区域堆栈实例

【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli

导读

本文以 AWS CLI 仓库中 CloudFormation 服务的官方示例文档 create-stack-instances.rst 为主体，深入讲解aws cloudformation create-stack-instances命令的完整用法：如何在一个已存在的 StackSet（堆栈集）下，向多个 AWS 账户和多个区域批量创建堆栈实例，并通过--operation-preferences控制失败容错与并发策略。读完后你将掌握该命令的参数语义、容错配置、幂等机制、常见错误场景，以及它与create-stack-set、update-stack-instances等命令的配套使用方式，并理解其底层参数在 AWS CLI 仓库服务模型中的真实定义与约束。

一、命令用途：把 StackSet 从"定义"推向"落地"

CloudFormation StackSet 允许你用一份模板在多个账户、多个区域中部署一组配置完全一致的堆栈。但create-stack-set只负责创建 StackSet 本身（即"模板 + 目标范围的元数据"），并不会立刻在任何账户中创建堆栈。真正把堆栈实例创建到指定账户与区域中的命令，正是create-stack-instances。

aws cloudformation create-stack-instances \ --stack-set-name my-stack-set \ --accounts 123456789012 223456789012 \ --regions us-east-1 us-east-2 us-west-1 us-west-2 \ --operation-preferences FailureToleranceCount=7

该命令的一次调用即可在2 个账户 × 4 个区域的组合下创建堆栈实例。CloudFormation 会为这次批量操作生成一个全局唯一的OperationId，并以 JSON 形式返回，后续可用describe-stack-set-operation跟踪该操作的执行进度。

在 AWS CLI 仓库中，该命令对应的完整输入参数模型定义于 awscli/botocore/data/cloudformation/2010-05-15/service-2.json 的CreateStackInstancesInputshape，共包含 7 个成员：StackSetName、Accounts、DeploymentTargets、Regions、ParameterOverrides、OperationPreferences、OperationId（以及CallAs）。下文将逐一展开。

二、核心参数详解

2.1 --stack-set-name（必选）

StackSet 的名称或唯一 ID，命令将基于该 StackSet 的模板与配置创建堆栈实例。这是本命令唯一必选的定位参数，对应模型中的StackSetName成员。若指定的 StackSet 不存在，服务端会返回StackSetNotFoundException。

2.2 --accounts 与 --deployment-targets：两种权限模型的账户指定方式

StackSet 支持两种权限模型，账户的指定方式也因此不同：

• 自助管理（Self-managed）权限：使用--accounts参数直接列出目标账户 ID，例如上例中的123456789012 223456789012。这是最常见、最直接的方式，也是官方示例文档 create-stack-instances.rst 采用的方式。
• 服务管理（Service-managed）权限：配合 AWS Organizations 使用，改用--deployment-targets参数。根据模型DeploymentTargetsshape 的定义，它支持 4 种字段：
  • Accounts：显式列出的账户 ID 列表；
  • AccountsUrl：指向 S3 上.csv或.txt文件（内容可为逗号分隔或换行分隔的账户列表）的 URL，字符串长度上限 5120 字符；
  • OrganizationalUnitIds：组织根或组织单元（OU）的 ID 列表，CloudFormation 会对这些 OU 及其子 OU 内的所有账户执行操作；
  • AccountFilterType：当同时给出Accounts与OrganizationalUnitIds时，控制二者如何联合生效，枚举值包括NONE、INTERSECTION（交集）、DIFFERENCE（差集）、UNION（并集）。

2.3 --regions

要在其中创建堆栈实例的 AWS 区域名称列表，对应模型中的RegionList。示例中指定的us-east-1 us-east-2 us-west-1 us-west-2四个区域会与账户列表形成笛卡尔积：每个账户在每个区域中各创建一个堆栈实例。

2.4 --operation-preferences：容错与并发控制

这是该命令最具实战价值的参数，对应模型StackSetOperationPreferencesshape。官方示例中的FailureToleranceCount=7即属于其中之一。完整字段如下：

示例中的FailureToleranceCount=7意味着：即使单个区域内有最多 7 个账户的堆栈创建失败，本次操作仍会继续尝试所有账户与所有区域（不会因局部失败而提前中止整批操作），这正是"尽可能扩大覆盖面、容忍局部失败"的容错诉求。注意FailureToleranceCount与MaxConcurrentCount是成对使用的计数型参数，使用时应避免与百分比型参数混用。

2.5 --parameter-overrides

一个 JSON 列表，用于在本次创建堆栈实例时覆盖StackSet 级参数值。任何覆盖仅对本次创建的这些实例生效，不会改动 StackSet 本身定义的默认参数。

2.6 --operation-id：幂等令牌

对应模型的ClientRequestTokenshape，长度上限 128，字符模式为[a-zA-Z0-9][-a-zA-Z0-9]*。它在功能上同时充当本次操作的唯一标识符与幂等令牌：如果因网络超时等原因需要重试，请复用同一个OperationId，服务端可据此识别"同一请求"，避免重复创建堆栈实例。若传入的 ID 已存在，会返回OperationIdAlreadyExistsException。

2.7 --call-as（服务管理权限专用）

仅对服务管理权限模型有效，取值SELF（作为组织的管理账户身份操作）或DELEGATED_ADMIN（作为委托管理员身份操作）。

三、返回结果与操作跟踪

命令成功后将返回如下 JSON（示例取自 create-stack-instances.rst）：

{ "OperationId": "d7995c31-83c2-xmpl-a3d4-e9ca2811563f" }

根据模型中CreateStackInstancesOutputshape 的定义，输出仅包含OperationId一个成员。它是此次 StackSet 操作的唯一标识，后续应通过describe-stack-set-operation命令查看各账户、各区域的执行状态，用list-stack-instances核对最终创建的实例清单，若需要撤销部分实例则使用delete-stack-instances。这三个命令在仓库中均有对应的官方示例文档（describe-stack-set-operation.rst、list-stack-instances.rst、delete-stack-instances.rst）。

四、前置步骤：先有 StackSet，后有实例

create-stack-instances依赖一个已存在的 StackSet。配套示例文档 create-stack-set.rst 演示了前置流程——用本地模板文件创建名为my-stack-set的堆栈集：

aws cloudformation create-stack-set \ --stack-set-name my-stack-set \ --template-body file://template.yaml \ --description "SNS topic"

输出中的StackSetId（格式为<StackSetName>:<UUID>，如my-stack-set:8d0f160b-d157-xmpl-a8e6-c0ce8e5d8cc1）可进一步用于精确定位 StackSet。随后再执行本文第一节的create-stack-instances命令，即可完成"创建 StackSet → 添加堆栈实例"的完整链路。这两份示例文档在 awscli/examples/cloudformation 目录中互相引用，构成了完整的使用闭环。

五、异常与失败处理

模型中CreateStackInstances操作声明的错误类型包括：

• StackSetNotFoundException：--stack-set-name指向的 StackSet 不存在；
• OperationInProgressException：该 StackSet 上已有其他操作正在执行，StackSet 操作是串行互斥的；
• OperationIdAlreadyExistsException：幂等令牌--operation-id已被使用；
• StaleRequestException：请求携带的客户端令牌已过期或与正在进行的操作不一致；
• InvalidOperationException：请求在当前状态下不允许执行；
• LimitExceededException：超出账户或区域的资源/操作限制。

当单个区域内的失败账户数超过FailureToleranceCount（或FailureTolerancePercentage）时，CloudFormation 会停止该区域及后续区域的操作，此时应通过describe-stack-set-operation定位失败账户与失败原因（通常为权限不足、模板校验失败或区域不支持等），修正后结合幂等令牌重试。

六、与 update-stack-instances 的对比

批量实例创建完成后，若 StackSet 的模板或参数发生变化，可通过 update-stack-instances.rst 中演示的update-stack-instances命令将最新设置同步到现有实例：

aws cloudformation update-stack-instances \ --stack-set-name my-stack-set \ --accounts 123456789012 567890123456 \ --regions us-east-1 us-west-2 \ --operation-preferences FailureToleranceCount=3

它与create-stack-instances共享几乎完全相同的参数结构（--stack-set-name、--accounts、--regions、--operation-preferences），区别仅在于语义：前者在目标账户/区域中新建堆栈实例，后者更新已存在的实例；两者的输出均为OperationId。因此，掌握本文的参数语义后，可无缝迁移到更新、删除等同类 StackSet 批量操作命令上。

七、如何在本仓库中查阅该命令的完整模型与文档

• 命令示例文档：awscli/examples/cloudformation/create-stack-instances.rst，以及同目录下 CloudFormation 全部命令的示例（awscli/examples/cloudformation）；
• 服务模型（参数、约束、错误、输出）：awscli/botocore/data/cloudformation/2010-05-15/service-2.json；
• 示例文档的加载机制：AWS CLI 在生成命令帮助时，会从awscli/examples目录按命令名查找对应的.rst示例文件并注入帮助页，这一逻辑定义在 awscli/clidocs.py 的EXAMPLES_DIR路径配置中。

日常使用中，可以直接通过aws cloudformation create-stack-instances help在本地查看该命令的完整帮助，其中同样包含上述示例；所有参数与约束均以当前仓库中 service-2.json 所载版本为准。

【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli