nexus/K8S/Kubeadm init 集群初始化.md

#kubeadm #k8s #Kubernetes #cka

kubeadm init 是 Kubernetes 官方推荐的集群初始化工具，主要用于引导和部署 控制平面节点（Control Plane Node）。理解 kubeadm init 的工作原理与关键参数，是进行 K8s 运维实践以及备考 CKA（Certified Kubernetes Administrator）的核心要求。

---

一、 kubeadm init 的内部执行流程

当你在控制平面节点运行 kubeadm init 时，它会在后台自动完成以下一系列初始化步骤：

1. 预检（Preflight Checks）：检查系统环境（CPU/内存、内核版本、CRI 容器运行时、Port 端口占用、Swap 是否关闭等）。
2. 生成 PKI 证书：在 /etc/kubernetes/pki 目录生成 API Server、etcd、kubelet 等组件所需的 X.509 密钥与 CA 证书。
3. 生成 Kubeconfig 配置文件：在 /etc/kubernetes/ 目录生成 admin.conf、kubelet.conf、controller-manager.conf、scheduler.conf 等连接 API Server 的认证配置文件。
4. 生成静态 Pod 清单（Static Pod Manifests）：在 /etc/kubernetes/manifests/ 目录下生成 kube-apiserver.yaml、kube-controller-manager.yaml、kube-scheduler.yaml 和 etcd.yaml。本地 kubelet 守护进程会自动检测该目录并启动这些核心控制平面组件。
5. 等待控制平面启动与打标记：等待 API Server 就绪，为控制平面节点施加污点（Taint，默认限制普通 Pod 调度）。
6. 安装 Add-on 插件：自动安装 CoreDNS 和 kube-proxy。
7. 输出 Join 命令：生成包含 Bootstrap Token 的 Worker 节点加入命令。

---

二、 关键参数详解（常用与高频考点）

在命令行执行 kubeadm init 时，可以通过传入关键参数来自定义集群的架构与网络配置：

参数名称	说明与使用场景	示例 / 默认值
--apiserver-advertise-address	指定 API Server 通告和监听的网卡 IP 地址。多网卡环境下必须显式指定为内网/公网主网卡 IP。	--apiserver-advertise-address=192.168.1.10
--pod-network-cidr	指定 Pod 网络的虚拟 IP 地址段（Cluster CIDR）。使用 Flannel 或 Calico 等 CNI 插件时必须配置，且需与 CNI 的默认 CIDR 匹配。	--pod-network-cidr=10.244.0.0/16 (Flannel) --pod-network-cidr=192.168.0.0/16 (Calico)
--service-cidr	指定 Service 虚拟 IP 的地址段（ClusterIP 范围）。默认网段为 10.96.0.0/12 或 10.96.0.0/16。	--service-cidr=10.96.0.0/16
--kubernetes-version	显式指定要安装的 Kubernetes 版本。若不指定，默认拉取与当前 kubeadm CLI 相同的版本。	--kubernetes-version=v1.32.0
--control-plane-endpoint	指定控制平面的统一访问入口（IP 或 DNS 域名及端口）。多 Master 高可用集群必须配置，通常填入 Load Balancer 的 VIP 及端口。	--control-plane-endpoint="k8s-api.example.com:6443"
--cri-socket	指定节点容器运行时（CRI）的 Socket 文件路径。多容器运行时共存时（如 containerd 与 docker）需显式指定。	--cri-socket=unix:///run/containerd/containerd.sock
--upload-certs	将控制平面的加密证书上传至集群内部（存储于 kube-system 的 Secret 中），方便后续其他控制平面节点自动加入。	--upload-certs
--dry-run	模拟执行初始化过程，仅输出将要进行的操作和配置，不实际修改系统文件。	--dry-run
--config	指定 kubeadm 声明式 YAML 配置文件路径，适用于复杂的高级定制化安装。	--config=kubeadm-config.yaml

---

三、 典型初始化命令示例

单控制平面集群初始化示例：

