映射自定义网域

Beta 版

此功能须遵守服务专用条款的“通用服务条款”部分中的“非正式版产品条款”。 非正式版功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅发布阶段说明。

配置自定义网域以用于访问 Knative serving 服务。您可以将一个或多个自定义网域映射到单个服务，也可以将单个网域映射到所有服务使用的集群。自定义网域映射可以是基本网域（如 your-domain.com），也可以是子网域（如 your-subdomain.your-domain.com）。

默认情况下，您部署到 Knative serving 集群的服务会设置为 nip.io 基本网域。这样一来，您就可以立即通过类似如下的网址测试您的服务：

http://{SERVICE_NAME}.{NAMESPACE}.kuberun.{EXTERNAL_IP}.nip.io

详细了解测试网域。

准备工作

• 您必须拥有或购买要映射到服务的网域。 您可以使用任何域名注册商，但如果使用 Cloud Domains，则网域会自动针对 Knative serving 进行验证，因此您无需执行网域验证流程。

  如果要向 Cloud Domains 注册网域，请参阅在 Knative serving 控制台中向 Cloud Domains 注册网域。

• 您必须至少具有 Kubernetes Engine Developer Identity and Access Management 角色或等效权限。

• 如需使用自定义网域映射启用 HTTPS，您必须设置代管式 TLS 证书或配置您自己的证书。

• 如需将自定义网域映射到专用内部网络中的集群或服务，您必须停用代管式 TLS 证书。

映射自定义网域

您可以使用 Google Cloud 控制台或命令行工具来映射您的自定义网域。

一般而言，配置自定义网域需要执行以下操作：

1. 可选：预留负载均衡器的 IP 地址。
2. 在 Knative serving 中，将您的服务或集群映射到自定义网域。
3. 在域名注册商处更新 DNS 记录。

预留负载均衡器 IP 地址

安装 Knative serving 后，Istio Ingress 控制器会创建一个具有可用 IP 地址的负载均衡器。

您可能需要为 Anthos Ingress 控制器预留负载均衡器的 IP 地址，具体取决于您的 GKE 集群：

Google Cloud 外部

请参阅在其中运行 GKE 集群的环境的文档，以确定 IP 地址的管理方式以及负载均衡器的 IP 地址是否为静态地址。另请参阅 GKE 集群的配置页面。例如，根据您为 Google Distributed Cloud 配置负载均衡的方式，您可能已经预留了这些 IP 地址。

在 Google Cloud 上

您必须预留负载均衡器的外部 IP 地址，以确保在删除 Ingress 服务后负载均衡器的外部 IP 地址保持不变。根据集群配置，IP 地址可供外部使用或仅限内部使用（例如专用集群）。

Google Cloud 上的内部负载均衡器

如需详细了解如何预留内部负载均衡器的 IP 地址，请参阅以下页面：预留静态内部 IP 地址

Google Cloud 上的外部负载均衡器

如需预留外部负载均衡器的 IP 地址，请执行以下操作：

1. 获取负载均衡器的 IP 地址：

   控制台

   如需从 Google Cloud 控制台获取负载均衡器的外部 IP 地址，请执行以下操作：

   1. 在 Google Cloud 控制台中，前往 GKE 页面：
      前往 GKE
   2. 点击服务和 Ingress (Services and ingress)。
   3. 确定集群的 Istio Ingress 服务。服务的类型将为外部负载均衡器，名称将为 istio-ingressgateway。
   4. 找到集群的 Istio Ingress 服务后，复制其端点。这将是没有端口号的 IP 地址。例如，您可能会看到 00.000.000.000:11 列为端点，但只需复制 00.000.000.000。

   kubectl

   如需获取负载均衡器的外部 IP，请运行以下命令：

   kubectl get svc istio-ingressgateway -n ASM-INGRESS-NAMESPACE
   

   将 ASM-INGRESS-NAMESPACE 替换为 Cloud Service Mesh 入站流量所在的命名空间。如果您使用默认配置安装了 Cloud Service Mesh，请指定 istio-system。

   输出类似于以下内容：

   NAME                   TYPE           CLUSTER-IP     EXTERNAL-IP  PORT(S)
   istio-ingressgateway   LoadBalancer   XX.XX.XXX.XX   pending      80:32380/TCP,443:32390/TCP,32400:32400/TCP
   

   其中 EXTERNAL-IP 值是负载均衡器的外部 IP 地址。

2. 将该 IP 地址预留为静态 IP 地址：

   gcloud compute addresses create ADDRESS-NAME --addresses EXTERNAL-IP --region REGION

   您需要将其中的：

   • 将 ADDRESS-NAME 替换为您要为静态 IP 地址指定的名称。
   • 将 EXTERNAL-IP 替换为您在上一步中获得的负载均衡器的外部 IP 地址。
   • 将 REGION 替换为集群所在的区域。

