Agentspace 自訂網域

程式碼研究室簡介
schedule45 分鐘
subject上次更新時間：2025年5月27日
account_circle作者：Deepak Michael, Lorin Price, Zach Seils

本文提供參考架構，協助您設定自訂網域以存取 AgentSpace。使用者可以使用自訂網域，而非在 Agentspace 應用程式建立期間指派的 Google 管理網址。本程式碼研究室示範如何使用 nip.io 網域存取 Agentspace 日曆和雲端硬碟應用程式。nip.io 是免費的開放原始碼服務，可為任何 IP 位址提供萬用字元 DNS。基本上，您可以建立主機名稱，將其解析為特定 IP 位址，而無須設定自己的 DNS 伺服器或修改 /etc/hosts 檔案。

建議您使用自己的網域，但為了示範，本教學課程會使用 nip.io。

在下方所示的部署情境中 (圖 1)，AgentSpace 發布了含有日曆應用程式的資料儲存庫，可透過 Google 管理的公開網址存取。

圖 1

27591afa06891dcb.png

隨著資料儲存庫和後續應用程式持續成長，您需要進一步管理 Google 管理的公開網址，如下方部署情境所示 (圖 2)，以便將 Agentspace 應用程式和網址進行 1:1 對應。

圖 2.

7e31bfae7ac56b22.png

自訂網域可讓您將各種 AgentSpace 應用程式對應至使用者指定的單一客戶網域。這項功能可讓特定網址路徑與每個 Agentspace 應用程式建立關聯，提供更大的彈性，如以下部署情境所示 (圖 3)。舉例來說，客戶管理的網域 agentspace.cosmopup.com 會劃分為路徑規則，每個路徑規則會對應至特定的 Agentspace 應用程式，例如：

  • agentspace.cosmopup.com/drive-app，對應至 Workspace 雲端硬碟的 Agentspace 應用程式
  • agentspace.cosmopup.com/calendar-app，對應至 Workspace 日曆的 Agentspace 應用程式

透過網址對應設定的外部應用程式負載平衡器 主機和路徑規則，會控制將自訂網域對應至 Google 代管網址的邏輯。它會使用範例 agentspace.cosmopup.com/drive-app 執行下列函式

  • 負載平衡器收到自訂網域主機路徑 agentspace.cosmopup.com/drive-app
  • 已設定網址對應，以便進行進階主機和路徑規則比對
  • 主機 agentspace.cosmopup.com 可進行路徑比對和重寫
  • 自訂網域主機路徑 agentspace.cosmopup.com/drive-app 會受到 UrlRewrite 影響
  • PathPrefixRewrite 是 Agentspace 路徑：/us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd
  • hostRewrite 是 Agentspace 主機：vertexaisearch.cloud.google.com
  • 重新寫入作業會在轉送至後端服務之前執行
  • 後端服務會根據 Agentspace 網址將流量轉送至 Drive 應用程式

圖 3

f8d84ec5fef9af5a.png

課程內容

  • 建立全域外部應用程式負載平衡器
  • 建立後端服務重寫作業，並使用自訂網域和重寫作業將 Agentspace 應用程式
  • 如何整合 nip.io 和 Cloud DNS 來建立自訂網域
  • 如何驗證對 Agentspace 自訂網域的存取權

軟硬體需求

  • 具備擁有者權限的 Google Cloud 專案
  • 現有的 Agentspace 應用程式網址
  • 自有自訂網域 (選用)
  • 憑證 - 自行簽署或 Google 代管

2. 建構項目

您將建立具備進階流量管理功能的全域外部應用程式負載平衡器，為使用主機和路徑重寫的 Agentspace 應用程式啟用自訂網域路徑比對功能。部署完成後，您需要執行下列操作，驗證對 Agentspace 應用程式的存取權：

  • 開啟網路瀏覽器，前往自訂網域和指定路徑，即可存取 Agentspace 應用程式。

c62938d91e00ffa7.png

3. 網路需求

以下是網路需求的詳細說明：

元件

說明

虛擬私有雲 (agentspace-vpc)

自訂模式虛擬私有雲

網際網路 NEG

用於定義負載平衡器的外部後端的資源，其設定為 FQDN，表示 Agentspace Google 代管 FQDN (vertexaisearch.cloud.google.com)。網際網路 FQDN 會在 VPC 內執行 DNS 查詢，以便解析。

後端服務

