This topic describes how to enable API Server private domain access for existing VKE-managed clusters created before May 15, 2025, and adjust configurations for existing components and nodes accordingly.

Background

For VKE-managed clusters created on or after May 15, 2026, access to the control plane (API Server) by node-side components will be gradually migrated from CLB VIP access to internal domain-based access to enhance cluster control-plane performance and stability. For details, see Product announcement.

You can also choose to manually enable API Server private domain access for existing clusters created before this date. If you enable this access method, node-side components (such as kubelet, kube-proxy, and vpc-cni) will switch API Server access from the CLB VIP approach to the direct access mode, where the private domain name is dynamically resolved to the API Server ENI. This improves the performance and stability of node-side components' access to the API Server.

Usage instructions

API Server private domain access applies only to VKE-managed clusters.

The following clusters have API Server private domain access enabled by default:

VKE-managed clusters created on or after May 15, 2026.

You can check whether a cluster has API Server private domain access enabled by calling the ListClusters API. If the KubernetesConfig.AdvancedConfig.InternalDnsEnabled parameter in the response is true, private domain access is enabled.

Pre-checks

Before you begin, be sure to complete the following checks. Otherwise, nodes will fail to connect to the API Server.

Check security group configurations.

When the direct connection mode is enabled, traffic is directly sent to the ENI of the API Server. Therefore, ensure that the security group rules associated with the ENI allow direct connections.

Confirm that security groups for the nodes and ENIs allow ‌outbound traffic on port 6443.

Check DNS resolution configurations.

API Server domain name resolution relies on the default private DNS servers (100.96.0.2 and 100.96.0.3) within the VPC.

Default DNS configuration: If nodes use the default DNS configuration, no additional operation is required.

Custom DNS configuration: If you have configured a custom DNS server on nodes or containers, ensure the DNS server forwards requests for *.ivolces.com or API Server domain names to the VPC's default private DNS servers for resolution. For detailed steps, see Getting started with PrivateZone.

Procedure

Step 1: Enable API Server private domain resolution

Call the UpdateClusterConfig API to create an internal network resolution record within the VPC of the cluster.

The following is an example of the request body:

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

During the update process, the API Server will restart automatically. You can check the status in the Cluster jobs module of the cluster management page in the VKE console.

After the job is complete, call the ListClusters API and check the response for the value of the KubernetesConfig.AdvancedConfig.InternalDnsEnabled parameter. If the value is true, the configuration has taken effect.

Step 2: Verify the effectiveness of the private domain name

Before modifying the configuration of existing nodes, first verify that domain name resolution takes effect for new resources by creating new nodes or Pods.

Verify ECS nodes

Verify VCI Pods

Add a new node to the cluster. The kubelet on the new node automatically uses the private domain name. For node scale-out details, see Adding nodes.

After the node is ready, log in to the node via the ECS Terminal and run the following command to check whether the server address in the kubelet configuration file is the private domain name.

cat /etc/kubernetes/kubelet.conf

Step 3: Recreate Pods for key components in the existing cluster to apply the new configuration

Flannel cluster

VCP-CNI cluster

In the Flannel cluster, recreate the existing kube-proxy Pods to apply the new configuration.

warning

To ensure business stability, delete Pods in batches in the test or development environment first and verify that the Pods are recreated before deleting Pods in the production environment.

After the API Server domain name takes effect, VKE automatically switches the kube-proxy connection configuration from the IP address to this domain name. You need to recreate its existing Pods to load the new configuration.

Log in to the VKE console.

On the Cluster page, click the name of the target Flannel cluster.

In the left navigation pane of the cluster management page, click Configurations > ConfigMap.

Select the kube-system namespace and check whether kubeconfig.conf in the kube-proxy configuration is effective.

Delete the Pods in the kube-proxy DaemonSet to recreate them and load the new configuration.

Method 1
Delete existing kube-proxy Pods manually through the console. The Pods will be recreated and load the new configuration.
In the left navigation pane, click Workload > DaemonSet.
Select the kube-system namespace, find the kube-proxy DaemonSet, and click the name of the DaemonSet.
On the List of instances page of the kube-proxy details page, delete the Pods one by one to recreate them and load the new configuration.
Method 2
Alternatively, perform a rolling update on the kube-proxy DaemonSet via kubectl to apply the new configuration to all kube-proxy Pods.
Connect to the target cluster using kubectl. For details, see Connecting to clusters via kubectl.
Run the following command to perform a rolling update on the kube-proxy DaemonSet.

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

Run the following command to view the result of the rolling update.

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

The expected response is as follows:

daemonset "kube-proxy" successfully rolled out

Step 4: Modify the kubelet configurations of existing nodes

Update the kubelet configurations of existing nodes and restart the service to complete the switch to private domain-based access. To ensure cluster stability, this section covers two procedures: single-node verification and batch O&M.

Perform single-node verification.

Log in to an existing node using the ECS Terminal, run the following command to switch the API Server address from its IP to its domain name, and then restart kubelet.

# The following single-line command replaces the configuration and restarts the service.
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

The following table describes the variables in the command:

Variable	Description
{clb-ip}	The CLB IP address specified in the /etc/kubernetes/kubelet.conf configuration of the node. Run the cat /etc/kubernetes/kubelet.conf command on the node to view the CLB IP address in the server parameter.
{cluster-id}	Cluster ID. You can obtain it on the Overview page of the cluster.
{region-id}	Region ID. To obtain the ID (RegionId) of a specific region, see Service addresses.

The complete example is as follows:

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

In the VKE console, go to Nodes > Node to verify that the node is in the Running state.

After single-node verification is successful, use the Cloud Assistant feature in the ECS console to operate on the remaining existing nodes in batches.

You need to create a job on the Cloud Assistant page. Configure some parameters as described in the following table. For other steps and parameters, see Creating jobs.

Parameter	Description
Command
Command source	Select Manual input.
Command type	Select Linux Shell and enter the following code. # Enter the following parameters in the command content. 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
Object	Select the ECS instance corresponding to the node in the VKE cluster. You can obtain the Instance ID corresponding to the node from Nodes > Node in the VKE console.

Wait for the job to complete. After confirming that the node status is normal, repeat this operation until all existing nodes have been updated.

Volcengine Kubernetes Engine