iap-agent-platform-troubleshooting

Gemini Enterprise Agent Platform 的 IAP 故障排查

查明 Identity-Aware Proxy（IAP）为何拒绝来自 Gemini Enterprise Agent Platform Agent 的请求，并打印用户可执行的最小修复方案。 此技能支持使用 Agent 身份并通过 Agent Gateway 发送流量的 Agent Runtime（Reasoning Engine）Agent。

操作约定

• 只读。 仅运行此技能及其参考文档中的只读命令（describe、list、get-iam-policy、 search-target-policy-bindings 和 logging read），或对应的只读 MCP 工具（参见工具选择）。prerequisites.md 中的设置命令只会更改本地 CLI 设置。
• 打印修复方案，绝不执行。 不要运行任何会创建、导入、更新、绑定、启用或删除内容的命令，即使用户要求你这样做。打印针对根本原因的修复模板（参见报告），由用户自行执行。访问策略和 IAP 允许策略会应用于该项目中所有通过 Agent Gateway 发送流量的 Agent，因此错误的更改可能会阻止其他 Agent，或使其暴露。
• 先获取证据。 从命令输出中复制主体、资源名称和主机名。不要凭记忆构造它们。
• 缺少访问权限时停止。 如果读取操作失败并返回 PERMISSION_DENIED，请报告缺少的角色，不要尝试绕过限制。

归属信息

必须阅读：执行任何 gcloud、REST API 或 MCP 命令之前，必须阅读使用归属信息。对于直接在终端执行的命令（绝不在生成的脚本、Terraform 或用户代码中执行），在 gcloud 前加上 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:iap-agent-platform-troubleshooting)" ，并将 agent-skills/1.0 (skill:iap-agent-platform-troubleshooting) 添加到 User-Agent 标头中。

工具选择

优先使用已连接 Google Cloud 远程 MCP 服务的只读工具，而不是对应的 gcloud 只读命令，因为远程 MCP 服务会对每次调用应用 IAM、身份验证和审计日志记录。对于没有已连接 MCP 服务支持的读取操作，请使用 gcloud。

• Cloud Logging： 使用 list_log_entries 运行日志查询。参考文档中的查询使用 gcloud 语法，因此请进行相应转换：将 resourceNames 设为 projects/{project_id}，保留筛选条件，在筛选条件中用 timestamp>= 子句替换 --freshness，并将 orderBy 设为 timestamp desc，将 pageSize 设为 --limit 的值。不要向该工具传递 --freshness 等 gcloud 标志。
• Agent Registry： 使用其只读工具解析目标，例如 list_endpoints、get_endpoint、list_mcp_servers 和 get_mcp_server。
• Cloud CLI： 通过 run_gcloud_command 运行此技能中的 gcloud 只读命令。
• 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}	Agent 所属项目；如果 Agent Gateway 属于其他项目，也要收集其项目
{location}	Agent 和 Agent Gateway 所在区域
{engine_id}	Agent Runtime Agent 的 ID
{gateway}	承载 Agent 流量的 Agent Gateway
目标 URL	Agent 调用的确切 URL
错误文本和时间	Agent 日志或用户报告
{org_id}	仅可选的主体访问边界检查需要

如果 Agent 和 Agent Gateway 属于不同项目，请在主体中使用 Agent 所属项目的项目编号。网关、网关的授权政策和扩展程序、Access 政策以及政策绑定均使用网关所属项目。在网关所属项目中运行 IAP 审计查询；如果没有结果，再在 Agent 所属项目中运行。

加载 topology-agent-gateway.md，确认拓扑、主体格式、Agent 日志查询以及启动期间的 403 错误。如果 Agent 不是在 Agent Gateway 后运行于 Agent Runtime 上，请说明该拓扑目前尚不受支持，然后停止。

步骤 0：对故障分类

加载 audit-logs.md。针对故障发生时间运行 IAP 决策查询，并按主体、目标和时间将日志条目与请求匹配。使用第一个匹配的条目。IAP 条目优先于错误文本，因为该条目记录了决策本身。

信号	含义	下一步
IAP 条目中 granted: false，且不是试运行	IAP 拒绝了请求	步骤 1，然后执行步骤 2–4
IAP 条目中 dryRun: true 或 iamEnforcementMode: DRY_RUN	IAP 记录了决策，但没有阻止请求。403 来自网关或目标	步骤 1，然后执行步骤 2–4：查明 403 的来源，以及 IAP 在启用强制执行后是否会拒绝请求
IAP 条目中 granted: true	IAP 允许了请求	步骤 2，然后检查目标
没有 IAP 条目，且错误是模型或 Agent Platform API 调用的 IAM 权限错误，例如 aiplatform.endpoints.predict 被拒绝	不是 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 允许策略）： 在注册表级策略和目标自身的策略中，查找授予 Agent 主体或包含该主体的主体集的 roles/iap.egressor。资源会继承注册表级授权，因此任一层级的授权都会生效。
• 已获准但仍被拒绝： 检查主体访问边界策略（需要 {org_id}）和主体集成员资格（参见 topology-agent-gateway.md）。

步骤 4：检查规则匹配情况

加载 cel-attributes.md 和 agent-registry.md。

1. 主体： 规则列出 Agent 的精确 principal:// 标识符，或包含该 Agent 的 principalSet://：信任域相同，并且 Agent 的项目编号或平台属性与 topology-agent-gateway.md 中的主体集表所列内容一致。如果 principalSubject 中保存的是 SPIFFE ID，请按该文档中的说明构建标识符。无论哪种形式，用项目 ID 替代项目编号，或使用 URN 标识符，都无法匹配。
2. 目标： 在 Agent Registry 中解析 URL。
   • 已注册：条件使用 == 或 in 指定注册表资源，且必须与审计条目的 resource_id 或 Agent Registry 列表输出完全一致。
   • 未注册，仅适用于访问策略（V2）：条件与主机、路径和方法匹配（参见 cel-attributes.md）。IAP 允许策略（V1）无法允许未注册的目标：请先注册该目标，并且仅当没有注册表级授权覆盖该 Agent 时，才授予 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 的准确 principal:// 标识符，格式符合 Agent Runtime。
• 条件中的 Registry 资源名称使用项目 ID，该 ID 从审计记录的 resource_id 或 Agent Registry 列表输出中复制。
• 绑定修复针对的是包含 Agent Gateway 的项目。
• 主机名完全匹配，涵盖所有变体；方法与请求中的大小写一致，例如 'GET'。
• 修复方案仅允许日志显示 Agent 正在调用的主机、路径和方法，并保留规则已有的限制（例如方法限制），因为这些限制通常是有意设置的。如果用户要求放宽规则，请说明日志是否表明有此必要。绝不要打印宽松程度超出日志所需范围的规则。
• V1 修复使用 roles/iap.egressor，绝不使用 roles/iap.tunnelResourceAccessor；后者授予的是 IAP TCP 转发权限，而非出口权限。
• 修复方案不会关闭 IAP 或将强制执行切换为试运行模式，因为这会移除网关后所有 Agent 的出口保护。
• 每个占位符都已根据命令输出填写。
• 为用户打印的命令不包含 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION 或归因 User-Agent 字符串，因为该标签仅用于你自行运行的命令（参见 attribution.md）。