後端服務是負載平衡器與後端資源之間的橋樑。在本教學課程中，後端服務會與 Internet NEG 建立關聯。

憑證

如要為 Google Cloud 中的應用程式負載平衡器設定憑證，您可以使用 Certificate Manager 服務，並使用 Google 代管 或自行管理的 SSL 憑證

Cloud DNS

Cloud DNS 公開區域可用於將外部應用程式負載平衡器外部 IP 解析為 nip.io (agentspace.externalip.nip.io)。或者，您也可以使用自訂網域和包含負載平衡器 IP 位址的 A 記錄。

4. 程式碼研究室拓樸圖

c62938d91e00ffa7.png

f712980116d973a3.png

5. 設定和需求

自助式環境設定

  1. 登入 Google Cloud 控制台，然後建立新專案或重複使用現有專案。如果您還沒有 Gmail 或 Google Workspace 帳戶，請務必建立帳戶。

fbef9caa1602edd0.png

a99b7ace416376c4.png

5e3ff691252acf41.png

  • 「Project name」是這個專案參與者的顯示名稱。這是 Google API 不會使用的字元字串。您隨時可以更新。
  • 專案 ID 在所有 Google Cloud 專案中都是不重複的值，且無法變更 (設定後即無法變更)。Cloud 控制台會自動產生唯一字串，您通常不需要理會這個字串。在大多數程式碼研究室中，您需要參照專案 ID (通常會標示為 PROJECT_ID)。如果您不喜歡產生的 ID，可以產生另一個隨機 ID。或者，您也可以自行嘗試，看看是否可用。在這個步驟後就無法變更，且會在專案期間維持不變。
  • 提醒您，有些 API 會使用第三個值「專案編號」。如要進一步瞭解這三個值，請參閱說明文件。
  1. 接下來，您需要在 Cloud 控制台中啟用帳單功能，才能使用 Cloud 資源/API。執行這個程式碼研究室不會產生任何費用，如要關閉資源，避免在本教學課程結束後繼續產生費用，您可以刪除建立的資源或專案。Google Cloud 新使用者可享有價值 $300 美元的免費試用期。

啟動 Cloud Shell

雖然 Google Cloud 可透過筆記型電腦遠端操作，但在本程式碼研究室中，您將使用 Google Cloud Shell，這是在雲端運作的指令列環境。

在 Google Cloud 控制台中，按一下右上方工具列的 Cloud Shell 圖示：

55efc1aaa7a4d3ad.png

佈建並連線至環境的作業需要一些時間才能完成。完成後，畫面應如下所示：

7ffe5cbb04455448.png

這個虛擬機器會載入您需要的所有開發工具。提供永久的 5 GB 主目錄，而且在 Google Cloud 中運作，大幅提升網路效能和驗證功能。您可以在瀏覽器中完成本程式碼研究室的所有工作。您不需要安裝任何東西。

6. 事前準備

啟用 API

在 Cloud Shell 中，確認專案 ID 已設定完畢：

gcloud config list project
gcloud config set project [YOUR-PROJECT-ID]
project=[YOUR-PROJECT-ID]
region=[YOUR-REGION]
echo $project
echo $region

啟用所有必要服務：

gcloud services enable compute.googleapis.com
gcloud services enable dns.googleapis.com

7. 建立虛擬私有雲網路

虛擬私有雲網路

在 Cloud Shell 中執行下列操作：

gcloud compute networks create agentspace-vpc --subnet-mode custom

8. 設定負載平衡器元件

保留負載平衡器的外部 IP 位址

在 Cloud Shell 中為負載平衡器保留外部 IP 位址：

gcloud compute addresses create external-ip \
    --network-tier=PREMIUM \
    --ip-version=IPV4 \
    --global

在 Cloud Shell 中查看保留的 IP 位址：

gcloud compute addresses describe external-ip \
  --global | grep -i address:

輸出內容範例：

user@cloudshell$ gcloud compute addresses describe external-ip \
  --global | grep -i address:
address: 34.54.158.206

設定網際網路 NEG

建立網際網路 NEG，並將 –network-endpoint-type 設為 internet-fqdn-port (可存取外部後端的主機名稱和通訊埠)。如要解析 Agentspace，請使用 FQDN vertexaisearch.cloud.google.com 和通訊埠 443。

gcloud compute network-endpoint-groups create agentspace-ineg \
    --network-endpoint-type="internet-fqdn-port" \
    --global

