從 Gemini Enterprise Agent Platform 私下存取 Apigee

本頁內容適用於 Apigee，但不適用於 Apigee Hybrid。

查看 Apigee Edge 說明文件。

本文說明如何使用 Private Service Connect，設定從 Gemini Enterprise Agent Platform Agent Runtime 部署的代理程式，連線至 Apigee 發布的 API 和 Model Context Protocol (MCP) 工具。採用這種模式時，從代理程式到 Apigee 的流量會完全保持私密，不會通過公開網際網路。

總覽

Agent Runtime 會在 Google 管理的安全網路中部署代理程式，且無法存取您的虛擬私有雲 (VPC) 網路。Apigee 同樣會在 Google 代管的安全網路中執行。如要讓代理程式呼叫大型語言模型 (LLM) 或透過 Apigee 公開的 MCP 工具時，能以私密方式傳輸，您需要透過自己控管的虛擬私有雲網路，橋接這兩個 Google 代管網路。

本文說明該橋接器的下列模式：

完成這項設定後，當代理程式呼叫 https://APIGEE_HOSTNAME/... 時，要求會解析為虛擬私有雲中的 Private Service Connect 端點 IP，透過服務連結轉送至 Apigee 執行個體，並由符合要求路徑的 API Proxy 處理。

事前準備

本文的指令會使用下列預留位置。並替換為您環境中的值。

  • APIGEE_PROJECT_ID：包含 Apigee 機構的 Google Cloud 專案 ID。
  • SERVICE_PROJECT_ID：您要在 Agent Runtime 上部署代理程式的 Google Cloud 專案 ID。視您整理 Google Cloud 資源的方式而定，這可以是與 APIGEE_PROJECT_ID 相同的專案，也可以是不同的專案。
  • SERVICE_PROJECT_NUMBER：SERVICE_PROJECT_ID 的數值專案編號。您可以使用 gcloud projects describe SERVICE_PROJECT_ID --format="value(projectNumber)" 擷取。
  • HOST_PROJECT_ID：包含用戶虛擬私有雲網路、子網路和 Cloud DNS 私人區域的專案 ID。 Google Cloud 除非您使用共用虛擬私有雲，否則這與 SERVICE_PROJECT_ID 相同。如果您使用共用虛擬私有雲，這就是服務專案所連結的主專案。
  • REGION：Apigee 執行個體所在的區域 (例如 us-west1)。
  • VPC_NAME：HOST_PROJECT_ID 中的消費者虛擬私有雲網路名稱。
  • SUBNET_NAME：位於 REGION 的 VPC_NAME 子網路名稱。
  • APIGEE_HOSTNAME：您在 Apigee 環境群組中設定的主機名稱 (例如 api.internal.example.com)。
  • BASE_PATH：部署在 Apigee 上的 API Proxy 的基本路徑 (例如 /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 端點、Agent 執行階段部署)，這是最簡單的設定。
  • 環境群組，其環境已部署至該 Apigee 執行個體，且包含您希望代理程式呼叫的主機名稱。本文將該主機名稱稱為 APIGEE_HOSTNAME。
  • 至少有一個 API Proxy 部署在該環境群組的環境中。代理程式要呼叫的任何 Proxy 都必須可透過 https://APIGEE_HOSTNAME/BASE_PATH 存取。
  • HOST_PROJECT_ID 中的虛擬私有雲網路和子網路，與 Apigee 執行個體位於相同區域。本文將這些項目稱為 VPC_NAME 和 SUBNET_NAME。Agent Runtime 需要至少 /28 個子網路，並會施加額外的範圍限制。詳情請參閱 Agent Platform 說明文件中的「子網路 IP 範圍需求條件」。
  • 在適當的專案中啟用下列 API：
    • Apigee (apigee.googleapis.com) in APIGEE_PROJECT_ID.
    • Compute Engine (compute.googleapis.com) 和 Cloud DNS (dns.googleapis.com) 位於 HOST_PROJECT_ID 中。
    • Agent Platform (aiplatform.googleapis.com) in SERVICE_PROJECT_ID.
  • 在 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 Proxy 之間的流量流動情形，並以消費者虛擬私有雲中的 Private Service Connect 端點做為橋樑。

  1. 在 Agent Runtime 上執行的代理會向 APIGEE_HOSTNAME 發出 HTTPS 要求。
  2. 在 Agent Runtime PSC 介面上設定的 DNS 對等互連，會將查詢轉送至用戶端 VPC 中的 Cloud DNS 私人區域，該區域會傳回 Private Service Connect 端點的 IP 位址。
  3. 代理程式的要求會透過 PSC 介面傳出，進入您的消費者虛擬私有雲，並連至該 IP 位址上的 Private Service Connect 端點。
  4. Private Service Connect 端點會透過服務連線，將要求轉送至 Apigee 執行個體的服務連結。
  5. Apigee 執行個體會終止 TLS、將要求主機名稱與環境群組相符，並轉送至正確的 API Proxy。

