pulumi-context-api

Pulumi Context API でクエリする

Context API は、組織のクラウドインフラストラクチャについて、何が存在するか、何が何に依存しているか、変更によって何が影響を受けるかといった質問に、グラフとして回答します。Pulumi Discovery を通じて検出されたリソースを対象としており、Pulumi が管理するリソースだけに限りません。

関係性を含む質問では、Resource Search よりこちらを優先してください。Resource Search は個々のリソースを見つけますが、エッジをたどることはできません。そのため、「X に依存しているものは何か」に繰り返し検索して答えるのは遅く、通常は不完全です。

Enterprise エディションおよび Business Critical エディションの組織を対象としたパブリックプレビューです。また、resources:search を許可するロールが必要です（デフォルトの Member ロールと Admin ロールにはこの権限があります）。

まず、セッションにグラフツールがすでにあるか確認します

ある場合は、サーバーが登録したプレフィックスにかかわらず、graph_query と get_graph_schema を呼び出し、手順 1 と 2 はスキップします。graph_query ツールの説明には文法が記載されているので、その内容に基づいてセレクターを作成してください。ツールが組織と認証情報を自動的に解決し、ページネーションも最後まで処理します。説明だけでは不十分な場合、get_graph_schema は現在のフィールド名と制限を返し、要求すれば手順 1 の概要もすべて提供します。結果をどう扱うかについては、引き続き手順 3 に従ってください。

手順 1 と 2 は、シェルを利用できるものの、そのようなツールがないエージェント向けの手順です。

手順 1：必ず概要を取得する

Pulumi CLI v3.243.0 以降と、アクティブな pulumi login が必要です。

pulumi api GetGraphQuerySchema --output=markdown

これにより、セレクターの作成に必要な情報をまとめたガイドが返されます。用語、エッジの種類、エンジンの上限、具体的な例、ページネーション、完全性のルール、クエリが拒否される条件、そしてエラーではなく確信を持った誤答につながる落とし穴が含まれています。このガイドは、クエリに応答するデプロイから提供されるため、正式な仕様であり、スキーマのバージョンに応じて内容が変わります。このスキルはガイドを取得するための準備を行い、そこで終わります。以下の内容はすべてガイドに従ってください。セッションごとに最新のものを取得してください。以前のセッションで記憶したガイドには、現在のデプロイが提供していないスキーマが記載されている可能性があります。

この操作では組織を指定しません。ログインからアクセスできるすべての組織で、同じスキーマが使われます。この操作に --output=json を指定すると、同じ仕様が機械可読な形式で返されます。limits や fieldValues をプログラムから読み取る場合に便利ですが、セレクターの作成には Markdown を使ってください。

全文を読み、head、tail、バイト数の上限を使って途中で切り詰めないでください。 概要が途中で切れていると、セレクターが不正になり、クエリが拒否されます。

この呼び出しが失敗した場合

まだ概要を取得できていないため、ほかの場所で検索するのではなく、ここで対処してください。

応答	意味
401 Unauthorized	アクティブな pulumi login がない、またはトークンの有効期限が切れています
404 Not Found（詳細なし）	パスが間違っているか、デプロイにエンドポイントがありません
503 Service Unavailable	一時的なエラーです。再試行してください

利用権限のゲートは組織ごとに適用されるため、この呼び出しでは発生しません。ゲートは手順 2 で表面化します。その時点では、「拒否される場合」の表を含む概要をすでに取得しています。pulumi api が GetGraphQuerySchema 自体を認識しない場合、これは利用権限の問題ではありません。pulumi api list --refresh-spec を実行してキャッシュ済みの仕様を更新し、取得を再試行してください。

手順 2：クエリする

pulumi api GraphQuery -F orgName=<org> --input selector.json

本文はクエリテキストではなく、JSON セレクターです。記憶や別のセッションで見た文法ではなく、直前に読んだ概要に基づいて作成してください。

組織名を明示してください。省略すると、-F orgName は選択中のスタックまたはデフォルトの組織から解決されますが、デフォルトが利用権限のない個人アカウントであることもよくあります。pulumi whoami -v では、ログインからアクセスできるすべての組織を確認できます。ここで拒否された場合は、拒否理由となったゲートが示されます。「拒否される場合」の表を確認し、再試行する価値があるものと、ユーザーに報告すべきものを判断してください。

ステップ 3：回答する前に、プライマーの完全性に関するルールを適用します

すべての回答には、現在は meta.resultMode、 meta.visibility、pageInfo.continuationToken という忠実性を示す情報が含まれています。プライマーには、信頼できる情報のセットが記載されています。それらに関するルールを読み、従ってください。各情報への対処方法は異なるため、ここで古い内容を言い換えるくらいなら、何も書かないほうがよいでしょう。

最も重要なのは、完全性を主張するには、すべてが正しい状態である必要があるということです。影響分析、「これに依存するものはありません」という記述、網羅的なクリーンアップ一覧、グループ全体の合計値のいずれも、結果の切り詰め、探索の省略、ページの未取得があれば成り立ちません。そこまで確認できない場合は、回答がどこまでを対象としているかを明記してください。

グラフの対象範囲

リソース、スタック、それらの関係を、呼び出し元が参照できるスタックとアカウントに絞ったものです。回答できない内容の現時点での境界は、プライマーの「現時点で回答できないこと」セクションに記載されています。質問に回答できないと結論付ける前に確認し、グラフクエリでその不足を近似するのではなく、別の API を使用してください。

事前に知っておくべき境界のうち、使用する API を左右するものが 1 つあります。グラフが返すのは、各ノードタイプについてスキーマで定義されたフィールドの一部であり、リソースのプロパティ一式ではありません。各ノードタイプで照合できるフィールドと返却できるフィールドは、プライマーに記載されています。プロパティの値そのものが必要な質問の場合は、Resource Search から取得してください。

人間が読みやすい参考資料： Context API の概要と クエリガイド。