gcloud compute network-endpoint-groups update agentspace-ineg \
    --add-endpoint="fqdn=vertexaisearch.cloud.google.com,port=443" \
    --global

建立負載平衡器

在 Cloud Shell 中執行下列操作：

gcloud compute backend-services create agentspace-ineg-bes \
      --load-balancing-scheme=EXTERNAL_MANAGED \
      --protocol=HTTPS \
      --global

gcloud compute backend-services add-backend agentspace-ineg-bes \
      --network-endpoint-group=agentspace-ineg \
      --global-network-endpoint-group \
      --global

建立憑證

此時，您已建立網際網路 neg 和後端服務，在下一個部分，您需要建立要在 HTTPs 目標 Proxy 中使用的憑證資源。您可以使用 Google 代管的 SSL 憑證或自行管理的 SSL 憑證建立 SSL 憑證資源。我們建議使用 Google 代管的憑證，因為 Google Cloud 會自動取得、管理及更新這些憑證。

如要進一步瞭解本教學課程中所用全域外部應用程式負載平衡器支援的憑證，請參閱以下內容：

安全資料傳輸層 (SSL) 憑證總覽 | Load Balancing | Google Cloud

在下一個部分，您將建立自行簽署的憑證 (雖然也可以使用 Google 代管的憑證)，其中通用名稱必須對應至完整網域名稱 (agentspace.YOUR-EXTERNAL-IP.nip.io)，對應至先前產生的負載平衡器外部 IP 位址，如下所示：

常用名稱：agentspace.34.54.158.206.nip.io

在 Cloud Shell 中建立私密金鑰

openssl genrsa -out private-key-file.pem 2048

在 Cloud Shell 中建立 config.txt 檔案，用於產生 PEM 檔案。在 DNS 1 項目中指定完整網域名稱 agentspace.YOUR-EXTERNAL-IP.nip.io，例如下方設定中的 agentspace.34.54.158.206.nip.io。

cat <<'EOF' >config.txt
[req]
default_bits              = 2048
req_extensions            = extension_requirements
distinguished_name        = dn_requirements

[extension_requirements]
basicConstraints          = CA:FALSE
keyUsage                  = nonRepudiation, digitalSignature, keyEncipherment
subjectAltName            = @sans_list

[dn_requirements]
countryName               = Country Name (2 letter code)
stateOrProvinceName       = State or Province Name (full name)
localityName              = Locality Name (eg, city)
organizationName          = Organization Name (eg, company)
organizationalUnitName    = Organizational Unit Name (eg, section)
commonName                = Common Name (e.g. server FQDN or YOUR name)
emailAddress              = Email Address

[sans_list]
DNS.1                     = agentspace.YOUR-EXTERNAL-IP.nip.io

EOF

在 Cloud Shell 中，驗證是否已產生 config.txt 和 private-key-file.pem。

user@cloudshell:$ ls
config.txt  private-key-file.pem

在 Cloud Shell 中執行下列操作。

sudo openssl req -new -key private-key-file.pem \
    -out csr.pem \
    -config config.txt

範例：

user@cloudshell:$ sudo openssl req -new -key private-key-file.pem \
    -out csr.pem \
    -config config.txt
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) []:
State or Province Name (full name) []:
Locality Name (eg, city) []:
Organization Name (eg, company) []:
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name)[]:agentspace.34.54.158.206.nip.io
Email Address []:

在 Cloud Shell 中，驗證是否已建立憑證簽署所需的 PEM。

user@cloudshell:$ ls
config.txt  csr.pem  private-key-file.pem

在 Cloud Shell 中產生憑證。

sudo openssl x509 -req \
    -signkey private-key-file.pem \
    -in csr.pem \
    -out cert.cert \
    -extfile config.txt \
    -extensions extension_requirements \
    -days 365

輸出範例：

user@cloudshell:$ sudo openssl x509 -req \
    -signkey private-key-file.pem \
    -in csr.pem \
    -out cert.cert \
    -extfile config.txt \
    -extensions extension_requirements \
    -days 365
Certificate request self-signature ok
subject=CN = agentspace.34.54.158.206.nip.io

在 Cloud Shell 中，驗證 cert.cert 檔案是否已建立

user@cloudshell:$ ls
cert.cert  config.txt  csr.pem  private-key-file.pem

建立憑證資源，以便與外部負載平衡器建立關聯。請將憑證和私密金鑰參數替換為特定檔案名稱。

