Kubernetes安装部署教程

约 12 分钟读完 14 阅
文章导读
搜「Kubernetes安装部署教程」的人，多数不是不懂 Pod 和 Service 的概念，而是卡在命令敲完之后：kubeadm init 停在拉镜像、kubectl get nodes 报 localhost:8080 连不上、节点加进来却一直 NotReady。这三类基本覆盖了第一次部署失败的大头，所以下面按真实排查顺序写：先确认前提，再走最短可用路径，用一个具体集群把参数落到位，最后给出三
📋 目录
  1. 一 Kubernetes安装部署之前先确认这三件事
  2. 二 Kubernetes安装部署：最短可用路径
  3. 三 Kubernetes安装部署：一个真实场景的完整做法
  4. 四 Kubernetes安装部署：跑不通先查这三处
A A

搜「Kubernetes安装部署教程」的人，多数不是不懂 Pod 和 Service 的概念，而是卡在命令敲完之后：kubeadm init 停在拉镜像、kubectl get nodes 报 localhost:8080 连不上、节点加进来却一直 NotReady。这三类基本覆盖了第一次部署失败的大头，所以下面按真实排查顺序写：先确认前提，再走最短可用路径，用一个具体集群把参数落到位，最后给出三个高频卡点的判断位置。

第一次装 Kubernetes，建议用 kubeadm 单控制面把集群跑通，而不是一上来做高可用或多运行时选型。前提是三件事必须确认：kubeadm/kubelet/kubectl 版本对得上、执行账号有 root 权限且 swap 已关、kubeconfig 在你能读到的位置。跑通的标准不是 init 成功，而是 kubectl get nodes 显示 Ready 且 kube-system 下 Pod 全部 Running。版本偏差和镜像仓库地址会变，以官方版本偏差页面和你所用镜像站的说明为准，不要照抄旧教程里的固定版本号。

Kubernetes安装部署之前先确认这三件事

这三件事缺一件，后面的命令都会以看起来无关的报错失败，先花五分钟查完再动手。

  • 版本：控制面组件和节点组件版本差太大，kubeadm init 会直接拒绝或初始化后 kubelet 起不来。执行 kubeadm version -o short、kubelet --version、kubectl version --client，再 cat /etc/os-release 看发行版和内核对 containerd 的支持情况。能装哪些版本，用包管理器看：apt list -a kubeadm 或 yum --showduplicates list kubeadm。允许的跨版本偏差去 kubernetes.io 的 version skew policy 页面核对，不要凭印象。
  • 权限与主机状态：id -u 返回 0 才是 root，否则每条命令前加 sudo。swapon --show 有输出说明 swap 还开着，kubelet 默认会报 failed to run Kubelet: running with swap on is not supported，需要 swapoff -a 并注释 /etc/fstab 里的 swap 行。lsmod | grep br_netfilter 为空要手动 modprobe。云主机还要在控制台安全组页面放通 6443（API Server）、10250（kubelet）、以及你所选 CNI 需要的端口。
  • 入口位置：集群的入口就是 kubeconfig。ls -l /etc/kubernetes/admin.conf 是 kubeadm 生成的管理员凭证，普通用户要用它拷到 ~/.kube/config；已有配置时 echo $KUBECONFIG 看是否指向了别的文件，kubectl config view --minify 能看到当前实际生效的 cluster 和 server 地址。托管集群则去云控制台的集群详情页，字段通常叫“连接信息”或“kubeconfig”，下载后替换本地文件。

Kubernetes安装部署：最短可用路径

下面这段前置配置在所有节点以 root 执行，作用是加载内核模块、打开转发、关掉 swap，可以直接复制：

modprobe overlay
modprobe br_netfilter
cat >/etc/modules-load.d/k8s.conf <<'EOF'
overlay
br_netfilter
EOF
cat >/etc/sysctl.d/99-k8s.conf <<'EOF'
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward                 = 1
EOF
sysctl --system
swapoff -a
sed -ri 's/^([^#].*\sswap\s.*)$/#\1/' /etc/fstab

做完应该看到 sysctl --system 逐条打印出刚写入的三项，swapon --show 无输出。

