Run k0s in Docker

You can create a k0s cluster on top of docker. In such a scenario, by default, both controller and worker nodes are run in the same container to provide an easy local testing “cluster”.

Prerequisites

You will require a Docker environment running on a Mac, Windows, or Linux system.

Container images

The k0s containers are published both on Docker Hub and GitHub. For reasons of simplicity, the examples given here use Docker Hub (GitHub requires a separate authentication that is not covered). Alternative links include:

  • docker.io/k0sproject/k0s:v1.30.3-k0s.0
  • ghcr.io/k0sproject/k0s:v1.30.3-k0s.0

Note: Due to Docker Hub tag validation scheme, we have to use - as the k0s version separator instead of the usual +. So for example k0s version v1.30.3+k0s.0 is tagged as docker.io/k0sproject/k0s:v1.30.3-k0s.0.

Start k0s

1. Initiate k0s

You can run your own k0s in Docker:

  1. docker run -d --name k0s --hostname k0s --privileged -v /var/lib/k0s -p 6443:6443 --cgroupns=host docker.io/k0sproject/k0s:v1.30.3-k0s.0 -- k0s controller --enable-worker

Note: This command starts k0s with a worker. You may disable the worker by running it without the flag --enable-worker

2. (Optional) Create additional workers

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

For each required worker:

  1. Acquire a join token for the worker:

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

  2. Run the container to create and join the new worker:

    1. docker run -d --name k0s-worker1 --hostname k0s-worker1 --privileged -v /var/lib/k0s --cgroupns=host  docker.io/k0sproject/k0s:v1.30.3-k0s.0 k0s worker $token

3. Access your cluster

Access your cluster using kubectl:

  1. docker exec k0s k0s kubectl get nodes

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

Use Docker Compose (alternative)

As an alternative you can run k0s using Docker Compose:

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

Known limitations

No custom Docker networks

Currently, k0s nodes cannot be run if the containers are configured to use custom networks (for example, with --net my-net). This is because Docker sets up a custom DNS service within the network which creates issues with CoreDNS. No completely reliable workaounds are available, however no issues should arise from running k0s cluster(s) on a bridge network.

Next Steps