aws cloudformation update-stack-instances 实战指南跨账户跨区域批量更新 StackSet 栈实例【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli导读aws cloudformation update-stack-instances是 AWS CLI 中用于批量更新StackSet栈集在指定账户与区域中栈实例参数值的命令。本文以 update-stack-instances.rst 中的官方示例为核心结合本仓库 CloudFormation 服务模型service-2.json的 API 定义系统讲解该命令的适用场景、参数语义、操作偏好OperationPreferences配置、幂等机制、错误处理与后续跟踪方法。读完本文你将掌握如何通过一条命令在多账户多区域中安全、可控地重试或更新栈实例参数并能独立排查常见失败场景。命令概览与适用场景update-stack-instances对应 CloudFormation API 的UpdateStackInstances操作service-2.json#L1362-L1382其官方语义是为指定账户、指定 AWS 区域内的栈实例更新参数值。这里的“栈实例”指的是特定账户与特定区域中的一个栈。该命令最典型的场景有两个重试上次失败的 StackSet 操作当一次针对栈实例的更新因部分账户/区域失败而中止时可用update-stack-instances以最新设置对目标账户与区域重新发起更新。覆盖栈实例的模板参数值StackSet 模板定义的参数默认值属于栈集级当某个账户或区域需要不同的参数取值时可通过本命令对该范围内的栈实例单独覆盖参数值。需要特别注意的是该命令不会在尚未创建栈实例的账户/区域中新建栈——创建栈实例应使用create-stack-instances参见 create-stack-instances.rst更新整个 StackSet 本身的模板与参数应使用update-stack-set参见 update-stack-set.rst。官方示例详解update-stack-instances的官方示例update-stack-instances.rst如下aws cloudformation update-stack-instances \ --stack-set-name my-stack-set \ --accounts 123456789012 567890123456 \ --regions us-east-1 us-west-2 \ --operation-preferences FailureToleranceCount3输出{ OperationId: 103ebdf2-21ea-xmpl-8892-de5e30733132 }这个示例演示的是对名为my-stack-set的栈集在两个账户123456789012、567890123456与两个区域us-east-1、us-west-2中的现有栈实例重试更新并指定容错数量为 3即即使部分栈更新失败只要失败账户数未超过容错阈值CloudFormation 仍会在所有目标账户和区域中继续尝试更新。命令执行成功后CLI 返回一个OperationId。StackSet 操作都是异步执行的这个 ID 是后续跟踪操作进度、查询操作结果、甚至中止操作的唯一凭证。核心参数逐一拆解根据UpdateStackInstancesInput结构定义service-2.json#L9346-L9387该命令的输入参数如下。必选参数参数类型说明--stack-set-nameStringStackSet 的名称或唯一 ID用于定位目标栈集--regionsList要更新栈实例的一个或多个 AWS 区域名从服务模型可见required数组仅包含StackSetName与Regions也就是说--accounts或--deployment-targets与--regions组合起来构成了更新目标范围--regions是唯一始终必需的定位维度。目标范围Accounts 与 DeploymentTargets二选一--accounts[Self-managed permissions]以自管理权限模型部署时使用直接列出需要更新栈实例参数值的账户 IDAWS 账户 ID 为 12 位数字服务模型中的模式为^[0-9]{12}$。覆盖的参数值将应用到指定账户与区域中的所有栈实例。--deployment-targets[Service-managed permissions]以服务管理权限模型部署时使用指定 AWS Organizations 中的账户或组织单元OU。当目标是 OU 时覆盖值仅作用于当前处于该 OU 及其子 OU 中的账户未来新加入的账户不会自动套用本次覆盖值。二者不可同时指定。这也是示例中只使用--accounts的原因。参数覆盖ParameterOverrides--parameter-overrides用于对指定范围内的栈实例覆盖 StackSet 模板参数的值其行为规则service-2.json#L9369-L9371需要仔细把握覆盖当前值在列表中包含该参数并给出新值保持既有覆盖值不变在列表中包含该参数并将UsePreviousValue设为true不能同时指定新值与UsePreviousValuetrue恢复为 StackSet 级参数值提供参数列表但不包含该参数即可去掉此前的实例级覆盖保持全部参数现状完全不指定该属性。值得注意的限制该命令只能覆盖已存在于 StackSet 模板中的参数值若要新增或删除参数本身必须先用update-stack-set更新 StackSet 模板并且只有在栈实例完成新模板参数同步后才能对其使用update-stack-instances进行覆盖。此外在 StackSet 自身更新期间已覆盖的实例参数值不会被改动而是保留覆盖值。操作偏好OperationPreferences--operation-preferences是控制 StackSet 操作如何执行的开关集对应StackSetOperationPreferences结构service-2.json#L8322-L8355示例中的FailureToleranceCount3只是其中一个选项。全部可选键如下键取值/默认作用FailureToleranceCount整数默认0每个区域中允许失败的最大账户数超过则 CloudFormation 停止该区域操作且不再尝试后续区域FailureTolerancePercentage百分比默认0同上但按区域中账户数的百分比计算向下取整MaxConcurrentCount整数默认1同一时间最多并行操作的账户数上限MaxConcurrentPercentage百分比默认1同一时间最多并行操作的账户数百分比向下取整若取整为 0 则按 1 处理RegionConcurrencyTypeSEQUENTIAL/PARALLEL区域间是逐个顺序执行还是并行执行RegionOrder区域列表自定义区域执行的先后顺序ConcurrencyModeSTRICT_FAILURE_TOLERANCE/SOFT_FAILURE_TOLERANCE并发级别与容错的关系模式见下文关于容错与并发有两个易混淆点需要澄清容错语义FailureToleranceCount3表示每个区域内最多允许 3 个账户更新失败操作才会继续一旦失败账户数突破阈值该区域的操作即被停止且后续区域不再执行。百分比模式下计算时向下取整。ConcurrencyMode 二选一STRICT_FAILURE_TOLERANCE默认动态调低并发确保失败账户数永不越过FailureToleranceCount 1初始并发取MaxConcurrentCount与FailureToleranceCount 1的较小值随后按失败数等比下调。SOFT_FAILURE_TOLERANCE将容错与并发解耦始终按MaxConcurrentCount/MaxConcurrentPercentage设定的并发上限执行不受失败数量影响。从模型注释还可得知StackSetOperationPreferences对AutoDeployment自动部署不生效。另外在服务端存在节流throttling时实际并发数可能低于你设定的最大值这是正常现象。幂等与鉴权OperationId 与 CallAs--operation-id唯一标识本次 StackSet 操作同时充当幂等令牌——即使你因网络等原因重试请求只要携带相同 IDCloudFormation 也只执行一次。若省略SDK 会自动生成一个。示例中返回的OperationId正是这样一串 UUID。--call-as仅服务管理权限值为SELF默认管理账户管理员或DELEGATED_ADMIN已注册的委派管理员账户。自管理权限模型下固定使用SELF。实战带参数覆盖的更新命令在官方示例基础上加入参数覆盖与更精细的操作偏好即可应对真实部署需求。例如为上述两个账户与两个区域中的栈实例将模板参数InstanceType覆盖为t3.large并控制容错与并发aws cloudformation update-stack-instances \ --stack-set-name my-stack-set \ --accounts 123456789012 567890123456 \ --regions us-east-1 us-west-2 \ --parameter-overrides InstanceTypet3.large \ --operation-preferences \ FailureToleranceCount3 \ MaxConcurrentCount5 \ RegionConcurrencyTypePARALLEL \ ConcurrencyModeSOFT_FAILURE_TOLERANCE若只想重试失败实例而保持全部参数现状则可完全省略--parameter-overrides对应“保持全部参数现值”规则仅保留目标范围与操作偏好。操作执行后的跟踪与验证StackSet 操作异步进行返回的OperationId用于后续跟踪。本仓库的 CloudFormation 示例集提供了完整的配套命令awscli/examples/cloudformationdescribe-stack-set-operation查看本次操作的整体状态如RUNNING、SUCCEEDED、FAILEDlist-stack-set-operation-results按账户区域查看每一条操作结果状态枚举为PENDING、RUNNING、SUCCEEDED、FAILED、CANCELLEDservice-2.json#L8356-L8364其中CANCELLED可能由用户主动停止或因超出容错阈值触发stop-stack-set-operation需要立即中止时使用list-stack-instances核对各账户/区域栈实例的最终状态。若需确认操作是否受账户网关Account Gate函数影响可在list-stack-set-operation-results的输出中查看AccountGateResult字段service-2.json#L8389-L8391。错误与边界情况服务模型service-2.json#L1373-L1380明确列出了UpdateStackInstances可能抛出的六类错误便于排查错误含义StackSetNotFoundException指定的 StackSet 不存在StackInstanceNotFoundException目标账户/区域中不存在对应的栈实例应改用create-stack-instancesOperationInProgressException该 StackSet 上已有操作正在进行OperationIdAlreadyExistsException使用了已存在的操作 IDStaleRequestException请求过期例如 StackSet 在请求期间已被更新InvalidOperationException操作请求本身不合法如账户与 OU 混用等此外还需留意两个边界约束OU 数量上限单次update-stack-instances操作最多支持50 个组织单元OU如需更多要么拆分为多次调用每次少于 50 个 OU要么改为指定包含所有目标子 OU 的父 OU 作为目标。只更新既有实例命令无法在尚未部署栈实例的账户/区域创建新栈目标范围必须与既有栈实例匹配。小结update-stack-instances是 StackSet 体系中进行实例级参数覆盖与失败重试的关键命令。其核心要点可归纳为目标范围由--accounts自管理或--deployment-targets服务管理配合--regions共同圈定--parameter-overrides遵循“覆盖/保留/恢复/不动”四种语义--operation-preferences中的容错与并发参数决定了操作在部分失败时的推进策略OperationId既是幂等令牌也是后续跟踪操作的凭证。将本文命令与 describe-stack-set-operation.rst、list-stack-set-operation-results.rst 等配套示例结合使用即可构建完整的跨账户、跨区域栈实例更新闭环。【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 aws cloudformation update-stack-instances 实战指南：跨账户跨区域批量更新 StackSet 栈实例
aws cloudformation update-stack-instances 实战指南跨账户跨区域批量更新 StackSet 栈实例【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli导读aws cloudformation update-stack-instances是 AWS CLI 中用于批量更新StackSet栈集在指定账户与区域中栈实例参数值的命令。本文以 update-stack-instances.rst 中的官方示例为核心结合本仓库 CloudFormation 服务模型service-2.json的 API 定义系统讲解该命令的适用场景、参数语义、操作偏好OperationPreferences配置、幂等机制、错误处理与后续跟踪方法。读完本文你将掌握如何通过一条命令在多账户多区域中安全、可控地重试或更新栈实例参数并能独立排查常见失败场景。命令概览与适用场景update-stack-instances对应 CloudFormation API 的UpdateStackInstances操作service-2.json#L1362-L1382其官方语义是为指定账户、指定 AWS 区域内的栈实例更新参数值。这里的“栈实例”指的是特定账户与特定区域中的一个栈。该命令最典型的场景有两个重试上次失败的 StackSet 操作当一次针对栈实例的更新因部分账户/区域失败而中止时可用update-stack-instances以最新设置对目标账户与区域重新发起更新。覆盖栈实例的模板参数值StackSet 模板定义的参数默认值属于栈集级当某个账户或区域需要不同的参数取值时可通过本命令对该范围内的栈实例单独覆盖参数值。需要特别注意的是该命令不会在尚未创建栈实例的账户/区域中新建栈——创建栈实例应使用create-stack-instances参见 create-stack-instances.rst更新整个 StackSet 本身的模板与参数应使用update-stack-set参见 update-stack-set.rst。官方示例详解update-stack-instances的官方示例update-stack-instances.rst如下aws cloudformation update-stack-instances \ --stack-set-name my-stack-set \ --accounts 123456789012 567890123456 \ --regions us-east-1 us-west-2 \ --operation-preferences FailureToleranceCount3输出{ OperationId: 103ebdf2-21ea-xmpl-8892-de5e30733132 }这个示例演示的是对名为my-stack-set的栈集在两个账户123456789012、567890123456与两个区域us-east-1、us-west-2中的现有栈实例重试更新并指定容错数量为 3即即使部分栈更新失败只要失败账户数未超过容错阈值CloudFormation 仍会在所有目标账户和区域中继续尝试更新。命令执行成功后CLI 返回一个OperationId。StackSet 操作都是异步执行的这个 ID 是后续跟踪操作进度、查询操作结果、甚至中止操作的唯一凭证。核心参数逐一拆解根据UpdateStackInstancesInput结构定义service-2.json#L9346-L9387该命令的输入参数如下。必选参数参数类型说明--stack-set-nameStringStackSet 的名称或唯一 ID用于定位目标栈集--regionsList要更新栈实例的一个或多个 AWS 区域名从服务模型可见required数组仅包含StackSetName与Regions也就是说--accounts或--deployment-targets与--regions组合起来构成了更新目标范围--regions是唯一始终必需的定位维度。目标范围Accounts 与 DeploymentTargets二选一--accounts[Self-managed permissions]以自管理权限模型部署时使用直接列出需要更新栈实例参数值的账户 IDAWS 账户 ID 为 12 位数字服务模型中的模式为^[0-9]{12}$。覆盖的参数值将应用到指定账户与区域中的所有栈实例。--deployment-targets[Service-managed permissions]以服务管理权限模型部署时使用指定 AWS Organizations 中的账户或组织单元OU。当目标是 OU 时覆盖值仅作用于当前处于该 OU 及其子 OU 中的账户未来新加入的账户不会自动套用本次覆盖值。二者不可同时指定。这也是示例中只使用--accounts的原因。参数覆盖ParameterOverrides--parameter-overrides用于对指定范围内的栈实例覆盖 StackSet 模板参数的值其行为规则service-2.json#L9369-L9371需要仔细把握覆盖当前值在列表中包含该参数并给出新值保持既有覆盖值不变在列表中包含该参数并将UsePreviousValue设为true不能同时指定新值与UsePreviousValuetrue恢复为 StackSet 级参数值提供参数列表但不包含该参数即可去掉此前的实例级覆盖保持全部参数现状完全不指定该属性。值得注意的限制该命令只能覆盖已存在于 StackSet 模板中的参数值若要新增或删除参数本身必须先用update-stack-set更新 StackSet 模板并且只有在栈实例完成新模板参数同步后才能对其使用update-stack-instances进行覆盖。此外在 StackSet 自身更新期间已覆盖的实例参数值不会被改动而是保留覆盖值。操作偏好OperationPreferences--operation-preferences是控制 StackSet 操作如何执行的开关集对应StackSetOperationPreferences结构service-2.json#L8322-L8355示例中的FailureToleranceCount3只是其中一个选项。全部可选键如下键取值/默认作用FailureToleranceCount整数默认0每个区域中允许失败的最大账户数超过则 CloudFormation 停止该区域操作且不再尝试后续区域FailureTolerancePercentage百分比默认0同上但按区域中账户数的百分比计算向下取整MaxConcurrentCount整数默认1同一时间最多并行操作的账户数上限MaxConcurrentPercentage百分比默认1同一时间最多并行操作的账户数百分比向下取整若取整为 0 则按 1 处理RegionConcurrencyTypeSEQUENTIAL/PARALLEL区域间是逐个顺序执行还是并行执行RegionOrder区域列表自定义区域执行的先后顺序ConcurrencyModeSTRICT_FAILURE_TOLERANCE/SOFT_FAILURE_TOLERANCE并发级别与容错的关系模式见下文关于容错与并发有两个易混淆点需要澄清容错语义FailureToleranceCount3表示每个区域内最多允许 3 个账户更新失败操作才会继续一旦失败账户数突破阈值该区域的操作即被停止且后续区域不再执行。百分比模式下计算时向下取整。ConcurrencyMode 二选一STRICT_FAILURE_TOLERANCE默认动态调低并发确保失败账户数永不越过FailureToleranceCount 1初始并发取MaxConcurrentCount与FailureToleranceCount 1的较小值随后按失败数等比下调。SOFT_FAILURE_TOLERANCE将容错与并发解耦始终按MaxConcurrentCount/MaxConcurrentPercentage设定的并发上限执行不受失败数量影响。从模型注释还可得知StackSetOperationPreferences对AutoDeployment自动部署不生效。另外在服务端存在节流throttling时实际并发数可能低于你设定的最大值这是正常现象。幂等与鉴权OperationId 与 CallAs--operation-id唯一标识本次 StackSet 操作同时充当幂等令牌——即使你因网络等原因重试请求只要携带相同 IDCloudFormation 也只执行一次。若省略SDK 会自动生成一个。示例中返回的OperationId正是这样一串 UUID。--call-as仅服务管理权限值为SELF默认管理账户管理员或DELEGATED_ADMIN已注册的委派管理员账户。自管理权限模型下固定使用SELF。实战带参数覆盖的更新命令在官方示例基础上加入参数覆盖与更精细的操作偏好即可应对真实部署需求。例如为上述两个账户与两个区域中的栈实例将模板参数InstanceType覆盖为t3.large并控制容错与并发aws cloudformation update-stack-instances \ --stack-set-name my-stack-set \ --accounts 123456789012 567890123456 \ --regions us-east-1 us-west-2 \ --parameter-overrides InstanceTypet3.large \ --operation-preferences \ FailureToleranceCount3 \ MaxConcurrentCount5 \ RegionConcurrencyTypePARALLEL \ ConcurrencyModeSOFT_FAILURE_TOLERANCE若只想重试失败实例而保持全部参数现状则可完全省略--parameter-overrides对应“保持全部参数现值”规则仅保留目标范围与操作偏好。操作执行后的跟踪与验证StackSet 操作异步进行返回的OperationId用于后续跟踪。本仓库的 CloudFormation 示例集提供了完整的配套命令awscli/examples/cloudformationdescribe-stack-set-operation查看本次操作的整体状态如RUNNING、SUCCEEDED、FAILEDlist-stack-set-operation-results按账户区域查看每一条操作结果状态枚举为PENDING、RUNNING、SUCCEEDED、FAILED、CANCELLEDservice-2.json#L8356-L8364其中CANCELLED可能由用户主动停止或因超出容错阈值触发stop-stack-set-operation需要立即中止时使用list-stack-instances核对各账户/区域栈实例的最终状态。若需确认操作是否受账户网关Account Gate函数影响可在list-stack-set-operation-results的输出中查看AccountGateResult字段service-2.json#L8389-L8391。错误与边界情况服务模型service-2.json#L1373-L1380明确列出了UpdateStackInstances可能抛出的六类错误便于排查错误含义StackSetNotFoundException指定的 StackSet 不存在StackInstanceNotFoundException目标账户/区域中不存在对应的栈实例应改用create-stack-instancesOperationInProgressException该 StackSet 上已有操作正在进行OperationIdAlreadyExistsException使用了已存在的操作 IDStaleRequestException请求过期例如 StackSet 在请求期间已被更新InvalidOperationException操作请求本身不合法如账户与 OU 混用等此外还需留意两个边界约束OU 数量上限单次update-stack-instances操作最多支持50 个组织单元OU如需更多要么拆分为多次调用每次少于 50 个 OU要么改为指定包含所有目标子 OU 的父 OU 作为目标。只更新既有实例命令无法在尚未部署栈实例的账户/区域创建新栈目标范围必须与既有栈实例匹配。小结update-stack-instances是 StackSet 体系中进行实例级参数覆盖与失败重试的关键命令。其核心要点可归纳为目标范围由--accounts自管理或--deployment-targets服务管理配合--regions共同圈定--parameter-overrides遵循“覆盖/保留/恢复/不动”四种语义--operation-preferences中的容错与并发参数决定了操作在部分失败时的推进策略OperationId既是幂等令牌也是后续跟踪操作的凭证。将本文命令与 describe-stack-set-operation.rst、list-stack-set-operation-results.rst 等配套示例结合使用即可构建完整的跨账户、跨区域栈实例更新闭环。【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考