Kubernetes安装部署教程
  1. 装容器运行时和三个组件：Ubuntu 系是 apt install -y containerd && systemctl enable --now containerd，然后按 pkgs.k8s.io 官方安装页添加仓库，再 apt install -y kubelet kubeadm kubectl。做完 systemctl status containerd 应是 active (running)，kubeadm version -o short 有输出。
  2. 初始化控制面：kubeadm init --pod-network-cidr=10.244.0.0/16 --cri-socket unix:///run/containerd/containerd.sock --image-repository=<你的镜像站地址>。做完看到末尾打印 Your Kubernetes control-plane has initialized successfully! 和一段 kubeadm join 命令，两样都要留存。
  3. 配好 kubectl：mkdir -p $HOME/.kube && cp /etc/kubernetes/admin.conf $HOME/.kube/config && chown $(id -u):$(id -g) $HOME/.kube/config。做完 kubectl get nodes 能列出控制面节点，状态先显示 NotReady 是正常的。
  4. 装 CNI：按所选插件官方清单执行 kubectl apply -f <清单地址>，Flannel 与 Calico 的 Pod 网段参数要和上一步的 --pod-network-cidr 一致。做完 kubectl get pods -n kube-system 里 CNI 的 DaemonSet 全部 Running，节点转为 Ready。
  5. 加节点：在工作节点执行 init 结束时留存的 kubeadm join ...，带 --cri-socket。做完在控制面 kubectl get nodes 应看到两台都是 Ready。

按这个顺序判断是否真的跑通，不要跳步：先看 kubectl get nodes 是否 Ready，再看 kubectl get pods -n kube-system 是否全部 Running，再看 kubectl run t --image=busybox --restart=Never -- sleep 60 能否调度成功，最后才考虑加工作负载。

Kubernetes安装部署：一个真实场景的完整做法

场景取一个常见规模：3 台 Ubuntu 22.04 虚拟机，内网 192.168.10.0/24，控制面 192.168.10.11，两台工作节点 .12 和 .13，单节点最大 110 个 Pod，Service 网段用默认的 10.96.0.0/12，Pod 网段选 10.244.0.0/16，容器运行时用 containerd。

先在控制面把配置写成文件 /root/kubeadm-config.yaml，而不是堆一长串命令行参数，方便回看和复用：

apiVersion: kubeadm.k8s.io/v1beta4
kind: InitConfiguration
localAPIEndpoint:
  advertiseAddress: 192.168.10.11
  bindPort: 6443
nodeRegistration:
  criSocket: unix:///run/containerd/containerd.sock
---
apiVersion: kubeadm.k8s.io/v1beta4
kind: ClusterConfiguration
kubernetesVersion: v1.31.0
imageRepository: registry.aliyuncs.com/google_containers
networking:
  podSubnet: 10.244.0.0/16
  serviceSubnet: 10.96.0.0/12

两个字段要按环境替换：kubernetesVersion 换成第 1 步 apt list -a kubeadm 里实际能装到的那一版；imageRepository 换成你网络里确实连得通的镜像站地址。API 结构会随 kubeadm 主版本变化，稳妥做法是先跑一次 kubeadm config print init-defaults，以打印出的 apiVersion 和字段结构为准再改，然后 kubeadm init --config /root/kubeadm-config.yaml --dry-run 预检，无报错再正式执行。

Kubernetes安装部署教程

还有一个文件必须改：/etc/containerd/config.toml，找到 [plugins.'io.containerd.grpc.v1.cri'.containerd.runtimes.runc.options] 下的 SystemdCgroup，设为 true，再 systemctl restart containerd。用 containerd config default | grep SystemdCgroup 确认生效。不改这一项，kubelet 大概率起不来。

Kubernetes安装部署：跑不通先查这三处

按出现频率从高到低，三个卡点和各自的检查位置：

  • 节点一直 NotReady，kube-system 里没有 CNI Pod：kubectl describe node <节点名> 的 Conditions 里会看到 NetworkUnavailable，原因是 cni plugin not initialized。检查 kubectl get pods -n kube-system 是否存在 flannel 或 calico 的 Pod，以及 ls /etc/cni/net.d/ 是否为空。空目录就是 CNI 没装上或清单 apply 失败，回看 apply 时的报错。
  • kubelet 反复重启：journalctl -u kubelet -n 100 --no-pager 里若出现 failed to run Kubelet: misconfiguration: kubelet cgroup driver: "systemd" is different from docker cgroup driver: "cgroupfs"，就是上面说的 containerd SystemdCgroup 没开；若出现 running with swap on is not supported，回查 swapon --show 和 /etc/fstab。另一条常见的是 failed to get sandbox image，检查 crictl images 里有没有 pause 镜像。
  • kubectl 报 The connection to the server localhost:8080 was refused：这是没找到 kubeconfig，不是集群挂了。检查 ls -l /etc/kubernetes/admin.conf 是否存在，echo $KUBECONFIG 是否指了别的路径，以及当前用户 ~/.kube/config 的属主是不是自己。按第 2 节的第三条重新拷一次即可。

另外提醒一个容易被忽略的坑：kubeadm init 成功只代表控制面起来了，不代表集群可用。此时节点还是 NotReady，任何 Pod 都调度不上去，所以不要把 init 的成功输出当成部署完成，接着把 CNI 装完再看节点状态，才算这一步结束。