Agentspace 自定义网域

关于此 Codelab

45 分钟

上次更新时间：2025年5月27日

Deepak Michael, Lorin Price, Zach Seils 编写

1. 简介

本文档提供了一个参考架构，用于配置自定义网域以访问 AgentSpace。用户可以使用自定义网域，而不是在创建 Agentspace 应用时分配的 Google 管理的网址。此 Codelab 演示了如何使用 nip.io 网域访问 Agentspace 日历和云端硬盘应用。nip.io 是一项免费的开源服务，可为任何 IP 地址提供通配符 DNS。从本质上讲，它允许您创建可解析为特定 IP 地址的主机名，而无需设置自己的 DNS 服务器或修改 /etc/hosts 文件。

建议您使用自己的网域，但本教程中出于演示目的使用了 nip.io。

在下图所示的部署场景中（图 1），AgentSpace 发布了一个数据存储区，其中包含通过 Google 管理的公开网址访问的日历应用。

图 1

随着数据存储区和后续应用的不断增长，需要进一步管理 Google 管理的公共网址，如下方部署场景所示（图 2），从而实现 Agentspace 应用与网址的 1:1 映射。

图 2.

借助自定义网域，您可以将各种 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

学习内容

创建全球外部应用负载平衡器
使用自定义网域创建后端服务重写，并将重写操作重写到 Agentspace 应用
如何集成 nip.io 和 Cloud DNS 以创建自定义网域
如何验证对 Agentspace 自定义网域的访问权限

所需条件

具有所有者权限的 Google Cloud 项目
现有的 Agentspace 应用网址
自有自定义网域（可选）
证书 - 自签名或 Google 管理

2. 您将构建的内容

您将建立一个具有高级流量管理功能的全球外部应用负载平衡器，以使用主机和路径重写为 Agentspace 应用启用自定义网域路径匹配。部署完成后，您需要执行以下操作来验证对 Agentspace 应用的访问权限：

打开网络浏览器，然后前往您的自定义网域和指定路径，以访问 Agentspace 应用。

3. 网络要求

以下是网络要求的细分：

组件	说明
VPC (agentspace-vpc)	自定义模式 VPC
互联网 NEG	用于为负载平衡器定义外部后端的资源，配置为 FQDN，表示 Agentspace 的 Google 托管 FQDN (vertexaisearch.cloud.google.com)。互联网 FQDN 会在 VPC 内执行 DNS 查找以进行解析。
后端服务	后端服务充当负载平衡器与后端资源之间的桥梁。在本教程中，后端服务与互联网 NEG 相关联。
证书	如需在 Google Cloud 中为应用负载平衡器配置证书，您需要使用 Certificate Manager 服务以及 Google 管理的或自行管理的 SSL 证书
Cloud DNS	Cloud DNS 公共网域用于将外部应用负载平衡器的外部 IP 地址解析为 nip.io (agentspace.externalip.nip.io)。或者，使用自定义网域和包含负载平衡器 IP 地址的 A 记录。

4. Codelab 拓扑

5. 设置和要求

自定进度的环境设置

项目名称是此项目参与者的显示名称。它是 Google API 尚未使用的字符串。您可以随时对其进行更新。
项目 ID 在所有 Google Cloud 项目中是唯一的，并且是不可变的（一经设置便无法更改）。Cloud 控制台会自动生成一个唯一字符串；通常情况下，您无需关注该字符串。在大多数 Codelab 中，您都需要引用项目 ID（通常用 PROJECT_ID 标识）。如果您不喜欢生成的 ID，可以再随机生成一个 ID。或者，您也可以尝试自己的项目 ID，看看是否可用。完成此步骤后便无法更改该 ID，并且此 ID 在项目期间会一直保留。
此外，还有第三个值，即部分 API 使用的项目编号，供您参考。如需详细了解所有这三个值，请参阅文档。

接下来，您需要在 Cloud 控制台中启用结算功能，以便使用 Cloud 资源/API。运行此 Codelab 应该不会产生太多的费用（如果有的话）。若要关闭资源以避免产生超出本教程范围的结算费用，您可以删除自己创建的资源或删除项目。Google Cloud 新用户符合参与 300 美元免费试用计划的条件。

启动 Cloud Shell

虽然可以通过笔记本电脑对 Google Cloud 进行远程操作，但在此 Codelab 中，您将使用 Google Cloud Shell，这是一个在云端运行的命令行环境。

在 Google Cloud 控制台中，点击右上角工具栏中的 Cloud Shell 图标：

预配和连接到环境应该只需要片刻时间。完成后，您应该会看到如下内容：

这个虚拟机已加载了您需要的所有开发工具。它提供了一个持久的 5 GB 主目录，并且在 Google Cloud 中运行，大大增强了网络性能和身份验证功能。您在此 Codelab 中的所有工作都可以在浏览器中完成。您无需安装任何程序。

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. 创建 VPC 网络

VPC 网络

在 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 目标代理中使用的证书资源。您可以使用 Google 管理的 SSL 证书或自行管理的 SSL 证书创建 SSL 证书资源。我们建议您使用 Google 管理的证书，因为 Google Cloud 会自动获取、管理和续订这些证书。

