AWS CLI `cloudformation wait stack-create-complete` 命令详解：阻塞等待 CloudFormation 栈创建完成

本指南以 AWS CLI 官方示例文档 aws cloudformation wait stack-create-complete（位于仓库 awscli/examples/cloudformation/wait/stack-create-complete.rst）为核心，深入讲解 wait 子命令的语义、轮询参数与底层实现原理。读完本文，你将掌握如何用 wait stack-create-complete 在脚本中同步等待栈创建完成、如何配合 CI/CD 流水线使用，以及 wait 系列命令（stack-update-complete、stack-delete-complete 等）的适用场景与退出码约定。

一、命令概览：wait 子命令解决什么问题

在自动化部署脚本中，aws cloudformation create-stack 是异步操作——命令立即返回，而资源仍在后台创建。若脚本紧接着执行依赖栈内资源的后续步骤，就必须自行轮询 describe-stacks 判断栈状态，代码冗长且易出错。

AWS CLI 的 wait 子命令专门用于"阻塞等待某个条件满足"。官方示例给出其最典型用法（stack-create-complete.rst）：

aws cloudformation wait stack-create-complete \
    --stack-name "arn:aws:cloudformation:us-west-2:123456789012:stack/my-stack-1234/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"

这条命令会持续轮询 DescribeStacks API，直到 CloudFormation 确认指定的栈已成功创建后才返回。命令本身不产生任何输出（"This command produces no output"），成功退出码为 0；只有在轮询达到失败上限时才会以非零退出码结束，这一点对脚本判断至关重要。

注意示例中的 --stack-name 传的是栈的完整 ARN（含资源 ID 后缀），实际也支持直接传栈名称，例如 --stack-name my-stack-1234。

二、轮询行为与配置参数：30 秒间隔、120 次上限

wait stack-create-complete 的轮询参数并非写死在代码里，而是来自服务端的 waiter 模型定义。在仓库中，CloudFormation 的 waiter 配置位于 awscli/botocore/data/cloudformation/2010-05-15/waiters-2.json：

waiter 名称	底层轮询操作	delay（每次间隔秒数）	maxAttempts（最大尝试次数）	总等待时长上限
StackCreateComplete	DescribeStacks	30	120	约 60 分钟
StackDeleteComplete	DescribeStacks	30	120	约 60 分钟
StackUpdateComplete	DescribeStacks	30	120	约 60 分钟
StackImportComplete	DescribeStacks	30	120	约 60 分钟
StackRollbackComplete	DescribeStacks	30	120	约 60 分钟
StackExists	DescribeStacks	5	20	约 100 秒
ChangeSetCreateComplete	DescribeChangeSet	30	120	约 60 分钟
TypeRegistrationComplete	DescribeTypeRegistration	30	120	约 60 分钟

以 StackCreateComplete 为例，其定义为 operation: DescribeStacks、delay: 30、maxAttempts: 120。也就是说命令每 30 秒调用一次 DescribeStacks，最多尝试 120 次（约 1 小时）；期间一旦检测到成功条件（栈状态为 CREATE_COMPLETE）即立即返回。

从源码角度看，这个"检测条件"由 acceptor（接受器）集合实现。waiter 模型为 StackCreateComplete 定义了 15 个 acceptor，覆盖多种状态：栈状态为 CREATE_COMPLETE（成功）、CREATE_FAILED、ROLLBACK_COMPLETE、ROLLBACK_FAILED、DELETE_FAILED 等（失败），以及 ValidationError 异常（终止）。成功与失败判定都会让轮询结束，区别在于返回码不同。

三、底层实现：waiters.py 中的执行链路

wait 命令本身是 AWS CLI 的一个自定义命令，实现在 awscli/customizations/waiters.py。理解这段源码有助于把握命令的行为边界：

1. 动态挂载 wait 子命令：register_add_waiters 监听 building-command-table 事件，add_waiters 检查服务是否声明了 waiter 模型（通过 session.get_waiter_model(service_name, api_version)），若有则在命令表中注入 WaitCommand（waiters.py）。

2. 子命令按 waiter 名动态生成：WaiterStateCommandBuilder.build_all_waiter_state_cmds 遍历模型中的每个 waiter，把 StackCreateComplete 之类的名字转换为 CLI 风格 stack-create-complete，并生成对应的 WaiterStateCommand（waiters.py）。

3. 参数来自底层操作：每个 waiter 子命令的参数表复用其底层操作（DescribeStacks）的输入参数，所以 stack-create-complete 接受 --stack-name。

