#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 :6443 \
--token \
--discovery-token-ca-cert-hash sha256:
```
---
💡 **提示**：如果在 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
```