在 Cloud Shell 中執行下列操作：

gcloud compute ssl-certificates create agentspace-self-signed-cert \
    --certificate=cert.cert \
    --private-key=private-key-file.pem \
    --global

在 Cloud Shell 中執行下列操作：

gcloud compute url-maps create agentspace-lb \
      --default-service=agentspace-ineg-bes \
      --global

在 Cloud Shell 中執行下列操作：

gcloud compute target-https-proxies create https-proxy \
      --ssl-certificates=agentspace-self-signed-cert \
      --url-map=agentspace-lb \
      --global

在 Cloud Shell 中執行下列操作：

gcloud compute forwarding-rules create agentspace-fr \
      --load-balancing-scheme=EXTERNAL_MANAGED \
      --network-tier=PREMIUM \
      --address=external-ip \
      --target-https-proxy=https-proxy \
      --global \
      --ports=443

9. 建立公開 DNS 區域

在下一個部分，您將建立 nip.io 用於解析外部負載平衡器 IP 位址的公開 DNS 區域。

在 Cloud Shell 中執行下列操作，為外部負載平衡器 IP 位址建立變數：

externalip=<YOUR-EXTERNAL-IP>
echo $externalip

在 Cloud Shell 中執行下列操作：

gcloud dns --project=$project managed-zones create agentspace-dns --description="Agentspace public dns" --dns-name="$externalip.nip.io." --visibility="public"

在 Cloud Shell 中執行下列操作：

gcloud dns --project=$project record-sets create agentspace.$externalip.nip.io. --zone="agentspace-dns" --type="A" --ttl="300" --rrdatas="$externalip"

10. OAuth 憑證

在下一節中，您將為網頁應用程式建立 OAuth 憑證，將 Google 管理的網址重新導向至 oauth-redirect 進行驗證。您不需要使用產生的憑證來完成本教學課程。

如要進一步瞭解 Oauth，請參閱以下資源：

新增 Google 日曆和 Gmail 動作 | Google Agentspace

建立 OAuth 應用程式並新增範圍

  1. 依序前往「API 和服務」>「OAuth 同意畫面」：前往 OAuth 同意畫面
  2. 選取「內部」，然後按一下「建立」。
  3. 輸入 OAuth 應用程式的名稱。
  4. 輸入使用者支援電子郵件地址。
  5. 輸入開發人員的聯絡資訊。
  6. 按一下 [儲存並繼續]。

建立 OAuth 用戶端 ID

本程序說明如何為 Google Cloud 動作建立新的 OAuth 用戶端 ID。這個 OAuth 用戶端 ID 和密鑰也可以用於其他 Google Cloud 動作。如果您已有 Google Cloud 動作的 Google Cloud OAuth 用戶端 ID，可以使用該用戶端 ID 和密碼執行 Google 日曆動作，而不需要建立新的用戶端 ID。

  1. 前往「憑證」頁面，然後依序點選「建立憑證」>「OAuth 用戶端 ID」。
  2. 選取「網路應用程式」。
  3. 輸入用戶端 ID 的名稱。
  4. 按一下「新增 URI」，然後輸入以下 URI：https://vertexaisearch.cloud.google.com/oauth-redirect
  5. 按一下「建立」，然後複製下列資訊：
  • 用戶端 ID
  • 用戶端密碼

11. 找出 Agentspace 應用程式網址

下列程序會說明 Google 管理的 Agentspace 公開網址，這些網址是由 Google 產生，並對應至 Agentspace 的各個應用程式。網址的輸出內容是參考架構的範例，因此您必須確保網址正確無誤。

請務必為每個應用程式儲存網頁應用程式的連結。

日曆應用程式

Agentspace 網頁版網址：https://vertexaisearch.cloud.google.com/us/home/cid/bb6b8b27-939b-494d-9227-45903bb8afcf

b90c67aafd825ccd.png

雲端硬碟應用程式

Agentspace 網頁網址：

https://vertexaisearch.cloud.google.com/us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd

f8f850425fd11190.png

12. 建立進階主機與路徑規則

在下一節中，您將更新負載平衡器轉送規則，啟用使用 Cloud Console 定義主機和路徑規則的選項。下表列出自訂值 (由上而下排序)，並根據環境進行更新：

自訂值

範例：根據教學課程

主機

agentspace.YOUR-EXTERNAL-IP.nip.io

agentspace.34.54.158.206.nip.io

defaultService

