Registering Existing Kubernetes Clusters to Rancher

The control that Rancher has to manage a registered cluster depends on the type of cluster. We want to manage "set of" clusters within one Rancher UI, so this is guide how to perform the task quickly and ez.

Prerequisites

Kubernetes Node Roles

Registered RKE Kubernetes clusters must have all three node roles – etcd, controlplane and worker.

Permission

By default, Kubernetes Engine (*KE) does not grant the cluster-admin role, you must run these commands on KE clusters before you can register them.

To register a cluster in Rancher, you must have cluster-admin privileges within that cluster with serviceaccount type (instead of user).

kubectl create clusterrolebinding cluster-admin-binding --clusterrole=admin --serviceaccount=cattle-system:cattle-admin

Registering a Cluster

From Rancher Dashboard or Cluster Management, Following On the Clusters page, Import Existing a Cluster.
Choose Import any Kubernetes cluster -> Generic type
Named for the Cluster in the Cluster Name.
You can add some Member Roles here. 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.
In the Cluster Detail, there are cluster status and some command kubectl. Performing the kubectl in existed cluster to create rancher cluster agent to communicate with the Rancher UI.

Nam Le, on Flickr

Result

Your cluster is registered and assigned a state of Pending. Rancher is deploying resources to manage your cluster.

Nam Le, on Flickr

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

Why we use serviceaccount instead of user? I just figured out when read the file yaml in step 5. above, something look like:

...
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: cattle-admin-binding
  namespace: cattle-system
  labels:
    cattle.io/creator: "norman"
subjects:
- kind: ServiceAccount
  name: cattle
  namespace: cattle-system
roleRef:
  kind: ClusterRole
  name: cattle-admin
  apiGroup: rbac.authorization.k8s.io
...

So we have to change –user to –serviceaccount and following with namespace:account

--serviceaccount=cattle-system:cattle-admin

Tips

Mgmt Cluster is pending

After apply yaml, The Pending status with Mgmt Cluster Connected: False in Rancher typically means that Rancher is having trouble communicating with the downstream (imported) cluster.

When you import a cluster into Rancher, it deploys an agent pod into that cluster to establish the connection.

Check agent pod status:

kubectl -n cattle-system get pods

Look for rancher-agent-xxxxx. If it’s CrashLoopBackOff, Pending, or Error, then it couldn’t connect back to Rancher.

kubectl -n cattle-system logs <rancher-agent-pod-name>

Describe the pod to get the container name + error:

kubectl -n cattle-system describe pod cattle-cluster-agent-xxxxxx

kubectl -n cattle-system logs deployment/cattle-cluster-agent

=> Strict CA verification is enabled but encountered error finding root CA

Means the Rancher agent requires a CA certificate to trust your Rancher server’s HTTPS connection — but it can’t find the CA file (/etc/kubernetes/ssl/certs/serverca).

To fix this, you need to disable strict CA verification, in the step 5 above, Instead of applying it directly, download and looking for this:

- name: STRICT_VERIFY
  value: "true"

Rancher agent is deployed with STRICT_VERIFY=true, change to `STRICT_VERIFY=false

Also remove CATTLE_CA_CHECKSUM, safely remove this env (since it’s empty anyway):

- name: CATTLE_CA_CHECKSUM
  value: ""

Then reapply the YAML and force it to restart:

kubectl apply -f import.yaml

Or if the deployment already exists, force it to restart:

kubectl -n cattle-system rollout restart deployment cattle-cluster-agent

Ref

Ranchermanager

28-mar-2024,
Nam Le, [email protected],
https://nready.net