Kubernetes 在 Linux 上的安装并不神秘，但很多教程只给命令，不讲为什么，导致环境稍有差异就卡住。实际上，只要把容器运行时、内核参数、kubeadm 初始化这三条线理清，安装过程可以非常顺畅。本文以 Ubuntu 22.04 和 Rocky Linux 9 为例，覆盖在线和离线两种思路，并集中说明几个最容易被忽略的坑。
一、安装前准备：系统配置比安装命令更重要
很多安装失败并不是 kubeadm 本身的问题，而是系统基础条件不满足。首先是 swap 分区，Kubernetes 从设计上要求节点禁用 swap，因为 kubelet 无法准确统计内存使用，开启 swap 会导致 Pod 被意外驱逐。Ubuntu 系统可以执行 sudo swapoff -a 临时关闭，同时注释掉 /etc/fstab 中 swap 相关行，避免重启后恢复。如果必须保留 swap，可以在 kubelet 参数中设置 failSwapOn: false，但不建议在生产环境这样做。
接着是内核模块和网络参数。容器网络依赖 bridge 和 overlay 模块，同时需要开启 IP 转发。下面的命令把这些配置写入系统文件并立即生效：
cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf overlay br_netfilter EOF sudo modprobe overlay sudo modprobe br_netfilter cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf net.bridge.bridge-nf-call-iptables = 1 net.bridge.bridge-nf-call-ip6tables = 1 net.ipv4.ip_forward = 1 EOF sudo sysctl --system
配置完成后可以用 sudo sysctl net.ipv4.ip_forward 确认输出为 1。另一个容易漏掉的是主机名和 hosts 解析，每台节点的主机名必须唯一，且 /etc/hosts 中要包含本机 IP 与主机名的映射，否则 kubelet 可能无法正确注册节点。
容器运行时方面，Kubernetes 从 1.24 版本开始正式移除 Docker 作为内置运行时，推荐使用 containerd。如果系统自带 Docker，需要单独安装 cri-dockerd 才能继续使用，但这会多一层维护成本。安装 containerd 后，必须修改配置文件，将 SystemdCgroup 设置为 true，保证 cgroup 驱动与 kubelet 一致，否则会报 cgroup driver 不一致的错误。
sudo containerd config default | sudo tee /etc/containerd/config.toml sudo sed -i 's/SystemdCgroup = false/SystemdCgroup = true/' /etc/containerd/config.toml sudo systemctl restart containerd
如果节点位于国内网络，还需要为 containerd 配置镜像加速地址，修改 sandbox_image 和 registry mirror，否则 pause 镜像和组件镜像可能拉取失败。不同云厂商都有各自的加速端点，按实际情况替换即可。
二、kubeadm 初始化控制平面与加入工作节点
kubeadm 是目前社区最推荐的安装工具，它把证书生成、控制平面组件启动、kubeconfig 分发等步骤自动化。安装 kubeadm、kubelet 和 kubectl 时，需要先添加官方 apt 或 yum 源。以 Ubuntu 为例，执行以下命令：
sudo apt-get update sudo apt-get install -y apt-transport-https ca-certificates curl 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 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 sudo apt-get update sudo apt-get install -y kubelet kubeadm kubectl sudo apt-mark hold kubelet kubeadm kubectl
安装完成后，不要立刻执行 kubeadm init，而是先检查 kubelet 是否已经启动。有些教程会跳过这一步，导致后续加入节点时出现证书错误。可以先运行 sudo systemctl status kubelet 查看状态，kubelet 此时会因缺少配置文件而处于等待状态，这是正常的。
初始化控制平面时，建议使用配置文件而不是命令行参数，这样后续可以复用和审计。创建一个 kubeadm-init.yaml，内容如下：
apiVersion: kubeadm.k8s.io/v1beta3
kind: InitConfiguration
nodeRegistration:
criSocket: unix:///var/run/containerd/containerd.sock
kubeletExtraArgs:
cgroup-driver: systemd
---
apiVersion: kubeadm.k8s.io/v1beta3
kind: ClusterConfiguration
kubernetesVersion: stable-1.28
controlPlaneEndpoint: "172.16.10.10:6443"
networking:
podSubnet: "10.244.0.0/16"
serviceSubnet: "10.96.0.0/12"
其中 podSubnet 必须与后续安装的网络插件保持一致，Calico 默认使用 10.244.0.0/16，Flannel 也是这个网段。执行 sudo kubeadm init --config kubeadm-init.yaml 后，如果一切正常，最后会输出一段 kubeadm join 命令，这段命令要妥善保存，工作节点加入时需要用到。
控制平面初始化完成后，普通用户需要配置 kubectl 访问集群：
mkdir -p $HOME/.kube sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config sudo chown $(id -u):$(id -g) $HOME/.kube/config
接下来安装网络插件。网络插件不安装，集群的 CoreDNS 会一直处于 Pending 状态。以 Calico 为例，可以从官方下载 manifest 并应用：
kubectl apply -f calico.yaml
等待所有 Pod 变为 Running 后，再执行 kubectl get nodes，控制平面节点会从 NotReady 变为 Ready。工作节点加入时，只需要在节点上执行之前保存的 kubeadm join 命令。如果 token 过期，可以在控制平面执行 kubeadm token create --print-join-command 生成新的加入命令。
三、生产环境注意事项与高频错误排查
测试集群跑通只是第一步，生产环境还需要考虑证书续期、etcd 备份和控制平面高可用。kubeadm 默认签发的证书有效期为一年，可以通过 kubeadm certs check-expiration 查看过期时间，快到期的证书使用 kubeadm certs renew all 续期。etcd 数据建议定期快照，命令是 etcdctl snapshot save，并将快照文件复制到集群外的安全位置。
高频错误里，swap 未关闭是最常见的一个。如果 kubelet 日志中出现 failed to run Kubelet: running with swap on is not supported，说明需要重新执行 swapoff 并修改 fstab。另一个典型问题是镜像拉取失败，表现为节点反复重启容器，可以用 crictl pull 手动拉取暂停镜像和组件镜像，确认是网络问题还是 containerd 配置问题。网络插件冲突也经常出现，如果你之前安装过 Flannel，再切换 Calico，可能残留 iptables 规则或网卡配置，最稳妥的做法是重置节点后重新加入。
防火墙方面，如果节点之间端口不通，Pod 之间通信会异常。控制平面需要开放 6443、2379-2380、10250、10257、10259 等端口，工作节点需要开放 10250、30000-32767。云服务器还需要在安全组中放行这些端口，只在本机 firewall 中放行是不够的。
还有一个容易被忽略的配置是 kubelet 的资源预留。默认情况下 kubelet 不会为系统进程保留 CPU 和内存，当节点负载升高时，系统服务可能被 Pod 挤占，导致节点失联。可以在 kubelet 配置中加入 systemReserved 和 kubeReserved，并设置 evictionHard 阈值，避免节点进入不可调度状态。
四、二进制部署与离线安装的思路对比
kubeadm 适合大多数场景，但在某些离线或高度定制的环境里，二进制部署反而更可控。二进制部署的流程是手动下载 Kubernetes 组件二进制文件，为每个组件编写 systemd unit 文件，然后自建证书和 kubeconfig。这种方式安装步骤多，容易出错，但优点是每个环节都可以自定义，适合对集群架构有严格要求的团队。
离线安装的常见做法是在一台能访问互联网的机器上用 kubeadm config images pull 拉取所有镜像，再用 docker save 或 ctr images export 导出为 tar 包，拷贝到离线节点后导入。部署时通过 kubeadm init --image-repository 指向本地仓库地址，或者直接在每台节点上导入相同 tag 的镜像。对于网络插件，也可以提前下载 manifest 和镜像，减少安装过程中的网络依赖。
如果只是学习或测试，使用 minikube 或 kind 会更简单，但它们不适合生产。企业环境通常使用 kubeadm 或基于 kubeadm 的集群管理工具，例如 Rancher、Kubespray 等。选择哪种方案，核心是看团队对集群的控制能力和后续维护成本。只要把系统配置、运行时、网络插件这三处处理好，Linux 上安装 Kubernetes 就能少走很多弯路。
Kubernetes安装Linux容器编排kubeadm部署修改时间：2026-10-01 18:58:18