通过 Gemini Enterprise Agent Platform 私密访问 Apigee

本页面适用于 Apigee，但不适用于 Apigee Hybrid。

查看 Apigee Edge 文档。

本文档介绍了如何使用 Private Service Connect，将部署在 Gemini Enterprise Agent Platform 代理运行时上的代理与发布在 Apigee 上的 API 和 Model Context Protocol (MCP) 工具配置为专用连接。 采用此模式后，从代理到 Apigee 的流量将完全保持私密，不会通过公共互联网。

概览

Agent Runtime 会将您的代理部署在由 Google 管理的安全网络中，该网络无法访问您的虚拟私有云 (VPC) 网络。Apigee 同样在安全的 Google 管理的网络中运行。如果您希望代理对大语言模型 (LLM) 或通过 Apigee 公开的 MCP 工具的调用以私密方式进行，则需要通过您控制的 VPC 网络来桥接这两个 Google 管理的网络。

本文档介绍了该网桥的以下模式：

在此配置中，当您的代理调用 https://APIGEE_HOSTNAME/... 时，请求会解析为 VPC 中的 Private Service Connect 端点 IP，通过服务连接转发到您的 Apigee 实例，并由与请求路径匹配的 API 代理进行处理。

准备工作

本文档在命令中使用以下占位符。请将它们替换为您环境中的值。

  • APIGEE_PROJECT_ID：包含 Apigee 组织的 Google Cloud 项目 ID。
  • SERVICE_PROJECT_ID：您在 Agent Runtime 上部署智能体的 Google Cloud 项目 ID。此项目可以与 APIGEE_PROJECT_ID 相同，也可以是其他项目，具体取决于您如何整理 Google Cloud 资源。
  • SERVICE_PROJECT_NUMBER：SERVICE_PROJECT_ID 的数字项目编号。您可以使用 gcloud projects describe SERVICE_PROJECT_ID --format="value(projectNumber)" 检索该值。
  • HOST_PROJECT_ID：包含消费者 VPC 网络、子网和 Cloud DNS 私有区域的 Google Cloud 项目 ID。这与 SERVICE_PROJECT_ID 相同，除非您使用的是共享 VPC，在这种情况下，这是服务项目所附加到的宿主项目。
  • REGION：Apigee 实例所在的区域（例如 us-west1）。
  • VPC_NAME：HOST_PROJECT_ID 中使用方 VPC 网络的名称。
  • SUBNET_NAME：位于 REGION 中的 VPC_NAME 内的子网的名称。
  • APIGEE_HOSTNAME：您在 Apigee 环境组中配置的主机名（例如 api.internal.example.com）。
  • BASE_PATH：部署在 Apigee 上的 API 代理的基本路径（例如 /mcp 或 /orders）。
  • PARENT_DNS_NAME：您希望从专用区域提供服务的 APIGEE_HOSTNAME 的父 DNS 网域（例如 internal.example.com.）。该值必须以英文句点结尾。
  • APIGEE_INSTANCE_NAME：REGION 中 Apigee 实例的名称。

