iap-agent-platform-troubleshooting

Gemini Enterprise Agent Platform の IAP トラブルシューティング

Gemini Enterprise Agent Platform エージェントからのリクエストが Identity-Aware Proxy（IAP）によって拒否される理由を調べ、ユーザーが実行する最小限の修正を表示します。 このスキルは、エージェント ID を使用し、Agent Gateway 経由でトラフィックを送信する Agent Runtime（Reasoning Engine）エージェントをサポートします。

運用上の契約

• 読み取り専用です。 このスキルおよびその参照先に記載されている読み取りコマンド（describe、list、get-iam-policy、search-target-policy-bindings、logging read）、または対応する読み取り専用 MCP ツール（ツールの選択を参照）のみを実行してください。prerequisites.md に記載されているセットアップコマンドは、ローカルの CLI 設定のみを変更します。
• 修正方法を表示するだけで、実行しないでください。 ユーザーに頼まれても、何かを作成、インポート、更新、バインド、有効化、削除するコマンドは実行しないでください。根本原因に対する修正テンプレートを表示し（報告を参照）、実行はユーザーに任せてください。アクセス ポリシーと IAP の許可ポリシーは、そのプロジェクトで Agent Gateway 経由のトラフィックを送信するすべてのエージェントに適用されます。そのため、誤った変更を行うと、ほかのエージェントがブロックされたり、公開されたりする可能性があります。
• 証拠を優先してください。 プリンシパル、リソース名、ホスト名は、コマンド出力からコピーしてください。記憶を頼りに作成しないでください。
• アクセスできない場合は中止してください。 読み取りに PERMISSION_DENIED が発生した場合は、不足しているロールを報告し、回避策を試さないでください。

利用状況の帰属

必ずお読みください：gcloud、REST API、MCP の各コマンドを実行する前に、利用状況の帰属を必ずお読みください。ターミナルで直接実行するコマンド（生成スクリプト、Terraform、ユーザーコード内での実行は不可）では、gcloud の前に CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:iap-agent-platform-troubleshooting)" を付け、User-Agent ヘッダーに agent-skills/1.0 (skill:iap-agent-platform-troubleshooting) を追加してください。

ツールの選択

接続済みの Google Cloud リモート MCP サーバーの読み取りツールは、対応する gcloud の読み取りコマンドより優先して使用してください。リモート MCP サーバーは、すべての呼び出しに IAM、認証、監査ログを適用するためです。接続済みの MCP サーバーでカバーされない読み取りには gcloud を使用してください。

• Cloud Logging： list_log_entries でログクエリを実行してください。参照先のクエリは gcloud の構文を使用しているため、各クエリを適宜変更します。resourceNames に projects/{project_id} を設定し、フィルターはそのまま使用し、--freshness をフィルター内の timestamp>= 句に置き換え、orderBy を timestamp desc に、pageSize を --limit の値に設定してください。--freshness などの gcloud フラグをツールに渡さないでください。
• Agent Registry： list_endpoints、get_endpoint、list_mcp_servers、get_mcp_server などの読み取りツールで、宛先を特定してください。
• Cloud CLI： このスキル内の gcloud による読み取りは、run_gcloud_command で実行してください。
• IAP、Agent Gateway、認可ポリシー： これらを扱うリモート MCP サーバーはありません。そのため、gcloud を直接、または Cloud CLI MCP サーバー経由で使用して読み取ってください。

読み取り専用の契約は MCP ツールにも適用されます。create_binding や delete_service など、何かを作成、更新、削除するツールは呼び出さないでください。

前提条件

Google Cloud CLI がインストールされ、{project_id} に対して認証されている必要があります。まだの場合、または読み取りで PERMISSION_DENIED や API の無効化エラーが発生した場合は、prerequisites.md を読み込んでください。gcloud auth login、API、読み取り専用ロール、課金、デフォルト リージョン（us-central1）について記載されています。診断によってリソースが作成されることはないため、クリーンアップは不要です。

必要なコンテキスト

以下の値を収集してください。不足しているものがあれば、ユーザーに確認してください。

値	入手元
{project_id}, {project_number}	エージェントのプロジェクト。ゲートウェイが別のプロジェクトにある場合は、そのプロジェクト
{location}	エージェントと Agent Gateway のリージョン
{engine_id}	Agent Runtime エージェントの ID
{gateway}	エージェントのトラフィックを処理する Agent Gateway
宛先 URL	エージェントが呼び出した正確な URL
エラーテキストと発生時刻	エージェントのログまたはユーザーの報告
{org_id}	オプションのプリンシパルアクセス境界の確認にのみ必要

エージェントと Agent Gateway が別のプロジェクトにある場合、プリンシパルにはエージェントのプロジェクト番号を使用してください。ゲートウェイ、その認可ポリシーと拡張機能、Access ポリシー、ポリシーバインディングには、ゲートウェイのプロジェクトを使用してください。IAP 監査クエリはゲートウェイのプロジェクトで実行し、結果がなければエージェントのプロジェクトでも実行してください。

