Introduction

Running an ingress controller on Docker Desktop with WSL2 is a common local Kubernetes setup on Windows. The core job is to enable Docker Desktop's Kubernetes cluster, install an ingress controller such as ingress-nginx, and route a hostname on your machine to the controller so local traffic reaches your test service.

Enable Kubernetes in Docker Desktop

Before installing ingress, make sure Docker Desktop is using the WSL2 backend and Kubernetes is enabled. In Docker Desktop settings, the WSL2 integration and Kubernetes options both need to be turned on. After applying the settings, confirm that kubectl points to the Docker Desktop cluster.

kubectl config current-context
kubectl get nodes

You should see the docker-desktop context and at least one ready node. If this step fails, ingress installation is not the problem yet.

Install ingress-nginx

For local development, the ingress-nginx project is the most common controller. Apply the official deployment manifest and wait for the controller pods to become ready.

kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/static/provider/cloud/deploy.yaml
kubectl get pods -n ingress-nginx

On Docker Desktop, the service is usually exposed through localhost. Check the controller service:

kubectl get svc -n ingress-nginx

If the controller is running, you now have the component that reads Ingress resources and forwards traffic to services.

Deploy a Test Application

Use a very small application first so you can isolate ingress problems from application problems. This example deploys a demo HTTP container and exposes it as a ClusterIP service.

1apiVersion: apps/v1
2kind: Deployment
3metadata:
4  name: hello-web
5spec:
6  replicas: 1
7  selector:
8    matchLabels:
9      app: hello-web
10  template:
11    metadata:
12      labels:
13        app: hello-web
14    spec:
15      containers:
16        - name: hello-web
17          image: hashicorp/http-echo:1.0
18          args:
19            - "-text=hello from ingress"
20          ports:
21            - containerPort: 5678
22---
23apiVersion: v1
24kind: Service
25metadata:
26  name: hello-web
27spec:
28  selector:
29    app: hello-web
30  ports:
31    - port: 80
32      targetPort: 5678

Apply it:

kubectl apply -f hello-web.yaml
kubectl get pods
kubectl get svc hello-web

Create the Ingress Resource

Now define an ingress that routes a hostname to the service. The ingressClassName should match the installed controller.

1apiVersion: networking.k8s.io/v1
2kind: Ingress
3metadata:
4  name: hello-web
5spec:
6  ingressClassName: nginx
7  rules:
8    - host: hello-web.local
9      http:
10        paths:
11          - path: /
12            pathType: Prefix
13            backend:
14              service:
15                name: hello-web
16                port:
17                  number: 80

Apply and inspect it:

kubectl apply -f hello-web-ingress.yaml
kubectl describe ingress hello-web

Then add 127.0.0.1 hello-web.local to your Windows hosts file and test:

curl http://hello-web.local/

If everything is correct, the request should return the demo text.

Troubleshooting on Docker Desktop and WSL2

Most local ingress failures fall into a short list. If curl reaches nothing, verify the controller pod and the test service separately. If the service works through kubectl port-forward but not through the ingress hostname, the problem is in ingress or local name resolution, not in the app.

Useful commands:

kubectl logs -n ingress-nginx deploy/ingress-nginx-controller
kubectl get ingress
kubectl get endpoints hello-web

If the ingress exists but there are no endpoints, the service selector does not match the pod labels. If the hostname does not resolve, the hosts-file entry is missing or incorrect.

Common Pitfalls

• Assuming Docker Desktop enables an ingress controller automatically.
• Skipping verification of the docker-desktop Kubernetes context before debugging manifests.
• Forgetting to set ingressClassName to the controller you actually installed.
• Testing the hostname before adding it to the local hosts file.
• Debugging the ingress first when the underlying service is not healthy.

Summary

• Start by enabling Kubernetes in Docker Desktop and confirming the docker-desktop context works.
• Install ingress-nginx and verify its controller pods are ready.
• Deploy a small service first so ingress debugging stays focused.
• Create an Ingress resource with ingressClassName: nginx and map a local hostname to 127.0.0.1.
• Use controller logs, service endpoints, and a direct service test to isolate failures quickly.