云原生容器编排CLI开发工具【免费下载链接】minikubeRun Kubernetes locally项目地址https://gitcode.com/gh_mirrors/mi/minikube点击查看免费下载导读本指南讲解如何在 Windows 的 WSL 2Windows Subsystem for Linux 2环境中配置 minikube使其通过Docker 驱动运行本地 Kubernetes 集群并打通从 Windows 浏览器访问集群内服务这条链路。读完本文你将掌握 WSL 2 中两种 Docker 提供方式WSL 发行版内安装 Docker Engine / Docker Desktop 的 WSL 集成的完整配置流程、minikube start --driverdocker的启动要点以及 NodePort 与 LoadBalancer 两类服务在 WSL 2 网络限制下的正确访问方式及其底层原理。WSL 2 与 Docker 驱动为什么需要专门配置minikube 的 Docker 驱动Docker driver允许将 Kubernetes 直接装入一个已有的 Docker 环境Kubernetes 节点以容器形式运行在 Linux 上无需启用虚拟化。官方文档对 WSL 用户的明确要求是如果使用 WSL必须先完成本指南的步骤见 Docker 驱动文档 的 Requirements 一节。在 Windows WSL 2 场景下有两个需要解决的天然问题Docker 从哪里来WSL 2 是一个轻量级虚拟机Windows 上的 Docker 不会自动对 WSL 发行版可见需要显式配置。网络连通性WSL 2 的节点 IPminikube ip输出的地址无法从 Windows 宿主机直接访问必须借助端口转发或隧道。minikube 在源码层面明确识别了这一场景NeedsPortForward()会检测当前进程运行在 WSL 中并返回true从而让 minikube 走端口转发路径详见下文从源码看 WSL 识别小节。官方支持两种在 WSL 2 中提供 Docker 的方式WSL 发行版内直接安装 Docker Engine——在运行minikube的同一个 Linux 发行版中安装 Docker。Docker Desktop 的 WSL 集成——在 Windows 上安装 Docker Desktop并对其启用 WSL 集成。两者任选其一即可后续minikube start --driverdocker的用法完全一致。第一步安装 WSL 并确认版本为 WSL 2首先安装 WSL。Windows 10 及以上系统可在管理员 PowerShell 中执行wsl --install安装完成后确认当前默认发行版运行在 WSL 2 而非 WSL 1wsl --list --verbose输出示例NAME STATE VERSION * Ubuntu Running 2VERSION列显示2即表示使用的是 WSL 2。如果显示1可以通过wsl --set-version 发行版名称 2进行转换。第二步按需选择 Docker 提供方式方式 A在 WSL 发行版内安装 Docker Engine进入你的 WSL 发行版终端按照 Docker Engine 官方安装指南完成安装选择对应发行版的安装步骤并务必执行 Linux 安装后的非 root 用户配置步骤即把当前用户加入docker用户组否则后续minikube start时可能因权限不足而失败sudo usermod -aG docker $USER newgrp docker这也是 Docker 驱动文档 Requirements 中特别强调的步骤。配置完成后Docker 守护进程随 WSL 发行版一起运行minikube 直接与该发行版内的 Docker 通信。方式 B使用 Docker Desktop 的 WSL 集成在 Windows 上安装 Docker Desktop for Windows安装时保持默认的 WSL 2 backend 选项。打开 Docker Desktop进入Settings Resources WSL integration。在列表中找到你要运行 minikube 的发行版例如 Ubuntu打开其集成开关点击 Apply Restart。配置完成后WSL 发行版内的docker命令会直接连接到 Docker Desktop 的守护进程。需要留意的是这种模式下 Docker 守护进程运行在 Windows 侧外部守护进程minikube 源码中的NeedsPortForward()会因此对 docker 驱动返回true见 driver.go这正是 WSL 场景下必须使用端口转发访问服务的原因之一。第三步在 WSL 内验证 Docker 可用无论采用哪种方式回到 WSL 终端验证 Docker 命令可用docker version docker psdocker version应能正常输出版本信息Client 与 Server 均可见docker ps应能正常返回可以为空列表且不报权限错误如果报permission denied说明方式 A 的非 root 配置未完成。第四步用 Docker 驱动启动 minikube在 WSL 终端内执行minikube start --driverdocker命令执行后minikube 会拉取 kicbase 基础镜像并以容器方式启动一个 Kubernetes 节点。如需将 Docker 设为默认驱动以后直接执行minikube start即可minikube config set driver docker补充WSL 2 下可能需要的 cgroup 挂载修复Docker 驱动的官方文档在 Known Issues 中记录了一个 WSL2实验性支持场景下的已知问题见 Docker 驱动文档如果启动过程中出现与systemdcgroup 相关的错误需要在 WSL 发行版内执行sudo mkdir /sys/fs/cgroup/systemd sudo mount -t cgroup -o none,namesystemd cgroup /sys/fs/cgroup/systemd从 Windows 浏览器访问你的服务这是 WSL 2 Docker 驱动场景下最容易踩坑的地方minikube 节点运行在容器内minikube ip输出的节点 IP 从 Windows 宿主机上无法直接访问。请勿尝试用浏览器直接访问该 IP。需要根据服务类型选择下述两种方式之一。NodePort 服务使用minikube service对类型为NodePort的服务执行minikube service service-name --url命令会输出形如http://127.0.0.1:port的地址直接在 Windows 浏览器打开即可。注意此命令会以前台进程方式持续运行维持 SSH 隧道使用 URL 期间请保持终端窗口打开按Ctrl-C结束时会自动清理网络路由。从源码看其实现当检测到 Docker 驱动且NeedsPortForward()返回true时service.go 中的startKicServiceTunnel会调用kic.NewServiceTunnel为服务的每个端口建立 SSH 本地端口转发并返回http://127.0.0.1:local_port形式的 URL见 service_tunnel.go。SSH 隧道由ssh -N -L保持终端关闭即隧道断开。LoadBalancer 服务使用minikube tunnel对类型为LoadBalancer的服务在另一个独立终端中运行并保持minikube tunnelminikube tunnel会在宿主机上创建一条指向集群 Service CIDR 的网络路由以集群 IP 为网关并在命令行中显示运行状态machine / route / services 等。之后在浏览器中通过minikube tunnel输出的外部 IP 访问服务即可没有运行 tunnel 时kubectl get svc中 LoadBalancer 服务的 EXTERNAL-IP 会一直显示pending。Ctrl-C结束进程时路由会被清理。tunnel 命令的实现位于 tunnel.go它通过 Kubernetes clientset 查询集群中的 LoadBalancer 服务在driver.NeedsPortForward(co.Config.Driver)为真正是 WSL 场景时走 SSH 隧道路径同时支持--cleanup默认true用于清理异常退出遗留的孤儿路由与--bind-address参数。快速验证示例在 WSL 终端中依次执行可快速验证整条链路kubectl create deployment hello-minikube1 --imagekicbase/echo-server:1.0 kubectl expose deployment hello-minikube1 --typeNodePort --port8080 minikube service hello-minikube1 --url浏览器访问输出的http://127.0.0.1:port应能看到 echo-server 的响应内容。从源码看 WSL 场景的识别与端口转发决策minikube 是如何知道当前处于 WSL 中并切换访问策略的关键在于 detect.go 中的IsMicrosoftWSL()func IsMicrosoftWSL() bool { return os.Getenv(WSL_DISTRO_NAME) ! || os.Getenv(WSLPATH) ! }它通过检查WSL_DISTRO_NAMEWSL 发行版内必然存在或WSLPATH环境变量来判定进程是否运行在 WSL 中。随后 driver.go 的NeedsPortForward()会综合判断func NeedsPortForward(name string) bool { if !IsKIC(name) { return false } if oci.IsExternalDaemonHost(name) { return true } // Docker for Desktop if runtime.GOOS darwin || runtime.GOOS windows || detect.IsMicrosoftWSL() { return true } ... }即只要驱动是 KIC 系Docker 驱动即属此类且进程运行在 Windows/macOS 或 WSL或 Docker 守护进程为外部宿主中minikube 就会判定节点 IP 不可直达从而在minikube service/minikube tunnel中启用端口转发路径。这正是本指南前文所有用 127.0.0.1 而非节点 IP操作建议的底层依据。常见问题与排障现象排查方向docker ps报permission denied未完成非 root 用户配置执行sudo usermod -aG docker $USER并重新登录会话minikube start报 systemd cgroup 相关错误执行上文 cgroup 挂载修复命令后重试浏览器无法访问minikube ip输出的 IP属预期行为改用minikube service name --url或minikube tunnel能访问127.0.0.1:port但打不开服务确认minikube service --url所在终端未关闭检查浏览器未设置代理端口小于 1024 的服务无法访问Windows 下旧版 OpenSSH 客户端仅支持 root 转发特权端口升级 SSH 客户端如choco install openssh另外需注意Docker 驱动的ingress、ingress-dns插件目前仅支持 Linux且 minikube 在 macOS/WSL 场景下不会使用节点 IP 直达方式相关网络限制的完整讨论见 Docker 驱动文档 的 Known Issues 一节。相关资源访问应用Accessing apps手册NodePort / LoadBalancer 访问的完整示例、NodePort 端口范围调整--extra-configapiserver.service-node-port-range及孤儿路由清理minikube tunnel --cleanupDocker 驱动参考文档驱动要求、Rootless Docker 用法、已知问题与排障源码参考driver.go端口转发决策、detect.goWSL 检测、service.goservice 隧道、tunnel.gotunnel 命令完成上述配置后你便拥有了一个在 Windows 上基于 WSL 2 Docker 驱动的本地 Kubernetes 开发环境集群在 WSL 中启动服务通过 127.0.0.1 隧道从 Windows 浏览器无缝访问开发体验与原生 Linux 基本一致。赞分享云原生容器编排CLI开发工具【免费下载链接】minikubeRun Kubernetes locally项目地址https://gitcode.com/gh_mirrors/mi/minikube点击查看免费下载相关推荐WSL 2 中使用 Docker 容器的完整指南WSL 2 中使用 Docker 容器的完整指南 容器技术概述 容器技术是现代软件开发中不可或缺的一部分它通过轻量级的虚拟化方式将应用程序及其依赖项打包在一文档/教程Testcontainers 在 Windows 上的完整运行指南Docker Desktop、WSL2 与 WSL 配置详解Testcontainers 在 Windows 上的完整运行指南Docker Desktop、WSL2 与 WSL 配置详解 Testcontainers测试容器运行时Git Credential Manager 在 WSL 中的配置指南Windows 与 WSL 共享凭据的完整方案Git Credential Manager 在 WSL 中的配置指南Windows 与 WSL 共享凭据的完整方案 本文以 Git Credential M开发工具认证鉴权创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考