您需要具备以下条件：

  • 一个或多个启用了结算功能的 Google Cloud 项目（如上文所述）。
  • APIGEE_PROJECT_ID 中至少有一个实例的现有 Apigee 组织。 本文档在与您的 Apigee 实例相同的区域中创建所有服务使用方网络资源（网络连接、Private Service Connect 端点、代理运行时部署），这是最简单的配置。
  • 环境已部署到相应 Apigee 实例，并且包含您希望代理调用的主机名的环境组。本文档将该主机名称为 APIGEE_HOSTNAME。
  • 至少有一个 API 代理部署到该环境组中的某个环境。您希望代理调用的任何代理都必须可在 https://APIGEE_HOSTNAME/BASE_PATH 上访问。
  • HOST_PROJECT_ID 中的 VPC 网络和子网，与 Apigee 实例位于同一区域。本文档将这些版本称为 VPC_NAME 和 SUBNET_NAME。Agent Runtime 需要至少 /28 的子网，并施加额外的范围限制。如需了解详情，请参阅 Agent Platform 文档中的子网 IP 范围要求。
  • 在相应项目中启用以下 API：
    • APIGEE_PROJECT_ID 中的 Apigee (apigee.googleapis.com)。
    • HOST_PROJECT_ID 中的 Compute Engine (compute.googleapis.com) 和 Cloud DNS (dns.googleapis.com)。
    • SERVICE_PROJECT_ID 中的 Agent Platform (aiplatform.googleapis.com)。
  • 在 HOST_PROJECT_ID 中创建 Cloud DNS 可用区和记录、Compute Engine 地址、网络连接和 Private Service Connect 转发规则，以及在 APIGEE_PROJECT_ID 中更新 Apigee 实例和环境组配置所需的足够 IAM 权限。如需详细了解所需角色，请参阅 Apigee 角色、Cloud DNS 访问权限控制和 Compute Engine IAM 角色。

架构

以下步骤介绍了部署在 Agent Runtime 上的代理与托管在 Apigee 上的 API 代理之间的流量流，其中使用使用方 VPC 中的 Private Service Connect 端点作为桥梁。

  1. 在 Agent Runtime 上运行的智能体向 APIGEE_HOSTNAME 发出 HTTPS 请求。
  2. 在 Agent Runtime PSC 接口上配置的 DNS 对等互连会将查找转发到使用方 VPC 中的 Cloud DNS 专用区域，该区域会返回 Private Service Connect 端点的 IP 地址。
  3. 代理的请求通过 PSC 接口流出到您的使用方 VPC，并到达该 IP 地址上的 Private Service Connect 端点。
  4. Private Service Connect 端点通过服务连接将请求转发到 Apigee 实例的服务连接。
  5. Apigee 实例终止 TLS，将请求主机名与环境组进行匹配，然后路由到正确的 API 代理。

第 1 步：在使用方 VPC 中配置网络

此部分配置了两个项目中的资源。每个命令都包含一个明确的 --project 标志，因此您可以从任何有效的 gcloud 配置运行这些命令：

  • Cloud DNS 资源（专用可用区和记录）是在 HOST_PROJECT_ID 中创建的，因为专用可用区会附加到消费者 VPC 网络。
  • Private Service Connect 端点资源（静态内部 IP 地址和转发规则）和网络连接是在 SERVICE_PROJECT_ID 中创建的。这些命令中的每一个都使用对 HOST_PROJECT_ID 中共享子网或 VPC 网络的跨项目引用。在单项目部署中，SERVICE_PROJECT_ID 和 HOST_PROJECT_ID 是相同的，因此在各个步骤中所有权不会发生变化。如需详细了解 Private Service Connect 端点的共享 VPC 模型，请参阅在共享 VPC 服务项目中创建端点。

创建 Cloud DNS 私有区域

创建仅对使用方 VPC 可见的 Cloud DNS 专用区域。 代理使用此区域（通过 DNS 对等互连）将 APIGEE_HOSTNAME 解析为专用 IP 地址。

gcloud dns managed-zones create apigee-private \
  --project=HOST_PROJECT_ID \
  --dns-name="PARENT_DNS_NAME" \
  --description="Private zone for Apigee PSC access" \
  --visibility=private \
  --networks=VPC_NAME

如需详细了解 Cloud DNS 专用可用区，请参阅专用可用区。

创建网络连接

在您希望 Agent Runtime PSC 接口出现的同一区域和子网中创建网络连接。当代理部署时，Agent Runtime 会将其 PSC 接口绑定到此连接。

在单项目部署中，在 SERVICE_PROJECT_ID（也是 HOST_PROJECT_ID）中创建网络连接。在共享 VPC 部署中，您可以在服务项目或宿主项目中创建网络连接；Agent Platform 建议在服务项目中创建，以简化权限管理。如需有关选择和相应 IAM 角色的指南，请参阅将 Private Service Connect 接口与共享 VPC 搭配使用。

