# K3s — Lightweight Certified Kubernetes Distribution

> K3s is a fully compliant, lightweight Kubernetes distribution that runs in less than 512MB RAM. Perfect for edge, IoT, ARM, CI/CD, and resource-constrained environments.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

```bash
# Install on any Linux (takes 30 seconds)
curl -sfL https://get.k3s.io | sh -

# Check status
sudo k3s kubectl get nodes

# Run a workload
sudo k3s kubectl create deployment nginx --image=nginx
sudo k3s kubectl expose deployment nginx --port=80 --type=NodePort
```

## Intro

**K3s** is a fully compliant Kubernetes distribution designed for resource-constrained environments. Built by Rancher Labs (now SUSE), it packages Kubernetes into a single binary under 100MB that uses less than 512MB of RAM, making it perfect for edge computing, IoT devices, CI/CD pipelines, and developers who want Kubernetes without the operational complexity.

With 32.7K+ GitHub stars and Apache-2.0 license, K3s is the most popular lightweight Kubernetes distribution, certified by the CNCF and used in production from home labs to large enterprises.

## What K3s Does

- **Single Binary**: Everything (API server, scheduler, kubelet, etc.) in one <100MB binary
- **Low Resource**: Runs Kubernetes in <512MB RAM (minimum)
- **Easy Install**: One curl command to install a complete cluster
- **SQLite or etcd**: Lightweight SQLite backend by default, embedded etcd for HA
- **Built-in**: Traefik ingress, Flannel CNI, CoreDNS, local-path storage, metrics-server
- **ARM Support**: Runs on Raspberry Pi and other ARM devices
- **Air-Gap Ready**: Install without internet connection
- **High Availability**: HA cluster with embedded etcd (3+ server nodes)
- **Upgrade**: Simple version upgrades with automatic migration

## Architecture

```
┌─────────────────────────────────────┐
│       K3s Single Binary              │
│  ┌──────────┐  ┌──────────────┐     │
│  │API Server│  │  Scheduler   │     │
│  └──────────┘  └──────────────┘     │
│  ┌──────────┐  ┌──────────────┐     │
│  │Controller│  │   Kubelet    │     │
│  │  Manager │  │              │     │
│  └──────────┘  └──────────────┘     │
│  ┌──────────┐  ┌──────────────┐     │
│  │  Kine    │  │  Containerd  │     │
│  │ (SQLite) │  │              │     │
│  └──────────┘  └──────────────┘     │
└─────────────────────────────────────┘
```

K3s replaces etcd with Kine (an abstraction layer), which can use SQLite, PostgreSQL, MySQL, or embedded etcd.

## Installation

### Single Node (Dev/Test)

```bash
# Install server (master)
curl -sfL https://get.k3s.io | sh -

# Kubeconfig is at /etc/rancher/k3s/k3s.yaml
sudo chmod 644 /etc/rancher/k3s/k3s.yaml
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml

kubectl get nodes
```

### Multi-Node Cluster

```bash
# On the server (master) node
curl -sfL https://get.k3s.io | sh -
sudo cat /var/lib/rancher/k3s/server/node-token
# Save this token!

# On worker nodes
curl -sfL https://get.k3s.io | K3S_URL=https://server-ip:6443 K3S_TOKEN=your-token sh -
```

### High Availability (3 servers with embedded etcd)

```bash
# First server
curl -sfL https://get.k3s.io | sh -s - server 
  --cluster-init 
  --token=shared-secret

# Additional servers
curl -sfL https://get.k3s.io | sh -s - server 
  --server https://first-server:6443 
  --token=shared-secret
```

### Uninstall

```bash
# On server
/usr/local/bin/k3s-uninstall.sh

# On agent
/usr/local/bin/k3s-agent-uninstall.sh
```

## Key Features

### Built-in Components

K3s includes batteries-included components you'd otherwise need to install separately:

