k3s

What is k3s image?

The k3s image runs K3s, a certified Kubernetes distribution designed to be simple to install, operate, and maintain. K3s packages core Kubernetes components into a single binary, removes nonessential dependencies, and replaces heavier defaults (like etcd) with lighter alternatives when appropriate. It includes built-in support for containerd, networking, ingress, and service load balancing, making it well suited for edge clusters, development environments, CI systems, and small production deployments. In modern infrastructure, K3s is often used where full upstream Kubernetes would be too resource-intensive, while still preserving API compatibility and ecosystem support.

How to use this image

The k3s image can be used to run a single-node Kubernetes cluster or as part of a multi-node setup with server and agent roles.

Run a single-node cluster locally:

docker run -d --name k3s \
  --privileged \
  -p 6443:6443 \
  rancher/k3s server

Retrieve the kubeconfig:

dockerexec k3scat /etc/rancher/k3s/k3s.yaml

Run an agent node and join a server:

docker run -d --privileged \
  -e K3S_URL=https://server-ip:6443 \
  -e K3S_TOKEN=<node-token> \
  rancher/k3s agent

K3s listens on port 6443 for the Kubernetes API and logs to stdout. In production, configuration is typically provided via environment variables or config files baked into the image or managed through systemd when running on hosts.

Image variants

K3s images are tightly coupled to Kubernetes patch versions; production environments should pin exact tags to avoid unexpected upgrades.