4. 核心调用：WaiterCaller.invoke 使用 create_nested_client 按当前会话的 region、endpoint、SSL 校验设置构造客户端，然后 client.get_waiter(...).wait(**parameters) 执行真正轮询（waiters.py）。

5. 帮助文档生成：WaiterStateDocBuilder 依据 acceptor 和 delay/maxAttempts 自动生成命令描述，并明确写到："It will poll every 30 seconds until a successful state has been reached. This will exit with a return code of 255 after 120 failed checks."——即轮询耗尽 120 次仍未成功时，以退出码 255 结束（waiters.py）。

这一退出码约定是脚本编程的关键：0 表示成功，255 表示等待超时（栈未在约 1 小时内创建完成，或已进入失败状态）。

四、wait 系列子命令：一份可复用的"状态同步"清单

aws cloudformation wait 下共提供 8 个与栈/变更集/类型注册相关的 waiter 子命令，对应示例文档均位于 awscli/examples/cloudformation/wait/ 目录：

子命令	等待的完成条件	关键参数
stack-create-complete	栈创建完成（CREATE_COMPLETE）	--stack-name
stack-update-complete	栈更新完成（UPDATE_COMPLETE）	--stack-name
stack-delete-complete	栈删除完成（栈已不存在）	--stack-name
stack-rollback-complete	栈回滚操作完成	--stack-name
stack-import-complete	栈内全部支持导入的资源导入成功	--stack-name
stack-exists	确认栈真实存在（约 100 秒内，每 5 秒轮询一次）	--stack-name
change-set-create-complete	变更集创建就绪、可以执行	--stack-name + --change-set-name
type-registration-complete	资源类型注册完成	--registration-token

典型用法：

# 等待栈更新完成
aws cloudformation wait stack-update-complete \
    --stack-name "arn:aws:cloudformation:us-west-2:123456789012:stack/my-stack-1234/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"

# 等待删除完成
aws cloudformation wait stack-delete-complete \
    --stack-name "arn:aws:cloudformation:us-west-2:123456789012:stack/my-stack-1234/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111"

# 等待变更集创建就绪
aws cloudformation wait change-set-create-complete \
    --stack-name my-stack \
    --change-set-name my-change-set

# 等待资源类型注册完成
aws cloudformation wait type-registration-complete \
    --registration-token "f5525280-104e-4d35-bef5-8f1f1example"

这些命令与 stack-create-complete 一样，成功时无输出并以退出码 0 返回；失败/超时时以退出码 255 返回。

五、实战场景与建议

1. 配合 create-stack 使用：在 aws cloudformation create-stack 之后立即调用 wait stack-create-complete，即可在脚本中实现同步部署；栈创建失败（如资源不可用）时 wait 会在检测到失败 acceptor 后尽快以 255 退出，无需干等满 1 小时。

2. 流水线中使用 && 串联：利用退出码语义可以写出清晰的失败即停流水线：

   aws cloudformation create-stack --stack-name my-stack --template-body file://template.yaml
   aws cloudformation wait stack-create-complete --stack-name my-stack
   aws deploy push ...   # 栈就绪后再执行后续步骤
   

3. 配合变更集先预览再执行：先 change-set-create-complete 等待变更集就绪，审查变更内容后再 execute-change-set，最后 stack-update-complete 等待更新落地。

4. 注意长耗时上限：StackCreateComplete 默认最长等待约 60 分钟。如果模板中资源众多、单资源创建本身可能超过 1 小时，应评估是否改用自定义轮询逻辑（如结合 describe-stacks --query "Stacks[0].StackStatus" 与 sleep 循环）以获得更大灵活度。

5. 脚本中区分两种失败：超时（120 次轮询均未成功）与确定性失败（收到 CREATE_FAILED、ROLLBACK_COMPLETE 等失败 acceptor）都以 255 退出，如需区分可先自行 describe-stacks 查看最终栈状态。

六、小结

aws cloudformation wait stack-create-complete 是 AWS CLI 为异步 CloudFormation 操作提供的官方"同步等待"工具：每 30 秒轮询一次 DescribeStacks，最多 120 次，栈状态变为 CREATE_COMPLETE 时静默返回（退出码 0），失败或超时则以 255 退出。其轮询间隔与次数来自 waiters-2.json 的模型定义，执行逻辑则落在 waiters.py 的 WaiterCaller 中。配合同一目录下的 stack-update-complete、stack-delete-complete、change-set-create-complete 等兄弟命令（示例见 awscli/examples/cloudformation/wait/），可以低成本地为部署脚本构建出健壮的异步操作状态同步层。