Important: RKE add-on install is only supported up to Rancher v2.0.8

If you are currently using the RKE add-on install method, please follow these directions to migrate to the Helm install.

The following instructions will help guide you through migrating from the RKE Add-on install to managing Rancher with the Helm package manager.

You will need the to have kubectl installed and the kubeconfig YAML file (kube_config_rancher-cluster.yml) generated by RKE.

Note: This guide assumes a standard Rancher install. If you have modified any of the object names or namespaces, please adjust accordingly.

Note: If you are upgrading from from Rancher v2.0.13 or earlier, or v2.1.8 or earlier, and your cluster’s certificates have expired, you will need to perform additional steps to rotate the certificates.

Point kubectl at your Rancher Cluster

Make sure kubectl is using the correct kubeconfig YAML file. Set the KUBECONFIG environmental variable to point to kube_config_rancher-cluster.yml:

  1. export KUBECONFIG=$(pwd)/kube_config_rancher-cluster.yml

After setting the KUBECONFIG environment variable, verify that it contains the correct server parameter. It should point directly to one of your cluster nodes on port 6443.

  1. kubectl config view -o=jsonpath='{.clusters[*].cluster.server}'
  2. https://NODE:6443

If the output from the command shows your Rancher hostname with the suffix /k8s/clusters, the wrong kubeconfig YAML file is configured. It should be the file that was created when you used RKE to create the cluster to run Rancher.

Save your certificates

If you have terminated ssl on the Rancher cluster ingress, recover your certificate and key for use in the Helm install.

Use kubectl to get the secret, decode the value and direct the output to a file.

  1. kubectl -n cattle-system get secret cattle-keys-ingress -o jsonpath --template='{ .data.tls\.crt }' | base64 -d > tls.crt
  2. kubectl -n cattle-system get secret cattle-keys-ingress -o jsonpath --template='{ .data.tls\.key }' | base64 -d > tls.key

If you specified a private CA root cert

  1. kubectl -n cattle-system get secret cattle-keys-server -o jsonpath --template='{ .data.cacerts\.pem }' | base64 -d > cacerts.pem

Remove previous Kubernetes objects

Remove the Kubernetes objects created by the RKE install.

Note: Removing these Kubernetes components will not affect the Rancher configuration or database, but with any maintenance it is a good idea to create a backup of the data before hand. See Creating Backups-Kubernetes Install for details.

  1. kubectl -n cattle-system delete ingress cattle-ingress-http
  2. kubectl -n cattle-system delete service cattle-service
  3. kubectl -n cattle-system delete deployment cattle
  4. kubectl -n cattle-system delete clusterrolebinding cattle-crb
  5. kubectl -n cattle-system delete serviceaccount cattle-admin

Remove addons section from rancher-cluster.yml

The addons section from rancher-cluster.yml contains all the resources needed to deploy Rancher using RKE. By switching to Helm, this part of the cluster configuration file is no longer needed. Open rancher-cluster.yml in your favorite text editor and remove the addons section:

Important: Make sure you only remove the addons section from the cluster configuration file.

  1. nodes:
  2.   - address: <IP> # hostname or IP to access nodes
  3.     user: <USER> # root user (usually 'root')
  4.     role: [controlplane,etcd,worker] # K8s roles for node
  5.     ssh_key_path: <PEM_FILE> # path to PEM file
  6.   - address: <IP>
  7.     user: <USER>
  8.     role: [controlplane,etcd,worker]
  9.     ssh_key_path: <PEM_FILE>
  10.   - address: <IP>
  11.     user: <USER>
  12.     role: [controlplane,etcd,worker]
  13.     ssh_key_path: <PEM_FILE>
  15. services:
  16.   etcd:
  17.     snapshot: true
  18.     creation: 6h
  19.     retention: 24h
  21. # Remove addons section from here til end of file
  22. addons: |-
  23.   ---
  24.   ...
  25. # End of file

Follow Helm and Rancher install steps

From here follow the standard install steps.