WSL2环境下搭建Kubernetes v1.34.2与Docker开发环境

1. 项目概述

在Windows Subsystem for Linux (WSL)环境下搭建Kubernetes集群是当前云原生开发的热门实践。本文将详细演示如何在WSL2的Ubuntu 22.04系统中，部署Kubernetes v1.34.2与Docker的完整开发环境。这种组合特别适合需要在本地进行容器编排测试的开发者和DevOps工程师。

重要提示：自Kubernetes v1.24起已移除对Dockershim的原生支持，必须通过cri-dockerd组件实现Docker与Kubernetes的集成。

2. 环境准备与基础配置

2.1 WSL2与Ubuntu安装

首先确保Windows系统已启用WSL2功能：

bash复制wsl --install -d Ubuntu-22.04
wsl --set-version Ubuntu-22.04 2

2.2 系统基础配置

更新软件源并安装必要工具：

bash复制sudo apt update && sudo apt upgrade -y
sudo apt install -y curl apt-transport-https ca-certificates gnupg lsb-release wget

2.3 关键内核参数设置

Kubernetes运行需要特定的内核模块：

bash复制cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF
sudo modprobe overlay
sudo modprobe br_netfilter

网络参数调整：

bash复制cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-iptables = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward = 1
EOF
sudo sysctl --system

3. Docker引擎安装与配置

3.1 官方Docker安装

添加Docker官方仓库：

bash复制sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \
https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

安装Docker组件：

bash复制sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

3.2 用户权限配置

将当前用户加入docker组：

bash复制sudo usermod -aG docker $USER
newgrp docker

4. Kubernetes组件安装

4.1 添加Kubernetes仓库

bash复制curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.34/deb/Release.key | \
sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg

echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] \
https://pkgs.k8s.io/core:/stable:/v1.34/deb/ /' | \
sudo tee /etc/apt/sources.list.d/kubernetes.list

4.2 安装指定版本组件

bash复制sudo apt update
sudo apt install -y kubelet=1.34.2-1.1 kubeadm=1.34.2-1.1 kubectl=1.34.2-1.1
sudo apt-mark hold kubelet kubeadm kubectl

5. cri-dockerd安装与配置

5.1 下载安装包

bash复制wget https://github.com/Mirantis/cri-dockerd/releases/download/v0.3.23/cri-dockerd_0.3.23.3-0.ubuntu-$(lsb_release -cs)_amd64.deb
sudo dpkg -i cri-dockerd_0.3.23.3-0.ubuntu-$(lsb_release -cs)_amd64.deb

5.2 服务配置

创建服务覆盖文件：

bash复制sudo mkdir -p /etc/systemd/system/cri-docker.service.d/
cat <<EOF | sudo tee /etc/systemd/system/cri-docker.service.d/override.conf
[Service]
ExecStart=
ExecStart=/usr/bin/cri-dockerd --container-runtime-endpoint fd:// --network-plugin=cni --pod-infra-container-image=registry.k8s.io/pause:3.10
EOF

启动服务：

bash复制sudo systemctl daemon-reload
sudo systemctl enable cri-docker.service
sudo systemctl restart cri-docker.service

6. Kubernetes集群初始化

6.1 预拉取镜像

bash复制sudo kubeadm config images pull \
  --kubernetes-version=v1.34.2 \
  --cri-socket=unix:///var/run/cri-dockerd.sock

6.2 主节点初始化

bash复制IP_ADDR=$(hostname -I | awk '{print $1}')
sudo kubeadm init \
  --apiserver-advertise-address=$IP_ADDR \
  --pod-network-cidr=10.244.0.0/16 \
  --service-cidr=10.96.0.0/12 \
  --kubernetes-version=v1.34.2 \
  --cri-socket=unix:///var/run/cri-dockerd.sock

6.3 kubectl配置

bash复制mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

7. 网络插件部署

安装Flannel网络组件：

bash复制kubectl apply -f https://github.com/flannel-io/flannel/releases/latest/download/kube-flannel.yml

允许主节点调度Pod：

bash复制kubectl taint nodes --all node-role.kubernetes.io/control-plane-

8. 验证与测试

8.1 集群状态检查

bash复制kubectl get nodes
kubectl get pods -A

8.2 测试应用部署

bash复制kubectl create deployment nginx --image=nginx:alpine
kubectl expose deployment nginx --port=80 --type=NodePort
kubectl get svc nginx

访问测试：

bash复制curl http://localhost:$(kubectl get svc nginx -o jsonpath='{.spec.ports[0].nodePort}')

9. 常见问题排查

9.1 节点NotReady状态

检查kubelet日志：

bash复制sudo journalctl -u kubelet -f

9.2 Pod启动失败

查看Pod详情：

bash复制kubectl describe pod <pod-name>

9.3 网络连接问题

检查Flannel Pod日志：

bash复制kubectl logs -n kube-flannel <flannel-pod-name>

10. 环境清理

重置Kubernetes集群：

bash复制sudo kubeadm reset -f --cri-socket=unix:///var/run/cri-dockerd.sock
sudo rm -rf /etc/cni/net.d $HOME/.kube/config

在实际使用中，建议定期清理未使用的Docker镜像以节省磁盘空间。对于WSL环境，还需要注意内存分配问题，可通过在%USERPROFILE%.wslconfig文件中配置内存限制来优化性能。