トポロジーエージェントゲートウェイを読み込み、トポロジー、プリンシパルの形式、エージェントログのクエリ、起動時の 403 エラーを確認してください。エージェントが Agent Gateway の背後で Agent Runtime 上で動作していない場合は、このトポロジーはまだサポートされていないと伝え、そこで終了してください。

ステップ 0：障害を分類する

audit-logs.mdを読み込みます。障害発生時刻の IAP 判定クエリを実行し、プリンシパル、宛先、時刻でエントリをリクエストに照合してください。一致する最初の行を使用します。エントリには判定そのものが記録されているため、IAP エントリはエラーテキストより優先されます。

シグナル	意味	次の手順
granted: false で、ドライランではない IAP エントリ	IAP がリクエストを拒否しました	ステップ 1、その後ステップ 2～4
dryRun: true または iamEnforcementMode: DRY_RUN の IAP エントリ	IAP は判定を記録しましたが、リクエストをブロックしていません。403 はゲートウェイまたは宛先から返されています	ステップ 1、その後ステップ 2～4：403 の発生元と、IAP の強制適用後にリクエストが拒否されるかどうかを特定します
granted: true の IAP エントリ	IAP はリクエストを許可しました	ステップ 2、その後、宛先を確認
IAP エントリがなく、aiplatform.endpoints.predict の拒否など、モデルまたは Agent Platform API 呼び出しに対する IAM 権限エラーがある	IAP の送信拒否ではありません	終了し、agent-platform-troubleshooting を案内します
リクエストに対する IAP エントリがない	Data Access 監査ログが無効になっているか、IAP より前にゲートウェイがリクエストを拒否しました	ステップ 1（ログの確認）、その後ステップ 2

ステップ 1：テレメトリーを確認する

1. audit-logs.mdの Data Access の確認を実行します。ログが無効になっている場合は、過去のリクエストが記録されていないことを説明し、「IAP の Data Access 監査ログを有効にする」テンプレートを出力して、ユーザーが障害を再現するまで終了してください。
2. 一致したエントリから、principalSubject、宛先、ポリシーバージョン、およびエントリに含まれている場合は CEL 評価の詳細を記録します。エントリによってレイアウトが異なるため、それぞれの値はaudit-logs.mdのフィールド表にあるフィールド名から読み取ってください。宛先は metadata.destination が存在する場合はその値であり、ゲートウェイを示すことのある authorizationInfo[].resource ではありません。
3. エントリに metadata.destination.unregistered が含まれているか、audited_resource_name が unregisteredResource または unregisteredEndpoint で終わる場合、宛先は未登録として扱います。これは、ホスト名が登録されていないか、MCP サーバーの場合は呼び出されたツールがツール仕様に含まれていないことを意味します（agent-registry.mdを参照）。ステップ 4 のために、この情報を保持してください。

ステップ 2：ゲートウェイチェーンを確認する

gateway-setup.md を読み込みます。ゲートウェイ、その認可ポリシー、認可拡張機能を確認します。

• policyProfile: REQUEST_AUTHZ を持つ認可ポリシーの target.resources にゲートウェイが記載されていない場合、拡張機能は実行されず、IAP エントリも存在しません。これが根本原因です。
• 想定している拡張機能ではなく、ポリシーが指定している拡張機能を読みます。その service は iap.googleapis.com でなければなりません。metadata.iapPolicyVersion、metadata.iamEnforcementMode、failOpen を記録します。これらによって、IAP が評価するポリシー、リクエストをブロックするかどうか、IAP の呼び出しが失敗またはタイムアウトした際にリクエストを通過させるかどうかが決まります。

ステップ 3：ポリシーとバインディングを確認する

policy-model.md を読み込み、ステップ 2 で確認したバージョンのセクションを使用します。

• V2（アクセス ポリシー）： プロジェクトまたはゲートウェイにバインドされたすべてのポリシーを読みます。いずれかのポリシーにある拒否ルールが優先され、バインディングのないポリシーは適用されないためです。
• V1（IAP 許可ポリシー）： レジストリ全体のポリシーと宛先自体のポリシーで、エージェントのプリンシパル、またはそのプリンシパルを含むプリンシパルセットに付与された roles/iap.egressor を探します。リソースはレジストリ全体の付与を継承するため、どちらかのレベルでの付与が適用されます。
• 許可されているのに拒否される場合： プリンシパル アクセス境界ポリシー（{org_id} が必要です）とプリンシパルセットのメンバーシップを確認します（topology-agent-gateway.md を参照）。

ステップ 4：ルールの一致を確認する

cel-attributes.md と agent-registry.md を読み込みます。

