为存量集群开启 API Server 内部域名访问

适用范围

• 仅适用于ACK托管集群Pro版，且集群版本为1.30及以上。

• 混合云节点池暂无法启用本功能。

• 以下集群已默认启用API Server内部域名，无需手动启用：

  • 2024年11月以后新建，且版本为1.20及以上的集群。

  • 通过DescribeClusterDetail查询，若internal_dns_config.enabled为true，则表明已启用。

变更和影响

• 网络路径变更与安全组影响：

  启用后，节点访问 API Server 的通信路径将从API Server负载均衡（CLB）固定 IP 地址切换为内部域名直连。

  • 变更前（CLB 转发）：节点 -> CLB IP -> API Server

  • 变更后（内网域名直连）：节点 -> (内部域名解析) -> API Server ENI

  这意味着流量将绕过 CLB，直接访问API Server ENI。因此，需确保节点所在安全组与其 ENI 所在安全组之间网络互通。

• 公网访问依赖：启用后，API Server对外的默认路由将变更为集群 VPC。若集群配置了依赖公网地址的 OIDC Issuer URL 或外部 Webhook，需确保集群 VPC 具备公网访问能力，否则API Server将无法连接外部服务。

• 配置生效范围：

  • 启用后，kubelet 和 kube-proxy 访问API Server的路径将由访问负载均衡（CLB）固定 IP 地址切换至直连 API Server ENI。

  • default 命名空间下的 kubernetes Service Endpoints 会由指向API Server CLB IP切换为 API Server ENI IP，允许集群内的 Operator 等应用直连。

前置检查

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

步骤一：开启API Server内部域名解析

调用OpenAPI ModifyCluster，在集群 VPC 内创建内网解析记录。本小节以默认情况为例，即节点使用阿里云默认内网 DNS。

如节点或容器使用自建 DNS 服务器，请参见下文自定义 DNS 说明。

1. 调用ModifyCluster，填写参数。

   {
       "control_plane_endpoints_config": {
           "internal_dns_config": {
               "enabled": true
           }
       }
   }

2. 更新过程中，API Server会自动重启。等待重启完成，通过DescribeClusterDetail查看internal_dns_config.enabled参数取值为true，确认配置生效。

步骤二：修改 kube-proxy 配置

API Server域名生效后，将 kube-proxy 的连接地址从 IP 切换为该域名。

1. 在ACK集群列表页面，单击目标集群名称，在集群详情页左侧导航栏，选择配置管理 > 配置项。

2. 命名空间选择 kube-system，定位 kube-proxy-worker和kube-proxy-worker-windows。

3. 逐一在 kubeconfig 字段中，定位 server 参数，修改为以下格式。

   https://apiserver.{cluster_id}.{region_id}.cs.aliyuncs.com:6443

   • {cluster_id}：集群 ID。

   • {region_id}：集群地域 ID（如 cn-hangzhou）。

步骤三：验证内部域名是否生效

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

• 节点池、灵骏节点池中的节点：

  在集群中扩容一个新节点，新节点的 kubelet 和 kube-proxy 将自动使用内部域名。

  待节点就绪后，登录节点，通过以下命令查看其kubelet配置文件的server地址是否为内部域名。

  cat /etc/kubernetes/kubelet.conf

• 虚拟节点：

  ACK Virtual Node组件需为v2.14.0及以上。

  开启内部域名后，新建的ECI Pod和ACS Pod默认通过内部域名与API Server交互。

  此时，新增一个Pod，Pod能够正常进入Ready状态。

步骤四：重建存量 kube-proxy Pod 使其生效

kube-proxy 配置更新后，重建其存量 Pod 以加载新配置。

1. 在ACK集群列表页面，单击目标集群名称，在集群详情页左侧导航栏，选择工作负载 > 守护进程集。

2. 命名空间选择 kube-system，定位并单击 kube-proxy-worker和kube-proxy-worker-windows，在容器组页签下，按照页面提示逐一删除其Pod，使其重建并加载新配置。

   重要

   为确保业务平稳，需采用灰度方式分批删除，观察 Pod 重建正常后再执行后续删除。

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

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

1. 单节点验证。

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

      • {clb-ip}：当前 /etc/kubernetes/kubelet.conf 中配置的 CLB IP

      • {cluster-id}：集群 ID

      • {region-id}：地域 ID

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

      示例如下：

      sed -i.bak 's#https://10.XX.XX.1:6443#https://apiserver.c34f3cdb665954e2f8e8e40a824a*****.cn-hangzhou.cs.aliyuncs.com:6443#g' /etc/kubernetes/kubelet.conf && systemctl restart kubelet

   2. 完成后，在控制台观察节点，确保处于就绪状态。

2. 批量运维剩余节点。

   单节点验证成功后，在控制台使用批量运维节点功能，对剩余的存量节点分批次进行批量操作。

   1. 在ACK集群列表页面，单击目标集群名称，在集群详情页左侧导航栏，选择节点管理 > 节点。

   2. 勾选待执行操作的节点，单击页面下方的批量运维，然后选择执行 Shell 命令。按照页面提示配置执行命令，提交批量任务的执行。

      # 在执行命令的命令内容中，填入以下参数
      sed -i.bak 's#https://{clb-ip}:6443#https://apiserver.{cluster-id}.{region-id}.cs.aliyuncs.com:6443#g' /etc/kubernetes/kubelet.conf && systemctl restart kubelet

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

附录

相关文档

• 【产品变更】关于ACK托管集群节点访问控制面（API Server）的链路切换公告

• Kube API Server