在获取负载均衡器的 IP 地址之后，您就可以使用它来映射自定义网域了：

• 映射到服务
• 映射到集群

映射服务

选择以下方法之一来将自定义网域映射到 Knative serving 服务。每项服务可以映射到多个网域。

控制台

1. 在 Google Cloud 控制台中打开网域映射页面：

   前往“网域映射”

   请注意，如果显示窗口太小，则不会显示“映射自定义网域”按钮，您必须点击页面右侧的三点状垂直椭圆图标。

2. 点击添加映射，然后选择添加服务网域映射以将网域映射到单个服务。您可以将多个网域映射到每项服务。

3. 从“添加映射”表单的下拉列表中，选择要将自定义网域映射到的服务：

4. 输入域名。 例如 your-domain.com 或 subdomain.your-domain.com。网域要求：

   • 系统不支持基本路径映射。术语“基本路径”是指域名之后的网址路径名称。例如，users 是 your-domain.com/users 的基本路径。Knative serving 仅允许您将网域映射至 /，而不能映射到特定的基本路径。因此，必须通过在服务容器内使用路由器或使用 Firebase Hosting 来处理任何路径路由。
   • 您不能将您的网域映射到与您的服务网址匹配的子网域。服务的网址定义为 http://{service}.{namespace}.{your-domain.com}，因此如果您在 test.default.your-domain.com 中有服务，则不能创建映射到同一子网域 test.default.your-domain.com 的网域映射。

5. 点击继续。

6. 访问您的网域注册商网站，并使用上一步中显示的 DNS 记录更新您的 DNS 记录。您可以随时显示上步中所示的 DNS 记录，点击网域映射所对应“...”操作菜单中的 DNS 记录即可。

7. 点击完成。

gcloud

1. 将服务映射到自定义网域：

   gcloud run domain-mappings create --service SERVICE --domain DOMAIN

   您需要将其中的：

   • 将 SERVICE 替换为您的服务名称。
   • 将 DOMAIN 替换为您的自定义网域。例如 your-domain.com 或 subdomain.your-domain.com。 网域要求：
     • 系统不支持基本路径映射。术语“基本路径”是指域名之后的网址路径名称。例如，users 是 your-domain.com/users 的基本路径。Knative serving 仅允许您将网域映射至 /，而不能映射到特定的基本路径。因此，必须通过在服务容器内使用路由器或使用 Firebase Hosting 来处理任何路径路由。
     • 您不能将您的网域映射到与您的服务网址匹配的子网域。服务的网址定义为 http://{service}.{namespace}.{your-domain.com}，因此如果您在 test.default.your-domain.com 中有服务，则不能创建映射到同一子网域 test.default.your-domain.com 的网域映射。

现在，您的自定义网域已映射到 Knative serving，您必须在域名注册商处添加 DNS 记录。

映射集群

选择以下方法之一以将自定义网域映射到集群：

控制台

1. 在 Google Cloud 控制台中打开网域映射页面：

   前往“网域映射”

   请注意，如果显示窗口太小，则不会显示“映射自定义网域”按钮，您必须点击页面右侧的三点状垂直椭圆图标。

2. 点击添加映射，然后选择添加默认网域以将网域映射到集群中的所有服务。默认情况下，您部署的新服务会使用映射网域。

3. 点击复选框以将新网域映射应用于集群中的所有现有服务。

4. 从“添加映射”表单的下拉列表中，选择要将自定义网域映射到的集群：

5. 输入域名。 例如 your-domain.com 或 subdomain.your-domain.com。网域要求：

   • 系统不支持基本路径映射。术语“基本路径”是指域名之后的网址路径名称。例如，users 是 your-domain.com/users 的基本路径。Knative serving 仅允许您将网域映射至 /，而不能映射到特定的基本路径。因此，必须通过在服务容器内使用路由器或使用 Firebase Hosting 来处理任何路径路由。
   • 您不能将您的网域映射到与您的服务网址匹配的子网域。服务的网址定义为 http://{service}.{namespace}.{your-domain.com}，因此如果您在 test.default.your-domain.com 中有服务，则不能创建映射到同一子网域 test.default.your-domain.com 的网域映射。

6. 点击继续。

7. 访问您的网域注册商网站，并使用上一步中显示的 DNS 记录更新您的 DNS 记录。您可以随时显示上步中所示的 DNS 记录，点击网域映射所对应“...”操作菜单中的 DNS 记录即可。

8. 点击完成。

kubectl

