Help Center/ Cloud Container Engine/ User Guide/ Clusters/ Connecting to a Cluster/ Accessing a Cluster Using a Custom Domain Name
Updated on 2025-02-18 GMT+08:00
View PDF
Share

Accessing a Cluster Using a Custom Domain Name

Scenario

Subject Alternative Name (SAN) allows multiple values (including IP addresses, domain names, and so on) to be associated with certificates. A SAN is usually used by the client to verify the server validity in TLS handshakes. Specifically, the validity check includes whether the server certificate is issued by a CA trusted by the client and whether the SAN in the certificate matches the IP address or DNS domain name that the client actually accesses.

If the client cannot directly access the private IP or EIP of the cluster, you can sign the IP address or DNS domain name that can be directly accessed by the client into the cluster server certificate as a SAN to enable two-way authentication on the client, which improves security. Typical use cases include DNAT access and domain name access.

If you have particular proxy access requirements or need to access resources in other regions, you can customize a SAN. Typical domain name access scenarios:

  • Add the domain name mapping by either adding the DNS domain name address in the host domain name configuration on the client or configuring /etc/hosts on the client host.
  • Use domain name access in the intranet. DNS allows you to configure mappings between cluster EIPs and custom domain names. After an EIP is updated, you can continue to use two-way authentication and the domain name to access the cluster without downloading the kubeconfig.json file again.
  • Add A records on a self-built DNS server.

Prerequisites

A cluster of v1.19 or later is available.

Customizing a SAN

  1. Log in to the CCE console.
  2. Click the name of the target cluster in the cluster list to go to the cluster Overview page.
  3. In the Connection Information area, click next to Custom SAN. In the dialog box displayed, enter the IP address or domain name and click Save.

    Figure 1 Custom SAN

    • The kube-apiserver will be restarted and the kubeconfig certificate will be updated, which will take approximately 5 minutes. Do not perform any operations on the cluster during this period. After the operation is complete, download the updated kubeconfig certificate.
    • A maximum of 128 domain names or IP addresses, separated by commas (,), are allowed.
    • If a custom domain name needs to be bound to an EIP, ensure that you have configured an EIP.

Connecting to a Cluster Using the SAN

Using kubectl to access the cluster

  1. Download the kubeconfig.json file again after the SAN is modified.

    1. Log in to the CCE console and click the cluster name to access the cluster console.
    2. On the Overview page, locate the Connection Info area, click Configure next to kubectl. On the page displayed, download the configuration file.

  2. Configure kubectl.

    1. Log in to your client and copy the kubeconfig.json file downloaded in 1.b to the /home directory on your client.
    2. Configure the kubectl authentication file. 
      cd /home
mkdir -p $HOME/.kube
mv -f kubeconfig.json $HOME/.kube/config
    3. Change the kubectl access mode and use the SAN to access the cluster. 
      kubectl config use-context customSAN-0

      In the preceding command, customSAN-0 indicates the configuration name of the custom SAN. If multiple SANs are configured, the number in the configuration name of each SAN starts from 0 and increases in ascending order, for example, customSAN-0, customSAN-1, and so on.

Using an X.509 certificate to access the cluster

  1. After the SAN is modified, download the X.509 certificate again.

    1. Log in to the CCE console and click the cluster name to access the cluster console.
    2. On the Overview page, locate the Connection Info area, and click Download next to X.509 certificate.
    3. In the Obtain Certificate dialog box displayed, select the certificate expiration time and download the X.509 certificate of the cluster as prompted.

  2. Call native Kubernetes APIs using the cluster certificate.

    For example, run the curl command to call an API to obtain the pod information. In the following information, example.com:5443 indicates the custom SAN.

    curl --cacert ./ca.crt --cert ./client.crt --key ./client.key  https://example.com:5443/api/v1/namespaces/default/pods/

    For more cluster APIs, see Kubernetes API.

Parent Topic: Connecting to a Cluster