本节面向 2025 年 5 月 15 日之前创建的存量 VKE 托管集群，说明如何开启 API Server 私网域名访问能力，并完成存量组件与存量节点的配置切换。

背景信息

为提升集群控制面的性能和稳定性，自 2026 年 5 月 15 日起新建的 VKE 托管集群中，节点侧组件访问 API Server 的链路将逐步从 CLB VIP 访问切换为通过私网域名访问。详细说明，请参见产品公告。

在此之前创建的存量集群，可自定义开启 API Server 私网域名访问能力。开启后，节点侧组件（如 kubelet、kube-proxy、vpc-cni）可从使用 CLB VIP 访问 API Server 切换为使用私网域名动态解析至 API Server ENI 后直通访问，提升节点侧组件访问 API Server 的性能和稳定性。

使用说明

开启 API Server 私网域名访问能力仅适用于 VKE 托管集群。

以下集群已默认启用 API Server 私网域名，无需手动启用：

2026 年 5 月15 日以后新建的 VKE 托管集群。

通过 ListClusters 查询集群是否已开启 API Server 私网域名访问，若KubernetesConfig.AdvancedConfig.InternalDnsEnabled为true，则表明已启用。

前置检查

执行操作前，请务必完成以下检查，否则会导致节点无法连接 API Server。

检查安全组配置。

开启直连后，流量将直达 API Server 的 ENI。需确保其 ENI 所在安全组规则允许直连。

检查节点及节点弹性网卡的安全组出方向，确保未禁止访问 6443 端口。

检查 DNS 解析配置。

API Server 域名解析依赖 VPC 默认内网 DNS（100.96.0.2和100.96.0.3）。

默认情况：若节点使用默认 DNS 配置，无需额外操作。

自定义 DNS：若在节点或容器上配置了自定义 DNS 服务器，需确保该 DNS 服务器能将*.ivolces.com或 API Server 域名转发给 VPC 默认内网 DNS 进行解析。详细操作，请参见私网解析 PrivateZone 快速入门。

操作步骤

步骤一：开启 API Server 私网域名解析

调用 UpdateClusterConfig 接口，在集群 VPC 内创建内网解析记录。

请求体示例如下所示：

{
"KubernetesConfig": {
"AdvancedConfig": {
"InternalDnsEnabled": true
}
}
}

更新过程中，API Server 会自动重启。您可以在容器服务控制台目标集群管理页的集群任务页面查询状态。

任务完成，调用 ListClusters 接口，查询KubernetesConfig.AdvancedConfig.InternalDnsEnabled参数取值，若取值为true，表示配置已生效。

步骤二：验证私网域名生效情况

修改存量节点前，通过创建新节点或新 Pod 来验证域名解析是否已对新增资源生效。

ECS 节点验证

VCI Pod 验证

在集群中扩容一个新节点，新节点的 kubelet 自动使用私网域名。扩容节点相关操作，请参见新增节点。

待节点就绪后，通过 ECS Terminal 方式登录节点，并执行以下命令查看其 kubelet 配置文件的 Server 地址是否为私网域名。

cat /etc/kubernetes/kubelet.conf

步骤三：重建存量集群中重要组件 Pod 使新配置生效

Flannel 网络模型集群

VCP-CNI 网络模型集群

Flannel 网络模型下重建存量 kube-proxy Pod 使新配置生效。

注意

为确保业务平稳，建议先在测试环境或开发环境中分批删除 Pod，观察 Pod 重建正常后再到生产环境执行删除操作。

API Server 域名生效后，VKE 会自动将 kube-proxy 的连接地址配置从 IP 切换为该域名。需要重建其存量 Pod 以加载新配置。

登录容器服务控制台。

在集群页面，单击目标 Flannel 网络模型集群名称。

在集群管理页面左侧导航栏，选择配置管理 > 配置项。

选择 kube-system 命名空间，查看 kube-proxy 配置项下的kubeconfig.conf是否生效。

删除 kube-proxy DaemonSet 下的 Pod，使其重建并加载新配置。

方法一
通过控制台手动删除存量 kube-proxy Pod。Pod 重建并加载新配置。
左侧导航栏选择工作负载 > 守护进程。
选择 kube-system 命名空间，找到 kube-proxy 守护进程，单击名称。
在 kube-proxy 详情页的实例列表页面逐一删除 Pod，使其重建并加载新配置。
方法二
您也可以通过 kubectl 命令，滚动更新 DaemonSet kube-proxy，使新配置在存量 kube-proxy Pod 中生效。
通过 kubectl 连接目标集群。详细操作，请参见使用 kubectl 连接集群。
执行以下命令，滚动更新 DaemonSet kube-proxy。

kubectl rollout restart daemonset kube-proxy -n kube-system

执行以下命令查看滚动更新结果。

kubectl rollout status daemonset kube-proxy -n kube-system

预期返回结果如下：

daemonset "kube-proxy" successfully rolled out

步骤四：修改存量节点的 kubelet 配置

更新存量节点的 kubelet 配置并重启服务，完成向私网域名访问的切换。为确保集群稳定性，本小节分为单节点验证和批量运维两部分。

单节点验证。

选择一个存量节点，通过 ECS Terminal 方式登录节点，并执行以下命令，将 API Server 地址从 IP 切换为域名，并重启 kubelet。

# 以下为单行命令，将替换配置与重启服务合并执行
sed -i.bak 's#https://{clb-ip}:6443#https://{cluster-id}.vke.{region-id}.ivolces.com:6443#g' /etc/kubernetes/kubelet.conf && \
systemctl restart kubelet && \
systemctl status kubelet

命令中的变量说明如下：

变量	说明
{clb-ip}	当前节点/etc/kubernetes/kubelet.conf中配置的 CLB IP。在节点上执行 cat /etc/kubernetes/kubelet.conf命令，查看server参数的中 CLB IP。
{cluster-id}	集群 ID。可在集群概览页面获取。
{region-id}	地域 ID。请参见服务地址获取地域 ID（RegionId）。

完整示例如下：

sed -i.bak 's#https://10.**.**.**:6443#https://cd6ptisscv4o*********.vke.cn-beijing.ivolces.com:6443#g' /etc/kubernetes/kubelet.conf && \
systemctl restart kubelet && \
systemctl status kubelet

完成后，在容器服务控制台节点管理 > 节点页面观察节点，确保处于运行中状态。

单节点验证成功后，在云服务器控制台使用云助手功能，对剩余的存量节点分批次进行批量操作。

您需要在云助手页面，创建作业。其中部分参数，按如下表说明配置，其余操作和参数配置，请参见创建作业。

参数	说明
执行命令
命令来源	选择手工输入。
命令类型	选择 Linux Shell，然后输入如下代码块内容。 # 在执行命令的命令内容中，填入以下参数 sed -i.bak 's#https://{clb-ip}:6443#https://{cluster-id}.vke.{region-id}.ivolces.com:6443#g' /etc/kubernetes/kubelet.conf && systemctl restart kubelet
执行对象	选对 VKE 集群内节点对应的 ECS 实例。您可以在容器服务控制台节点管理 > 节点页面查看节点对应的实例 ID。

等待作业执行完成，观测节点状态无误后重复此操作，直至完成存量节点的更新。

容器服务