本章说明：
kubeadm、kubelet 和 kubectl 是部署和管理 Kubernetes 集群的核心工具。kubeadm 负责集群的初始化和节点加入操作，是官方推荐的高可用集群搭建工具；kubelet 运行在每个节点上，负责管理 Pod 和容器的生命周期，是节点与控制平面通信的代理；kubectl 是命令行客户端，用于与集群交互和执行各种管理操作。本章将在所有节点上完成这三个工具的安装、版本锁定、基础配置和启动验证。需要注意的是，此时 kubelet 启动后会不断尝试连接 apiserver，由于集群尚未初始化，出现连接失败是正常现象，待后续章节完成集群初始化后会自动恢复。
部署节点： 所有节点（master01、master02、master03、worker01、worker02）
3.1 配置 Kubernetes APT 源
作用说明： Ubuntu 系统默认的软件源中不包含 Kubernetes 组件，需要手动添加 Kubernetes 官方 APT 仓库，才能通过 apt 命令安装 kubeadm、kubelet 和 kubectl。
部署节点： 所有节点
bash
# 步骤1：更新本地的软件包索引，确保能获取到最新的软件包信息
sudo apt update
# 步骤2：安装必需的依赖包
# apt-transport-https：允许通过 HTTPS 协议访问软件仓库
# ca-certificates：验证仓库证书的有效性
# curl：命令行下载工具，用于获取签名密钥
sudo apt install -y apt-transport-https ca-certificates curl
# 步骤3：下载 Kubernetes 官方 APT 仓库的 GPG 签名密钥
# 该密钥用于验证下载的软件包是否被篡改，确保安全性
# --dearmor：将 GPG 密钥从二进制格式转换为文本格式
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.28/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
# 步骤4：添加 Kubernetes APT 仓库到软件源列表
# signed-by：指定用于验证的 GPG 密钥文件
# deb：软件包类型
# /：软件仓库的根路径
echo "deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.28/deb/ /" | sudo tee /etc/apt/sources.list.d/kubernetes.list
# 步骤5：再次更新软件包索引，使新添加的 Kubernetes 仓库生效
sudo apt update验证 APT 源配置：
bash
# 查看 Kubernetes APT 源配置文件是否创建成功
cat /etc/apt/sources.list.d/kubernetes.list
# 搜索可用的 kubeadm 版本（确认源已生效）
apt-cache policy kubeadm预期输出：
bash
deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.28/deb/ /
Installed: (none)
Candidate: 1.28.2-00
Version table:
1.28.2-00 500
500 https://pkgs.k8s.io/core:/stable:/v1.28/deb Packages3.2 安装指定版本组件
作用说明： 安装与后续章节完全匹配的 Kubernetes v1.28.2 版本组件，确保版本一致性，避免因版本差异导致的兼容性问题。安装完成后锁定版本，防止系统更新时意外升级。
部署节点： 所有节点
bash
# 步骤1：安装 kubeadm、kubelet、kubectl 的指定版本
# kubeadm：集群初始化和管理工具
# kubelet：节点代理，管理 Pod 和容器
# kubectl：命令行客户端，操作集群
# -y：自动确认安装，无需手动输入 Y
sudo apt install -y kubeadm=1.28.2-00 kubelet=1.28.2-00 kubectl=1.28.2-00
# 步骤2：锁定三个组件的版本，防止 apt upgrade 时自动更新
# apt-mark hold：阻止软件包被升级
sudo apt-mark hold kubeadm kubelet kubectl
# 步骤3：验证 kubeadm 版本
kubeadm version
# 步骤4：验证 kubelet 版本
kubelet --version
# 步骤5：验证 kubectl 客户端版本
kubectl version --client预期输出：
bash
kubeadm version: &version.Info{Major:"1", Minor:"28", GitVersion:"v1.28.2", GitCommit:"894a3e1ed4d7f75722b5090359983e9b3fb", GitTreeState:"clean", BuildDate:"2023-09-13T09:34:32Z", GoVersion:"go1.20.8", Compiler:"gc", Platform:"linux/amd64"}
Kubernetes v1.28.2
Client Version: v1.28.2
Kustomize Version: v5.0.4-0.20230601165947-6ce0bf390ce3验证版本锁定：
bash
# 查看被锁定的软件包列表
apt-mark showhold预期输出：
bash
kubeadm
kubelet
kubectl3.3 配置 kubelet
作用说明： kubelet 是运行在每个节点上的核心代理，负责接收 PodSpec 并确保容器按预期运行。本节配置 kubelet 的 cgroup 驱动（与 containerd 保持一致）和容器运行时连接参数。
部署节点： 所有节点
3.3.1 创建 kubelet 配置目录
bash
# 创建 kubelet 配置文件的存放目录
# /var/lib/kubelet 是 kubelet 的默认数据目录，存放 Pod 数据和配置
sudo mkdir -p /var/lib/kubelet3.3.2 配置 cgroup 驱动
作用说明： cgroup 驱动控制着如何管理系统资源。kubelet 和容器运行时（containerd）必须使用相同的 cgroup 驱动，否则会导致资源统计不一致或 Pod 启动失败。Ubuntu 24.04 使用 cgroup v2，systemd 驱动是官方推荐的最佳实践。
bash
# 创建 kubelet 配置文件，指定 cgroup 驱动为 systemd
# tee 命令将输入内容写入指定文件，sudo 确保有写入权限
# <<EOF ... EOF 是 Here Document 语法，用于多行输入
cat | sudo tee /var/lib/kubelet/config.yaml <<EOF
apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
cgroupDriver: systemd
EOF验证配置文件创建成功：
bash
# 查看 kubelet 配置文件内容
cat /var/lib/kubelet/config.yaml预期输出：
bash
apiVersion: kubelet.config.k8s.io/v1beta1
kind: KubeletConfiguration
cgroupDriver: systemd3.3.3 配置 kubelet 启动参数
作用说明： kubelet 启动时需要指定容器运行时类型及其 socket 路径，以便通过 CRI（容器运行时接口）与 containerd 通信。
bash
# 配置 kubelet 的额外启动参数
# KUBELET_EXTRA_ARGS：kubelet 服务的环境变量文件
# --container-runtime=remote：使用远程容器运行时（CRI 兼容）
# --container-runtime-endpoint：指定 containerd 的 socket 地址
cat | sudo tee /etc/sysconfig/kubelet <<EOF
KUBELET_EXTRA_ARGS="--container-runtime=remote --container-runtime-endpoint=unix:///run/containerd/containerd.sock"
EOF验证配置：
bash
# 查看 kubelet 启动参数配置
cat /etc/sysconfig/kubelet预期输出：
bash
KUBELET_EXTRA_ARGS="--container-runtime=remote --container-runtime-endpoint=unix:///run/containerd/containerd.sock"3.4 启动 kubelet
作用说明： 设置 kubelet 开机自启并立即启动服务。此时集群尚未初始化，kubelet 会不断尝试连接 apiserver 但失败，这是预期行为。
部署节点： 所有节点
bash
# 步骤1：设置 kubelet 开机自启（enable）
# 步骤2：立即启动 kubelet 服务（start）
# --now：同时执行 enable 和 start，一步到位
sudo systemctl enable --now kubelet
# 步骤3：查看 kubelet 服务状态
sudo systemctl status kubelet预期输出：
bash
● kubelet.service - kubelet: The Kubernetes Node Agent
Loaded: loaded (/usr/lib/systemd/system/kubelet.service; enabled; preset: enabled)
Active: activating (auto-restart) since Mon 2026-05-12 10:30:00 CST; 5s ago
Docs: https://kubernetes.io/docs/
Process: 12345 ExecStart=/usr/bin/kubelet (code=exited, status=1/FAILURE)
Main PID: 12345 (code=exited, status=1/FAILURE)
CPU: 100ms重要说明： 此时
Active: activating (auto-restart)和status=1/FAILURE是正常现象 。因为集群尚未初始化，API Server 还未启动，kubelet 无法完成 TLS 引导注册，会不断重试连接。集群初始化后，kubelet 会自动恢复并进入active (running)状态。
3.5 kubelet 状态监控
作用说明： 在继续后续章节前，确认 kubelet 已正确配置并处于预期的等待状态。
部署节点： 所有节点
bash
# 查看 kubelet 服务日志（最近 20 行，确认重试行为正常）
sudo journalctl -u kubelet -n 20 --no-pager
# 实时查看 kubelet 日志（按 Ctrl+C 退出）
sudo journalctl -u kubelet -f预期日志内容（应包含类似以下信息）：
bash
failed to run Kubelet: misconfiguration: kubelet cgroup driver: "systemd" is different from docker cgroup driver: "cgroupfs"或
bash
Unable to connect to the server: dial tcp 192.168.3.60:6443: connect: connection refused这些错误是正常的，表示 kubelet 正在等待 API Server 启动。
3.6 日常运维操作
作用说明： 本节列出 kubeadm/kubelet/kubectl 在生产环境中的日常运维命令。
部署节点： 所有节点
3.6.1 查看版本信息
bash
# 查看 kubeadm 详细版本
kubeadm version
# 查看 kubelet 版本
kubelet --version
# 查看 kubectl 版本及客户端配置
kubectl version --client --output=yaml3.6.2 重启 kubelet
bash
# 重启 kubelet 服务（修改配置后需要重启）
sudo systemctl restart kubelet
# 查看重启后状态
sudo systemctl status kubelet3.6.3 查看 kubelet 配置
bash
# 查看 kubelet 配置文件
cat /var/lib/kubelet/config.yaml
# 查看 kubelet 启动参数
cat /etc/sysconfig/kubelet
# 查看 kubelet 服务文件
cat /usr/lib/systemd/system/kubelet.service3.6.4 取消版本锁定（如需升级）
bash
# 取消 kubeadm 的版本锁定
sudo apt-mark unhold kubeadm
# 取消 kubelet 的版本锁定
sudo apt-mark unhold kubelet
# 取消 kubectl 的版本锁定
sudo apt-mark unhold kubectl
# 升级到指定版本（示例）
sudo apt install -y kubeadm=1.29.0-00 kubelet=1.29.0-00 kubectl=1.29.0-00
# 重新锁定版本
sudo apt-mark hold kubeadm kubelet kubectl3.7 常见问题排查
作用说明： 本节列出 kubeadm/kubelet/kubectl 安装过程中可能遇到的常见问题及解决方案。
3.7.1 APT 源添加失败
问题现象：
bash
gpg: no valid OpenPGP data found解决方案：
bash
# 清理可能损坏的密钥文件
sudo rm -f /etc/apt/keyrings/kubernetes-apt-keyring.gpg
# 重新下载密钥（使用国内镜像加速）
curl -fsSL https://mirrors.aliyun.com/kubernetes/apt/doc/apt-key.gpg | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
# 重新添加仓库
echo "deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://mirrors.aliyun.com/kubernetes/apt/ kubernetes-xenial main" | sudo tee /etc/apt/sources.list.d/kubernetes.list
# 更新仓库
sudo apt update3.7.2 版本不存在
问题现象：
bash
E: Version '1.28.2-00' for 'kubeadm' was not found解决方案：
bash
# 查看可用版本列表
apt-cache madison kubeadm
# 选择可用版本安装
sudo apt install -y kubeadm=<可用版本> kubelet=<可用版本> kubectl=<可用版本>3.7.3 kubelet 无法启动
问题现象：
bash
Failed to start kubelet.service: Unit kubelet.service not found.解决方案：
bash
# 重新加载 systemd 配置
sudo systemctl daemon-reload
# 重新安装 kubelet
sudo apt install --reinstall -y kubelet
# 重新启动
sudo systemctl enable --now kubelet3.8 本章小结
本章验证清单：
| 检查项 | 验证命令 | 预期结果 |
|---|---|---|
| APT 源配置 | cat /etc/apt/sources.list.d/kubernetes.list |
显示正确的仓库地址 |
| kubeadm 已安装 | kubeadm version |
v1.28.2 |
| kubelet 已安装 | kubelet --version |
v1.28.2 |
| kubectl 已安装 | kubectl version --client |
v1.28.2 |
| 版本已锁定 | apt-mark showhold |
显示 kubeadm/kubelet/kubectl |
| kubelet 配置文件 | cat /var/lib/kubelet/config.yaml |
cgroupDriver: systemd |
| kubelet 服务已启用 | systemctl is-enabled kubelet |
enabled |
| kubelet 服务状态 | systemctl status kubelet |
activating 或 running（正常） |
下一章预告：
kubeadm/kubelet/kubectl 安装配置完成后，下一章将部署负载均衡器 Keepalived + HAProxy，为 kube-apiserver 提供高可用入口。