AWS CLI 深入实战：用 `aws cloudformation list-stacks` 高效查询与过滤 CloudFormation 栈

导读

aws cloudformation list-stacks 是 AWS CLI 中用于批量查询 CloudFormation 栈摘要信息（Stack Summary）的核心命令。它不返回单个栈的完整资源与输出详情，而是以"摘要卡片"的形式展示当前账号与区域下所有栈的名称、ID、状态、创建时间等关键信息，并支持通过 --stack-status-filter 按状态精确过滤。本文将以 awscli/examples/cloudformation/list-stacks.rst 中的官方示例为骨架，结合当前仓库中 CloudFormation 服务模型与分页器定义，完整讲解该命令的用法、过滤机制、返回字段、分页行为，以及与 describe-stacks 的分工差异，帮助你快速掌握栈生命周期监控与巡检的实用技能。

一、命令概览：list-stacks 能做什么

在 AWS CloudFormation 的日常运维中，你经常需要回答这样的问题：

• 当前账号/区域里一共有哪些栈？
• 有哪些栈创建成功、哪些正在回滚、哪些删除失败了？
• 哪些栈最近被更新过？

list-stacks 正是为这些场景设计的批量摘要查询命令。根据当前仓库中的服务模型 awscli/botocore/data/cloudformation/2010-05-15/service-2.json（ListStacks 操作，位于该文件第 1071–1083 行），该命令的官方语义是：

返回状态与指定 StackStatusFilter 匹配的栈的摘要信息。已删除栈的摘要信息会在删除后保留 90 天。如果未指定 StackStatusFilter，则返回所有栈的摘要信息（包括现存栈与已删除栈）。

这带来两个关键推论，也是使用时的两个"坑"：

1. 默认返回包含已删除栈：如果不对状态做过滤，输出里会混入 90 天保留期内的 DELETE_COMPLETE 栈，日常巡检时容易被"幽灵栈"干扰。
2. 只返回摘要，不返回细节：list-stacks 的结果里没有 Outputs（输出值）、Parameters（参数）、Resources（资源列表）等信息，这些需要配合 describe-stacks 获取。

因此，几乎在所有实战场景中，list-stacks 都应该与 --stack-status-filter 搭配使用。

二、官方示例逐行解读

仓库中的官方示例文档 awscli/examples/cloudformation/list-stacks.rst 给出了最小可用的过滤用法：

aws cloudformation list-stacks --stack-status-filter CREATE_COMPLETE

命令解析：--stack-status-filter 接受一个或多个栈状态码，只返回状态匹配的栈。示例中指定 CREATE_COMPLETE，即只列出创建成功的栈。

对应的输出（JSON 数组形式）：

[
    {
        "StackId": "arn:aws:cloudformation:us-east-1:123456789012:stack/myteststack/466df9e0-0dff-08e3-8e2f-5088487c4896",
        "TemplateDescription": "AWS CloudFormation Sample Template S3_Bucket: Sample template showing how to create a publicly accessible S3 bucket. **WARNING** This template creates an S3 bucket. You will be billed for the AWS resources used if you create a stack from this template.",
        "StackStatusReason": null,
        "CreationTime": "2013-08-26T03:27:10.190Z",
        "StackName": "myteststack",
        "StackStatus": "CREATE_COMPLETE"
    }
]

注意两点：

• 命令返回的是一个 JSON 数组，数组元素是每个栈的摘要对象（在服务模型 service-2.json 中对应 StackSummary 结构，见第 8554–8612 行）；
• 输出中只有 StackId、TemplateDescription、StackStatusReason、CreationTime、StackName、StackStatus 这几个字段，属于"精简约简版"信息。

三、StackSummary 返回字段完整解析

从服务模型 service-2.json 第 8554–8612 行的 StackSummary 结构可以看到，每个栈摘要对象可能包含以下字段：

字段	类型	说明
StackId	string	栈的唯一标识符（ARN 形式）
StackName	string	栈的名称（必填字段）
TemplateDescription	string	创建该栈所用模板的 Description 描述
CreationTime	datetime	栈的创建时间（必填字段）
LastUpdatedTime	datetime	栈的最后更新时间，仅当栈至少更新过一次时返回
DeletionTime	datetime	栈的删除时间
StackStatus	string	栈的当前状态（必填字段）
StackStatusReason	string	与栈状态关联的成功/失败消息
ParentId	string	嵌套栈场景下，直接父栈的 StackId
RootId	string	嵌套栈场景下，最顶层根栈的 StackId
DriftInformation	object	栈实际配置与模板期望配置是否发生漂移（drift）的摘要
LastOperations	object	最近对该栈执行过的操作信息

实战提示：示例输出里的 StackStatusReason 为 null，表示栈处于正常终态、没有额外状态说明。如果栈创建或更新失败，该字段通常会给出具体的失败原因，是排查问题的第一手信息。另外，LastUpdatedTime 只有在栈被更新过之后才会出现——这也解释了为什么"干净"的示例输出中没有该字段。

四、--stack-status-filter：状态过滤的完整取值

--stack-status-filter 对应服务模型 service-2.json 中的 StackStatusFilter 结构（第 8545–8548 行），它是一个字符串列表类型，成员取值来自 StackStatus 枚举（第 8517–8544 行）。完整合法的状态码如下：

