Ubuntu上使用Kind快速搭建本地Kubernetes开发测试集群

1. 先搞清楚 kind 到底解决什么问题以及它和普通 K8s 集群的区别如果你在 Ubuntu 上想快速搭建一个 Kubernetes 集群用于本地开发、测试或者学习但又不想折腾虚拟机、多台机器或者复杂的网络配置那么 kind 就是你当前最值得尝试的工具。它的核心价值就一句话用 Docker 容器来模拟 K8s 节点让你能在单机上秒级启动一个功能完整的 K8s 集群。很多人第一次接触 kind 会困惑它和 Minikube、kubeadm 或者云厂商的托管服务有什么区别我一般会这么解释Minikube 通常需要一个虚拟机或 Docker作为底层更像一个“单节点”的完整模拟kubeadm 是生产级集群的安装器需要多台实体或虚拟机。而 kind 的思路更“轻”它直接把每个 K8s 节点包括控制平面和工作节点都跑成 Docker 容器。这意味着启动极快因为节点就是容器创建和销毁几乎是秒级的。环境纯净集群生命周期完全由 Docker 容器管理清理时直接删容器就行几乎不会污染宿主机。多集群支持你可以轻松在本地同时运行多个不同版本、不同配置的 K8s 集群相互隔离。CI/CD 友好很多项目的 CI 流水线会选择用 kind 来创建一个临时 K8s 环境跑完测试就销毁成本极低。所以kind 最适合的场景是本地开发测试、CI/CD 集成测试、K8s 新功能或版本尝鲜、以及教学演示。如果你是要部署一个长期运行、高可用的生产集群那 kind 不是你的菜该用 kubeadm 或直接上云托管服务。在开始安装前你必须明确一个前置条件kind 本身是一个二进制命令行工具但它依赖于 Docker 来创建容器节点。所以整个流程的逻辑是先确保 Docker 在 Ubuntu 上能正常工作然后再安装 kind 命令行工具最后用 kind 去创建集群。2. 环境准备确保 Docker 是正常可用的状态在安装 kind 之前Docker 环境必须是就绪的。这步看似简单但却是后续所有步骤的基石很多“创建集群失败”的问题都卡在这里。2.1 安装与验证 Docker如果你的 Ubuntu 还没有安装 Docker可以通过官方仓库安装。这里以 Ubuntu 22.04 LTS 为例。# 1. 更新软件包索引并安装必要的依赖 sudo apt-get update sudo apt-get install -y ca-certificates curl gnupg # 2. 添加 Docker 的官方 GPG 密钥 sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg sudo chmod ar /etc/apt/keyrings/docker.gpg # 3. 设置 Docker 仓库 echo \ deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ $(. /etc/os-release echo $VERSION_CODENAME) stable | \ sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 4. 安装 Docker Engine sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin安装完成后不要急着往下走先做两个关键验证# 验证1Docker 服务是否运行 sudo systemctl status docker # 你应该看到 active (running) 的状态。如果没有启动它 sudo systemctl start docker sudo systemctl enable docker # 设置开机自启 # 验证2运行一个测试容器 sudo docker run hello-world如果hello-world容器能成功运行并输出欢迎信息说明 Docker 引擎本身是好的。2.2 处理权限问题避免一直用 sudo默认情况下运行docker命令需要sudo权限。为了方便我们通常将当前用户加入docker组。# 将当前用户加入 docker 组 sudo usermod -aG docker $USER # 重要生效组变更 newgrp docker执行newgrp docker后你当前终端会话就拥有了docker组的权限。打开一个新的终端窗口直接运行docker ps如果不报权限错误就说明配置成功了。这是很多教程里容易忽略的一步如果不生效后续kind命令也会因为调用 Docker API 失败而报错。2.3 排查潜在的 Docker 启动失败问题根据网络热词里提到的一些常见错误这里给出排查思路。如果你遇到docker desktop failed to start because virtualisation support wasn’t detected这类问题虽然这是 Desktop 版错误但根源类似或者 WSL2/VMware 环境下的虚拟机问题核心是检查虚拟化支持。对于物理机安装的 Ubuntu检查 CPU 虚拟化支持在终端运行egrep -c ‘(vmx|svm)’ /proc/cpuinfo如果输出大于 0说明支持。如果为 0需要进入 BIOS/UEFI 设置中开启 Intel VT-x 或 AMD-V 选项。检查 KVM 模块运行lsmod | grep kvm应该能看到kvm_intel或kvm_amd模块。如果没有尝试sudo modprobe kvm并安装cpu-checker包运行kvm-ok来检查。对于 VMware 或 WSL2 内的 Ubuntu 虚拟机VMware确保虚拟机设置中已为处理器勾选“虚拟化 Intel VT-x/EPT 或 AMD-V/RVI”。WSL2WSL2 本身基于 Hyper-V其内部的 Docker 实际上是Docker Desktop for Windows通过 WSL2 后端运行的你需要在 Windows 主机上安装 Docker Desktop 并启用 WSL2 集成。在纯 WSL2 的 Ubuntu 分发版里直接安装 Docker Engine 可能会遇到更多底层问题。一个关键建议对于本地开发如果你的主机是 Windows我通常更推荐直接使用Docker Desktop for Windows并启用 WSL2 后端然后在 WSL2 的 Ubuntu 中安装kind二进制文件。这样 Docker 守护进程由 Windows 版的 Docker Desktop 管理稳定性更好也避免了在 WSL2 内直接运行 Docker Engine 的复杂配置。3. 安装 kind 命令行工具并创建第一个集群Docker 环境就绪后安装 kind 本身非常简单它就是一个独立的二进制文件。3.1 下载并安装 kind从 kind 的 GitHub Releases 页面下载最新版本。以下命令下载的是 Linux 系统下的 amd64 架构版本。# 下载 kind 二进制文件 (请检查官网替换为最新版本号例如 v0.22.0) curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.22.0/kind-linux-amd64 # 赋予执行权限 chmod x ./kind # 移动到系统 PATH 目录方便全局调用 sudo mv ./kind /usr/local/bin/kind安装后验证一下kind version你应该能看到类似kind v0.22.0 go1.21.0 linux/amd64的输出。3.2 创建你的第一个 Kubernetes 集群现在用一行命令创建集群kind create cluster这个命令会拉取一个用于运行 K8s 节点的 Docker 镜像如kindest/node:v1.28.0。创建一个名为kind的 Docker 网络。启动一个容器作为 Kubernetes 控制平面节点。默认情况下也会创建一个工作节点容器单节点集群。生成一个 kubeconfig 文件并更新你本地~/.kube/config的上下文指向这个新集群。整个过程大约需要 1-2 分钟取决于网络下载镜像的速度。完成后你会看到Creating cluster “kind” … ✓这样的成功信息。3.3 验证集群状态创建完成后立即进行验证这是确认安装成功的关键。# 1. 检查 kubectl 是否指向了 kind 集群 (context 应为 kind-kind) kubectl cluster-info --context kind-kind # 2. 查看集群节点状态两个节点一个控制平面一个工作节点都应显示 Ready kubectl get nodes # 3. 查看所有系统 Pod 的状态等待所有 Pod 都变成 Running kubectl get pods -A如果kubectl命令未找到你需要安装它。可以通过官方方式或使用包管理器# 例如使用 apt 安装版本可能不是最新 sudo apt-get update sudo apt-get install -y kubectl # 或使用 curl 下载指定版本 curl -LO “https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl” chmod x kubectl sudo mv kubectl /usr/local/bin/关键点kubectl get pods -A显示的所有kube-system命名空间下的 Pod如 CoreDNS、etcd 等都需要变成Running状态集群才算完全就绪。刚创建完可能有些 Pod 还在ContainerCreating等待一两分钟再检查。4. 进阶配置与日常操作指南默认配置能跑起来但实际使用时你肯定需要更多控制。kind 的强大之处在于其灵活的配置。4.1 使用配置文件创建多节点集群创建一个kind-config.yaml文件# kind-config.yaml kind: Cluster apiVersion: kind.x-k8s.io/v1alpha4 nodes: - role: control-plane - role: worker - role: worker这个配置定义了一个三节点集群一个控制平面两个工作节点。使用配置文件创建集群kind create cluster --name multi-node-cluster --config kind-config.yaml注意我们通过--name指定了集群名称。这样你就可以在本地管理多个不同名称的 kind 集群。4.2 将本地镜像加载到 kind 集群中这是开发中最常用的功能之一。你在本地构建了 Docker 镜像例如my-app:latest需要让 kind 集群里的 Pod 能用上。# 假设你本地已有镜像 my-app:latest docker build -t my-app:latest . # 将镜像加载到名为 kind 的集群中如果集群名不是默认的用 --name 指定 kind load docker-image my-app:latest # 如果你有多个集群可以指定集群名 kind load docker-image my-app:latest --name multi-node-cluster这个命令会将本地的 Docker 镜像导入到 kind 集群所有节点的容器环境中。之后你在 Pod 的 YAML 里指定image: my-app:latest就可以直接使用了无需配置镜像仓库。4.3 端口映射与 Ingress默认情况下集群服务Service的 NodePort 或 LoadBalancer 类型在宿主机上是无法直接访问的。需要在创建集群时通过配置将容器端口映射到宿主机。# kind-config-with-port.yaml kind: Cluster apiVersion: kind.x-k8s.io/v1alpha4 nodes: - role: control-plane extraPortMappings: - containerPort: 80 hostPort: 8080 listenAddress: “127.0.0.1” # 可选绑定到本地回环 protocol: tcp - containerPort: 443 hostPort: 8443 protocol: tcp这样创建集群后你在集群内部署一个监听 80 端口的服务就可以在宿主机上通过http://localhost:8080访问了。对于 Ingresskind 有一个特别的配置可以启用一个基于 nginx 的 Ingress 控制器kind create cluster --configkind-config-with-port.yaml kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/static/provider/kind/deploy.yaml等待 Ingress Controller 的 Pod 变成Running你就可以使用 Ingress 资源了。4.4 集群的日常管理# 列出所有 kind 集群 kind get clusters # 切换 kubectl 上下文到指定集群 kubectl config use-context kind-multi-node-cluster # 删除一个集群 kind delete cluster --name multi-node-cluster # 删除所有 kind 集群 kind delete clusters --all重要提醒删除集群会销毁其中所有容器和数据是不可逆的。确保你已经保存了需要的数据如通过 PersistentVolume 持久化的数据但 kind 默认的本地存储也会随容器消失。5. 常见问题排查与性能优化建议即使按照步骤操作你也可能会遇到一些问题。下面是我在多次使用中总结的排查顺序。5.1 集群创建失败现象kind create cluster命令长时间卡住或报错退出。排查顺序检查 Docker首先运行docker ps和docker run hello-world确认 Docker 本身无问题。如果 Docker 命令都报错回到第二步检查 Docker 安装和权限。检查镜像拉取kind 需要拉取kindest/node镜像。如果网络不好可能会超时。可以尝试预先拉取镜像docker pull kindest/node:v1.28.0版本需与 kind 默认版本一致可通过kind version查看提示。检查资源运行docker info查看 Docker 总资源。如果宿主机内存或磁盘空间不足Docker 容器可能无法启动。kind 每个节点容器大约需要 2GB 内存确保你的机器有足够余量。查看详细日志使用kind create cluster --name test -v 1或更高-v级别输出更详细的日志看卡在哪一步。检查防火墙或安全软件某些安全策略可能会阻止 Docker 容器间的网络通信导致集群内部组件无法启动。5.2 kubectl 无法连接集群现象kubectl get nodes报错The connection to the server localhost:8080 was refused。排查确认集群存在kind get clusters看你的集群是否在列表中状态是否为RUNNING。确认 kubeconfigkubectl config view查看当前配置。确保当前上下文current-context是你刚创建的 kind 集群如kind-kind。可以用kubectl config use-context kind-kind切换。检查 kubeconfig 文件权限极少情况下~/.kube/config文件权限不对kubectl无法读取。5.3 Pod 一直处于 Pending 或 ContainerCreating 状态现象kubectl get pods -A显示 Pod 长时间不变成Running。排查查看 Pod 详情kubectl describe pod pod-name -n namespace在Events部分会有最直接的错误原因。常见原因包括Failed to pull image镜像拉取失败。如果是本地镜像确认已用kind load docker-image加载。Insufficient memory/cpu节点资源不足。kind 集群资源受限于 Docker 容器资源限制。0/1 nodes are available: 1 node(s) had taint…节点有污点Pod 无法调度。查看节点状态kubectl describe node node-name看节点是否内存、磁盘压力过大或者 NotReady。5.4 性能优化与使用建议资源分配如果你的开发机内存充足比如16GB以上可以考虑在创建集群时通过 Docker 的--resource限制需在 kind 配置中通过extraMounts和kubeadm配置间接调整或直接配置 Docker 守护进程为节点容器分配更多内存和 CPU这能提升集群运行应用的性能。镜像缓存kind 节点容器本身会有一个容器镜像存储。频繁创建销毁集群时每次都要重新拉取kindest/node镜像。你可以通过配置使用一个本地的镜像仓库缓存来加速但这属于进阶用法。持久化存储kind 默认使用emptyDir或hostPath映射到容器内的存储集群删除后数据会丢失。对于需要持久化的数据建议使用网络存储如 NFS的 PersistentVolume或者将宿主机目录通过extraMounts挂载到节点容器内但这只是开发测试用途。多集群管理当你有多个 kind 集群时善用kubectl config use-context和kubectl config get-contexts来切换。也可以使用kubectx这类工具来管理上下文。最后对于 Ubuntu 上的 kind我个人最核心的建议是先把 Docker 这一层彻底打通确保docker run和用户权限没问题那么 kind 的安装和基本使用几乎不会遇到障碍。把它当作一个快速搭建、用完即焚的沙盒环境这才是 kind 设计哲学的正确使用方式。当你要进行更复杂的网络、存储或多集群互联测试时再回头来深入研究它的配置文件。