文档中心

容器服务

请输入

连接集群

使用自定义域名连接集群

本文介绍如何通过为集群的 kube-apiserver 证书添加主题备用名称（Subject Alternative Name，SAN），实现使用自定义域名连接 VKE 集群。

应用场景

SAN 是 X.509 证书的一项扩展，允许将 IP 地址、DNS 域名等多种 Value 与同一份证书关联。在 TLS 握手过程中，客户端会校验服务端证书的合法性，其中包括检查证书的 SAN 字段是否与客户端实际访问的地址匹配。

在 VKE 中，当客户端因网络环境限制而无法直接使用 kube-apiserver 的默认地址（内网 IP 或公网 EIP）时，您可以为集群的 kube-apiserver 证书添加自定义 SAN，将客户端可访问的代理 IP 或域名签入证书。这样，即使通过中间地址访问，kubectl 等客户端依然能够完成服务端证书校验，建立安全的双向认证连接。

典型的应用场景包括：

DNAT 代理访问：客户端通过网络地址转换（DNAT）设备访问 kube-apiserver，实际访问 IP 与 kube-apiserver 的 IP 不一致。

跨云或本地数据中心连接：位于其他云厂商或本地数据中心（IDC）的客户端，需要通过特定的域名或固定 IP 连接 VKE 集群。

统一域名访问：为多个集群的 kube-apiserver 配置统一域名，通过 DNS 解析管理访问入口，避免因 IP 变更而频繁修改客户端配置。

前提条件

在开始操作前，请确保满足以下条件：

自定义域名准备：已准备好计划使用的自定义域名，并完成 DNS 解析配置，将该域名指向客户端可访问、且能路由到 kube-apiserver 的 IP 地址（如代理 IP 或负载均衡 IP）。此步骤需要您自行实现。

网络可达性：客户端必须能够通过网络访问您计划添加为 SAN 的自定义 IP 或域名，并且该 IP 或域名最终能路由到集群的 kube-apiserver。

操作权限：请确保已拥有修改 VKE 集群配置的相关权限。详细操作，请参见配置 RBAC 权限。

操作步骤

步骤一：添加自定义 SAN

通过控制台添加

通过 API 添加

您可以在 VKE 控制台为新建或已有的集群添加自定义 SAN。

注意

修改自定义 SAN 会触发 kube-apiserver 组件短暂重启以加载新证书，此过程通常持续数分钟。为避免影响业务，建议在业务低峰期执行此操作。kube-apiserver 重启期间，集群管理操作可能会短暂中断。

登录容器服务控制台。

在左侧导航栏中选择集群，单击目标集群名称，进入集群管理页面。

在集群总览页面的概览页签，找到自定义证书 SAN 参数，单击参数后的编辑图标。

在弹出的对话框中，输入或粘贴符合规范的自定义 IP、域名或 URI，多个配置以中英文逗号、回车或空格分隔。

说明

最多支持 6 条自定义证书 SAN。

单击确定保存更改。

步骤二：使用 SAN 连接集群

成功添加自定义 SAN 并等待 kube-apiserver 重启完成后，您可以通过 kubectl 使用自定义域名连接集群。

通过 kubectl 连接目标集群。具体操作说明，请参见通过 kubectl 连接集群。

复制集群的私网访问凭证，并将其保存为kubeconfig本地文件。

说明

集群私网访问凭证获取方法，请参见访问凭证管理。

echo '在此粘贴您复制的私网访问凭证内容' > ~/cluster-private.kubeconfig
export KUBECONFIG=~/cluster-private.kubeconfig

执行如下命令，将私网访问凭证中的server地址替换为您的自定义域名。

sed -i 's#${old-server-address}#https://${your-custom-domain}:6443#g' ~/cluster-private.kubeconfig
## 将 ${old-server-address} 替换为集群私网访问凭证中 server 参数的原始值。
## 将 ${your-custom-domain} 替换为您的自定义域名。
## 完整示例如下:
## sed -i 's#https://192.168.214.185:6443#https://xxx.example.com:6443#g' ~/cluster-private.kubeconfig

执行以下命令，检查替换自定义域名后是否能成功连接到集群。

kubectl cluster-info

预期回显如下，若包含您配置的自定义 SAN 地址，则说明配置成功。

Kubernetes control plane is running at https://${your-custom-domain}:6443
CoreDNS is running at https://${your-custom-domain}:6443/api/v1/namespaces/kube-system/services/coredns:dns/proxy
...

后续操作

为保证集群访问的安全性，请了解容器服务提供的安全组。详情请参见安全组设置。

最近更新时间：2026.06.16 19:42:03

这个页面对您有帮助吗？

有用

无用