projects/<projectid>/global/backendServices/agentspace-ineg-bes

查看螢幕截圖

prefixMatch

/<Agentspace app#1 名稱>

/drive-app

backendService

projects/<projectid>/global/backendServices/agentspace-ineg-bes

查看螢幕截圖

pathPrefixRewrite

/<Agentspace URL path of app#1>

/us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd

hostRewrite

vertexaisearch.cloud.google.com

vertexaisearch.cloud.google.com

prefixMatch

/<Agentspace app#2 名稱>

/calendar-app

backendService

projects/<projectid>/global/backendServices/agentspace-ineg-bes

查看螢幕截圖

pathPrefixRewrite

/<應用程式 2 的 Agentspace 網址路徑>

/us/home/cid/bb6b8b27-939b-494d-9227-45903bb8afcf

hostRewrite

vertexaisearch.cloud.google.com

vertexaisearch.cloud.google.com

前往下列位置存取主機與路徑規則

負載平衡 → agentspace-lb → 選取「編輯」

依序選取「轉送規則」→「進階主機與路徑規則」

選取「新增主機與路徑規則」

4bc965db43aed21b.png

系統現在會提示您建立新的主機和路徑規則，請在「主機」部分插入 agentspace.YOUR-EXTERNAL-IP.nip.io 或自訂網域。

f36e4fa11c950d8d.png

在「路徑比對器」欄位 (比對項目、操作和服務) 中，使用環境設定更新下方內容，然後選取「更新」。

defaultService: projects/<projectid>/global/backendServices/agentspace-ineg-bes
name: matcher1
routeRules:
- matchRules:
 - prefixMatch: /<name of Agentspace app#1>
 priority: 1
 routeAction:
   weightedBackendServices:
   - backendService: projects/<projectid>/global/backendServices/agentspace-ineg-bes
     weight: 100
   urlRewrite:
     pathPrefixRewrite: /<Agentspace URL path of app#1>
     hostRewrite: vertexaisearch.cloud.google.com
- matchRules:
 - prefixMatch: /<name of Agentspace app#2>
 priority: 2
 routeAction:
   weightedBackendServices:
   - backendService: projects/<projectid>/global/backendServices/agentspace-ineg-bes
     weight: 101
   urlRewrite:
     pathPrefixRewrite: /<Agentspace URL path of app#2>
     hostRewrite: vertexaisearch.cloud.google.com

螢幕截圖範例：

22788283124c59ec.png

cef8f571ca17bf42.png

13. 驗證

部署作業已完成！您可以透過網路瀏覽器或終端機，使用自訂網域存取 Agentspace 應用程式，方法是指定 agentspace.YOUR-EXTERNAL-IP.nip.io/path，例如 agentspace.34.54.158.206.nip.io，如下所示：

Agentspace 應用程式：drive-app

路徑：agentspace.34.54.158.206.nip.io/drive-app

Agentspace 應用程式：drive-app

路徑：agentspace.34.54.158.206.nip.io/calendar-app

14. 清理

如要刪除 OAuth 憑證，請執行下列操作：

依序前往「API 和服務」→「憑證」

在「OAuth 2.0 Client IDs」下方選取憑證，然後刪除

從單一 Cloud Shell 終端機刪除實驗室元件：

gcloud compute forwarding-rules delete agentspace-fr --global -q

gcloud compute target-https-proxies delete https-proxy --global -q

gcloud compute url-maps delete agentspace-lb --global -q

cloud compute ssl-certificates delete agentspace-self-signed-cert --global -q

gcloud compute backend-services delete agentspace-ineg-bes --global -q

gcloud compute network-endpoint-groups delete agentspace-ineg --global -q

gcloud dns --project=$projectid record-sets delete agentspace.$externalip.nip.io --zone="agentspace-dns" --type="A"

gcloud dns --project=$projectid managed-zones delete agentspace-dns

gcloud compute addresses delete external-ip --global -q

gcloud compute networks delete agentspace-vpc -q

15. 恭喜

恭喜！您已成功設定並驗證 Agentspace 的連線，使用自訂網域搭配進階流量管理的外部應用程式負載平衡器。

您已建立負載平衡器基礎架構，並瞭解如何建立網際網路 NEG、Cloud DNS 和進階流量管理，啟用主機和路徑重寫功能，以便使用自訂網域連線至 Agentspace。

Cosmopup 認為程式碼研究室很棒！

c911c127bffdee57.jpeg

參考文件