Docker Desktop on Windows 11 Prox64 often fails to share files with Kubernetes clusters because the default Hyper-V backend restricts access to WSL2 distros where K3s runs. The most reliable fix is switching Docker’s backend to WSL2, ensuring your project directory is explicitly shared in settings, and verifying that the Kubernetes engine is restarted after these changes take effect.
Understanding the Architecture Mismatch
When you enable Kubernetes in Docker Desktop on Windows, it does not run a traditional Linux VM. Instead, it spins up a lightweight cluster using K3s inside one of your installed WSL2 distributions, typically named
docker-desktop or
docker-desktop-data. If your Docker Desktop is still configured to use the Hyper-V backend, there is a fundamental isolation layer between the Windows host, the Hyper-V VM, and the WSL2 instance. Files mounted from your Windows filesystem into containers running inside the WSL2-based Kubernetes cluster may appear empty, read-only, or completely inaccessible. This is not a bug in Kubernetes itself, but a consequence of how file systems are virtualized across different hypervisor technologies. Switching to the WSL2 backend aligns the container runtime with the underlying Linux kernel environment that Kubernetes expects.
Switching Docker Backend to WSL2
The first critical step is to ensure Docker Desktop is using the WSL2 backend rather than Hyper-V. This allows seamless integration between the Docker daemon and the WSL2 distribution hosting the Kubernetes cluster. Open the Docker Desktop application and click on the gear icon to open Settings. Navigate to the General tab under Resources. You will see an option labeled "Use the WSL 2 based engine." Check this box if it is not already selected. If you are currently using Hyper-V, you must restart Docker Desktop for this change to take effect. Once restarted, verify the status by checking the bottom left corner of the Docker window; it should indicate that WSL2 is active. This change alone resolves many file sharing issues because it removes the translation layer that often breaks volume mounts when interacting with Kubernetes services.
Configuring Shared Folders Correctly
Even with the correct backend, specific directories must be explicitly allowed to be shared with the WSL2 instance. Go to Settings again, then navigate to Resources > File Sharing. Here, you must add the root path of your project directory. For example, if your code is located at
C:\Users\YourName\Projects\MyApp, you need to add
/mnt/c/Users/YourName/Projects/MyApp or simply
/c/Users/YourName/Projects/MyApp depending on your WSL version. It is crucial to use the absolute path within the WSL2 filesystem structure. After adding the path, apply and restart Docker Desktop. This tells the Docker daemon exactly which parts of the Windows NTFS filesystem are safe to expose as volumes to containers. Without this explicit configuration, Kubernetes pods attempting to mount these paths will fail with permission denied errors or show empty directories.
Verifying Kubernetes Volume Mounts
After changing settings, you must verify that the Kubernetes engine has picked up the new configuration. Sometimes, the K3s cluster remains cached with old volume definitions. Restart the Kubernetes service by clicking the stop button next to the Kubernetes logo in the Docker Desktop dashboard, waiting for it to fully stop, and then starting it again. Once running, deploy a simple test pod that mounts your shared volume. Use a command like
kubectl get pods to check the status. If the pod is in a Pending state, describe it with
kubectl describe pod <pod-name> to look for events related to volume attachment. Common errors include "no such file or directory" or "permission denied," which usually point back to incorrect path formatting in the
volumeMounts section of your deployment YAML. Ensure that the
hostPath or
persistentVolumeClaim references match the shared folder paths defined in Docker Settings.
For more insights on managing resources in this environment, see
Managing Memory and Processor Swap in WSL2 with Docker Desktop on Ubuntu. Additionally, understanding which files are actually accessible can help troubleshoot unexpected behavior, so refer to
Which files are shared between docker container and host? for detailed explanations of mount points.
Troubleshooting Persistent Issues
If file sharing still fails after these steps, consider clearing the Docker data cache. In rare cases, corrupted metadata about mounted volumes can persist even after configuration changes. Stop all containers and delete the local images and volumes through the Docker Desktop UI or via CLI commands like
docker system prune -a. Be cautious as this removes unused data. Another potential issue is antivirus software interfering with real-time scanning of files being accessed by the WSL2 subsystem. Adding exclusions for your project directory and the WSL2 virtual hard disk (usually located in %LOCALAPPDATA%\Docker) can resolve performance drops or access blocks. Finally, ensure your Windows 11 build is up to date, as older versions of the OS had known bugs with WSL2 file system performance that affected Docker operations.
Frequently Asked Questions
Why do my Kubernetes pods show empty directories?
This typically happens when the path specified in the volume mount does not exist in the WSL2 filesystem or is not listed in Docker's File Sharing settings. Verify that the absolute path matches the WSL2 convention (e.g., /mnt/c/) and that the directory is explicitly added to the shared resources list in Docker Desktop settings.
Can I use Hyper-V backend with Kubernetes on Windows 11?
While technically possible, using Hyper-V creates significant friction for file sharing because Kubernetes runs inside WSL2. The two environments are isolated, making volume mounts unreliable. Switching to the WSL2 backend is strongly recommended for a stable development experience.
How do I find the correct path for my project in WSL2?
Open your WSL2 terminal and navigate to your project directory. Use the
pwd command to see the current path. Alternatively, Windows drives are mounted under /mnt/c/, /mnt/d/, etc. So a Windows path C:\Project would be /mnt/c/Project in Linux.
What should I do if Kubernetes crashes after changing file shares?
Kubernetes might crash if it tries to access a volume that was removed or renamed during the configuration change. Restart the Kubernetes engine from the Docker Desktop dashboard. If the issue persists, delete the existing K3s cluster data by stopping Docker and deleting the wsl distro instances named docker-desktop and docker-desktop-data.
Does enabling WSL2 backend affect Docker Compose?
No, enabling the WSL2 backend improves compatibility with Docker Compose as well. Both Docker Engine and Docker Compose benefit from the native Linux kernel performance provided by WSL2, leading to faster build times and more reliable file watching mechanisms.