Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
Change the hostname/URL and certificate of an existing Rancher installation

Steps to change the URL of Rancher installation and switch from a self-signed certificate to a certificate signed by recognized CA.

  1. Change the Rancher server-url setting to the new URL:

    • Navigate to https://<old_rancher_hostname>/g/settings/advanced
    • Edit server-url to https://<new_rancher_hostname>
  2. Clear the private CA certificate for the old certificate

    • Navigate to https://<old_rancher_hostname>/g/settings/advanced
    • Next to cacerts click context menu -> View in API
    • Click Edit
    • Clear the content of the value field
    • Click Show Request then Send Request
  3. Trigger a re-deployment of the cluster-agent and node-agent for each cluster:

    • Configure kubectl to point at the RKE cluster where Rancher server is running
    • Note down the IDs of the managed clusters: $ kubectl get clusters
    • For each cluster (including local) run:
    $ kubectl patch cluster <CLUSTER_ID> -p '{"status":{"agentImage":"dummy"}}' --type merge
  4. Note that this will disconnect all clusters from Rancher until the installation is upgraded with the new hostname / ingress configuration.

  5. Update the certificate for Rancher from private to public signed one:

  6. Upgrade Rancher installation using the helm upgrade command following the steps here:

    • Specify the currently installed Rancher version to prevent software upgrade
    • Pass all the values (--set) that were originally specified during installation
    • Pass the new Rancher hostname in the hostname variable
    • Ensure you specify --set privateCA=false to clear out the old private CA certificate


    helm upgrade rancher rancher-stable/rancher --version v2.1.6 \
    --set \
    --set ingress.tls.source=secret \
    --set privateCA=false \
    --set ...other...options

This comment has been minimized.

Copy link

@fr34kyn01535 fr34kyn01535 commented Feb 16, 2020

Editing cacerts is no longer possible..


This comment has been minimized.

Copy link
Owner Author

@janeczku janeczku commented Feb 17, 2020

Thanks for the info, @fr34kyn01535. Looks like changing the CA certificate now rather needs to be done via a helm upgrade.


This comment has been minimized.

Copy link

@fr34kyn01535 fr34kyn01535 commented Feb 17, 2020

Yes, works quite good, ranchers self-healing capabilities are awesome. To change the URL on agents simply edit their address in the api and redeploy them inplace. (for custom agents on dedicated machines) Then roll all certificates and redeploy all services.


This comment has been minimized.

Copy link

@resamaraschi resamaraschi commented Apr 2, 2020

Thanks for this useful gist. 👍


This comment has been minimized.

Copy link

@Nilegfx Nilegfx commented Apr 24, 2021

I am kinda lost here. could you please explain how can I do it with helm upgrade? I tried to do so in separate installation (dev env) but I always end up with this scenario


This comment has been minimized.

Copy link

@Nilegfx Nilegfx commented Apr 25, 2021

finally, I was able to do it.
Rancher docs doesn't mention anything about this and even this gist wasn't helpful in my case because I installed rancher with letsencrypt certificates.
so what I did:

  1. upgrade rancher via helm (don't forget to copy cluster config from rancher UI before you do the following as you won't have access to the cluster config once you changed the URL)
helm upgrade --install \
  --namespace cattle-system \
  --set \
  --set ingress.tls.source=letsEncrypt \
  --set \
  rancher \
  1. created a new DNS record (I use cloudflare to manage my DNS) it took around an hour for the DNS to be propagated (not sure why, but eventually it worked)
  2. the cluster got detached from rancher and showed health check failure
  3. ssh into the cluster
  4. install kubectl
  5. copied the old kubeconfig to the machine/node and configured `export KUBECONFIG=<OLD_CONFIG_DIR_IN_VM>
  6. get secrets kubectl -n cattle-system get secret
  7. modify the secret cattle-credentials-<RANDOM_HASH>. change data.url (encode it with base64 beforehand)
  8. modify both node and cluster agent in the same VM
    1. modify cluster agent deployment
      1. kubectl -n cattle-system edit deployment cattle-cluster-agent.
      2. change CATTLE_SERVER env to your new domain/url
    2. modify node agent
      1. kubectl -n cattle-system edit daemonsets cattle-node-agent
      2. change CATTLE_SERVER env to your new domain/url

I think in my case there was no need to modify any certificates because cert-manager was already installed at the first time I setup rancher.

I hope this helps someone.


This comment has been minimized.

Copy link

@sebastien-helbert sebastien-helbert commented May 24, 2021

Thanks for sharing this @Nilegfx it works as expected

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment