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:latest
- docker.pkg.github.com/k0sproject/k0s/k0s:"version"
Start k0s#
1. Initiate k0s#
You can run your own k0s in Docker:
docker run -d --name k0s --hostname k0s --privileged -v /var/lib/k0s -p 6443:6443 docker.io/k0sproject/k0s:latest
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:
-
Acquire a join token for the worker:
token=$(docker exec -t -i k0s k0s token create --role=worker)
-
Run the container to create and join the new worker:
docker run -d --name k0s-worker1 --hostname k0s-worker1 --privileged -v /var/lib/k0s docker.io/k0sproject/k0s:latest k0s worker $token
3. Access your cluster#
Access your cluster using kubectl:
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 into Lens.
Use Docker Compose (alternative)#
As an alternative you can run k0s using Docker Compose:
version: "3.9"
services:
k0s:
container_name: k0s
image: docker.io/k0sproject/k0s:latest
command: k0s controller --config=/etc/k0s/config.yaml --enable-worker
hostname: k0s
privileged: true
volumes:
- "/var/lib/k0s"
tmpfs:
- /run
- /var/run
ports:
- "6443:6443"
network_mode: "bridge"
environment:
K0S_CONFIG: |-
apiVersion: k0s.k0sproject.io/v1beta1
kind: Cluster
metadata:
name: k0s
# 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#
- Install using k0sctl: Deploy multi-node clusters using just one command
- Control plane configuration options: Networking and datastore configuration
- Worker node configuration options: Node labels and kubelet arguments
- Support for cloud providers: Load balancer or storage configuration
- Installing the Traefik Ingress Controller: Ingress deployment information