如需详细了解本教程中所用全球外部应用负载平衡器支持的证书，请参阅以下内容：

SSL 证书概览 | 负载均衡 | Google Cloud

在下一部分中，您将创建一个自签名证书（不过也可以改用 Google 管理的证书），该证书需要将常用名称映射到与之前生成的负载平衡器外部 IP 地址对应的完全限定域名 (agentspace.YOUR-EXTERNAL-IP.nip.io)，示例如下：

通用名称：agentspace.34.54.158.206.nip.io

在 Cloud Shell 中，创建私钥

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

在 Cloud Shell 中，创建用于生成 PEM 文件的 config.txt 文件。在 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 区域

在下一部分中，您将创建一个公共 DNS 区域，供 nip.io 用来解析外部负载平衡器 IP 地址。

在 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 凭据

在下一部分中，您将为 Web 应用创建 Oauth 凭据，以将 Google 管理的网址重定向到 oauth-redirect 以进行身份验证。本教程不需要使用生成的凭据。

如需详细了解 Oauth，请参阅以下内容：

添加 Google 日历和 Gmail 操作 | Google Agentspace

创建 OAuth 应用并添加范围

依次前往“API 和服务”>“OAuth 同意屏幕”：前往 OAuth 同意屏幕
选择“内部”，然后点击“创建”。
输入您的 OAuth 应用的名称。
输入用户支持电子邮件地址。
输入开发者联系信息。
点击保存并继续。

创建 OAuth 客户端 ID

此过程介绍了如何为 Google Cloud 操作创建新的 OAuth 客户端 ID。此 OAuth 客户端 ID 和 Secret 还可用于其他 Google Cloud 操作。如果您已有用于 Google Cloud 操作的 Google Cloud OAuth 客户端 ID，则可以将该客户端 ID 和密钥用于 Google 日历操作，而无需创建新的客户端 ID。

前往“凭据”页面，然后依次点击“创建凭据”>“OAuth 客户端 ID”。
选择“Web 应用”。
为您的客户端 ID 输入名称。
点击“添加 URI”，然后输入以下 URI：https://vertexaisearch.cloud.google.com/oauth-redirect
点击“创建”，然后复制以下信息：

客户 ID
客户端密钥

11. 确定 Agentspace 应用网址

以下步骤可识别 Google 为每个应用生成的 Google 管理的 Agentspace 公开网址，这些网址已映射到 Agentspace。网址的输出是基于参考架构的示例，因此您必须确保网址准确无误。

请务必为每个应用存储指向其 Web 应用的链接。

日历应用

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

云端硬盘应用

Agentspace Web 网址：

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

12. 创建高级主机和路径规则

在下一部分中，您将更新负载平衡器的路由规则，以启用使用 Cloud 控制台定义主机和路径规则的选项。下表概述了自定义值（自上而下顺序），这些值会根据您的环境进行更新：

	自定义值	基于教程的示例
主机	agentspace.YOUR-EXTERNAL-IP.nip.io	agentspace.34.54.158.206.nip.io
defaultService	projects/<projectid>/global/backendServices/agentspace-ineg-bes	查看屏幕截图
prefixMatch	/<Agentspace 应用 1 的名称>	/drive-app
backendService	projects/<projectid>/global/backendServices/agentspace-ineg-bes	查看屏幕截图
pathPrefixRewrite	/<Agentspace 网址 path of app#1>	/us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd
hostRewrite	vertexaisearch.cloud.google.com	vertexaisearch.cloud.google.com
prefixMatch	/<Agentspace 应用 2 的名称>	/calendar-app
backendService	projects/<projectid>/global/backendServices/agentspace-ineg-bes	查看屏幕截图
pathPrefixRewrite	/<Agentspace 网址 path of app#2>	/us/home/cid/bb6b8b27-939b-494d-9227-45903bb8afcf
hostRewrite	vertexaisearch.cloud.google.com	vertexaisearch.cloud.google.com

前往以下位置访问主机和路径规则

负载均衡 → agentspace-lb → 选择“修改”

依次选择“路由规则”→“高级主机和路径规则”

选择“添加主机和路径规则”

现在，系统会提示您创建新的主机和路径规则，请在“主机”部分插入 agentspace.YOUR-EXTERNAL-IP.nip.io 或自定义网域。

在“路径匹配器”（匹配项、操作和服务）字段中，使用您的环境配置更新以下内容，然后选择“更新”。

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

屏幕截图示例：

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 客户端 ID”下，选择您的凭据，然后删除

在一个 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 认为 Codelab 很棒！

Agentspace 自定义网域

1. 简介

学习内容

所需条件

2. 您将构建的内容

3. 网络要求

4. Codelab 拓扑

5. 设置和要求

自定进度的环境设置

启动 Cloud Shell

6. 准备工作

启用 API

7. 创建 VPC 网络

VPC 网络

8. 设置负载平衡器组件

预留负载平衡器的外部 IP 地址

设置互联网 NEG

创建负载平衡器

创建证书

9. 创建公共 DNS 区域

10. OAuth 凭据

11. 确定 Agentspace 应用网址

日历应用

云端硬盘应用

12. 创建高级主机和路径规则

13. 验证

14. 清理

15. 恭喜

参考文档