doc-exports/docs/cce/umn/cce_10_0367.html

<a name="cce_10_0367"></a><a name="cce_10_0367"></a>

<h1 class="topictitle1">Accessing a Cluster Using a Custom Domain Name</h1>
<div id="body0000001213596583"><div class="section" id="cce_10_0367__section33802116582"><h4 class="sectiontitle">Scenario</h4><p id="cce_10_0367__p59101350161213">Subject Alternative Name (<span class="keyword" id="cce_10_0367__keyword231114694619">SAN</span>) enables certificates to be associated with multiple values, including IP addresses and domain names. 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.</p>
<p id="cce_10_0367__p8678206135818">If a client cannot access the cluster's private IP address or EIP, add the client's accessible IP address or DNS domain name to the cluster server certificate as a SAN. This enhances security through two-way authentication. Typical use cases include DNAT access and domain name access.</p>
<p id="cce_10_0367__p1244315351158">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:</p>
<ul id="cce_10_0367__ul54106529187"><li id="cce_10_0367__li741065217186">Add the domain name mapping by either adding the DNS domain name address in the host domain name configuration on the client or configuring <strong id="cce_10_0367__b185291228388">/etc/hosts</strong> on the client host.</li><li id="cce_10_0367__li11410205215185">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 <strong id="cce_10_0367__b81618387398">kubeconfig.json</strong> file again.</li><li id="cce_10_0367__li6410952151810">Add A records on a self-built DNS server.</li></ul>
</div>
<div class="section" id="cce_10_0367__section1830417304596"><h4 class="sectiontitle">Prerequisites</h4><p id="cce_10_0367__p743513488317">A cluster of v1.19 or later is available.</p>
</div>
<div class="section" id="cce_10_0367__section13739162465410"><h4 class="sectiontitle">Adding a Custom SAN</h4><p id="cce_10_0367__p180423855614">You can add a custom SAN on the CCE console. To do so, perform the following operations:</p>
<ol id="cce_10_0367__ol14222161910276"><li id="cce_10_0367__li522271918277"><span>Log in to the <span id="cce_10_0367__ph730841015112615">CCE console</span>.</span></li><li id="cce_10_0367__li88264265271"><span>Click the name of the target cluster in the cluster list to go to the cluster <strong id="cce_10_0367__b1421542641913"><span id="cce_10_0367__text999619481471">Overview</span></strong> page.</span></li><li id="cce_10_0367__li1942836112713"><span>In the <strong id="cce_10_0367__b11906134417264">Connection Information</strong> area, click <span><img id="cce_10_0367__image194171230112913" src="en-us_image_0000002483959210.png"></span> next to <strong id="cce_10_0367__b04361849172613">Custom SAN</strong>. In the dialog box displayed, enter the IP addresses or domain names and click <strong id="cce_10_0367__b1062916962814">Save</strong>.</span><p><p id="cce_10_0367__p1138112428546"></p>
<div class="note" id="cce_10_0367__note182701752173012"><img src="public_sys-resources/note_3.0-en-us.png"><span class="notetitle"> </span><div class="notebody"><ul id="cce_10_0367__ul33951212205317"><li id="cce_10_0367__li1139518128534">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.</li><li id="cce_10_0367__li18395131225317">A maximum of 128 domain names or IP addresses, separated by commas (,), are allowed.</li><li id="cce_10_0367__li63959125533">If a custom domain name needs to be bound to an EIP, ensure that you have configured an EIP.</li></ul>
</div></div>
</p></li></ol>
</div>
<div class="section" id="cce_10_0367__section1436418499411"><h4 class="sectiontitle">Using kubectl to Access a Cluster</h4><p id="cce_10_0367__p14140647151512">After the SAN is modified, the original <strong id="cce_10_0367__b191247435479">kubeconfig.json</strong> file becomes invalid. If you previously accessed the cluster using kubectl, you need to reconfigure the settings.</p>
<ol id="cce_10_0367__ol17846131318516"><li id="cce_10_0367__li8846101312517"><a name="cce_10_0367__li8846101312517"></a><a name="li8846101312517"></a><span>Download the <strong id="cce_10_0367__b234512111189">kubeconfig.json</strong> file again after the SAN is modified.</span><p><ol type="a" id="cce_10_0367__en-us_topic_0000001199501150_ol20671122104318"><li id="cce_10_0367__en-us_topic_0000001199501150_li3389103917354">Log in to the <span id="cce_10_0367__ph4430172615223">CCE console</span> and click the cluster name to access the cluster console.</li><li id="cce_10_0367__en-us_topic_0000001199501150_li2323134272411">On the <strong id="cce_10_0367__b693013152286"><span id="cce_10_0367__text95391546144915">Overview</span></strong> page, locate the <strong id="cce_10_0367__b10930171552814">Connection Information</strong> area, and click <strong id="cce_10_0367__b13930141562817">Configure</strong> next to <strong id="cce_10_0367__b5930141519281">kubectl</strong>. On the page displayed, download the configuration file.</li></ol>
</p></li><li id="cce_10_0367__li93971939454"><span>Configure kubectl.</span><p><ol type="a" id="cce_10_0367__en-us_topic_0000001199501150_ol1332622418367"><li id="cce_10_0367__en-us_topic_0000001199501150_li1614451114349">Log in to your client and copy the <strong id="cce_10_0367__b1980919192313">kubeconfig.json</strong> file downloaded in <a href="#cce_10_0367__li8846101312517">1</a> to the <strong id="cce_10_0367__b280912198319">/home</strong> directory on your client.</li><li id="cce_10_0367__en-us_topic_0000001199501150_li1865650183618">Configure the kubectl authentication file.<pre class="screen" id="cce_10_0367__en-us_topic_0000001199501150_screen849155210477">cd /home
mkdir -p $HOME/.kube
mv -f kubeconfig.json $HOME/.kube/config</pre>
</li><li id="cce_10_0367__en-us_topic_0000001199501150_li8390171813517">Change the kubectl access mode and use the SAN to access the cluster.<pre class="screen" id="cce_10_0367__en-us_topic_0000001199501150_screen279213242247">kubectl config use-context <i><span class="varname" id="cce_10_0367__en-us_topic_0000001199501150_varname11838011173815">customSAN-0</span></i></pre>
<p id="cce_10_0367__en-us_topic_0000001199501150_p1764912302388">In the preceding command, <i><span class="varname" id="cce_10_0367__varname148811637193810">customSAN-0</span></i> indicates the configuration name of the custom SAN. When multiple SANs are configured, each SAN is named with an incrementing number starting from <strong id="cce_10_0367__b0953093813">0</strong>, such as <i><span class="varname" id="cce_10_0367__varname11587111369">customSAN-0</span></i>, <i><span class="varname" id="cce_10_0367__varname55812113368">customSAN-1</span></i>, and more.</p>
</li></ol>
</p></li><li id="cce_10_0367__li155017201576"><span>Run the following command on the client to check whether the client can access the cluster using kubectl:</span><p><pre class="screen" id="cce_10_0367__en-us_topic_0000001244141061_screen58291715181113">kubectl cluster-info    # Check the cluster information.</pre>
<p id="cce_10_0367__en-us_topic_0000001244141061_p191970445126">If the following information is displayed, the client can access the cluster using kubectl:</p>
<pre class="screen" id="cce_10_0367__en-us_topic_0000001244141061_screen9391278393">Kubernetes control plane is running at https://xx.xx.xx.xx:5443
CoreDNS is running at https://xx.xx.xx.xx:5443/api/v1/namespaces/kube-system/services/coredns:dns/proxy
To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.</pre>
</p></li></ol>
</div>
<div class="section" id="cce_10_0367__section18190162591412"><h4 class="sectiontitle">Using an X.509 Certificate to Access a Cluster</h4><p id="cce_10_0367__p5502103619173">After the SAN is modified, the original X.509 certificate becomes invalid. If you previously accessed the cluster using the X.509 certificate, you need to reconfigure the settings.</p>
<ol id="cce_10_0367__ol77312314142"><li id="cce_10_0367__li2073153115147"><span>After the SAN is modified, download the X.509 certificate again.</span><p><ol type="a" id="cce_10_0367__en-us_topic_0000001199501150_ol991412569431"><li id="cce_10_0367__en-us_topic_0000001199501150_li4829928181812">Log in to the <span id="cce_10_0367__ph488913220220">CCE console</span> and click the cluster name to access the cluster console.</li><li id="cce_10_0367__en-us_topic_0000001199501150_li179831852301">On the <strong id="cce_10_0367__b1735417290441"><span id="cce_10_0367__text7440733504">Overview</span></strong> page, locate the <strong id="cce_10_0367__b1235482911446">Connection Information</strong> area, and click <strong id="cce_10_0367__b1535582904410">Download</strong> next to <strong id="cce_10_0367__b735552917443">X.509 certificate</strong>.</li><li id="cce_10_0367__en-us_topic_0000001199501150_li76691210154417">In the <span class="uicontrol" id="cce_10_0367__uicontrol3315191115449"><b>Obtain Certificate</b></span> dialog box displayed, select the certificate validity period and download the <span class="keyword" id="cce_10_0367__keyword1231511154413">X.509 certificate</span> of the cluster as prompted.</li></ol>
</p></li><li id="cce_10_0367__li190215711519"><span>Call Kubernetes native APIs using the cluster certificate.</span><p><p id="cce_10_0367__en-us_topic_0000001199501150_p1870145813497">For example, run the <strong id="cce_10_0367__b143551337184420">curl</strong> command to call an API to obtain the pod information. In the following information, <i><span class="varname" id="cce_10_0367__varname149655191957">example.com:5443</span></i> indicates the custom SAN.</p>
<pre class="screen" id="cce_10_0367__en-us_topic_0000001199501150_screen157018584498">curl --cacert <i><span class="varname" id="cce_10_0367__en-us_topic_0000001199501150_varname8215622133210">./ca.crt</span></i> --cert <i><span class="varname" id="cce_10_0367__en-us_topic_0000001199501150_varname414983110226">./client.crt</span></i> --key <i><span class="varname" id="cce_10_0367__en-us_topic_0000001199501150_varname1660914275228">./client.key</span></i>  https://<i><span class="varname" id="cce_10_0367__en-us_topic_0000001199501150_varname1534114227226">example.com:5443</span></i>/api/v1/namespaces/default/pods/</pre>
<p id="cce_10_0367__p1247614577288">If the following information is displayed, the X.509 certificate is correctly configured and the API Server of the cluster is running properly:</p>
<pre class="screen" id="cce_10_0367__screen3587204810306">{
  "kind": "PodList",
  "apiVersion": "v1",
...</pre>
<p id="cce_10_0367__en-us_topic_0000001199501150_p12685134972212">For more cluster APIs, see <a href="https://kubernetes.io/docs/reference/kubernetes-api/" target="_blank" rel="noopener noreferrer">Kubernetes API</a>.</p>
</p></li></ol>
</div>
</div>
<div>
<div class="familylinks">
<div class="parentlink"><strong>Parent topic:</strong> <a href="cce_10_0140.html">Accessing a Cluster</a></div>
</div>
</div>