1. プリンシパル： ルールにエージェントの正確な principal:// 識別子、またはエージェントを含む principalSet:// が記載されていることを確認します。プリンシパルセットの表にあるとおり、信頼ドメインが同じであり、エージェントのプロジェクト番号またはプラットフォーム属性も一致している必要があります（topology-agent-gateway.md を参照）。principalSubject に SPIFFE ID が含まれる場合は、同ファイルの説明に従って識別子を作成します。どちらの形式でも、プロジェクト番号の代わりにプロジェクト ID を使った場合や、URN 識別子を使った場合は一致しません。
2. 宛先： Agent Registry で URL を解決します。
   • 登録済み：条件にはレジストリリソースが == または in で指定され、監査エントリの resource_id または Agent Registry のリスト出力と完全に一致します。
   • 未登録、かつアクセス ポリシー（V2）の場合のみ：条件がホスト、パス、メソッドに一致します（cel-attributes.md を参照）。IAP 許可ポリシー（V1）では未登録の宛先を許可できません。宛先を登録し、レジストリ全体の付与でエージェントが対象になっていない場合に限り、roles/iap.egressor を付与します。
3. 条件： V2 の場合は、監査エントリの CEL 評価の詳細を使用して、失敗した句を特定します。エントリに評価の詳細がない場合は、エントリの resource_id または unregistered の値と、条件内の各リテラルを自分で比較します。

レポート

根本原因に対応する修正手順のリファレンスだけを読み込んでください。

根本原因	読み込むファイル
Data Access の監査ログがオフになっている、または API が無効になっている	remediation-setup.md
認可ポリシーの対象にゲートウェイが含まれていない、または誤った拡張機能を呼び出している	remediation-gateway.md
Access ポリシー（V2）のルールが一致しない、または DENY ルールが一致する、バインディングがない、あるいは組織ポリシーの制約によってバインディングがブロックされている	remediation-access-policies.md
IAP 許可ポリシー（V1）の付与がない、宛先またはホスト名のバリエーションが登録されていない、あるいは MCP ツールがサーバーのツール仕様に含まれていない	remediation-registry.md

次のテンプレートを使用してください。

## Root cause
{root_cause_quoting_the_mismatched_value}

## Fix (you run this)
{why_smallest_change}
{filled_in_template}
Required role: {role}

## Wait time
{wait_time}

## Verify
- [ ] Reproduce the request.
- [ ] A new IAP audit entry shows granted: true for {principal} and {destination_url}.
- [ ] {read_command_that_confirms_the_change}

ドライランでは、IAP はまだ何もブロックしません。根本原因にはそのことを記載し、ログに記録された拒否は、強制適用した場合にブロックされるリクエストであることも記載してください。ユーザーは、強制適用する前にそのようなリクエストを見つけるためにドライランを実行します。ユーザーがリクエストを成功させる必要があり、強制適用後にポリシーで許可されない場合は、その修正を「強制適用を有効にする前に」の下に記載してください。読み取りコマンドで確認してください。ドライランのエントリにある granted の値では、ポリシーがリクエストを許可しているかどうかはわからないためです。

根本原因を一つに特定できる証拠がない場合は、確認した内容、まだ不明な点、次に実行する読み取りコマンドを列挙してください。修正は記載しないでください。

検証ループ

レポートを送信する前に、すべての項目を確認してください。一つでも満たしていない場合は、レポートを修正して再度確認してください。

• 実行したコマンドや MCP ツール呼び出しによって、リソースが変更されていません。すべての修正はユーザー向けに記載されています。
• 修正は追加的なものです。既存のバインディング、ルール、句を維持しています。
• DENY ルールが拒否の原因である場合、ブロックは意図的な可能性があるとレポートに記載し、そのルールの変更は、ルールの所有者が承認するための選択肢としてのみ提示しています。
• プリンシパルは、Agent Runtime 形式のエージェントの正確な principal:// 識別子です。
• 条件内のレジストリリソース名には、監査エントリの resource_id または Agent Registry の一覧出力からコピーしたプロジェクト ID を使用しています。
• バインディングの修正は、Agent Gateway が含まれるプロジェクトを対象としています。
• ホスト名は完全一致し、すべてのバリエーションが対象になっています。また、メソッドはリクエストで使われている大文字・小文字（例：'GET'）になっています。
• 修正で許可するのは、ログに記録されたエージェントの呼び出し先のホスト、パス、メソッドだけです。また、メソッドの制限など、ルールにすでに設定されている制限は維持しています。多くの場合、それらは意図的な設定です。ユーザーからルールを緩和するよう求められた場合は、それが必要であることをログが示しているかどうかを記載してください。ログが必要とする範囲を超えて緩いルールは、決して記載しないでください。
• V1 の修正では roles/iap.egressor を使用し、IAP TCP 転送を許可するものの、エグレスは許可しない roles/iap.tunnelResourceAccessor は使用していません。
• IAP をオフにしたり、強制適用をドライランに切り替えたりする修正はありません。これらの変更は、ゲートウェイ配下のすべてのエージェントからエグレス保護を取り除くためです。
• すべてのプレースホルダーにコマンド出力の値が入力されています。
• ユーザー向けに記載するコマンドには、CLOUDSDK_METRICS_REQUEST_ATTRIBUTION やアトリビューション用の User-Agent 文字列が含まれていません。このタグは自分で実行するコマンド専用です（attribution.md を参照）。