Debian上K8s安装过程中常见问题

Debian上K8s安装常见问题与排查清单

一 环境预检与系统要求

• 资源与系统版本：建议至少2核CPU、2GB内存、20GB磁盘（生产环境建议更高），操作系统优先选择Debian 12（Bookworm）或Debian 11（Bullseye）。内核需至少3.10，可通过uname -r检查。若资源不足或内核过旧，后续组件（如 kubelet）可能无法正常调度或启动。
• 唯一性校验：确保各节点的MAC地址与product_uuid唯一，避免因克隆镜像导致节点身份冲突。
• 基础准备：更新系统并安装依赖（apt-transport-https、curl、software-properties-common），设置主机名与**/etc/hosts**解析，保证节点间可互通。

二 容器运行时与内核网络

• 运行时选择：Kubernetes支持多种容器运行时，常见为containerd或Docker（包含 containerd）。安装后建议启用并设置为开机自启：systemctl enable --now containerd（或 Docker）。
• 内核模块与参数：加载overlay、br_netfilter模块，并开启桥接流量进入 iptables 与转发：
  • 模块：modprobe overlay && modprobe br_netfilter
  • 配置：/etc/modules-load.d/containerd.conf 写入 overlay\nbr_netfilter
  • sysctl：/etc/sysctl.d/99-kubernetes-k8s.conf 写入
    • net.bridge.bridge-nf-call-iptables = 1
    • net.ipv4.ip_forward = 1
  • 生效：sysctl --system
• 兼容性提示：若使用部分网络插件（如 Weave Net）出现通信异常，可能与iptables/nftables切换有关，可通过update-alternatives --config iptables选择iptables-legacy以提升兼容性。

三 初始化与网络插件

• 关闭 Swap：Kubernetes 要求关闭 Swap，否则 kubelet 预检失败。执行：
  • 临时：swapoff -a
  • 永久：注释 /etc/fstab 中的 swap 行（如 sed -i '/ swap / s/^/#/g' /etc/fstab）
• kubeadm 初始化要点：
  • 常用参数：--apiserver-advertise-address=<控制平面IP>、--pod-network-cidr=<与所选网络插件匹配>（如 Flannel 常用 10.244.0.0/16）
  • 镜像加速：国内环境可指定 --image-repository=registry.aliyuncs.com/google_containers
  • 记录生成的 kubeadm join ... 命令，用于工作节点加入
• 配置 kubectl：
  • mkdir -p $HOME/.kube
  • cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
  • chown $(id -u):$(id -g) $HOME/.kube/config
• 安装网络插件：初始化后必须安装 CNI 插件，否则节点将长时间处于 NotReady。常见选择：
  • Flannel：kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml
  • Calico：kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/master/manifests/calico.yaml
• 验证：kubectl get nodes 应显示 Ready。

四 端口与防火墙

• 常见放通端口（示例为 UFW）：
  • 控制平面：6443/TCP（API Server）
  • etcd：2379-2380/TCP
  • kubelet：10250/TCP（节点间通信与指标）
  • 调度器与控制器管理器：10251/TCP、10252/TCP
  • 可选节点状态：10255/TCP（只读端口，视安全策略开启）
• 操作示例：ufw allow 6443,2379:2380,10250,10251,10252,10255/tcp && ufw reload。如使用 firewalld/云安全组，需按等价的入站/出站规则放行。

五 镜像拉取与组件版本

• 镜像拉取失败：常见原因为墙内外网络差异或镜像仓库不可达。可优先使用国内镜像仓库（如 registry.aliyuncs.com/google_containers），或在节点上手动 docker pull / crictl pull 并重新打标签。
• 组件版本匹配：安装指定版本以避免 API/特性不兼容，例如：
  • apt-get install -y kubelet=1.26.0-00 kubeadm=1.26.0-00 kubectl=1.26.0-00
  • 安装后用 apt-mark hold kubelet kubeadm kubectl 固定版本，避免被系统升级干扰
• 快速定位：
  • 查看系统日志：journalctl -xe
  • 查看组件日志：journalctl -u kubelet、journalctl -u kubeadm
  • 集群状态：kubectl get nodes、kubectl get pods -A、kubectl describe pod <name> -n <ns>