k3d is a lightweight wrapper to run k3s (Rancher Lab’s minimal Kubernetes distribution) in docker. k3d makes it very easy to create single- and multi-node k3s clusters in docker, e.g. for local development on Kubernetes.


  • To use k3d, you will also need to install docker.
  • Install the latest version of k3d.
  • To interact with the Kubernetes cluster kubectl
  • (Optional) Helm is the package manager for Kubernetes


  1. Create a cluster and disable Traefik with the following command:

    $ k3d cluster create --api-port 6550 -p '9080:80@loadbalancer' -p '9443:443@loadbalancer' --agents 2 --k3s-arg '--disable=traefik@server:*'
  2. To see the list of k3d clusters, use the following command:

    $ k3d cluster list
  3. To list the local Kubernetes contexts, use the following command.

    $ kubectl config get-contexts
    CURRENT   NAME                 CLUSTER              AUTHINFO             NAMESPACE
    *         k3d-k3s-default      k3d-k3s-default      k3d-k3s-default
  4. If you run multiple clusters, you need to choose which cluster kubectl talks to. You can set a default cluster for kubectl by setting the current context in the Kubernetes kubeconfig file. Additionally you can run following command to set the current context for kubectl.

    $ kubectl config use-context k3d-k3s-default
    Switched to context "k3d-k3s-default".

Set up Istio for k3d

  1. Once you are done setting up a k3d cluster, you can proceed to install Istio with Helm 3 on it.

    $ kubectl create namespace istio-system
    $ helm install istio-base istio/base -n istio-system --wait
    $ helm install istiod istio/istiod -n istio-system --wait
  2. (Optional) Install an ingress gateway:

    $ helm install istio-ingressgateway istio/gateway -n istio-system --wait

Set up Dashboard UI for k3d

k3d does not have a built-in Dashboard UI like minikube. But you can still set up Dashboard, a web based Kubernetes UI, to view your cluster. Follow these instructions to set up Dashboard for k3d.

  1. To deploy Dashboard, run the following command:

    $ helm repo add kubernetes-dashboard https://kubernetes.github.io/dashboard/
    $ helm upgrade --install kubernetes-dashboard kubernetes-dashboard/kubernetes-dashboard --create-namespace --namespace kubernetes-dashboard
  2. Verify that Dashboard is deployed and running.

    $ kubectl get pod -n kubernetes-dashboard
    NAME                                         READY   STATUS    RESTARTS   AGE
    dashboard-metrics-scraper-8c47d4b5d-dd2ks    1/1     Running   0          25s
    kubernetes-dashboard-67bd8fc546-4xfmm        1/1     Running   0          25s
  3. Create a ServiceAccount and ClusterRoleBinding to provide admin access to the newly created cluster.

    $ kubectl create serviceaccount -n kubernetes-dashboard admin-user
    $ kubectl create clusterrolebinding -n kubernetes-dashboard admin-user --clusterrole cluster-admin --serviceaccount=kubernetes-dashboard:admin-user
  4. To log in to your Dashboard, you need a Bearer Token. Use the following command to store the token in a variable.

    $ token=$(kubectl -n kubernetes-dashboard create token admin-user)

    Display the token using the echo command and copy it to use for logging in to your Dashboard.

    $ echo $token
  5. You can access your Dashboard using the kubectl command-line tool by running the following command:

    $ kubectl proxy
    Starting to serve on

    Click Kubernetes Dashboard to view your deployments and services.


  1. When you are done experimenting and you want to delete the existing cluster, use the following command:

    $ k3d cluster delete k3s-default
    Deleting cluster "k3s-default" ...
Was this information useful?
Do you have any suggestions for improvement?

Thanks for your feedback!