以下命令会在 SERVICE_PROJECT_ID 中创建网络连接。在共享 VPC 部署中，子网引用必须包含宿主项目 ID。

gcloud compute network-attachments create agent-network-attachment \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --subnets=projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME \
  --connection-preference=ACCEPT_AUTOMATIC

预留静态内部 IP 地址

预留一个内部 IP 地址，用作代理连接到的 Private Service Connect 端点的 IP。在 SERVICE_PROJECT_ID 中创建地址资源，并在 HOST_PROJECT_ID 中引用共享子网，以便从该子网的范围中分配地址值。这与通过共享 VPC 使用静态内部 IP 地址中的共享 VPC 指南一致。

gcloud compute addresses create apigee-psc-endpoint-ip \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --subnet=projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME

检索预留的地址，您将在后面的步骤中使用该地址： 

gcloud compute addresses describe apigee-psc-endpoint-ip \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --format="value(address)"

本文档将此地址称为 PSC_ENDPOINT_IP。

获取 Apigee 实例的服务连接

使用 Apigee API 的 organizations.instances.get 方法检索 Apigee 实例的服务连接 URI。您可以使用此 URI 作为 Private Service Connect 端点的目标。 

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://apigee.googleapis.com/v1/organizations/APIGEE_PROJECT_ID/instances/APIGEE_INSTANCE_NAME"

响应包含 serviceAttachment 字段。本文档将该值称为 APIGEE_SERVICE_ATTACHMENT。 如需详细了解 Apigee 如何在每个实例上公开服务连接，请参阅管理实例。

创建 Private Service Connect 端点

创建充当 Private Service Connect 端点的转发规则。它以 Apigee 服务连接为目标，并使用您预留的静态 IP。在 SERVICE_PROJECT_ID 中创建转发规则，并在 HOST_PROJECT_ID 中引用共享 VPC 网络和 SERVICE_PROJECT_ID 中的地址。 

gcloud compute forwarding-rules create apigee-psc-endpoint \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --network=projects/HOST_PROJECT_ID/global/networks/VPC_NAME \
  --address=projects/SERVICE_PROJECT_ID/regions/REGION/addresses/apigee-psc-endpoint-ip \
  --target-service-attachment=APIGEE_SERVICE_ATTACHMENT

验证 Apigee 服务是否接受了连接： 

gcloud compute forwarding-rules describe apigee-psc-endpoint \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --format="value(pscConnectionStatus)"

状态必须为 ACCEPTED，然后端点才能转发流量。如需详细了解 Private Service Connect 端点，请参阅通过端点访问已发布服务的简介。

为相应主机名添加 DNS 记录

在专用地区中，创建一个将 APIGEE_HOSTNAME 解析为 PSC_ENDPOINT_IP 的 A 记录。此记录仅在 VPC_NAME 内部可见，因此外部客户端会继续通过公共 DNS 解析主机名。 

gcloud dns record-sets create APIGEE_HOSTNAME. \
  --project=HOST_PROJECT_ID \
  --zone=apigee-private \
  --type=A \
  --ttl=60 \
  --rrdatas=PSC_ENDPOINT_IP

第 2 步：配置 Apigee

将服务项目添加到实例使用方接受列表

Apigee 实例仅接受来自其 consumerAcceptList 中所列使用方项目的 Private Service Connect 连接。 连接的使用方与 SERVICE_PROJECT_ID 相关联，因为这是部署代理的项目。

默认情况下，与 Apigee 组织 (APIGEE_PROJECT_ID) 关联的项目已在该列表中。如果 SERVICE_PROJECT_ID 与 APIGEE_PROJECT_ID 相同，则无需进行任何更改，您可以跳过此部分。否则，请将 SERVICE_PROJECT_ID 添加到列表中。

首先，使用 organizations.instances.get 方法检查 consumerAcceptList 的当前值：

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://apigee.googleapis.com/v1/organizations/APIGEE_PROJECT_ID/instances/APIGEE_INSTANCE_NAME"

