Setting Up k3s: A Comprehensive Guide with Troubleshooting

Setting Up k3s: A Comprehensive Guide with Troubleshooting

1. What is k3s?

k3s is a lightweight Kubernetes distribution designed for production workloads in unattended, remote locations. It is a fully compliant Kubernetes runtime that is easier to install and manage than other Kubernetes distributions. k3s is optimized for running in resource-constrained environments, such as edge computing setups or IoT devices, but it is also suitable for traditional cloud environments.

2. How to Install k3s on Ubuntu

To install k3s on an Ubuntu system, follow these steps:

Prerequisites

Ensure your system meets the minimum requirements:

• Ubuntu 18.04 or later
• 2 GB RAM
• 2 CPUs
• 20 GB disk space
• Internet connectivity

Installation Steps

1. Update System Packages:

   sudo apt-get update
   sudo apt-get upgrade -y
   

2. Download k3s:

   curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION="v1.23.3+k3s1" sh -
   

3. Verify Installation:

   sudo systemctl status k3s
   

4. Configure k3s Service:

   sudo systemctl enable k3s
   

3. How to Run k3s

Once k3s is installed, it runs as a service. However, you can manually start, stop, or restart k3s using the following commands:

• Start k3s:

  sudo systemctl start k3s
  

• Stop k3s:

  sudo systemctl stop k3s
  

• Restart k3s:

  sudo systemctl restart k3s
  

4. How to Connect with kubectl

To manage your k3s cluster, you need to use kubectl, the Kubernetes command-line tool. Here’s how to set it up:

Configure kubectl

1. Set KUBECONFIG Environment Variable:

   export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
   

2. Check Cluster Status:

   kubectl get nodes
   

Troubleshooting

Error: “You must be logged in to the server (Unauthorized)”

If you encounter the error “You must be logged in to the server (Unauthorized)” when trying to run kubectl get pods -A, it usually means that your kubectl client is not properly configured to connect to the k3s cluster.

Solution:

1. Copy k3s.yaml to Client Host: Ensure that you have copied the k3s.yaml from the host running k3s to your client host’s ~/.kube/config directory.

   scp root@k3s-host:/etc/rancher/k3s/k3s.yaml ~/.kube/config
   

2. Set KUBECONFIG Environment Variable: Make sure the KUBECONFIG environment variable is set correctly.

   export KUBECONFIG=~/.kube/config
   

3. Check Certificate Expiry: Use the following command to check if the certificate has expired:

   openssl s_client -connect localhost:6443 -showcerts < /dev/null 2>&1 | openssl x509 -noout -enddate
   

   If the certificate has expired, you will need to regenerate it and update the k3s.yaml file accordingly.

Conclusion

k3s is a powerful tool for running Kubernetes in resource-constrained environments. By following the steps above, you can set up k3s on Ubuntu, run it, and manage it using kubectl. If you encounter any issues, the troubleshooting tips provided should help you resolve common problems.