Agentspace 自定义网域

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	一种用于为负载平衡器定义外部后端的资源，配置为表示 Agentspace Google 管理的 FQDN (vertexaisearch.cloud.google.com) 的 FQDN。互联网 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 管理的证书），该证书需要将常用名映射到完全限定域名 (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 中，创建一个用于生成 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 区域

在下一部分中，您将创建一个由 nip.io 使用的公共 DNS 可用区，以解析为外部负载平衡器 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 和密钥也可用于其他 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 生成的、映射到每个 Agentspace 应用的 Google 管理的 Agentspace 公共网址。网址的输出是基于参考架构的示例，因此您必须确保网址准确无误。

确保存储指向 Web 应用的链接（按应用）。

日历应用

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

云端硬盘应用

Agentspace 网址：

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	/<代理空间应用 1 的名称>	/drive-app
backendService	projects/<projectid>/global/backendServices/agentspace-ineg-bes	查看屏幕截图
pathPrefixRewrite	/<应用 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	/<应用 2 的 Agentspace 网址路径>	/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. 恭喜

参考文档