mcpField
P
pulumi-debug-failed-operation

pulumi-debug-failed-operation

github.com/pulumi云与 DevOps78361 次安装3 周前更新
代码仓库

关于 pulumi-debug-failed-operation

用于诊断并修复失败的 Pulumi 更新或预览。它帮助 Pulumi 用户确认目标操作、检查已记录的诊断信息，并将问题定位到代码、状态或环境后进行针对性修复。

主要功能

  1. 01确认目标操作和堆栈
  2. 02读取更新或预览诊断记录
  3. 03追踪错误对应的资源与原因
  4. 04将修复归类为代码、状态或环境问题
  5. 05针对根因进行最小修改

适用场景

  1. 01调查失败的 Pulumi 更新
  2. 02根据引擎事件诊断失败的预览
  3. 03区分资源代码错误与状态漂移
  4. 04定位凭据、权限或配额问题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/pulumi/agent-skills --skill pulumi-debug-failed-operation

安装后在 Claude Code 中输入/pulumi-debug-failed-operation确认已加载。

附带文件agents/openai.yamluse_cases.yaml

详细介绍

调试失败的 Pulumi 操作

某个 Pulumi 操作失败了。找出失败原因并修复它。用户通常会指出要调试的操作，因此先确定要调试的是哪个操作，并在进行其他操作之前向用户确认。操作失败时，Pulumi 已记录错误；确定操作后，你可以直接从记录中读取错误，无需再次运行任何操作。

以下命令通过 pulumi api 访问 Pulumi Cloud。pulumi api 是 Pulumi CLI 的子命令，可在 shell 中运行。每条命令都会针对你传入的显式 {orgName}/{projectName}/{stackName} 路径指定的堆栈，因此即使本地未选中该堆栈，你也可以读取其记录。稍后应用修复时，才需要选中该堆栈。

从用户提供的操作开始

用户通常会提供一组操作字段：组织、项目、堆栈和更新版本（或预览 ID）——通常会在描述中提及，例如“调试 vvm-dev 的第 161 次更新”。你需要这些信息来调用 API：{orgName}、{projectName}、{stackName}，以及版本或预览 ID。

根据上下文补全缺失字段。从当前选中的堆栈（pulumi stack --show-name、pulumi stack ls）或 Pulumi.yaml 中获取组织、项目或堆栈。缺少版本号时，使用该堆栈最近的一次更新。

在继续读取记录之前，简要确认你找到的操作、其版本或预览 ID，以及对应的堆栈。简单确认即可；用户已经告诉过你这些信息。

读取失败信息

失败的更新和失败的预览都会记录引擎事件，错误信息包含在这些事件的诊断消息中。使用上面确定的字段获取事件，并提取其中的消息。

对于失败的更新，使用带版本号的 update 路径：

pulumi api /api/stacks/{orgName}/{projectName}/{stackName}/update/<version>/events \
  | jq -r '.events[].diagnosticEvent | select(. != null) | "[\(.severity)] \(.message)"' \
  | sed 's/<{%reset%}>//g'

对于失败的预览，使用带预览 ID 的 preview 路径：

pulumi api /api/stacks/{orgName}/{projectName}/{stackName}/preview/<preview-id>/events \
  | jq -r '.events[].diagnosticEvent | select(. != null) | "[\(.severity)] \(.message)"' \
  | sed 's/<{%reset%}>//g'

读取每条消息，而不只是标记为 severity == "error" 的消息。提供程序错误带有该 error 标签；但程序错误（预览失败的常见原因）会作为标准错误诊断消息出现，标记为 info#err。末尾的 sed 会去掉 Pulumi 嵌入文本中的终端颜色代码，否则这些代码会显示为 <{%reset%}>。

找出原因及应在哪里修复

一次操作可能会因多个资源而失败，因此请先阅读所有诊断信息，再逐一处理每个错误。将每个错误追溯到引发它的资源（其 URN 和类型）、程序中声明该资源的位置，以及传递给它的输入。

错误文本会告诉你问题的类型，并由此指出应在哪里修复。Pulumi 修复分为三种，确定正确的位置可以避免修改根本没有问题的代码。

  • 程序。 代码有误：引用错误、类型错误、提供程序拒绝的输入，或在值解析完成前就使用了该值。这通常是失败的预览会报告的问题，因为计划无法构建。编辑代码来修复。
  • 状态。 代码正确，但存储的状态与实际云资源不一致。使用 pulumi refresh 协调偏差；对于状态之外已存在的资源，使用 pulumi import 纳入管理，而不是重新创建。请注意，应用操作在中途失败时，可能已经更改了某些资源，因此在决定之前请检查当前状态。
  • 环境。 问题出在 Pulumi 之外：凭据、权限、OIDC 或配额。请修复角色、ESC 环境，或提供程序拒绝的容量，而不是修改资源代码。

如果诊断信息为空或过于简略，无法据此采取行动，真正的错误通常不在记录中，而在该资源调用的程序的日志里。请到那里查看。如果你没有访问权限（例如缺少令牌、无法访问某次运行，或遇到 not-found），请停止并告知用户你受阻之处，以及你需要他们提供的唯一信息。

修复原因

做出能解决根本原因的最小更改。如何确认修复，以及如何交付修复（无论是本地修改还是拉取请求），都应遵循当前模式的工作流，而不是本技能的要求。

如果用户没有说明是哪次操作

如果用户没有提供任何线索，请调试该堆栈上最近一次操作。更新列表不会记录每次更新由谁运行，因此请通过 API 查找：

  1. 运行 pulumi whoami，获取当前用户的登录名。
  2. 使用 pulumi api /api/stacks/{orgName}/{projectName}/{stackName}/updates/latest 读取最新更新及其发起者，并将其 requestedBy.githubLogin 与第 1 步获取的登录名进行比较。
  3. 如果匹配，该更新就是要调试的操作。如果不匹配，则每次回退一个版本，运行 pulumi api /api/stacks/{orgName}/{projectName}/{stackName}/updates/<n>，直到 requestedBy.githubLogin 与用户匹配。

告诉用户你找到的是哪次操作、其版本、类型和结果，并在继续之前确认这就是他们所指的操作。

评论

支持 Markdown