映射自定义网域

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

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

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

详细了解测试网域

准备工作

映射自定义网域

您可以使用 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.comsubdomain.your-domain.com。网域要求:

    • 系统不支持基本路径映射。术语“基本路径”是指域名之后的网址路径名称。例如,usersyour-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.comsubdomain.your-domain.com。 网域要求:
      • 系统不支持基本路径映射。术语“基本路径”是指域名之后的网址路径名称。例如,usersyour-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.comsubdomain.your-domain.com。网域要求:

    • 系统不支持基本路径映射。术语“基本路径”是指域名之后的网址路径名称。例如,usersyour-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.comsubdomain.your-domain.com。 网域要求:

    • 系统不支持基本路径映射。术语“基本路径”是指域名之后的网址路径名称。例如,usersyour-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 提供商,请参阅添加记录

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

    控制台

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

      前往“网域映射”

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

    gcloud

    gcloud run domain-mappings describe --domain DOMAIN

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

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

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

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

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

    • 选择上一步中 DNS 记录返回的类型:AAAAACNAME
    • 使用名称 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 注册网域

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

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

    前往“网域映射”

  2. 点击注册网域

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

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

问题排查

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