How to change Rancher 2.x server-url

Single Server Installation

During this tutorial it is recommended to use the rancher-single-tool for Rancher single server installations. It isn't required but it makes the process much easier. As a result this guide will be based on using that tool.

1. Backup your Rancher installation using the guide found here.

2. Login to the Rancher web interface, navigate to the Global view by clicking the dropdown in the top left corner of the screen and selecting "Global Settings". From the settings page, change the server-url to match your new server url.

3. Now we need to upgrade your Rancher container to reflect new certs. This is required in most cases with the exception of already using a wildcard that also encompasses the new server-url.

   a. To generate a new self signed certificate for your new URL you can follow this link to update your self signed certificates

   b. To generate a new Let's Encrypt certificate you will need to change the Rancher server options to reflect this. You could do this with the following command.

   bash rancher-single-tool.sh -t'upgrade' -r'--acme-domain newhostname.company.com'

   c. If you were using certificates signed by a recognized CA before and just need to replace them, you should modify the docker options to reflect this change. Keep in mind that if you just replaced the cert files on the host path and the filenames didn't change, you can just restart the docker container. However if the filenames did change, I'm providing the example below of how you would do upgrade the container to see this change.

   bash rancher-single-tool.sh -t'upgrade' -d'-d -p 443:443 -p 80:80 --restart=unless-stopped --volume=/etc/rancherssl/certs/cert.pem:/etc/rancher/ssl/cert.pem --volume=/etc/rancherssl/certs/key.pem:/etc/rancher/ssl/key.pem'

   d. If you were using certificates signed by a private CA or you want to use your own self signed certifiactes (certificates not created by rancher-single-tool option -s). Below is an example of how you would do that. The same rule applies from option c. If the filenames have not changed you don't need to upgrade, you can just restart the container.

   bash rancher-single-tool.sh -t'upgrade' -d'-d -p 443:443 -p 80:80 --restart=unless-stopped --volume=/etc/rancherssl/certs/cert.pem:/etc/rancher/ssl/cert.pem --volume=/etc/rancherssl/certs/key.pem:/etc/rancher/ssl/key.pem --volume=/etc/rancherssl/certs/ca.pem:/etc/rancher/ssl/cacerts.pem'

4. Once your Rancher deployment is back up and running you need to redeploy the cattle-cluster-agents in the downstream clusters. You can do so by running either of the following commands:

kubectl annotate clusters.management.cattle.io <REPLACE_WITH_CLUSTERID> io.cattle.agent.force.deploy=true

OR

kubectl patch clusters.management.cattle.io <REPLACE_WITH_CLUSTERID> -p '{"status":{"agentImage":"dummy"}}' --type merge

Note, that the patch command works on 2.6.x clusters and earlier. On 2.7.x and later, use the annotate command.

HA Installation

1. Ensure that you have current etcd backups for your local rancher cluster.

2. Login to the Rancher web interface, navigate to the Global view by clicking the dropdown in the top left corner of the screen and selecting "Global Settings". From the settings page, change the server-url to match your new server url.

3. Log into a box where you have helm and kubectl installed. You will need your local Rancher cluster kubeconfig, ensure that it is set to the default config by either placing it in ~/.kube/config or by setting your KUBECONFIG environment variable.

4. Check current helm chart options:

   helm get values rancher -n cattle-system -o yaml > values.yaml
   cat values.yaml
   hostname: rancher.company.com

5. Craft an upgrade command based on the values provided in the previous step and then modify the hostname to match the new server hostname/url.

   vim values.yaml #update the hostname to match the new hostname
   helm upgrade rancher-stable/rancher --name rancher --namespace cattle-system --version=2.7.9 -f values.yaml

6. Run the upgrade command then wait for rollout to complete.

   kubectl -n cattle-system  rollout status deploy/rancher

7. Once your Rancher deployment is back up and running you need to redeploy the cattle-cluster-agents in the downstream clusters. You can do so by running either of the following commands:

   kubectl annotate clusters.management.cattle.io <REPLACE_WITH_CLUSTERID> io.cattle.agent.force.deploy=true
   
   OR
   
   kubectl patch clusters.management.cattle.io <REPLACE_WITH_CLUSTERID> -p '{"status":{"agentImage":"dummy"}}' --type merge
   
   Note, that the patch command works on 2.6.x clusters and earlier. On 2.7.x and later, use the annotate command.