容器与云原生 / 系统课时
初始化控制平面
初始化控制平面
本课使用 kubeadm 在首个节点上初始化 Kubernetes 控制平面,明确 CRI、API Server 地址与 Pod 网段,并配置管理员 kubeconfig。完成后可以用 kubectl 访问 API Server,并确认 etcd、调度器等核心静态 Pod 已运行。
学习目标
- 在初始化前确认 containerd、CRI Socket 和 kubeadm 满足条件
- 使用
kubeadm init创建控制平面并理解关键产物 - 配置管理员 kubeconfig,验证 API Server 与核心组件状态
检查初始化前条件
控制平面节点至少应已安装 kubeadm、kubelet、kubectl 和 containerd。下面按常见 kubeadm 部署方式关闭 swap,并确认 containerd 服务、CRI Socket 与 kubeadm 命令都存在。
sudo swapoff -a
sudo systemctl is-active containerd
test -S /run/containerd/containerd.sock && echo "CRI socket OK"
command -v kubeadm >/dev/null && echo "kubeadm OK"预期输出
active
CRI socket OK
kubeadm OK如果主机有多块网卡,要提前选定控制平面节点对集群通告的 IP。Pod 网段必须与宿主机网络、Service 网段及其他可路由网络避免重叠;某些 CNI 要求在初始化时显式指定该网段。
执行 kubeadm init
下面示例假设所选 CNI 需要预设 Pod CIDR。把 <IP> 替换为控制平面节点实际通告地址,把 <POD_CIDR> 替换为该 CNI 要求且不冲突的网段;如果你的 CNI 明确不要求 --pod-network-cidr,应移除该参数。
sudo kubeadm init \
--cri-socket unix:///run/containerd/containerd.sock \
--apiserver-advertise-address=<IP> \
--pod-network-cidr=<POD_CIDR>预期输出
Your Kubernetes control-plane has initialized successfully!
kubeadm join <IP>:6443 --token <VALUE> \
--discovery-token-ca-cert-hash sha256:<VALUE>初始化过程中,kubeadm 先执行预检,再生成证书与 kubeconfig,写入 etcd、API Server、Controller Manager、Scheduler 的静态 Pod 清单;kubelet 发现这些清单后通过 containerd 启动控制平面组件。最后 kubeadm 创建集群级配置、引导令牌和管理员访问配置。

kubeadm join 中的令牌属于敏感引导凭据,不应公开粘贴。若计划以后扩展为高可用控制平面,初始化前应设计稳定的共享控制平面端点,而不是长期依赖单机 IP。
配置管理员 kubeconfig
kubeadm init 会生成 /etc/kubernetes/admin.conf。普通用户使用 kubectl 时,把它复制到自己的 $HOME/.kube/config,并将文件所有权交给当前用户。
mkdir -p "$HOME/.kube"
sudo cp -f /etc/kubernetes/admin.conf "$HOME/.kube/config"
sudo chown "$(id -u):$(id -g)" "$HOME/.kube/config"
kubectl get --raw='/readyz'预期输出
okadmin.conf 具有集群管理员权限,不应分发给普通业务用户。多人使用集群时,应为不同人员签发独立凭据并通过 RBAC 授予最小权限。
检查核心组件状态
kubeadm 将控制平面核心组件作为静态 Pod 交给 kubelet 管理。可以直接筛选 tier=control-plane 的 Pod,确认四个关键组件都进入 Running。
kubectl -n kube-system get pods \
-l tier=control-plane \
-o custom-columns=NAME:.metadata.name,PHASE:.status.phase预期输出
NAME PHASE
etcd-<ID> Running
kube-apiserver-<ID> Running
kube-controller-manager-<ID> Running
kube-scheduler-<ID> Running实际顺序和 <ID> 会因主机名而不同。如果此时尚未安装 CNI,kubectl get nodes 中控制平面节点出现 NotReady,CoreDNS 处于 Pending 或尚未就绪通常是预期现象;先完成网络插件安装,再以节点 Ready 和 CoreDNS 正常运行为后续验收目标。
遇到 init 失败时怎么判断
预检阶段报 swap、端口占用或 CRI 不可用时,应修复前置条件后再初始化,不要通过忽略错误强行继续。证书或静态 Pod 已经写入后才失败,则先阅读 kubelet 与 containerd 日志,判断是镜像拉取、cgroup、主机名解析还是 API Server 启动问题。
只有在确认要放弃这次初始化并重新建集群时,才执行清理动作;不要在原因不明时反复重置。一次合格的控制平面初始化,应同时满足 API /readyz 返回 ok、四个控制平面静态 Pod 为 Running,并保留好后续节点加入所需的安全凭据。