K3s Lightweight Kubernetes

intermediate

Lightweight Kubernetes distribution for edge and IoT.

Overview

K3s is a fully compliant Kubernetes distribution developed by Rancher Labs, designed specifically for resource-constrained environments like edge computing, IoT devices, and development workspaces. Unlike traditional Kubernetes installations that require multiple binaries and complex setup procedures, K3s packages everything into a single binary under 50MB, including the Kubernetes API server, controller manager, scheduler, kubelet, and kube-proxy. This containerized K3s deployment creates a single-node Kubernetes cluster with all essential components pre-configured and ready to accept workloads. This Docker-based K3s server configuration eliminates the complexity of traditional Kubernetes installations by providing an instantly deployable cluster with built-in ingress controller (Traefik), DNS resolution (CoreDNS), and persistent volume provisioner (local-path). The setup automatically generates and exports kubeconfig files, enabling immediate kubectl access to manage deployments, services, and other Kubernetes resources. The privileged container mode and tmpfs mounts ensure proper systemd and container runtime functionality within the Docker environment. Developers working on Kubernetes applications, DevOps teams testing cluster configurations, and organizations deploying edge computing solutions will find this stack particularly valuable. The lightweight nature makes it perfect for laptop-based development, CI/CD pipeline testing, and production deployments in bandwidth-limited or resource-constrained environments where traditional Kubernetes would be impractical.

Key Features

Complete Kubernetes API compatibility with kubectl and Helm support
Integrated Traefik ingress controller for HTTP/HTTPS routing and SSL termination
CoreDNS for cluster-internal service discovery and external DNS resolution
Local-path storage provisioner for automatic persistent volume creation
Automatic kubeconfig generation with configurable file permissions
Multi-architecture support for ARM64, ARMv7, and x86_64 deployments
SQLite embedded datastore eliminating etcd complexity and resource overhead
Agent node expansion capability for multi-node cluster configurations

Common Use Cases

1Kubernetes application development and testing on local workstations
2CI/CD pipeline integration for automated Kubernetes deployment testing
3Edge computing deployments in retail stores, factories, and remote locations
4IoT gateway management for container-based sensor data processing
5Homelab Kubernetes clusters for learning and personal project hosting
6Rapid prototyping of microservices architectures without cloud dependencies
7Educational environments teaching Kubernetes concepts with minimal hardware

Prerequisites

Docker Engine with privileged container support enabled
Minimum 512MB RAM available for the K3s server process
Ports 6443, 80, and 443 available on the host system
Basic kubectl knowledge for cluster interaction and workload deployment
Understanding of Kubernetes concepts like pods, services, and deployments
K3S_TOKEN environment variable configured for secure agent communication

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  k3s-server: 
3    image: rancher/k3s:latest
4    container_name: k3s-server
5    command: server
6    tmpfs: 
7      - /run
8      - /var/run
9    privileged: true
10    environment: 
11      K3S_TOKEN: ${K3S_TOKEN}
12      K3S_KUBECONFIG_OUTPUT: /output/kubeconfig.yaml
13      K3S_KUBECONFIG_MODE: "644"
14    volumes: 
15      - k3s_server:/var/lib/rancher/k3s
16      - ./kubeconfig:/output
17    ports: 
18      - "6443:6443"
19      - "80:80"
20      - "443:443"
21
22volumes: 
23  k3s_server:

.env Template

.env

1K3S_TOKEN=supersecrettoken

Usage Notes

1Docs: https://docs.k3s.io/
2Kubeconfig exported to ./kubeconfig/kubeconfig.yaml
3Use: export KUBECONFIG=$(pwd)/kubeconfig/kubeconfig.yaml && kubectl get nodes
4Includes Traefik ingress, CoreDNS, local-path provisioner by default
5Add agents: docker run -d rancher/k3s agent --server https://server:6443 --token K3S_TOKEN
6~50MB binary, <512MB RAM - perfect for edge/IoT deployments

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  k3s-server:
5    image: rancher/k3s:latest
6    container_name: k3s-server
7    command: server
8    tmpfs:
9      - /run
10      - /var/run
11    privileged: true
12    environment:
13      K3S_TOKEN: ${K3S_TOKEN}
14      K3S_KUBECONFIG_OUTPUT: /output/kubeconfig.yaml
15      K3S_KUBECONFIG_MODE: "644"
16    volumes:
17      - k3s_server:/var/lib/rancher/k3s
18      - ./kubeconfig:/output
19    ports:
20      - "6443:6443"
21      - "80:80"
22      - "443:443"
23
24volumes:
25  k3s_server:
26EOF
27
28# 2. Create the .env file
29cat > .env << 'EOF'
30K3S_TOKEN=supersecrettoken
31EOF
32
33# 3. Start the services
34docker compose up -d
35
36# 4. View logs
37docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/k3s/run | bash

Troubleshooting

K3s server fails to start with 'permission denied': Ensure Docker daemon is running with privileged container support and the container has privileged: true
kubectl connection refused on port 6443: Verify the K3s server container is fully started and check docker logs k3s-server for initialization errors
Kubeconfig file not generated in ./kubeconfig directory: Create the kubeconfig directory before starting and ensure proper write permissions for the Docker daemon user
Pods stuck in Pending state: Check available resources with kubectl describe nodes and verify the local-path storage provisioner is running in kube-system namespace
Traefik ingress not routing traffic: Confirm services have proper ingress annotations and check Traefik dashboard at the cluster IP for routing configuration
Agent nodes cannot join cluster: Verify K3S_TOKEN matches between server and agent, and ensure port 6443 is accessible from agent nodes to the server

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

k3s

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download