kubeadm init \
  --apiserver-advertise-address=192.168.1.10 \
  --image-repository=registry.k8s.io \
  --kubernetes-version=v1.32.0 \
  --pod-network-cidr=10.244.0.0/16 \
  --service-cidr=10.96.0.0/16 \
  --cri-socket=unix:///run/containerd/containerd.sock

初始化成功后，请根据终端提示，执行以下命令配置普通用户的 kubectl 访问权限：

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

---

四、 如何产生 Worker 节点的 Join 命令

节点加入集群依赖于 Bootstrap Token 机制。Token 建立节点与控制平面之间的双向信任。

1. 方式一：首次初始化完成后直接复制

在 kubeadm init 成功结束时的终端最后几行，会自动打印出 Worker 节点加入所需的完整命令：

kubeadm join 192.168.1.10:6443 --token l5kotg.hiivo73eu000bbfu \
  --discovery-token-ca-cert-hash sha256:13b3aac808908114d45b6ad91640babd8613d8136b21d405711a1204c68fa8a4

2. 方式二：Token 过期或丢失时，一键重新生成（推荐）

kubeadm 创建的初始引导 Token 默认有效期为 24 小时。如果旧 Token 已过期或找不到了，只需在控制平面节点运行以下命令即可重新生成完整的 Join 命令：

kubeadm token create --print-join-command

shenwei@shenwei-ubuntu-2:~$ sudo kubeadm token create --print-join-command
kubeadm join 192.168.3.45:6443 --token r5aix1.dqoljbanm0rbyvn5 --discovery-token-ca-cert-hash sha256:d590fc92d4353ff628f89e02ab9e1a19d1e28d0c42f7d695378b257d71e3b386

运行后终端会直接输出一条全新的、可立即粘贴在 Worker 节点上执行的 kubeadm join 命令。

3. 方式三：分步手动获取与拼接（理解原理）

如果需要手工查看或拼接命令各个组成部分：

1. 获取或新建 Token：

# 查看当前有效的 Token 列表
kubeadm token list

# 如果没有有效 Token，新建一个
kubeadm token create

1. 计算 CA 证书指纹哈希（--discovery-token-ca-cert-hash）： 在控制平面节点上运行以下命令，提取 /etc/kubernetes/pki/ca.crt 的 SHA-256 哈希值：

openssl x509 -pubkey -in /etc/kubernetes/pki/ca.crt | \
  openssl rsa -pubin -outform der 2>/dev/null | \
  openssl dgst -sha256 -hex | sed 's/^.* //'

1. 手动拼接 Join 命令：

kubeadm join <CONTROL_PLANE_IP>:6443 \
  --token <TOKEN> \
  --discovery-token-ca-cert-hash sha256:<HASH_VALUE>

---

💡 提示：如果在 Worker 节点执行 kubeadm join 失败或需要重新引导节点，可以在该 Worker 节点上先运行 kubeadm reset 清理历史状态，然后再重新运行 kubeadm join。

五、 Troubleshooting

1. 启动sudo kubeadm init，发现无法拉取镜像

解决方案： Use Host IP for Containerd Proxy

If your local proxy (e.g., Clash, V2Ray, Shadowsocks) is running on 127.0.0.1:10808, use the host's actual LAN IP address or 172.17.0.1 instead of 127.0.0.1 in the containerd config.

1. Find your host IP address:

    ip route show | grep default

_(e.g., `192.168.1.100`)_

2. Update /etc/systemd/system/containerd.service.d/http-proxy.conf:

[Service]
Environment="HTTP_PROXY=http://192.168.1.100:7890"
Environment="HTTPS_PROXY=http://192.168.1.100:7890"
Environment="NO_PROXY=localhost,127.0.0.1,10.96.0.0/12,192.168.0.0/16"

Important: Ensure your local proxy client is set to "Allow LAN connections" (listen on 0.0.0.0 rather than 127.0.0.1).

3. Reload and restart:

sudo systemctl daemon-reload
sudo systemctl restart containerd