When managing an imported cluster, Rancher connects to a Kubernetes cluster that has already been set up. Therefore, Rancher does not provision Kubernetes, but only sets up the Rancher agents to communicate with the cluster.

Keep in mind that editing your Kubernetes cluster still has to be done outside of Rancher. Some examples of editing the cluster include adding and removing nodes, upgrading the Kubernetes version, and changing Kubernetes component parameters.

Prerequisites

If your existing Kubernetes cluster already has a cluster-admin role defined, you must have this cluster-admin privilege to import the cluster into Rancher.

In order to apply the privilege, you need to run:

kubectl create clusterrolebinding cluster-admin-binding \
  --clusterrole cluster-admin \
  --user [USER_ACCOUNT]

before running the kubectl command to import the cluster.

By default, GKE users are not given this privilege, so you will need to run the command before importing GKE clusters. To learn more about role-based access control for GKE, please click here.

Importing a Cluster

  1. From the Clusters page, click Add Cluster.
  2. Choose Import.
  3. Enter a Cluster Name.

  4. Use Member Roles to configure user authorization for the cluster.

    • Click Add Member to add users that can access the cluster.
    • Use the Role drop-down to set permissions for each user.

  5. Click Create.
  6. The prerequisite for cluster-admin privileges is shown (see Prerequisites above), including an example command to fulfil the prerequisite.
  7. Copy the kubectl command to your clipboard and run it on a node where kubeconfig is configured to point to the cluster you want to import. If you are unsure it is configured correctly, run kubectl get nodes to verify before running the command shown in Rancher .
  8. If you are using self signed certificates, you will receive the message certificate signed by unknown authority. To work around this validation, copy the command starting with curl displayed in Rancher to your clipboard. Then run the command on a node where kubeconfig is configured to point to the cluster you want to import.
  9. When you finish running the command(s) on your node, click Done.

    Result:

    • Your cluster is created and assigned a state of Pending. Rancher is deploying resources to manage your cluster.
    • You can access your cluster after its state is updated to Active.
    • Active clusters are assigned two Projects Default (containing the namespace default) and System (containing the namespaces cattle-system,ingress-nginx,kube-public and kube-system, if present).

Note: You can not re-import a cluster that is currently active in a Rancher setup.