搭一个本地集群：kind 与 kubectl 上手

这一章你会得到什么#

前面两章都在讲概念，从现在开始动手。这一章结束后，你的电脑上会跑着一个真实的 Kubernetes 集群，kubectl get nodes 会返回 Ready，后面每一章的命令都能直接粘贴执行。

本地集群的价值在于容错：随便折腾、随便删，重建只要几分钟。学习 Kubernetes 最怕的就是不敢动手，而 kind（Kubernetes in Docker）就是为「把整个集群塞进几个容器里」而设计的。

kind 的原理很直白：每一个「节点」其实是一个 Docker 容器，容器里跑着 kubelet、containerd 和控制平面组件。所以它对宿主机几乎没有额外要求，只要有 Docker 就行。

你的电脑
 │
 ├── Docker（容器运行时）
 │     ├── kind-kube101-control-plane   ← 一个容器 = 一个「节点」
 │     ├── kind-kube101-worker
 │     └── kind-kube101-worker2
 │
 └── kubectl
       │ 读取 ~/.kube/config 里的 context
       ▼
     https://127.0.0.1:<随机端口>  ──► 控制平面（apiserver）

理清这张图，后面所有命令都能对上号：kind 管的是左边那些容器，kubectl 走右边那条线跟 apiserver 说话。

前置条件：先让 Docker 跑起来#

kind 需要容器运行时来承载节点容器，所以第一步是确认 Docker 可用：

docker version
docker info

• macOS / Windows：装 Docker Desktop，启动后确认菜单栏图标是运行状态。
• Linux：装 Docker Engine 即可，装完把当前用户加入 docker 组，然后重新登录：

sudo usermod -aG docker $USER

docker info 能打印出 Server 版本和资源信息就说明就绪了。如果报 Cannot connect to the Docker daemon，说明 Docker 没启动，先解决这一步，不要继续往下装。

安装 kubectl 和 kind#

kubectl 是操作集群的命令行客户端，它和集群版本要大致匹配（前后差一个小版本没问题）。

macOS 用 Homebrew：

brew install kubectl

Linux 用官方软件源（以 Debian / Ubuntu 为例）：

curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.31/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.31/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list
sudo apt-get update
sudo apt-get install -y kubectl

不想用软件源，也可以直接下二进制：

curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

kind 有三种装法，选一种：

brew install kind                          # macOS / Linux 用 Homebrew
go install sigs.k8s.io/kind@latest         # 有 Go 环境

没有 Go 又不想用 Homebrew，就下载官方二进制（把版本号和平台换成你自己的，最新版本号见 kind 发布页）：

# Linux x86_64
curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.24.0/kind-linux-amd64
# macOS Apple Silicon
curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.24.0/kind-darwin-arm64
chmod +x ./kind
sudo mkdir -p /usr/local/bin
sudo mv ./kind /usr/local/bin/kind

装完确认两者都能执行：

kubectl version --client
kind version

动手：创建第一个单节点集群#

kind create cluster --name kube101

kind create cluster --name kube101 --image kindest/node:v1.31.0

验证：四条命令认识你的集群#

kubectl cluster-info
kubectl get nodes -o wide
kubectl get ns
kubectl get pods -A

环境自检清单#

每次重装系统、换了网络、或者隔几天回来继续学，先花一分钟跑一遍这张表。只要有一项不满足，后面所有章节都会跟着出错，先修环境再往下走。

最后一条是「端到端验证」：它创建一个临时 Pod，在集群内部解析 kubernetes.default.svc.cluster.local 这个 Service 的完整域名。这里刻意写全名，避免镜像里 nslookup 对搜索域的处理差异带来误判。跑完记得清理：

kubectl get pods -n demo
kubectl delete pod dns-test -n demo

如果 demo 命名空间还不存在，这条命令会报 namespaces "demo" is not found，用 kubectl create namespace demo 建一个即可（第 4 章 第一个 Pod 也会做这件事）。

