Skip to content

Kind 单节点部署 ​

Kind 单节点集群在一台主机上提供完整的 Kubernetes 环境。一个 control-plane 节点同时承担集群管理与工作负载运行职责,适合本地开发、清单调试和 CI 冒烟测试。

单节点集群不提供高可用,也无法模拟多机故障。它的价值在于以较低成本验证集群能否正常启动、核心组件是否就绪,以及工作负载的基本行为。

核心概念 ​

单节点不等于单组件 ​

单节点集群仍然是一个完整的 Kubernetes 集群:一个节点同时承担 control-plane 与 worker 的职责。API Server、etcd、调度器、控制器管理器、kubelet、containerd、kube-proxy 都运行在同一个节点容器里。

因此单节点可以验证绝大多数清单和控制器行为,但无法验证跨节点调度、节点故障转移和真正的多机网络。

节点角色与污点 ​

Kind 创建的单节点集群只有一个 control-plane 角色。Kind 默认去掉 control-plane 的 NoSchedule 污点,使业务 Pod 可以直接调度到这个节点。否则单节点集群将没有可运行工作负载的节点。

这个默认行为也意味着:单节点上观察到的调度结果,不能直接代表生产环境“control-plane 不运行工作负载”的行为。

节点镜像决定 Kubernetes 版本 ​

Kind 的 Kubernetes 版本由节点镜像决定,而不是由宿主机上的 kubectl 决定。固定节点镜像如下:

text
kindest/node:v1.37.0@sha256:a1ed56cfb0e7b93589bdf97c8cd566405a265939e3620fc4f5de89adff580ae5

固定 @sha256 摘要可以保证拿到的是 Kind 官方为该版本构建的镜像,不受标签漂移影响。仅指定 v1.37.0 通常也可行,但在 CI 中建议固定摘要。

kubeconfig 与 context ​

Kind 把集群访问配置写入 ~/.kube/config,context 名为 kind-<集群名>。默认集群名是 kind,所以不指定 --name 时 context 是 kind-kind。

多个集群并存时,所有操作都应带 --context:

bash
kubectl --context kind-kind-single get nodes

关键机制 ​

创建过程 ​

kind create cluster 的执行过程包含以下步骤:

  • 拉取(或复用)节点镜像;
  • 创建 Docker 网络与节点容器;
  • 在容器内准备证书、kubeconfig、挂载和预加载镜像;
  • 启动 systemd,执行 kubeadm init;
  • 安装 CNI 与默认 StorageClass;
  • 把 kubeconfig 合并到宿主机。

--wait 120s 使命令阻塞至 control plane 就绪,避免脚本在集群尚未就绪时继续执行。该参数并不表示所有节点均已 Ready;节点就绪状态仍需单独等待。

默认组件 ​

单节点集群启动后,kube-system 命名空间通常包含:

组件作用
kube-apiserver集群 API 入口
etcd集群状态存储
kube-schedulerPod 调度
kube-controller-manager控制器循环
coredns集群 DNS
kindnet默认 CNI
kube-proxyService 转发
local-path-provisioner默认 StorageClass standard

不同 Kind 版本可能略有差异,以 kubectl get pods -A 的实际输出为准。

端口与网络 ​

Kind 会把 API Server 端口映射到宿主机,kubeconfig 中记录的是宿主机可访问的地址。业务端口不会自动暴露:

  • 需要从宿主机访问 Service 时,用 kubectl port-forward;
  • 需要固定端口时,在集群配置里写 extraPortMappings;
  • macOS 与 Windows 上不能直接访问节点容器 IP。

边界与常见误区 ​

误区实际行为正确做法
单节点可以验证高可用只有一个 etcd 与一个 control-plane,没有故障转移高可用验证使用 3 control-plane 配置
创建成功就代表节点可用--wait 只等到 control plane 就绪再执行 kubectl wait --for=condition=Ready nodes
本地镜像可以直接被 Pod 使用节点内是独立的 containerd,看不到宿主机 Docker 镜像先 kind load docker-image
删除集群后数据还在节点容器被删除,容器内数据丢失需要保留时挂载宿主机目录
旧版 Kind 可以运行任意新节点镜像Kind 与节点镜像存在兼容范围按 release notes 选择匹配版本

单节点还有两个资源边界:

  • Docker Desktop 的内存上限就是集群上限;低于 4 GB 时,单节点也可能因内存不足启动失败。
  • 容器共享宿主机内核与 inotify 限额;节点较多或监听文件较多时,需要调整宿主机 fs.inotify.max_user_watches。

参数速查 ​

