K3s Cluster Installation Guide (Master and Worker Nodes)

This guide provides step-by-step instructions for setting up a K3s Kubernetes cluster, including a master node, worker nodes, and configuring a development machine for cluster management. It also covers the installation and access of the Kubernetes Dashboard.

1. K3s Master Node Setup

The master node will host the Kubernetes control plane. This setup uses an external database for K3s configuration and taints the node to prevent application pods from running on it by default.

Install Helm (Optional but Recommended)

Helm is a package manager for Kubernetes.

curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash

Create K3s Master Node

This command installs K3s as a server, configures it to use an external MySQL database, and applies a node-taint to designate it as a control plane only node.

curl -sfL https://get.k3s.io | sh -s - server \
  --datastore-endpoint="mysql://k3suser:<database-password>@tcp(<database-host>:3306)/k3sdb" \
  --node-taint CriticalAddonsOnly=true:NoExecute

• --datastore-endpoint: Specifies an external database for K3s state (e.g., MySQL, PostgreSQL, etcd).
• --node-taint CriticalAddonsOnly=true:NoExecute: Prevents regular workloads from being scheduled on the master node, reserving it for control plane components.

Uninstall K3s Master

To completely remove K3s from the master node:

sudo /usr/local/bin/k3s-uninstall.sh

Retrieve K3s Token for Worker Nodes

Worker nodes need a token to join the cluster. This command retrieves the token from the master node.

sudo chmod 644 /etc/rancher/k3s/k3s.yaml # Adjust permissions temporarily if needed
sudo cat /var/lib/rancher/k3s/server/node-token

2. K3s Worker Node Setup

Worker nodes are where your application pods will run. They join the cluster by connecting to the master node and using the shared token.

Join Worker Node to Cluster

curl -sfL https://get.k3s.io | K3S_URL=https://<master-ip>:6443 K3S_TOKEN=<your-token> sh -

• K3S_URL: The URL of the K3s master node (typically https://<master-ip>:6443).
• K3S_TOKEN: The token retrieved from the master node.

3. Development Machine Setup

To manage your K3s cluster from a separate machine, you need kubectl installed and configured with the cluster’s kubeconfig.

Install kubectl

kubectl is the command-line tool for interacting with Kubernetes clusters.

   curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
   sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
   kubectl version --client

Configure kubeconfig

1. Retrieve kubeconfig from Master: On your K3s master node, get the content of its kubeconfig file:

   sudo cat /etc/rancher/k3s/k3s.yaml

2. Create .kube/config on Dev Machine: On your development machine, create the directory ~/.kube/ if it doesn’t exist, and then create a file named config inside it. Paste the content obtained from the master node into this file.

3. Update Master IP in kubeconfig: Edit the config file on your dev machine. Change the server entry from https://127.0.0.1:6443 (or similar) to https://<master-ip>:6443, replacing <master-ip> with the actual IP address of your K3s master node.

Now your development machine is ready to manage the K3s cluster.

4. Kubernetes Dashboard Setup

The Kubernetes Dashboard is a web-based UI that allows you to manage and troubleshoot applications in your cluster.

Install Kubernetes Dashboard

Deploy the Dashboard components to your cluster. Always check the official Kubernetes Dashboard GitHub repository for the latest recommended version.

kubectl apply -f https://raw.githubusercontent.com/kubernetes/dashboard/v2.7.0/aio/deploy/recommended.yaml # Check for latest version

Dashboard RBAC Configuration

To access the Dashboard, you need to create a ServiceAccount and ClusterRoleBinding to grant it the necessary permissions.

dashboard.admin-user.yml

Create a file named dashboard.admin-user.yml with the following content:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: admin-user
  namespace: kubernetes-dashboard # The namespace where the Dashboard is installed

dashboard.admin-user-role.yml

Create a file named dashboard.admin-user-role.yml with the following content:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: admin-user
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin # Grants full admin access, use with caution
subjects:
- kind: ServiceAccount
  name: admin-user
  namespace: kubernetes-dashboard

Deploy RBAC Configuration

Apply the ServiceAccount and ClusterRoleBinding:

kubectl create -f dashboard.admin-user.yml -f dashboard.admin-user-role.yml

Get Bearer Token

Retrieve the bearer token for the admin-user ServiceAccount. You will use this token to log into the Dashboard UI.

kubectl -n kubernetes-dashboard create token admin-user

Start Dashboard Proxy Locally

To access the Dashboard UI from your development machine, you can use kubectl proxy.

kubectl proxy

This will typically make the Dashboard accessible at a URL similar to:

http://localhost:8001/api/v1/namespaces/kubernetes-dashboard/services/https:kubernetes-dashboard:/proxy/

Open this URL in your web browser. When prompted, select “Token” and paste the bearer token you retrieved in the previous step.