步驟 1：在用戶虛擬私有雲中設定網路

本節會設定兩個專案的資源。每個指令都包含明確的 --project 標記，因此您可以從任何有效的 gcloud 設定執行指令：

  • Cloud DNS 資源 (私人區域和記錄) 會在 HOST_PROJECT_ID 中建立，因為私人區域會附加至消費者虛擬私有雲網路。
  • Private Service Connect 端點資源 (靜態內部 IP 位址和轉送規則) 和網路連結會在 SERVICE_PROJECT_ID 中建立。這些指令都會使用跨專案參照，指向 HOST_PROJECT_ID 中的共用子網路或虛擬私有雲網路。在單一專案部署中，SERVICE_PROJECT_ID 和 HOST_PROJECT_ID 相同，因此各步驟的擁有權不會變更。如要進一步瞭解 Private Service Connect 端點的共用虛擬私有雲模型，請參閱「在共用虛擬私有雲服務專案中建立端點」。

建立 Cloud DNS 私人區域

建立僅供用戶虛擬私有雲使用的 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 介面繫結至這個附件。

在單一專案 Deployment 中，請在 SERVICE_PROJECT_ID (也就是 HOST_PROJECT_ID) 中建立網路連結。在 Shared VPC Deployment 中，您可以在服務專案或主專案中建立網路連結；Agent Platform 建議使用服務專案，以簡化權限。如需選擇適當介面和對應 IAM 角色的指引，請參閱「搭配使用 Private Service Connect 介面與 Shared VPC」。

下列指令會在 SERVICE_PROJECT_ID 中建立網路連結。在 Shared 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 中參照共用虛擬私有雲網路，以及 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 Proxy 的環境群組中。如果沒有，請新增該項目。

如需操作說明，請參閱「使用環境群組」。

步驟 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。這個專案包含用戶虛擬私有雲和私人區域。
    • targetNetwork: VPC_NAME.

SERVICE_PROJECT_ID(service-SERVICE_PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com) 的 Agent Platform 服務代理必須具備設定 DNS 對接和更新網路附件的權限。如「Agent Platform 服務代理必要角色」一文所述，授予必要角色。在共用虛擬私有雲部署作業中，主專案會套用額外角色；詳情請參閱「使用 Private Service Connect 介面搭配共用虛擬私有雲」。

從代理程式碼中，在 https://APIGEE_HOSTNAME/BASE_PATH 呼叫 API Proxy。在 Agent Runtime 環境中，這個主機名稱會透過 DNS 對等互連解析為 PSC_ENDPOINT_IP，要求會透過 Private Service Connect 端點傳輸至虛擬私有雲，然後傳輸至 Apigee。

驗證私人路徑

部署代理程式後，請確認要求是否透過私有路徑傳送至 Apigee：

  • 使用「建立 Private Service Connect 端點」中的指令，確認轉送規則狀態為 ACCEPTED。
  • 從附加至 VPC_NAME 的 Compute Engine VM (在 Shared VPC 部署中，這個 VM 可以位於主專案或附加至 Shared VPC 的服務專案中) 執行 dig +short APIGEE_HOSTNAME。REGION結果必須是 PSC_ENDPOINT_IP。這會確認私有區域是否在 VPC 內正確解析主機名稱。
  • 從同一個 VM 將要求傳送至已部署的 API Proxy (位於 https://APIGEE_HOSTNAME/BASE_PATH)，並確認您收到預期回應。
  • 叫用已部署的代理程式，並確認要求已獲得處理。然後使用 Apigee Analytics 或 Debug，確認要求已送達環境群組主機名稱上的預期 API Proxy。

後續步驟