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 CLI のサブコマンドである pulumi api を使用して Pulumi Cloud にアクセスします。各コマンドは、指定した {orgName}/{projectName}/{stackName} のパスでスタックを対象にするため、記録を読む際に、そのスタックをローカルで選択しておく必要はありません。修正を適用するときには、スタックの選択が必要になります。

ユーザーが指定した操作から始める

通常、ユーザーは組織、プロジェクト、スタック、更新バージョン（またはプレビュー ID）などのフィールドを操作の情報として提示します。多くの場合、「vvm-dev の update 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 が付いた stderr 診断として出力されます。末尾の sed は、Pulumi がテキストに埋め込むターミナルのカラーコードを取り除きます。取り除かない場合、カラーコードは <{%reset%}> のように表示されます。

原因と修正箇所を特定する

1 つの操作で複数のリソースからエラーが発生することがあるため、まずすべての診断情報を読み、その後、各エラーに順に対処してください。各エラーを、エラーを発生させたリソース（その URN と型）、プログラム内でそのリソースが宣言されている箇所、そしてそのリソースに渡される入力までたどります。

エラーテキストから問題の種類が分かり、修正箇所を特定できます。Pulumi での修正箇所は次の 3 つのいずれかです。正しい箇所を特定すれば、問題ではなかったコードを編集せずに済みます。

  • プログラム。 コードに誤りがあります。参照先の誤り、型の誤り、プロバイダーに拒否された入力、または値が確定する前に使用されたケースなどです。通常、プレビューが失敗した場合はこれが報告されます。プランを構築できなかったためです。コードを編集して修正してください。
  • 状態。 コードは正しいものの、保存された状態と実際のクラウドリソースに食い違いがあります。pulumi refresh でドリフトを調整し、状態の管理対象外で既に存在するリソースは、再作成するのではなく pulumi import で管理対象にします。適用の途中で失敗した操作によって、一部のリソースが既に変更されている場合があるため、判断する前に現在の状態を確認してください。
  • 環境。 問題は Pulumi の外部にあります。認証情報、権限、OIDC、またはクォータが原因です。リソースのコードではなく、ロール、ESC 環境、またはプロバイダーに拒否された容量を修正してください。

診断情報が空か、対処するには不十分な場合、実際のエラーは通常、その記録ではなく、リソースがシェルから呼び出したもののログにあります。そちらを確認してください。アクセスに必要なもの（トークン、実行、見つからないリソースなど）が手元にない場合は作業を止め、何が障害になっているかと、ユーザーから必要なものを 1 つ伝えてください。

原因を修正する

根本原因に対処する、最小限の変更を行ってください。修正の確認方法と、ローカルでの編集またはプルリクエストのどちらで変更を届けるかは、このスキルではなく、現在のモードのワークフローに従ってください。

ユーザーが操作を指定していない場合

ユーザーから手がかりがない場合は、スタックで最後に実行された操作をデバッグします。更新一覧には各更新を実行したユーザーが記録されていないため、API で確認してください。

  1. pulumi whoami を実行して、現在のユーザーのログイン名を取得します。
  2. 次のコマンドで最新の更新とその実行を要求したユーザーを確認し、requestedBy.githubLogin を手順 1 で取得したログイン名と比較します。
    pulumi api /api/stacks/{orgName}/{projectName}/{stackName}/updates/latest
  3. 一致した場合は、その更新をデバッグします。一致しない場合は、次のコマンドでバージョンを 1 つずつさかのぼり、requestedBy.githubLogin がユーザーと一致するまで確認します。
    pulumi api /api/stacks/{orgName}/{projectName}/{stackName}/updates/<n>

対象となった操作、そのバージョン、種類、結果をユーザーに伝え、先へ進む前にその操作で間違いないか確認してください。

コメント

Markdown 対応