换成多节点集群#

单节点够学 Pod 和 Deployment，但学不到「Pod 落在哪台机器上」这件事。而且 第 8 章 Ingress 需要把宿主机的 80/443 端口映射进集群，这要在创建集群时就配好。

新建一个 kind-config.yaml：

kind: Cluster
apiVersion: kind.x-k8s.io/v1alpha4
name: kube101
nodes:
  - role: control-plane
    kubeadmConfigPatches:
      - |
        kind: InitConfiguration
        nodeRegistration:
          kubeletExtraArgs:
            node-labels: "ingress-ready=true"
    extraPortMappings:
      - containerPort: 80
        hostPort: 80
        protocol: TCP
      - containerPort: 443
        hostPort: 443
        protocol: TCP
  - role: worker
  - role: worker

三个关键点：

• nodes 里第一个是控制平面，后面两个是工作节点，一共 1 控制面 + 2 工作节点。
• extraPortMappings 把宿主机的 80 和 443 映射到控制平面节点容器里，第 8 章 Ingress 的 Ingress Controller 会监听这两个端口。
• node-labels 给控制平面节点打上 ingress-ready=true，方便按节点选择器部署 Ingress Controller。

先删掉旧集群，再用配置文件重建：

kind delete cluster --name kube101
kind create cluster --config kind-config.yaml
kubectl get nodes

这次应该看到三行，其中一行的 ROLES 是 control-plane，另外两行是 <none>。

清理与重建集群#

kind 的集群就是几个容器，删起来很干净：

kind get clusters
kind delete cluster --name kube101

kind delete cluster 会把节点容器和 kubeconfig 里的 context 一起删掉。想彻底重来，删完直接重新 kind create cluster 即可。

kubeconfig 与 context#

kubectl 靠 ~/.kube/config 里的 context 决定连哪个集群。kind 创建集群时会自动添加并切换到 kind-<集群名> 这个 context。

kubectl config get-contexts
kubectl config current-context
kubectl config use-context kind-kube101

如果你同时有多个集群（比如还连着一个测试环境的集群），每次执行命令前确认当前 context，否则很可能把实验操作打到不该碰的集群上。

本课程为什么统一用 kind#

本课程统一用 kind：它更接近真实集群的多节点形态，后面讲调度和 Ingress 时不会受限于单节点。已经装过 minikube 的同学不用卸载，两者可以共存，只要注意 context 别选错。下一节我们把常见轻量发行版放在一起对比，并快速体验一次 k3s。

轻量发行版怎么选：kind / minikube / k3s / k0s / RKE2#

本课程用 kind，但真实项目里你会遇到别的选择。「发行版」的差别不在 API——它们跑的都是标准 Kubernetes——而在控制面怎么打包、默认装了什么、能不能满足合规要求。

怎么选，一句话版本：学概念和跑 CI 用 kind；只是想快速体验用 minikube 或 k3s；边缘与资源受限用 k3s；要过安全基线用 RKE2；想把网络和入口完全自己掌控用 k0s。 它们的 kubeconfig、kubectl 命令完全一致，所以换发行版的成本主要在运维方式，而不是应用清单。

参考：reference/k8s-in-action/.arch/k3s/README.md

k3s 快速体验：十分钟换一套发行版#

想亲手摸一下非 kind 的集群，k3s 是最省事的一条路——一条命令装完，kubectl 直接可用：

curl -sfL https://get.k3s.io | sh -
sudo k3s kubectl get nodes
sudo k3s kubectl get pods -A
# 把 kubeconfig 挪到常用位置（k3s 默认只给 root 用）
mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $(id -u):$(id -g) ~/.kube/config
kubectl get nodes
# 体验完清理
sudo /usr/local/bin/k3s-uninstall.sh

