Install Istio to Docker Desktop (WSL 2)

Istio3 is an open-source service mesh1, one of those tools that sounds intimidating until you see what it does: it puts a smart proxy next to every service in your cluster, and suddenly you have traffic control, security, and observability without touching your application code. The hard part is getting it running, and on Windows, the documentation is a bit vague, since the website only provides documentation for nix-based systems.

This guide fills that gap: I will walk you through installing Istio on Docker Desktop with WSL 2, the way I actually got it working on my machine.

📦 Install Istio

Download the istioctl.exe executable from the official istio releases page, extract it, and place it in a folder of your choice. istioctl is the command line tool that manages the whole mesh, so it deserves a permanent home on your disk.

Adding the environment variable will be straightforward: add the directory location of the istioctl to PATH. Do not skip this step, istioctl is useless if your shell cannot find it. Once it is on the PATH, open a new terminal and confirm it works with istioctl version.

Install the istio namespace and services in kubernetes:

istioctl install --set profile=default -y

This command deploys the Istio control plane into your cluster. The default profile is the right starting point for most users, and the -y flag skips the confirmation prompt. It will take a few minutes the first time, since it is pulling a stack of images.

Also set istio to automatically inject Envoy sidecar proxies when deploying applications and services to the default namespace:

kubectl label namespace default istio-injection=enabled

This is the step that makes the magic automatic. With that label in place, every new pod you deploy to the default namespace gets an Envoy sidecar injected next to it, and the mesh starts observing and routing its traffic without any changes to your application code.

🧰 Troubleshoot

Things do not always go smoothly on a local setup, so here are the checks I run when something looks off.

Determine if the Kubernetes cluster is running in an environment that supports an external load balancer:

kubectl get svc istio-ingressgateway -n istio-system

On Docker Desktop, an external load balancer is not always available, and the ingress gateway may sit in a pending state. The command above tells you which column is stuck, and whether you need to fall back to port forwarding or a NodePort.

Check if there are any problems presented in the analyze command:

istioctl analyze

This is the closest thing Istio has to a health check for your configuration. It inspects your cluster and points out misconfigurations with suggested fixes, so run it whenever something is not behaving.

Also, check the endpoint if it’s empty or returning any headers and data:

curl -s -I -H "Host:keycloak.7f000101.nip.io" http://[IP_ADDRESS]

If the response comes back with HTTP headers and a status code, the ingress is alive and routing. If it comes back empty, the mesh is dropping the traffic somewhere between the gateway and the service.

🧠 Final Thoughts

Istio on Docker Desktop is a great way to learn service mesh concepts without spinning up a cloud cluster, and once the pillars are in place, the injection label does the heavy lifting for you. Windows support may not get the love that Linux docs do, but the tools work, and the troubleshooting commands above cover the three ways it usually breaks.

Start small: deploy one service, watch the sidecar appear, and curl through the gateway. Before long, the mesh stops being a mystery and starts being the best debugging tool in your stack. Thanks for reading!

1. Service mesh is a dedicated infrastructure layer for facilitating service-to-service communications between services or microservices, using a proxy. ↩︎
2. Kubernetes is an open-source container-orchestration system for automating computer application deployment, scaling, and management. It was originally designed by Google and is now maintained by the Cloud Native Computing Foundation. ↩︎
3. Istio is a service mesh, a modernized service networking layer that provides a transparent and language-independent way to flexibly and easily automate application network functions. ↩︎