Docs

Volcengine Kubernetes Engine

Connecting to clusters

Connecting to clusters using custom domain names

This topic describes how to add a Subject Alternative Name (SAN) to the kube-apiserver certificate of a VKE cluster to connect to the cluster by using a custom domain name.

Application scenarios

SAN is an extension of the X.509 certificate. It allows multiple values, such as IP addresses and domain names, to be associated with the same certificate. During the TLS handshake, the client validates the legitimacy of the server certificate, including checking whether the SAN field of the certificate matches the address accessed by the client.

In VKE, when the client cannot directly use the default address of the kube-apiserver (private network IP or EIP) because of network limitations, you can add a custom SAN to the kube-apiserver certificate of a cluster. This adds the proxy IP or domain name accessible to the client to the certificate. In this way, even when accessing through an intermediate address, clients such as kubectl can still complete server certificate verification and establish a secure mutual TLS connection.

Typical application scenarios include:

DNAT proxy access: Clients access kube-apiserver through a Destination Network Address Translation (DNAT) device, and the actual accessed IP is different from the kube-apiserver IP.

Cross-cloud or on-premises data center connection: Clients located in other cloud providers or on-premises data centers (IDC) need to connect to a VKE cluster via a specific domain name or fixed IP.

Unified domain access: Configure a unified domain for kube-apiserver across multiple clusters and manage access entries via DNS resolution. This prevents frequent client configuration changes due to IP changes.

Prerequisites

Before performing an operation, make sure that the following conditions are met:

Custom domain name: You have prepared a custom domain to be used and configured DNS resolution to point the domain to an IP address that is accessible to the client and can route to kube-apiserver (such as the proxy IP or load balancer IP). You need to perform this step by yourself.

Network reachability: The client must be able to access the custom IP or domain to be added as a SAN over the network, and the IP or domain must ultimately route to the kube-apiserver of the cluster.

Operation permissions: Make sure that you have the necessary permissions to modify VKE cluster configurations. For detailed operations, see Granting RBAC permissions.

Procedure

Step 1: Add a custom SAN

Use the console

Use the API

You can add a custom SAN for a new or existing cluster in the VKE console.

warning

Modifying custom SANs will trigger a brief restart of the kube-apiserver add-on to load the new certificate. This typically lasts a few minutes. To prevent your business from being affected, we recommend performing this operation during off-peak hours. During the kube-apiserver restart, cluster management operations may be briefly interrupted.

In the left navigation bar, click Cluster. In the right part of the page, click the target cluster name to go to its management page.

On the Overview tab of the Overview page for the cluster, find the SAN domain name parameter, and click the edit icon next to the parameter.

In the pop-up dialog, enter or paste the custom IP addresses, domain names, or URIs that meet the requirements. Separate multiple entries with Chinese or English commas, line breaks, or spaces.

tip

Up to six SANs are supported.

Click Confirm to save the changes.

Step 2: Use the SAN to connect to the cluster

After the custom SAN is added and the kube-apiserver is restarted, you can use kubectl to connect to the cluster by using the custom domain name.

Connect to the target cluster using kubectl. For details, see Connecting to clusters using kubectl.

Copy the private network access credentials of the cluster and save them as a local kubeconfig file.

tip

For the method of obtaining the private network access credentials of a cluster, see Managing access credentials.

echo 'Paste_your_copied_private_network_kubeconfig_here' > ~/cluster-private.kubeconfig
export KUBECONFIG=~/cluster-private.kubeconfig

Run the following command to replace the server address in the private network access credentials with your custom domain name.

sed -i 's#${old-server-address}#https://${your-custom-domain}:6443#g' ~/cluster-private.kubeconfig
## Replace ${old-server-address} with the original value of the server parameter of the cluster private network access credentials.
## Replace ${your-custom-domain} with your custom domain name.
## The complete example is as follows:
## sed -i 's#https://192.168.214.185:6443#https://xxx.example.com:6443#g' ~/cluster-private.kubeconfig

Run the following command to check whether you can connect to the cluster after the replacement.

kubectl cluster-info

The expected output is as follows. If it includes the custom SAN address you configured, the configuration is successful.

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
...

Subsequent operations

To ensure secure cluster access, learn about the security group settings provided by VKE. For details, see Configuring security groups.

Last updated: 2026.07.24 10:53:34