AWS CLI 深入实战用aws cloudformation list-stacks高效查询与过滤 CloudFormation 栈【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli导读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.jsonListStacks操作位于该文件第 1071–1083 行该命令的官方语义是返回状态与指定StackStatusFilter匹配的栈的摘要信息。已删除栈的摘要信息会在删除后保留 90 天。如果未指定StackStatusFilter则返回所有栈的摘要信息包括现存栈与已删除栈。这带来两个关键推论也是使用时的两个坑默认返回包含已删除栈如果不对状态做过滤输出里会混入 90 天保留期内的DELETE_COMPLETE栈日常巡检时容易被幽灵栈干扰。只返回摘要不返回细节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结构可以看到每个栈摘要对象可能包含以下字段字段类型说明StackIdstring栈的唯一标识符ARN 形式StackNamestring栈的名称必填字段TemplateDescriptionstring创建该栈所用模板的 Description 描述CreationTimedatetime栈的创建时间必填字段LastUpdatedTimedatetime栈的最后更新时间仅当栈至少更新过一次时返回DeletionTimedatetime栈的删除时间StackStatusstring栈的当前状态必填字段StackStatusReasonstring与栈状态关联的成功/失败消息ParentIdstring嵌套栈场景下直接父栈的 StackIdRootIdstring嵌套栈场景下最顶层根栈的 StackIdDriftInformationobject栈实际配置与模板期望配置是否发生漂移drift的摘要LastOperationsobject最近对该栈执行过的操作信息实战提示示例输出里的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-stacksdescribe-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 table7.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 目录。【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考