Running k0s in Docker

In this tutorial you’ll create a k0s cluster on top of docker. By default, both controller and worker are run in the same container to provide an easy local testing “cluster”. The tutorial also shows how to add additional worker nodes to the cluster.

Prerequisites

Docker environment on Mac, Windows or Linux. Get Docker.

Container images

The k0s containers are published both on Docker Hub and GitHub. The examples in this page show Docker Hub, because it’s more simple to use. Using GitHub requires a separate authentication (not covered here). Alternative links:

  • docker.io/k0sproject/k0s:latest
  • docker.pkg.github.com/k0sproject/k0s/k0s:”version”

Installation steps

1. Start k0s

You can run your own k0s in Docker easily with:

  1. docker run -d --name k0s --hostname k0s --privileged -v /var/lib/k0s -p 6443:6443 docker.io/k0sproject/k0s:latest

2. Create additional workers (optional)

If you want to attach multiple workers nodes into the cluster you can then distribute your application containers to separate workers.

First, we need a join token for the worker:

  1. token=$(docker exec -t -i k0s k0s token create --role=worker)

Then create and join a new worker by running the container with:

  1. docker run -d --name k0s-worker1 --hostname k0s-worker1 --privileged -v /var/lib/k0s docker.io/k0sproject/k0s:latest k0s worker $token

Repeat for as many workers you need, and have resources for. :)

3. Access your cluster

You can access your cluster with kubectl:

  1. docker exec k0s kubectl get nodes

Alternatively, grab the kubeconfig file with docker exec k0s cat /var/lib/k0s/pki/admin.conf and paste it e.g. into Lens.

Docker Compose (alternative)

You can also run k0s with Docker Compose:

  1. version: "3.9"
  2. services:
  3.   k0s:
  4.     container_name: k0s
  5.     image: docker.io/k0sproject/k0s:latest
  6.     command: k0s controller --config=/etc/k0s/config.yaml --enable-worker
  7.     hostname: k0s
  8.     privileged: true
  9.     volumes:
  10.       - "/var/lib/k0s"
  11.     tmpfs:
  12.       - /run
  13.       - /var/run
  14.     ports:
  15.       - "6443:6443"
  16.     network_mode: "bridge"
  17.     environment:
  18.       K0S_CONFIG: |-
  19.         apiVersion: k0s.k0sproject.io/v1beta1
  20.         kind: Cluster
  21.         metadata:
  22.           name: k0s
  23.         # Any additional configuration goes here ...

Known limitations

No custom Docker networks

Currently, we cannot run k0s nodes if the containers are configured to use custom networks e.g. with --net my-net. This is caused by the fact that Docker sets up a custom DNS service within the network and that messes up CoreDNS. We know that there are some workarounds possible, but they are bit hackish. And on the other hand, running k0s cluster(s) in bridge network should not cause issues.

Next Steps