kubectl get nodes 出现一个 Ready 节点、kubectl get pods -A 里 Traefik 与 CoreDNS 都在跑，就说明集群可用。注意它和 kind 的 context 会同时存在，切回来记得 kubectl config use-context kind-kube101。

  k3s 单进程形态（每个 server 节点）
  ┌──────────────────────────────────────┐
  │ k3s server 进程                       │
  │   ├── kube-apiserver                 │
  │   ├── kube-controller-manager        │
  │   ├── kube-scheduler                 │
  │   └── embedded etcd（--cluster-init）│
  └──────────────────────────────────────┘
        ▲  kubeconfig / agent 都指向 VIP:6443
        │  kube-vip 必须先在集群里跑起来

有三处差异在生产上特别关键，和 kubespray 集群不一样：

1. 控制面是一个进程，HA 靠 `--cluster-init` + VIP。 第一台用 --cluster-init 初始化 embedded etcd，其余节点用 --server https://<VIP>:<apiserver 端口> 加入（k3s 默认 6443，若入口经 haproxy/keepalived 转发在别的端口，就写那个端口）。kube-vip 必须在第二台 join 之前就部署好，因为 join 时指定的 --server 地址必须已经存在；ARP 模式下 ssh <VIP> 就能看到它漂在哪台机器上。参考：reference/k8s-in-action/.arch/k3s/kube-vip/README.md
2. etcd 快照是自带功能。 默认每天 00:00 与 12:00 各打一次快照，只保留最近 5 份自动快照，目录是 /var/lib/rancher/k3s/server/db/snapshots；sudo k3s etcd-snapshot save 手工补一份（on-demand-* 前缀，不会被自动清理）。恢复的顺序不能乱：先在所有控制面 systemctl stop k3s，在其中一台上执行 k3s server --cluster-reset --cluster-reset-restore-path=<快照文件>，再把 db 目录改名移走，然后启动并让其它节点重新加入。参考：reference/k8s-in-action/.arch/k3s/etcd.md
3. 打包组件会被回退。 Traefik、ServiceLB、local-path 这些默认组件由 /var/lib/rancher/k3s/server/manifests 托管，直接 kubectl patch 改它们的 Deployment，k3s 重启时会被覆盖回默认版本；要持久化改动，就在该目录下放一个同名的 .skip 空文件，把这份清单「接管」出来。参考：reference/k8s-in-action/.arch/k3s/patch/README.md

常见坑#

排错速查表#

上面几条按「现象」整理成一张表，出问题时对着找，比从头回忆快得多。

自测题#

小结#

• kind 把每个节点做成一个 Docker 容器，因此只需要 Docker 就能在本地跑出真实集群。
• 创建集群是 kind create cluster --name kube101，验证靠 kubectl cluster-info、kubectl get nodes -o wide、kubectl get ns、kubectl get pods -A 四条命令。
• 多节点集群用 kind-config.yaml 描述：1 个 control-plane + 2 个 worker，并预留 80 / 443 端口给后面的 Ingress。
• kind delete cluster 可以随时推倒重来；学习期重建往往比修更快。
• 轻量发行版各有定位：kind 学多节点、minikube 快速体验、k3s 边缘与单机、k0s 极简、RKE2 安全合规；API 一致，差别在运维方式。
• 永远先确认 kubectl config current-context，再执行会改动集群的命令。

相关章节：组件分工看不懂时回到 第 2 章 集群架构；集群起来之后从 第 4 章 第一个 Pod 开始练命令。

练习#

1. 用 kind create cluster --name scratch 再建一个集群，然后用 kubectl config get-contexts 观察两个 context，最后把它删掉。
2. 给 kind-config.yaml 增加一个工作节点，重建集群，用 kubectl get nodes -o wide 确认新节点加入。
3. 跑 kubectl get pods -n kube-system -o wide，对照 第 2 章 集群架构 里的组件表，找出哪些 Pod 跑在哪个节点上。

集群有了，下一章我们创建第一个 Pod，把 kubectl 最常用的几条命令一次练熟。