k3s Architecture

A k3s cluster is made of server nodes (the control plane) and agent nodes (the workers).

Every Kubernetes cluster has two kinds of machines. k3s calls them server nodes and agent nodes.

Server node

A server runs the control plane: the API server, scheduler, controller-manager, and the datastore (SQLite or etcd). It decides what should run and where. A server also runs workloads unless you stop it from doing so.

Agent node

An agent is a pure worker. It runs the kubelet and containerd, receives instructions from the server, and runs your Pods. Agents hold no cluster state.

A k3s server node and agent nodes joined by a tokenServer node (control plane)API server + schedulercontroller-managerdata store (SQLite/etcd)kubelet + containerdjoin with node token on :6443Agent node 1kubelet · kube-proxy · containerdruns your PodsAgent node 2kubelet · kube-proxy · containerdruns your Pods
Agents authenticate to the server with a shared node token, then start receiving work.

Example

Example · bash
# List the roles of each node
kubectl get nodes

# Example output:
# NAME       STATUS   ROLES                  AGE   VERSION
# server-1   Ready    control-plane,master   5m    v1.30.5+k3s1
# agent-1    Ready    <none>                 3m    v1.30.5+k3s1

When to use it

  • A platform team provisions one k3s server node as the control plane and adds three agent nodes to distribute application workloads.
  • An operations engineer reviews k3s architecture to understand why the API server and kubelet both run inside the single k3s process.
  • A Kubernetes trainer uses k3s server/agent topology to teach cluster concepts without managing multi-component overhead.

More examples

Query control-plane health

Queries the readyz and livez endpoints to confirm all k3s control-plane components are healthy.

Example · bash
kubectl get --raw='/readyz?verbose'
kubectl get --raw='/livez?verbose'

Join an agent to the server

Registers a worker (agent) node by pointing it at the server URL with the shared node token.

Example · bash
K3S_URL=https://192.168.1.10:6443
K3S_TOKEN=$(cat /var/lib/rancher/k3s/server/node-token)
curl -sfL https://get.k3s.io | K3S_URL=$K3S_URL K3S_TOKEN=$K3S_TOKEN sh -

View control-plane system pods

Shows the system pods that form the k3s control plane and built-in networking layer.

Example · bash
kubectl get pods -n kube-system -o wide | \
  awk 'NR==1 || /coredns|traefik|svclb|metrics-server/'

Related

k3s single binaryk3s agents workers

Discussion

  • Be the first to comment on this lesson.