Installing a K3s Cluster on Premises Using the Command Line

As outlined in Installing a Kubernetes Cluster Overview, there are several Kubernetes distributions available for installing a cluster on premises. We recommend K3s, a lightweight Kubernetes distribution that is easy to install and requires significantly fewer resources than a standard Kubernetes setup.

Prerequisite: Before setting up an on-premises Kubernetes cluster, you need a remote access to the host machines to run the commands that install Kubernetes on each node. We recommend using SSH (Secure Shell). Learn more

To install the K3s Kubernetes cluster on premises using the command line:

1. Install K3s on the server nodes. Select one of the following options.

   • Single server node

     This option consumes fewer resources, but the control plane is not highly available, and the cluster's state is stored in an embedded SQLite database.

     To spin up the server node, run:

     curl -sfL https://get.k3s.io | K3S_KUBECONFIG_MODE="644" sh -s - server --disable traefik --disable servicelb --disable coredns

   • Three server nodes

     This provides high availability for the control plane and uses an embedded etcd database for a resilient datastore.

     1. First, choose a random secret token. Run the following command on the first server node:

        curl -sfL https://get.k3s.io | K3S_TOKEN=SUPER_SECRET_TOKEN K3S_KUBECONFIG_MODE="644" sh -s - server --cluster-init --disable traefik --disable servicelb --disable coredns

        Wait for the single-node cluster to be created. This usually takes under one minute but may take longer.

     2. (Optional) Verify that the cluster exists with kubectl get nodes .

     3. On the other two server nodes, join the cluster:

        curl -sfL https://get.k3s.io | K3S_TOKEN=SUPER_SECRET_TOKEN K3S_KUBECONFIG_MODE="644" sh -s - server --server https://<node1_ip>:6443 --disable traefik --disable servicelb --disable coredns

        Replace <node1_ip> with the actual IP address of the first node.

2. Get the server token. On any of the server nodes, retrieve the token with this command:

   sudo cat /var/lib/rancher/k3s/server/node-token

   This step is necessary if you also want to add at least one agent node.

3. Install K3s on the agent nodes. Join the agent node with the following command:

   curl -sfL https://get.k3s.io | K3S_URL=https://<server_node_ip>:6443 K3S_TOKEN=<node_token> sh -s - agent

   Replace <server_node_ip> with the actual IP address of one of the server nodes and <node_token> with the token retrieved in Step 2.

4. Verify the installation. On any of the server nodes, run the following command to check the status of all nodes in your cluster:

   kubectl get nodes

   The output should list all your nodes, and their status should be Ready. For example:

   NAME STATUS ROLES AGE VERSION n1 Ready control-plane,etcd,master 2m4s v1.27.3+k3s1 n2 Ready control-plane,etcd,master 1m9s v1.27.3+k3s1 n3 Ready control-plane,etcd,master 1m5s v1.27.3+k3s1 n4 Ready <none> 1m1s v1.27.3+k3s1

5. If the nodes are not showing as active (running) or not showing at all, you can troubleshoot by checking the status of the K3s service on each node. The output also includes recent log entries that can help you diagnose possible issues.

   • On a server node, run:

     systemctl status k3s

   • On an agent node, run:

     systemctl status k3s-agent

What's Next?

Setting Up Access to the Kubernetes Cluster