How do I replace the cluster domain with minimal downtime?

Add the new domain and save the old one:

  1. In the controlPlaneManager.apiserver.certSANs section, enter the following parameters:
    • kubernetes.default.svc.<old clusterDomain>
    • kubernetes.default.svc.<new clusterDomain>
  2. In the kubeDns.clusterDomainAliases section, enter:
    • the old clusterDomain.
    • the new clusterDomain.
  3. Wait until kube-apiserver is restarted.
  4. Replace the old clusterDomain with the new one in dhctl config edit cluster-configuration

Important! If your Kubernetes version is 1.20 and higher, your controllers in the cluster use advanced ServiceAccount tokens to work with apiserver. Those tokens have extra fields iss: and aud: that contain clusterDomain (e.g. "iss": "https://kubernetes.default.svc.cluster.local"). After changing clusterDomain apiserver starts to deny queries with old tokens and controllers are bond to provide errors (including deckhouse). The solution is to wait until Kubernetes rotates the tokens (it will be quite fast despite the expiration date) or restart all pods with controllers.

Important! If you use istio module, you have to restart all the application pods under istio control after changing clusterDomain.