How to Install and Use K3D

Getting Started

I have discovered K3D a bit late but it is one of the best tools for local Kubernetes development It does not run your Kubernetes cluster inside a virtual machine just like Minikube does. It uses Docker and allows you to create multi-node clusters. You may want to check their official page for more information.

I created a sample project to install and configure K3D for my local Kubernetes development and also added some sample deployments with ingress service.


Docker and Helm need to be installed in your local development environment. Please do not proceed with the installation before installing Docker and Helm.


I followed the official documentation to installK3Don my local development environment but made a few changes. I skipped the deployment of Traefik because K3D install V1 and I wanted to install the latest version of Traefik. You can also prefer another ingress controller like nginx.

You can install the environment by running a single script - and the script itself is quite self-explanatory:

# Create Cluster
k3d cluster create ${CLUSTER_NAME} --api-port \
-p 80:80@loadbalancer \
-p 443:443@loadbalancer \
--k3s-server-arg "--no-deploy=traefik" --agents ${NODE_COUNT} --servers ${SERVER_COUNT}

# Install Traefik V2
helm repo add traefik
helm install traefik traefik/traefik

# Wait until Traefik deployment is finished
while [[ $(kubectl get pods -l "${TRAEFIK_LABEL}" -o 'jsonpath={..status.conditions[?(@.type=="Ready")].status}') != "True" ]]
  sleep 1

# Expose Traefik Dashboard
kubectl port-forward $(kubectl get pods --selector "" --output=name) 9000:9000 &
echo "You can reach Traefik dashbaord by: http://localhost:9000/dashboard/"

# Set cluster context to new cluster
kubectl config use-context k3d-${CLUSTER_NAME}

# Show cluster info
kubectl cluster-info

You may want to change the global variables for your own environment. Once the script is running you can check the Traefik Dashboard by visiting http://localhost:9000/dashboard/#/.

Example Deployment

You can check one of the example deployments in the main project directory and apply it via kubectl apply -f <sample-directory> command. If you do not edit anything in the YAML definitions, it will create a host-based ingress rule for the deployment. If you check the Traefik HTTP services, you will find your rule as below:

Please note that if you want to use the host-based ingress rule, you will have to add the FQDN to your /etc/hosts file.

Example deployment output will look like this:

$ kubectl get svc,ingress,deployment vault
NAME            TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)    AGE
service/vault   ClusterIP   <none>        8200/TCP   65m

NAME                              CLASS    HOSTS            ADDRESS   PORTS   AGE   <none>   vault.onur.lab             80      65m

NAME                    READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/vault   1/1     1            1           65m

Last updated