1. 运行以下命令，从 config-domain ConfigMap 中移除现有基本网域，并将其替换为您的自定义网域：

   kubectl patch configmap config-domain --namespace knative-serving --patch \
   '{"data": {"nip.io": null, "DOMAIN": ""}}'

   将 DOMAIN 替换为您的自定义网域。例如 your-domain.com 或 subdomain.your-domain.com。 网域要求：

   • 系统不支持基本路径映射。术语“基本路径”是指域名之后的网址路径名称。例如，users 是 your-domain.com/users 的基本路径。Knative serving 仅允许您将网域映射至 /，而不能映射到特定的基本路径。因此，必须通过在服务容器内使用路由器或使用 Firebase Hosting 来处理任何路径路由。
   • 您不能将您的网域映射到与您的服务网址匹配的子网域。服务的网址定义为 http://{service}.{namespace}.{your-domain.com}，因此如果您在 test.default.your-domain.com 中有服务，则不能创建映射到同一子网域 test.default.your-domain.com 的网域映射。

现在，您的自定义网域已映射到 Knative serving，您必须在域名注册商处添加 DNS 记录。

在网域注册商处添加 DNS 记录

在 Knative serving 中，将服务映射到自定义网域后，您需要在域名注册商处更新 DNS 记录。为方便起见，Knative serving 会生成并显示您需要输入的 DNS 记录。您必须在域名注册商处添加这些记录以指向 Knative serving 服务，映射才能生效。

如果您使用 Cloud DNS 作为 DNS 提供商，请参阅添加记录。

注意：一些第三方 CDN 提供商可能会在无意中拦截验证请求，从而阻止这些请求到达 Knative serving 服务并导致网域映射失败或其证书无法续订。例如，如果您使用的是 Cloudflare CDN，则应在“SSL/TLS”标签页的“Edge Certificates”标签页中关闭“Always use https”选项。

1. 按照以下方式检索网域映射的 DNS 记录信息：

   控制台

   1. 前往 Knative serving 网域映射页面：

      前往“网域映射”

   2. 点击服务右侧的三点状垂直椭圆图标，然后点击 DNS 记录以显示所有 DNS 记录：

   gcloud

   gcloud run domain-mappings describe --domain DOMAIN

   将 DOMAIN 替换为您的自定义网域。例如 your-domain.com 或 subdomain.your-domain.com。

   您需要在 resourceRecords 标题下返回的所有记录。

2. 访问域名注册商并登录您的账号，然后打开 DNS 配置页面。

3. 找到网域配置页面的主机记录部分，然后添加您在将网域映射到 Knative serving 服务时收到的各条资源记录。

4. 在 DNS 提供商处将上述各 DNS 记录添加到账号时，请按如下所述操作：

   • 选择上一步中 DNS 记录返回的类型：A、AAAA 或 CNAME。
   • 使用名称 www 映射到 www.your-domain.com。
   • 使用名称 @ 映射 your-domain.com。
   • 使用通配符 * 来映射到 *.your-domain.com。

5. 保存您在网域账号的 DNS 配置页面中所做的更改。在大多数情况下，这些更改只需几分钟即可生效，但在某些情况下，可能需要几个小时，具体取决于注册商以及网域的任何先前 DNS 记录的存留时间 (TTL)。您可以使用 dig 工具（如此在线 dig 版本）确认 DNS 记录已成功更新。

6. 通过浏览您的新服务网址（例如 https://www.your-domain.com）来测试是否成功。请注意，发放代管式 SSL/TLS 证书可能需要几分钟的时间。

将已通过验证的域名所有者添加到其他用户或服务账号

当某位用户验证网域时，网域仅会针对该用户的账号进行验证。这意味着，只有该用户才能添加使用这个网域的其他网域映射。因此，要使其他用户能够添加使用这个网域的映射，您必须将这些用户添加为已通过验证的所有者。

注意：经过验证的域名所有者可以在确认后替换来自其他项目的现有网域映射。

如果您需要将经过验证的域名所有者添加到其他用户或服务账号，则可以通过 Search Console 页面添加权限：

1. 使用网络浏览器导航到以下地址：

   https://search.google.com/search-console/welcome

2. 在属性下，点击要为其添加用户或服务账号的网域。

3. 向下滚动到已验证所有者列表，点击添加所有者，然后输入 Google 账号电子邮件地址或服务账号 ID。

   如需查看您的服务账号列表，请打开 Google Cloud 控制台中的“服务账号”页面：

   转到“服务账号”页面

在 Knative serving 控制台中向 Cloud Domains 注册网域

预览 — Registering a domain with Cloud Domains within the Knative serving console

此功能须遵守服务专用条款的“通用服务条款”部分中的“非正式版产品条款”。 非正式版功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅发布阶段说明。

如需在 Knative serving 控制台中向 Cloud Domains 注册网域，请执行以下操作：

1. 前往 Knative serving 网域映射页面：

   前往“网域映射”

2. 点击注册网域。

3. 按照注册网域中的说明完成注册流程。

4. 完成本页面前面的步骤，以将您的网域映射到 Knative serving，然后在您的网域注册商处添加 DNS 记录。

问题排查

查看排查自定义网域和代管式 TLS 问题中的常见问题。