生命周期阶段	状态码
创建	CREATE_IN_PROGRESS、CREATE_FAILED、CREATE_COMPLETE
回滚	ROLLBACK_IN_PROGRESS、ROLLBACK_FAILED、ROLLBACK_COMPLETE
删除	DELETE_IN_PROGRESS、DELETE_FAILED、DELETE_COMPLETE
更新	UPDATE_IN_PROGRESS、UPDATE_COMPLETE_CLEANUP_IN_PROGRESS、UPDATE_COMPLETE、UPDATE_FAILED、UPDATE_ROLLBACK_IN_PROGRESS、UPDATE_ROLLBACK_FAILED、UPDATE_ROLLBACK_COMPLETE_CLEANUP_IN_PROGRESS、UPDATE_ROLLBACK_COMPLETE
审核	REVIEW_IN_PROGRESS
导入	IMPORT_IN_PROGRESS、IMPORT_COMPLETE、IMPORT_ROLLBACK_IN_PROGRESS、IMPORT_ROLLBACK_FAILED、IMPORT_ROLLBACK_COMPLETE

--stack-status-filter 支持同时传多个状态，语法上直接在命令后面追加多个值即可：

# 列出所有创建失败和回滚完成的栈
aws cloudformation list-stacks \
  --stack-status-filter CREATE_FAILED ROLLBACK_COMPLETE

实战用法建议：

• 巡检故障栈：过滤 CREATE_FAILED、UPDATE_FAILED、ROLLBACK_FAILED、DELETE_FAILED 等失败态，快速定位需要人工介入的栈；
• 监控进行中的操作：过滤 *_IN_PROGRESS 状态，观察创建/更新/删除是否卡住；
• 清理回收：过滤 DELETE_COMPLETE，结合 describe-stacks 确认后再做资源核销。

五、分页行为与 NextToken

当栈数量很大时，list-stacks 的输出会分页。从 service-2.json 中 ListStacksInput（第 5231–5244 行）和 ListStacksOutput（第 5245–5258 行）可以看到：

• 请求参数 NextToken：上一次调用返回的翻页令牌；
• 响应字段 NextToken：如果输出超过 1 MB，会返回标识下一页的字符串；若没有更多页则为 null。

AWS CLI 在底层会自动处理分页，但在某些场景（例如配合脚本逐页拉取）你需要手动使用令牌。此时更推荐直接使用 CLI 的内置分页参数 --max-items 与 --next-token，或者干脆依赖 CLI 的 --page-size 控制单次请求的页大小。

值得一提的是，当前仓库的 paginators-1.json（第 63–67 行）将 ListStacks 注册为可自动分页操作：

"ListStacks": {
  "input_token": "NextToken",
  "output_token": "NextToken",
  "result_key": "StackSummaries"
}

这意味着默认情况下，CLI 会使用 NextToken 自动翻页，把 StackSummaries 聚合返回，你不需要手动拼接每一页结果。这在栈数量超过单页上限时尤其省心。

六、与 describe-stacks 的分工：该用哪个？

list-stacks 和 describe-stacks 容易混淆，两者的核心区别是：

维度	list-stacks	describe-stacks
返回粒度	全部栈的摘要（数组）	单个（或多个）栈的完整详情
过滤方式	--stack-status-filter 按状态过滤	--stack-name 指定栈名
是否含 Outputs/Parameters	不含	含（若栈定义/产生了这些信息）
是否返回已删除栈	是（90 天内）	否（主要针对现存栈）
典型场景	批量巡检、状态概览、生命周期统计	查看某栈的输出值、标签、能力声明等细节

仓库中的 describe-stacks.rst 给出了对照示例：aws cloudformation describe-stacks --stack-name myteststack 返回的是一个包含 Stacks 键的 JSON 对象，其中能看到 Tags、Outputs（如 S3 桶输出的 BucketName 和 BucketValue）、Capabilities、DisableRollback 等 list-stacks 中不存在的字段。

推荐的组合拳：

# 第一步：用 list-stacks 找出所有创建成功的栈名
aws cloudformation list-stacks --stack-status-filter CREATE_COMPLETE

# 第二步：对感兴趣的栈，用 describe-stacks 查看输出值等细节
aws cloudformation describe-stacks --stack-name myteststack

这种"先列表、后详查"的两段式流程，是云资源巡检脚本中最常见的模式。

七、进阶：结合 jq 与文本输出做自动化巡检

7.1 仅提取栈名

aws cloudformation list-stacks --stack-status-filter CREATE_COMPLETE \
  --query "StackSummaries[].StackName" --output text

--query（基于 JMESPath）可以精确投影字段；--output text 让每个值各占一行，便于后续管道处理。注意这里的 StackSummaries 就是分页器定义中的 result_key，也是输出 JSON 数组对应的键名。

7.2 只列出最近创建的 5 个栈

aws cloudformation list-stacks --stack-status-filter CREATE_COMPLETE \
  --query "StackSummaries[0:5].{Name:StackName,Status:StackStatus,Created:CreationTime}" \
  --output table

7.3 输出到文件留档

aws cloudformation list-stacks --stack-status-filter CREATE_COMPLETE \
  --output json > stacks-snapshot.json

八、约束与适用前提

• 区域维度：list-stacks 按当前生效的区域（Region）查询，不跨区域聚合。如需多区域巡检，应循环遍历区域参数（如 --region us-east-1）。
• 账号维度：只返回当前凭证对应账号下的栈。
• 删除保留期：已删除栈的摘要仅保留 90 天，超出后无法再通过本命令查询。
• 数据依据：以上字段与取值均来自当前仓库的 service-2.json 与 paginators-1.json，与 AWS 官方 API 文档一致，可直接作为脚本开发的参考依据。

结语

aws cloudformation list-stacks --stack-status-filter CREATE_COMPLETE 虽是一行命令，背后却连接着服务模型的字段定义、状态机枚举与分页机制。掌握它的状态过滤语义与"只返回摘要"的特性，就能在日常巡检中精准定位失败栈、追踪进行中的变更，并与 describe-stacks 配合形成完整的两段式排查链路。更多 CloudFormation 栈操作示例（创建、更新、删除、变更集、等待器等），可继续浏览仓库的 awscli/examples/cloudformation 目录。