文档首页/ 云容器引擎 CCE/ 用户指南/ 集群/ 连接集群/ 通过自定义域名访问集群
更新时间：2025-07-18 GMT+08:00
查看PDF
分享

通过自定义域名访问集群

操作场景

主题备用名称（Subject Alternative Name，缩写SAN）允许将多种值（包括IP地址、域名等）与证书关联。SAN通常在TLS握手阶段被用于客户端校验服务端的合法性：服务端证书是否被客户端信任的CA所签发，且证书中的SAN是否与客户端实际访问的IP地址或DNS域名匹配。

当客户端无法直接访问集群内网私有IP地址或者弹性公网IP地址时，您可以将客户端可直接访问的IP地址或者DNS域名通过SAN的方式签入集群服务端证书，以支持客户端开启双向认证，提高安全性。典型场景例如DNAT访问、域名访问等特殊场景。

如果您有特殊的代理访问或跨域访问需求，可以通过自定义SAN实现。域名访问场景的典型使用方式如下：

  • 客户端配置Host域名指定DNS域名地址，或者客户端主机配置/etc/hosts，添加域名映射。
  • 云上内网使用，云解析服务DNS支持配置集群弹性IP与自定义域名的映射关系。后续更新弹性IP可以继续使用双向认证+自定义域名访问集群，无需重新下载kubeconfig.json配置文件。
  • 自建DNS服务器，自行添加A记录。

前提条件

已创建一个v1.19及以上版本的集群。

添加自定义SAN

您可以在CCE控制台中，添加自定义SAN，具体步骤如下：

  1. 登录CCE控制台。
  2. 在集群列表中单击集群名称，进入集群“概览”页。
  3. 在连接信息的自定义SAN处单击，在弹出的窗口中添加IP地址或域名，然后单击“保存”。

    图1 自定义SAN

    • 当前操作将会短暂重启kube-apiserver并更新kubeconfig证书，此动作大约耗时5分钟，请避免在此期间操作集群。更新完成后请重新下载kubeconfig证书。
    • 请输入域名或IP，以英文逗号（,）分隔，最多128个。
    • 自定义域名如需绑定弹性公网，请确保已配置公网地址。

使用SAN连接集群

修改SAN后，原有的kubeconfig.json配置文件和X509证书将会失效。如果您的客户端机器中已配置“通过kubectl连接集群”或“通过X509证书连接集群”，则需要重新配置，具体步骤如下：

修改SAN后，原有的kubeconfig.json配置文件将会失效。如果您之前是通过kubectl的方式连接集群，则需要重新配置。

  1. 修改SAN后，需重新下载kubeconfig.json配置文件。

    1. 登录CCE控制台，单击集群名称进入集群。
    2. 在集群“概览”页中的“连接信息”版块，单击kubectl后的“配置”按钮，查看kubectl的连接信息，并在弹出页面中下载配置文件。

  2. 配置kubectl。

    1. 登录到您的客户端机器，复制1中下载的配置文件（kubeconfig.json）到您客户端机器的/home目录下。
    2. 配置kubectl认证文件。 
      cd /home
mkdir -p $HOME/.kube
mv -f kubeconfig.json $HOME/.kube/config
    3. 切换kubectl的访问模式，使用SAN连接集群。 
      kubectl config use-context customSAN-0

      其中customSAN-0为自定义SAN对应的配置名称。如同时设置了多个SAN，每个SAN对应配置名称中的数字从0开始依次增大，例如customSAN-0、customSAN-1，以此类推。

  3. 在客户端中执行以下命令，检查客户端能否通过kubectl连接集群。 

    kubectl cluster-info    # 查看集群信息

    若回显结果如下，则说明客户端能够通过kubectl连接集群。

    Kubernetes control plane is running at https://xx.xx.xx.xx:5443
CoreDNS is running at https://xx.xx.xx.xx:5443/api/v1/namespaces/kube-system/services/coredns:dns/proxy
To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.

修改SAN后，原有的X509证书将会失效。如果您之前是通过X509证书的方式连接集群，则需要重新配置。

  1. 修改SAN后，需重新下载X509证书。

    1. 登录CCE控制台，单击集群名称进入集群。
    2. 查看集群“概览”页，在右边“连接信息”下证书认证一栏，单击“下载”。
    3. 在弹出的“证书获取”窗口中，根据系统提示选择证书的过期时间并下载集群X509证书。

  2. 使用集群证书调用Kubernetes原生API。

    例如使用curl命令调用接口查看Pod信息，如下所示，其中example.com:5443为自定义SAN。

    curl --cacert ./ca.crt --cert ./client.crt --key ./client.key  https://example.com:5443/api/v1/namespaces/default/pods/

    若回显结果如下，则说明X509证书配置正确且集群的API Server正常运行。

    {
  "kind": "PodList",
  "apiVersion": "v1",
...

    更多集群接口请参见Kubernetes API。

相关文档

父主题： 连接集群