> ## Documentation Index
> Fetch the complete documentation index at: https://docs.karchunt.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Kubernetes Installation
## Installation Options
To setup a Kubernetes cluster, there are **several options** available, each with its own **advantages** and **use cases**. Below are some of the most popular methods for installing Kubernetes:
* **Minikube**: A local Kubernetes cluster that is easy to set up and ideal for development and testing purposes.
* **kubeadm**: A tool that provides a simple way to create a Kubernetes cluster on any machine
* **k3s**: A lightweight Kubernetes distribution designed for edge computing and IoT devices.
* **microk8s**: A minimal Kubernetes distribution that is easy to install and suitable for development and testing.
In this guide, I will use **k3s** for the installation process. However, the steps may vary slightly depending on the method you choose. Always refer to the official documentation for the specific installation method you decide to use.
## k3s Installation
Here is the [documentation](https://docs.k3s.io/) as well as the [GitHub repository](https://github.com/k3s-io/k3s).
**k3s** is a **lightweight** Kubernetes distribution that is designed to be **easy to install** and **operate**. It is ideal for edge computing, IoT devices, and development environments.
The **easiest way** to **install k3s** is to use the **installation script** provided by the k3s project. You can run the following command in your terminal:
```bash theme={"theme":"github-dark-dimmed"}
curl -sfL https://get.k3s.io | sh -
```
This command will download and execute the installation script, which will set up **k3s**, its **dependencies**, and `kubectl` on your machine.
Make sure you have **curl** installed on your system before running the above command.
```bash icon="terminal" title="Terminal Output" lines expandable theme={"theme":"github-dark-dimmed"}
kcserver@kcserver:~$ curl -sfL https://get.k3s.io | sh -
[sudo] password for kcserver:
[INFO] Finding release for channel stable
[INFO] Using v1.34.6+k3s1 as release
[INFO] Downloading hash https://github.com/k3s-io/k3s/releases/download/v1.34.6%2Bk3s1/sha256sum-amd64.txt
[INFO] Downloading binary https://github.com/k3s-io/k3s/releases/download/v1.34.6%2Bk3s1/k3s
[INFO] Verifying binary download
[INFO] Installing k3s to /usr/local/bin/k3s
[INFO] Skipping installation of SELinux RPM
[INFO] Creating /usr/local/bin/kubectl symlink to k3s
[INFO] Creating /usr/local/bin/crictl symlink to k3s
[INFO] Skipping /usr/local/bin/ctr symlink to k3s, command exists in PATH at /usr/bin/ctr
[INFO] Creating killall script /usr/local/bin/k3s-killall.sh
[INFO] Creating uninstall script /usr/local/bin/k3s-uninstall.sh
[INFO] env: Creating environment file /etc/systemd/system/k3s.service.env
[INFO] systemd: Creating service file /etc/systemd/system/k3s.service
[INFO] systemd: Enabling k3s unit
Created symlink /etc/systemd/system/multi-user.target.wants/k3s.service → /etc/systemd/system/k3s.service.
[INFO] systemd: Starting k3s
```
After the installation is complete, you can verify that k3s is running by checking the status of the service:
```bash theme={"theme":"github-dark-dimmed"}
sudo systemctl status k3s
```
```bash lines expandable title="Terminal Output" icon="terminal" highlight={3} theme={"theme":"github-dark-dimmed"}
● k3s.service - Lightweight Kubernetes
Loaded: loaded (/etc/systemd/system/k3s.service; enabled; preset: enabled)
Active: active (running) since Sun 2026-04-05 14:56:14 +08; 4min 11s ago
Docs: https://k3s.io
Process: 16564 ExecStartPre=/sbin/modprobe br_netfilter (code=exited, status=0/SUCCESS)
Process: 16565 ExecStartPre=/sbin/modprobe overlay (code=exited, status=0/SUCCESS)
Main PID: 16567 (k3s-server)
Tasks: 131
Memory: 1.4G (peak: 1.5G)
CPU: 52.314s
CGroup: /system.slice/k3s.service
├─16567 "/usr/local/bin/k3s server"
├─16604 "containerd "
├─17469 /var/lib/rancher/k3s/data/d76b59b2203578bb4cb3438338ccad2f0d3e194bef799a8957f21430b7d5f1e3/bin/containerd-shim-runc-v2 -namespace k8s.io -id 49fddc6859a2d2fbe7ff60f4bd4>
├─17483 /var/lib/rancher/k3s/data/d76b59b2203578bb4cb3438338ccad2f0d3e194bef799a8957f21430b7d5f1e3/bin/containerd-shim-runc-v2 -namespace k8s.io -id 39949c6a74f96b8adc19795a224>
├─17495 /var/lib/rancher/k3s/data/d76b59b2203578bb4cb3438338ccad2f0d3e194bef799a8957f21430b7d5f1e3/bin/containerd-shim-runc-v2 -namespace k8s.io -id 09dbfa4e70ab7c0baba199f2d9a>
├─18699 /var/lib/rancher/k3s/data/d76b59b2203578bb4cb3438338ccad2f0d3e194bef799a8957f21430b7d5f1e3/bin/containerd-shim-runc-v2 -namespace k8s.io -id 8ed894d3d30a49244d85dc18c88>
└─18788 /var/lib/rancher/k3s/data/d76b59b2203578bb4cb3438338ccad2f0d3e194bef799a8957f21430b7d5f1e3/bin/containerd-shim-runc-v2 -namespace k8s.io -id c872773fae31e06fa777f93b171>
Apr 05 14:57:20 kcserver k3s[16567]: I0405 14:57:20.545650 16567 resource_quota_monitor.go:228] "QuotaMonitor created object count evaluator" logger="resourcequota-controller" resource="t>
Apr 05 14:57:20 kcserver k3s[16567]: I0405 14:57:20.545657 16567 resource_quota_monitor.go:228] "QuotaMonitor created object count evaluator" logger="resourcequota-controller" resource="s>
Apr 05 14:57:20 kcserver k3s[16567]: I0405 14:57:20.545663 16567 resource_quota_monitor.go:228] "QuotaMonitor created object count evaluator" logger="resourcequota-controller" resource="a>
Apr 05 14:57:20 kcserver k3s[16567]: I0405 14:57:20.545675 16567 resource_quota_monitor.go:228] "QuotaMonitor created object count evaluator" logger="resourcequota-controller" resource="t>
Apr 05 14:57:20 kcserver k3s[16567]: I0405 14:57:20.545681 16567 resource_quota_monitor.go:228] "QuotaMonitor created object count evaluator" logger="resourcequota-controller" resource="s>
Apr 05 14:57:20 kcserver k3s[16567]: I0405 14:57:20.545692 16567 resource_quota_monitor.go:228] "QuotaMonitor created object count evaluator" logger="resourcequota-controller" resource="i>
Apr 05 14:57:20 kcserver k3s[16567]: I0405 14:57:20.545787 16567 shared_informer.go:349] "Waiting for caches to sync" controller="resource quota"
Apr 05 14:57:20 kcserver k3s[16567]: I0405 14:57:20.746118 16567 shared_informer.go:356] "Caches are synced" controller="resource quota"
Apr 05 14:57:21 kcserver k3s[16567]: I0405 14:57:21.155050 16567 shared_informer.go:349] "Waiting for caches to sync" controller="garbage collector"
Apr 05 14:57:21 kcserver k3s[16567]: I0405 14:57:21.255550 16567 shared_informer.go:356] "Caches are synced" controller="garbage collector"
```
You should see output indicating that the k3s service is active and running.
You can also check the Kubernetes cluster status using `kubectl`:
```bash theme={"theme":"github-dark-dimmed"}
kubectl get nodes
```
This command should show your node(s) in a `Ready` state.
If you faced the kubectl permission issue, you can refer to step 3 of this guide to resolve it.
You can refer this [link](https://devops.stackexchange.com/questions/16043/error-error-loading-config-file-etc-rancher-k3s-k3s-yaml-open-etc-rancher) for more details.
If you encounter a permission issue when running `kubectl` commands (e.g., `kubectl get nodes`), it may be because the `k3s` installation creates a kubeconfig file that is owned by root. To fix this issue, you can change the ownership of the kubeconfig file to your user.
```bash title="Issue" icon="terminal" theme={"theme":"github-dark-dimmed"}
kcserver@kcserver:~$ kubectl get nodes
WARN[0000] Unable to read /etc/rancher/k3s/k3s.yaml, please start server with --write-kubeconfig-mode or --write-kubeconfig-group to modify kube config permissions
error: error loading config file "/etc/rancher/k3s/k3s.yaml": open /etc/rancher/k3s/k3s.yaml: permission denied
```
To resolve this, run the following command to **change the ownership** of the kubeconfig file:
```bash title="Fix Permission Issue" icon="terminal" theme={"theme":"github-dark-dimmed"}
mkdir ~/.kube 2> /dev/null
export KUBECONFIG=~/.kube/config
sudo k3s kubectl config view --raw > "$KUBECONFIG"
chmod 600 "$KUBECONFIG"
```
To make it persistent across reboots, you can add the above commands to your shell profile (e.g., `~/.bashrc` or `~/.profile`):
```bash theme={"theme":"github-dark-dimmed"}
nano ~/.bashrc
source ~/.bashrc
```
Add the following lines to the end of the file:
```bash title="~/.bashrc" icon="terminal" theme={"theme":"github-dark-dimmed"}
# Set KUBECONFIG environment variable
export KUBECONFIG=~/.kube/config
```
After making these changes, you should be able to run `kubectl` commands without encountering permission issues:
```bash title="Verify kubectl Access" icon="terminal" theme={"theme":"github-dark-dimmed"}
kcserver@kcserver:~$ kubectl get nodes
NAME STATUS ROLES AGE VERSION
kcserver Ready control-plane 22m v1.34.6+k3s1
```