参数 / 命令含义
--name集群名,决定容器名前缀与 kubectl context
--image节点镜像,决定 Kubernetes 版本与架构
--wait等待 control plane 就绪的超时时间,必须带单位
--config使用 YAML 配置节点、网络和端口映射
kind get clusters列出本机所有 Kind 集群
kind export kubeconfig重新导出指定集群的 kubeconfig
kind delete cluster删除集群容器、网络与 kubeconfig 条目
kind export logs导出节点日志,用于创建失败排查

实践 ​

环境要求 ​

验证环境:

  • macOS 或 Linux;
  • Docker 25 及以上,Docker 引擎正在运行;
  • kubectl 1.37.x;
  • 至少 2 CPU、4 GB 内存给 Docker;建议 8 GB。

Windows 需要 Docker Desktop 与 WSL2,命令在 WSL2 终端执行。

安装 Kind 与 kubectl ​

macOS:

bash
brew install kind kubectl

Linux 或固定版本:

bash
# KIND_VERSION: the release to install, for example v0.33.0
KIND_VERSION=v0.33.0
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/')
curl -Lo kind "https://kind.sigs.k8s.io/dl/${KIND_VERSION}/kind-${OS}-${ARCH}"
chmod +x kind
sudo mv kind /usr/local/bin/kind

检查:

bash
kind version
docker info
kubectl version --client

创建单节点集群 ​

bash
kind create cluster \
  --name kind-single \
  --image kindest/node:v1.37.0@sha256:a1ed56cfb0e7b93589bdf97c8cd566405a265939e3620fc4f5de89adff580ae5 \
  --wait 120s

创建过程会输出拉取镜像、准备节点、启动 control plane 等步骤。首次执行需要下载节点镜像,时间取决于网络。

验证集群 ​

bash
# list all local kind clusters
kind get clusters

# check the API server endpoint
kubectl --context kind-kind-single cluster-info

# check node status and container IP
kubectl --context kind-kind-single get nodes -o wide

# check system components
kubectl --context kind-kind-single get pods -A

# check the default storage class
kubectl --context kind-kind-single get storageclass

期望结果:

  • kind get clusters 输出 kind-single;
  • 节点状态为 Ready;
  • kube-system 下的核心 Pod 为 Running;
  • StorageClass 列表中存在 standard (default)。

可选的 DNS 冒烟测试:

bash
kubectl --context kind-kind-single run dns-test \
  --image=busybox:1.36 --restart=Never --rm -i --command \
  -- nslookup kubernetes.default

一键脚本 ​

脚本 kind-single-node.sh把上面的步骤串成一次执行:

bash
cd zq-xu.github.io/docs/public/demos/kind
./scripts/kind-single-node.sh

脚本按顺序完成:

  1. 检查 Docker 与 kubectl,Docker 未运行时直接报错退出;
  2. 如果本机没有 kind,下载 v0.33.0 到 ~/.local/bin;
  3. 集群不存在时创建 kind-single,已存在则复用;
  4. 等待所有节点 Ready;
  5. 打印节点、StorageClass 与系统 Pod。

脚本是幂等的:重复执行不会删除已有集群。需要重建时先执行:

bash
kind delete cluster --name kind-single

可通过环境变量覆盖默认值:

bash
CLUSTER_NAME=kind-dev \
NODE_IMAGE=kindest/node:v1.36.4@sha256:099e049362a1526b2db71494e1947aae99bd16290d7c895f2b7ea312e3cbfaed \
./scripts/kind-single-node.sh

清理 ​

bash
kind delete cluster --name kind-single

删除会移除节点容器、Docker 网络和 kubeconfig 中对应的 context。集群内的数据不会保留。

故障排查 ​

现象常见原因处理
Cannot connect to the Docker daemonDocker 未启动或当前用户无权限启动 Docker Desktop / dockerd,确认 docker info 可用
拉取节点镜像失败网络无法访问 Docker Hub先手动 docker pull 节点镜像,或配置镜像加速
timed out waiting for control planeDocker 内存不足、inotify 限额过低提高 Docker 内存到 8 GB;按官方 known issues 调整 fs.inotify.*
节点持续处于 NotReadyCNI 未就绪或节点启动失败kubectl describe node,并 kind export logs --name kind-single
bind: address already in use宿主机端口被其他集群或进程占用删除旧集群,或在配置中改用其他 hostPort
kubectl 找不到 contextkubeconfig 未合并或使用了错误的 KUBECONFIGkind export kubeconfig --name kind-single

创建失败时保留现场:

bash
kind create cluster --name kind-debug --retain --wait 120s
kind export logs --name kind-debug ./kind-logs

~~~我是有底线的~~~