Kubernetes在Debian上的安装技巧

在 Debian 上安装 Kubernetes 的实用技巧

一 环境与前置检查

• 硬件建议：至少2 核 CPU、2 GB 内存、20 GB 磁盘；所有节点间网络互通，主机名可解析（可用 /etc/hosts 或 DNS）。
• 基础准备：系统更新（sudo apt update && sudo apt upgrade -y）；时间同步（建议使用 NTP/chrony）；确保能访问外网软件源。
• 内核与模块：加载 overlay、br_netfilter；开启桥接与转发参数，保证容器网络与 kube-proxy 正常工作。
• 防火墙与端口：如使用 UFW，放行控制面与工作节点所需端口（见下文“端口速查”）；云上环境同步放通安全组。
• 容器运行时：优先使用 containerd（与 kubelet 的 systemd cgroup 配合更稳定）；如使用 Docker，需确保与 kubelet cgroup 驱动一致。

二 使用 containerd 的推荐安装路径

• 安装与内核参数
  • 安装 containerd：sudo apt-get update && sudo apt-get install -y containerd
  • 启用内核模块与 sysctl：
    • echo -e “overlay\nbr_netfilter” | sudo tee /etc/modules-load.d/containerd.conf
    • sudo modprobe overlay && sudo modprobe br_netfilter
    • cat <<EOF | sudo tee /etc/sysctl.d/99-kubernetes-k8s.conf net.bridge.bridge-nf-call-iptables = 1 net.ipv4.ip_forward = 1 net.bridge.bridge-nf-call-ip6tables = 1 EOF
    • sudo sysctl --system
• 配置 containerd 使用 systemd cgroup
  • 生成默认配置：containerd config default | sudo tee /etc/containerd/config.toml
  • 编辑 /etc/containerd/config.toml，在 [plugins.“io.containerd.grpc.v1.cri”.containerd.runtimes.runc.options] 下设置：SystemdCgroup = true
  • 重启并自启：sudo systemctl restart containerd && sudo systemctl enable containerd
• 安装 kubeadm/kubelet/kubectl
  • 导入 GPG（推荐新版签名方式）：curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.33/deb/Release.key | gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
  • 添加源（按需替换版本，如 v1.33）：echo “deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.33/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
• 初始化控制面（示例）
  • 单控制面：sudo kubeadm init --pod-network-cidr=10.244.0.0/16
  • 高可用或指定端点：sudo kubeadm init --control-plane-endpoint=<VIP_or_DNS> --pod-network-cidr=10.244.0.0/16
• 配置 kubectl
  • mkdir -p $HOME/.kube
  • sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
  • sudo chown $(id -u):$(id -g) $HOME/.kube/config
• 安装网络插件
  • Flannel：kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml
  • Calico：kubectl apply -f https://docs.projectcalico.org/manifests/calico.yaml
• 加入工作节点
  • 使用 kubeadm init 输出中的 kubeadm join 命令；如 token 过期，可在控制面执行：kubeadm token create --print-join-command

三 常见坑与快速排查

• 端口未放行：控制面常见端口 6443（API）、2379/2380（etcd）；工作节点常见端口 10250（kubelet）、30000–32767（NodePort）。UFW 示例：sudo ufw allow 6443,2379,2380,10250/tcp && sudo ufw allow 30000:32767/tcp && sudo ufw reload。

• Swap 未关闭：kubelet 要求关闭 swap。临时：sudo swapoff -a；永久：sudo sed -i ‘/ swap / s/^(.*)$/#\1/g’ /etc/fstab。

• cgroup 驱动不一致：containerd 需设置 SystemdCgroup = true；kubelet 默认使用 systemd，若用 Docker，需确保 Docker 也使用 systemd cgroup（否则 Pod 可能一直处于 ContainerCreating）。

• 节点 NotReady：优先检查网络插件是否安装成功（kubectl get pods -n kube-system），再查看 kubelet 日志（sudo journalctl -u kubelet -f）与节点事件（kubectl describe node ）。

• 镜像拉取慢或失败：可配置国内镜像源或使用企业/云厂商镜像仓库；初始化时可通过 --image-repository 指定镜像仓库前缀（如 registry.aliyuncs.com/google_containers）。

四 端口速查与版本选择

• 端口速查
  • 控制面：6443（Kubernetes API）、2379–2380（etcd 集群通信）
  • 工作节点：10250（kubelet API）、10251（kube-scheduler）、10252（kube-controller-manager）、30000–32767（NodePort 范围）
• 版本选择
  • 建议选择当前稳定大版本中的一个小版本（如 v1.33.x），并保持控制面与节点组件版本一致或兼容；安装时通过 APT 源锁定版本，避免误升级（sudo apt-mark hold kubelet kubeadm kubectl）。