Kubernetes 1.33.7部署实战：常见问题与解决方案

1. Kubernetes 1.33.7 部署实战与深度排错指南

最近在部署Kubernetes 1.33.7集群时，遇到了不少"坑"，从控制平面启动失败到网络插件问题，再到权限配置和资源调度异常。本文将完整还原整个部署过程，并针对每个关键错误提供解决方案。这些经验来自实际生产环境中的反复验证，不同于官方文档的理想化场景，更聚焦于真实环境中可能遇到的各类问题及其解决方法。

2. 基础环境准备与关键配置

2.1 系统要求与前置检查

在开始安装前，必须确保系统满足以下最低要求：

• 2核CPU及以上（实测1核会导致控制平面组件频繁崩溃）
• 2GB可用内存（建议4GB以上，否则kubelet容易OOM）
• 20GB可用磁盘空间
• 完全兼容的Linux发行版（推荐Ubuntu 20.04+/CentOS 7+）
• 禁用交换分区（swapoff -a并永久注释/etc/fstab中的swap行）

关键系统参数检查：

bash复制# 检查内存和交换空间
free -h

# 检查磁盘空间
df -h

# 确保IP转发已启用（必须为1）
sysctl net.ipv4.ip_forward

# 如果未启用，执行以下命令临时生效并永久写入配置
echo "net.ipv4.ip_forward = 1" | sudo tee -a /etc/sysctl.conf
sysctl -p

2.2 Containerd运行时配置

Kubernetes 1.33.7默认使用containerd作为容器运行时，正确配置其sandbox镜像至关重要：

bash复制# 检查当前sandbox镜像配置
grep sandbox_image /etc/containerd/config.toml

# 如果未正确配置或使用国外镜像源，执行替换（使用阿里云镜像源）
sed -i 's#sandbox_image = ".*"#sandbox_image = "registry.aliyuncs.com/google_containers/pause:3.10"#g' /etc/containerd/config.toml

# 重启containerd使配置生效
systemctl restart containerd

注意：pause镜像是Kubernetes Pod的基础镜像，配置错误会导致所有Pod无法启动。国内环境务必使用可靠的镜像源，否则可能因网络问题导致镜像拉取失败。

3. 控制平面初始化与关键错误解决

3.1 kubeadm init 完整命令与参数解析

以下是经过验证可用的初始化命令，包含每个关键参数的说明：

bash复制kubeadm init \
  --apiserver-advertise-address=192.168.235.128 \  # 指定API Server监听地址
  --image-repository registry.aliyuncs.com/google_containers \  # 使用国内镜像源
  --kubernetes-version v1.33.7 \  # 明确指定版本避免兼容问题
  --service-cidr=10.96.0.0/12 \  # 服务虚拟IP范围
  --pod-network-cidr=10.244.0.0/16 \  # Pod IP范围(需与CNI插件匹配)
  --ignore-preflight-errors=all \  # 跳过非致命性检查(生产环境慎用)
  --cri-socket=unix:///run/containerd/containerd.sock \  # 明确指定容器运行时接口
  --v=5  # 详细日志输出级别

3.2 控制平面启动失败深度排查

当遇到如下错误时：

code复制error execution phase wait-control-plane: failed while waiting for the control plane to start: [kube-controller-manager check failed...]

这表明控制平面组件(kube-apiserver, kube-controller-manager, kube-scheduler)未能正常启动。按以下步骤排查：

1. 检查容器运行状态：

bash复制crictl --runtime-endpoint unix:///run/containerd/containerd.sock ps -a | grep kube | grep -v pause

2. 查看组件日志：

bash复制# 获取故障容器ID后查看日志
crictl --runtime-endpoint unix:///run/containerd/containerd.sock logs <container_id>

3. 常见根本原因：

• 镜像拉取失败（特别是kube-apiserver、kube-proxy等核心组件）
• 端口冲突（6443, 10257, 10259等）
• 证书生成失败
• 资源不足（内存/CPU）

4. 彻底重置环境：

bash复制kubeadm reset -f --cri-socket=unix:///run/containerd/containerd.sock
rm -rf /etc/kubernetes/
rm -rf /var/lib/kubelet/
rm -rf /etc/cni/net.d/
iptables -F && iptables -t nat -F && iptables -t mangle -F && iptables -X
ipvsadm --clear
systemctl restart containerd

4. 关键问题解决方案实录

4.1 CNI网络插件缺失问题

