Agentspace 自定义网域，WIF 支持

1. 简介

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

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

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

图 1

27591afa06891dcb.png

数据存储区和后续应用持续增长，导致需要进一步管理公共 Google 管理的网址，如下面的部署方案（图 2）所示，从而实现代理空间应用与网址的 1:1 映射。

图 2.

c03abe66bd3ad4df.png

借助自定义网域，您可以将各种 AgentSpace 应用映射到单个用户指定的客户网域。此功能可让您将特定网址路径与每个 Agentspace 应用相关联，从而提供更大的灵活性，如下面的部署方案（图 3）所示。例如，客户管理的网域 agentspace.cosmopup.com 分段为路径规则，每个路径规则都映射到特定的 Agentspace 应用，例如：

  • agentspace.cosmopup.com/drive-app，用于映射到 Workspace 云端硬盘的 Agentspace 应用
  • agentspace.cosmopup.com/sharepoint-app，可映射到 SharePoint 的 Agentspace 应用

外部应用负载平衡器的 主机和路径规则通过网址映射进行配置，用于控制将自定义网域映射到 Google 管理的网址的逻辑。它使用示例 agentspace.cosmopup.com/drive-app 执行以下功能

  • 自定义网域主机路径 agentspace.cosmopup.com/drive-app 由负载平衡器接收
  • 网址映射已配置为支持高级主机和路径规则匹配
  • 主机 agentspace.cosmopup.com 符合路径匹配和重定向条件
  • 自定义网域主机路径 agentspace.cosmopup.com/drive-app 受 UrlRedirect 约束
  • pathRedirect 是 Agentspace 路径：/us/home/cid/5970a1b4-080a-4b44-8acd-fa89460cf0cd
  • hostRedirect 是 Agentspace 主机：vertexaisearch.cloud.google.com
  • 自定义网域主机路径 agentspace.cosmopup.com/sharepoint-app 受 UrlRedirect 约束
  • pathRedirect 是 Agentspace 路径：/signin/locations/global/workforcePools/your-pool-name/providers/your-provider-name?continueUrl=https://vertexaisearch.cloud.google/home/cid/f190000-0000-4d0a-0000-d08df6e3bef6
  • hostRedirect 是 Agentspace 主机：auth.cloud.google
  • 重定向操作在路由到后端服务之前执行

图 3

8344f80c160f30f8.png

学习内容

  • 创建全球外部应用负载平衡器
  • 创建路由以将自定义网域重定向到 Agentspace 应用
  • 如何集成 nip.io 和 Cloud DNS 以创建自定义网域
  • 如何验证对 Agentspace 自定义网域的访问权限

所需条件

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

2. 构建内容

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

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

786e8b2de2d2c68b.png

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 拓扑

786e8b2de2d2c68b.png

8344f80c160f30f8.png

5. 设置和要求

自定进度的环境设置

  1. 登录 Google Cloud 控制台，然后创建一个新项目或重复使用现有项目。如果您还没有 Gmail 或 Google Workspace 账号，则必须创建一个。

fbef9caa1602edd0.png

a99b7ace416376c4.png

5e3ff691252acf41.png

  • 项目名称是此项目参与者的显示名称。它是 Google API 尚未使用的字符串。您可以随时对其进行更新。
  • 项目 ID 在所有 Google Cloud 项目中是唯一的，并且是不可变的（一经设置便无法更改）。Cloud 控制台会自动生成一个唯一字符串；通常情况下，您无需关注该字符串。在大多数 Codelab 中，您都需要引用项目 ID（通常用 PROJECT_ID 标识）。如果您不喜欢生成的 ID，可以再随机生成一个 ID。或者，您也可以尝试自己的项目 ID，看看是否可用。完成此步骤后便无法更改该 ID，并且此 ID 在项目期间会一直保留。
  • 此外，还有第三个值，即部分 API 使用的项目编号，供您参考。如需详细了解所有这三个值，请参阅文档。
  1. 接下来，您需要在 Cloud 控制台中启用结算功能，以便使用 Cloud 资源/API。运行此 Codelab 应该不会产生太多的费用（如果有的话）。若要关闭资源以避免产生超出本教程范围的结算费用，您可以删除自己创建的资源或删除项目。Google Cloud 新用户符合参与 300 美元免费试用计划的条件。

启动 Cloud Shell

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

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

55efc1aaa7a4d3ad.png

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

7ffe5cbb04455448.png

这个虚拟机已加载了您需要的所有开发工具。它提供了一个持久的 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. 设置负载平衡器组件

预留负载平衡器的外部 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

8. 创建公共 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"

9. 确定 Agentspace 应用网址

以下过程介绍了由 Google 生成的、映射到每个应用 Agentspace 的 Google 管理型 Agentspace 公共网址。网址的输出是基于参考架构的示例，因此您必须确保网址准确无误。

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

云端硬盘应用

Agentspace 网址：

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

f8f850425fd11190.png

SharePoint 应用

Agentspace 网页网址：https://auth.cloud.google/signin/locations/global/workforcePools/your-pool-name/providers/your-provider-name?continueUrl=https://vertexaisearch.cloud.google/home/cid/f190000-0000-4d0a-0000-d08df6e3bef6

f31a1939b9b83525.png

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

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

自定义值

基于教程的示例

主机

agentspace.YOUR-EXTERNAL-IP.nip.io

agentspace.34.54.158.206.nip.io

defaultService

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

projects/your-project-id/global/backendServices/agentspace-ineg-bes

prefixMatch

/<name of Agentspace app#1>

/drive-app

pathRedirect

/<应用 1 的代理空间网址路径>

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

hostRedirect

vertexaisearch.cloud.google.com

vertexaisearch.cloud.google.com

prefixMatch

/<Agentspace 应用 2 的名称>

/sharepoint-app

pathRedirect

/<应用 2 的 Agentspace 网址路径>

//signin/locations/global/workforcePools/your-pool-name/providers/your-provider-name?continueUrl=https://vertexaisearch.cloud.google/home/cid/f190000-0000-4d0a-0000-d08df6e3bef6

hostRedirect

auth.cloud.google

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
  urlRedirect:
    pathRedirect: /<Agentspace URL path of app#1>
    hostRedirect: vertexaisearch.cloud.google.com
    redirectResponseCode: FOUND
- matchRules:
  - prefixMatch: /<name of Agentspace app#2>
  priority: 2
  urlRedirect:
    pathRedirect: /<Agentspace URL path of app#2>
    hostRedirect: auth.cloud.google
    redirectResponseCode: FOUND

屏幕截图示例：

5470a123dca793b9.png

777dcb5191fd8d41.png

11. 验证

部署已完成！您可以通过网络浏览器或终端使用自定义网域访问 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 应用：sharepoint-app

路径：agentspace.34.54.158.206.nip.io/sharepoint-app

12. 清理

如需删除 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

13. 恭喜

恭喜！您已成功配置并验证了与 Agentspace 的连接，该连接使用自定义网域，并通过具有高级流量管理功能的外部应用负载平衡器实现。

您创建了负载平衡器基础架构，了解了如何创建互联网 NEG、Cloud DNS 和高级流量管理，这些功能可实现主机和路径重定向，从而允许使用自定义网域连接到 Agentspace。

Cosmopup 认为 Codelab 非常棒！

c911c127bffdee57.jpeg

参考文档