在响应中查找 consumerAcceptList 字段。

然后，通过使用 consumerAcceptList 上的更新掩码调用 organizations.instances.patch 方法来更新列表。由于该字段会替换现有列表，因此请包含必须保留访问权限的每个项目 ID，包括 APIGEE_PROJECT_ID 和部署代理的任何其他服务项目：

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"consumerAcceptList": ["APIGEE_PROJECT_ID", "SERVICE_PROJECT_ID"]}' \
  "https://apigee.googleapis.com/v1/organizations/APIGEE_PROJECT_ID/instances/APIGEE_INSTANCE_NAME?updateMask=consumerAcceptList"

再次运行 get 命令，验证 SERVICE_PROJECT_ID 是否已包含在 consumerAcceptList 中，以确认更新。

验证环境组主机名

确认 APIGEE_HOSTNAME 列在托管 API 代理的环境组中。如果不是，请添加该字段。

如需查看相关说明，请参阅使用环境组。

第 3 步：使用 PSC 接口和 DNS 对等互连部署代理

将代理部署到 Agent Runtime 时，请使用引用您创建的网络连接的 PSC 接口对其进行配置，并配置到专用区域的 DNS 对等互连。如需了解完整的部署过程和支持的框架，请参阅 Agent Platform 文档中的将 Private Service Connect 接口与 Agent Runtime 搭配使用和部署代理。

在代理的 PSC 接口配置中配置以下两个字段（请参阅 PscInterfaceConfig 参考资料）：

  • networkAttachment：将此参数设置为您在第 1 步中创建的网络连接的完整资源名称，格式为 projects/SERVICE_PROJECT_ID/regions/REGION/networkAttachments/agent-network-attachment。 如果您是在宿主项目中创建的网络连接，请在此路径中使用 HOST_PROJECT_ID。
  • dnsPeeringConfigs：添加一个包含以下字段的条目，以便 Agent Runtime 通过您的私有区域解析 APIGEE_HOSTNAME：
    • domain：PARENT_DNS_NAME。该值必须以英文句点结尾。
    • targetProject：HOST_PROJECT_ID。这是包含使用方 VPC 和专用区域的项目。
    • targetNetwork：VPC_NAME。

SERVICE_PROJECT_ID (service-SERVICE_PROJECT_NUMBER@gcp-sa-aiplatform.) 的 Agent Platform Service Agent 必须具有配置 DNS 对等互连和更新网络连接的权限。按照代理平台服务代理所需的角色中所述授予所需的角色。 在共享 VPC 部署中，宿主项目会应用其他角色；请参阅将 Private Service Connect 接口与共享 VPC 搭配使用。

从代理代码中，调用 https://APIGEE_HOSTNAME/BASE_PATH 处的 API 代理。 在 Agent Runtime 环境中，此主机名通过 DNS 对等互连解析为 PSC_ENDPOINT_IP，并且请求通过 Private Service Connect 端点进入您的 VPC，然后到达 Apigee。

验证专用路径

部署代理后，验证请求是否通过专用路径到达 Apigee：

  • 使用创建 Private Service Connect 端点中的命令，确认转发规则状态为 ACCEPTED。
  • 从附加到 REGION 中 VPC_NAME 的 Compute Engine 虚拟机（在共享 VPC 部署中，此虚拟机可以位于宿主项目中，也可以位于附加到共享 VPC 的服务项目中）运行 dig +short APIGEE_HOSTNAME。结果必须是 PSC_ENDPOINT_IP。这确认了专用可用区可在 VPC 内正确解析主机名。
  • 在同一虚拟机中，向已部署的 API 代理发送请求 (https://APIGEE_HOSTNAME/BASE_PATH)，并确认您收到了预期响应。
  • 调用已部署的代理，并确认请求已得到处理。然后，使用 Apigee Analytics 或调试来确认请求是否已到达环境组主机名上的预期 API 代理。

后续步骤