```
├── Traefik (v2)         — Ingress controller
├── Flannel             — CNI networking
├── CoreDNS             — DNS service
├── Metrics Server      — kubectl top support
├── Local Path Provisioner — Default storage
├── Helm Controller     — HelmChart CRD support
└── Klipper LoadBalancer — ServiceType=LoadBalancer
```

Disable any component if you want to use alternatives:
```bash
curl -sfL https://get.k3s.io | sh -s - 
  --disable traefik 
  --disable servicelb
```

### Using with Rancher

```yaml
# Deploy Rancher management UI on K3s
kubectl create namespace cattle-system
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml

helm repo add rancher-stable https://releases.rancher.com/server-charts/stable
helm install rancher rancher-stable/rancher 
  --namespace cattle-system 
  --set hostname=rancher.yourdomain.com
```

### Deploy Helm Charts

```yaml
# K3s natively supports HelmChart CRD
apiVersion: helm.cattle.io/v1
kind: HelmChart
metadata:
  name: grafana
  namespace: kube-system
spec:
  chart: grafana
  repo: https://grafana.github.io/helm-charts
  targetNamespace: monitoring
  valuesContent: |-
    service:
      type: LoadBalancer
    adminPassword: your-password
```

### Air-Gap Installation

```bash
# Download K3s binary and images
wget https://github.com/k3s-io/k3s/releases/download/v1.28.0%2Bk3s1/k3s
wget https://github.com/k3s-io/k3s/releases/download/v1.28.0%2Bk3s1/k3s-airgap-images-amd64.tar.gz

# On target machine
sudo mkdir -p /var/lib/rancher/k3s/agent/images/
sudo cp k3s-airgap-images-amd64.tar.gz /var/lib/rancher/k3s/agent/images/
sudo cp k3s /usr/local/bin/
sudo chmod +x /usr/local/bin/k3s
```

## Use Cases

| Scenario | Why K3s? |
|----------|----------|
| Edge computing | Low resource, ARM support |
| IoT devices | Raspberry Pi compatible |
| CI/CD pipelines | Fast startup, single binary |
| Developer workstation | Full K8s, low overhead |
| Home lab | Easy install, full featured |
| Branch offices | Air-gap ready |
| GitOps (Flux/ArgoCD) | HelmChart CRD support |

## K3s vs Alternatives

| Feature | K3s | K8s (kubeadm) | K0s | MicroK8s |
|---------|-----|---------------|-----|----------|
| Binary size | ~100MB | ~1GB+ | ~180MB | ~200MB |
| RAM (idle) | 512MB | 2GB+ | 500MB | 600MB |
| Install time | 30s | 30+ min | 30s | 60s |
| Backend | SQLite/etcd | etcd | etcd | dqlite |
| Certification | CNCF certified | Native | CNCF certified | CNCF certified |
| Best for | Edge, dev, prod | Prod at scale | Prod, edge | Ubuntu users |

## FAQ

**Q: Is K3s functionally equivalent to full Kubernetes?**
A: Yes. K3s is a CNCF-certified Kubernetes distribution that passes all conformance tests. The difference is only in packaging — K3s is smaller and easier to deploy, but it runs the same Kubernetes underneath.

**Q: Is it suitable for production?**
A: Very much so. Many companies run K3s at scale in production. SUSE (Rancher's parent company) offers commercial support. In HA mode (3+ server nodes) it provides production-grade availability.

**Q: K3s or Docker Swarm — which should I choose?**
A: If you want the simplicity of Docker Swarm, pick Docker Swarm. If you want the Kubernetes ecosystem (Helm, Operators, complex workloads) but don't want the complexity of full K8s, pick K3s. K3s is the better long-term choice.

## Sources & Credits

- GitHub: [k3s-io/k3s](https://github.com/k3s-io/k3s) — 32.7K+ ⭐ | Apache-2.0
- Official site: [k3s.io](https://k3s.io)

---
Source: https://tokrepo.com/en/workflows/k3s-lightweight-certified-kubernetes-distribution-300fbdf6
Author: AI Open Source