Follow these steps to update the SSL certificate of the ingress in a Rancher High Availability installation or switch from the default self-signed to a custom certificate:
First, concat the server certificate followed by any intermediate certificate(s) to a file named tls.crt and provide the corresponding certificate key in a file named tls.key.
If you are switching the install from using the Rancher generated CA or a Let’s Encrypt issued certificates use the following command to create the tls-rancher-ingress secret resource in your Rancher HA cluster:
$ kubectl -n cattle-system create secret tls tls-rancher-ingress \
--cert=tls.crt \
--key=tls.key
Alternatively, to update an existing certificate secret:
$ kubectl -n cattle-system create secret tls tls-rancher-ingress \
--cert=tls.crt \
--key=tls.key \
--dry-run --save-config -o yaml | kubectl apply -f -
If the certificate has been signed by a private CA, copy the CA certificate into a file named cacerts.pem and create or update the tls-ca secret in the cattle-system namespace.
To create the initial secret:
$ kubectl -n cattle-system create secret generic tls-ca \
--from-file=cacerts.pem
To update an existing tls-ca secret:
$ kubectl -n cattle-system create secret generic tls-ca \
--from-file=cacerts.pem \
--dry-run --save-config -o yaml | kubectl apply -f -
This step is only required, if Rancher was initially configured to use the Rancher generated CA (ingress.tls.source=rancher) or with a Let's Encrypt issued certificate (ingress.tls.source=letsEncrypt).
It ensures that both the Rancher pods and the ingress resource are properly configured to use the certificate provided in the secret.
To update the Helm deployment you will need to use the same (--set) options that you used to initially install Rancher. Check with:
$ helm get values rancher
Also check the currently deployed version of the chart:
$ helm ls rancher | sed 1d | cut -f6
Then update the Rancher Helm installation with your original values, making sure to set ingress.tls.source=secret and specifying the current chart version to prevent an application upgrade.
helm upgrade rancher rancher-stable/rancher --version <CURRENT_VERSION> \
--set hostname=rancher.my.org \
--set ingress.tls.source=secret \
--set ...
When the upgrade is completed, navigate to https://<Rancher_SERVER>/v3/settings/cacerts to verify that the value matches the CA certificate set in the tls-ca secret.
This step is only required if either:
- Rancher was initially configured to use the Rancher generated CA (
ingress.tls.source=rancher) or with a Let's Encrypt issued certificate (ingress.tls.source=letsEncrypt) - or you have changed the CA certificate for the certificate provided as a secret
When Rancher is configured with a certificate signed by a private CA, the CA certificate is provided to the Rancher agents via the Rancher API. To verify the downloaded certificate, agents compare the checksum against the CATTLE_CA_CHECKSUM environment variable that they are configured with. When the private CA certificate is updated on the Rancher server, the agents have to be updated with a matching value in the CATTLE_CA_CHECKSUM variable.
Manually patch the agent resources, updating the CATTLE_CA_CHECKSUM environment variable to the value matching the checksum of the new CA certificate. Generate the new checksum value like so:
$ curl -k -s -fL <RANCHER_SERVER>/v3/settings/cacerts | jq -r .value > cacert.tmp
$ sha256sum cacert.tmp | awk '{print $1}'
$ kubectl edit -n cattle-system ds/cattle-node-agent
$ kubectl edit -n cattle-system deployment/cluster-agent
Generate and apply the agent definitions from the Rancher API following the steps here: https://gist.github.com/superseb/d59f26102f0a8671672f8035811b2184
Also see this Gist to generate a kubeconfig for custom clusters: https://gist.github.com/superseb/f6cd637a7ad556124132ca39961789a4