症状：CoreDNS Pod处于ContainerCreating状态，describe查看事件显示：

code复制Failed to create pod sandbox: rpc error: code = Unknown desc = failed to setup network for sandbox

解决方案：

bash复制# 下载并安装CNI插件(根据架构选择)
CNI_VERSION="v1.3.0"
ARCH="amd64"  # 或 arm64
mkdir -p /opt/cni/bin
curl -L "https://github.com/containernetworking/plugins/releases/download/${CNI_VERSION}/cni-plugins-linux-${ARCH}-${CNI_VERSION}.tgz" | \
  sudo tar -C /opt/cni/bin -xz

# 验证安装
ls -lh /opt/cni/bin/

# 重启kubelet并重建Pod
systemctl restart kubelet
kubectl delete pod -n kube-system coredns-757cc6c8f8-7sbd9
kubectl delete pod -n kube-system coredns-757cc6c8f8-k5bv8

4.2 节点调度与污点问题

错误信息：

code复制Warning FailedScheduling 2m46s default-scheduler 0/1 nodes are available: 1 node(s) had untolerated taint {node-role.kubernetes.io/control-plane: }

解决方案（移除控制平面节点的NoSchedule污点）：

bash复制# 移除新版污点标签
kubectl taint nodes --all node-role.kubernetes.io/control-plane:NoSchedule-

# 兼容旧版污点标签（双重保险）
kubectl taint nodes --all node-role.kubernetes.io/master:NoSchedule-

生产环境注意：移除污点后工作负载可以调度到控制平面节点，可能影响稳定性。建议仅在测试环境或资源受限时使用此方案。

4.3 权限与kubectl别名问题

当执行kubectl命令出现：

code复制Error from server (Forbidden): pods is forbidden: User "system:root" cannot list resource "pods" in API group "" at the cluster scope

检查并修复kubectl别名问题：

bash复制# 检查是否存在冲突别名
alias | grep kubectl

# 移除问题别名
unalias kubectl

# 验证默认配置
kubectl get nodes

正确做法是使用admin.conf配置文件：

bash复制export KUBECONFIG=/etc/kubernetes/admin.conf
# 或
kubectl --kubeconfig=/etc/kubernetes/admin.conf get nodes

5. 部署后验证与运维技巧

5.1 集群健康状态检查

bash复制# 查看所有节点状态（应显示Ready）
kubectl get nodes -o wide

# 检查所有系统Pod状态（应全部Running）
kubectl get pods -n kube-system

# 详细检查集群组件健康状态
kubectl get --raw='/readyz?verbose'

# 检查事件日志（关注Warning和Error）
kubectl get events --sort-by='.metadata.creationTimestamp' -A

5.2 持久化运维配置建议

1. 日志收集：

bash复制# 查看kubelet日志
journalctl -u kubelet -f

# 查看containerd日志
journalctl -u containerd -f

2. 资源监控：

bash复制# 安装metrics-server
kubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml

# 验证节点资源使用
kubectl top nodes

3. 网络验证：

bash复制# 部署测试Pod验证网络连通性
kubectl run busybox --image=busybox -- sleep 3600
kubectl exec busybox -- ping <另一个Pod的IP>

6. 经验总结与避坑指南

1. 镜像源选择：

• 国内环境务必使用可靠的镜像仓库（如阿里云、腾讯云镜像源）
• 可预先拉取所有所需镜像：kubeadm config images pull --image-repository=registry.aliyuncs.com/google_containers

2. 版本兼容性：

• Kubernetes版本与容器运行时、CNI插件版本需严格匹配
• 1.33.x系列推荐使用containerd 1.6+和CNI插件1.3.0+

3. 资源预留：

• 为系统守护进程预留至少500MB内存：kubelet --system-reserved=memory=500Mi
• 避免内存压力导致kubelet被OOM Killer终止

4. 证书管理：

• 定期检查证书有效期：kubeadm certs check-expiration
• 更新证书：kubeadm certs renew all

5. 备份策略：

• 定期备份/etc/kubernetes/和/var/lib/etcd/
• 使用etcdctl snapshot save创建etcd快照

通过这次部署实践，我深刻体会到Kubernetes安装过程中"细节决定成败"的道理。特别是在资源受限的环境下，每个配置项都需要精心调整。建议在正式环境部署前，先在相同配置的测试环境完整走通整个流程。当遇到问题时，善用kubectl describe和journalctl查看详细日志，这些工具能提供90%以上的问题线索。