容器与云原生 / 系统课时

初始化控制平面

初始化控制平面

本课使用 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 命令都存在。

bash
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"

预期输出

text
active
CRI socket OK
kubeadm OK

如果主机有多块网卡,要提前选定控制平面节点对集群通告的 IP。Pod 网段必须与宿主机网络、Service 网段及其他可路由网络避免重叠;某些 CNI 要求在初始化时显式指定该网段。

执行 kubeadm init

下面示例假设所选 CNI 需要预设 Pod CIDR。把 <IP> 替换为控制平面节点实际通告地址,把 <POD_CIDR> 替换为该 CNI 要求且不冲突的网段;如果你的 CNI 明确不要求 --pod-network-cidr,应移除该参数。

bash
sudo kubeadm init \
  --cri-socket unix:///run/containerd/containerd.sock \
  --apiserver-advertise-address=<IP> \
  --pod-network-cidr=<POD_CIDR>

预期输出

text
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 init 初始化控制平面流程

kubeadm join 中的令牌属于敏感引导凭据,不应公开粘贴。若计划以后扩展为高可用控制平面,初始化前应设计稳定的共享控制平面端点,而不是长期依赖单机 IP。

配置管理员 kubeconfig

kubeadm init 会生成 /etc/kubernetes/admin.conf。普通用户使用 kubectl 时,把它复制到自己的 $HOME/.kube/config,并将文件所有权交给当前用户。

bash
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'

预期输出

text
ok

admin.conf 具有集群管理员权限,不应分发给普通业务用户。多人使用集群时,应为不同人员签发独立凭据并通过 RBAC 授予最小权限。

检查核心组件状态

kubeadm 将控制平面核心组件作为静态 Pod 交给 kubelet 管理。可以直接筛选 tier=control-plane 的 Pod,确认四个关键组件都进入 Running。

bash
kubectl -n kube-system get pods \
  -l tier=control-plane \
  -o custom-columns=NAME:.metadata.name,PHASE:.status.phase

预期输出

text
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,并保留好后续节点加入所需的安全凭据。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

初始化控制平面

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通