Debian装K8s需注意啥

在 Debian 上部署 Kubernetes（K8s）有不少“坑”和前置条件，下面按必看事项 → 系统准备 → 安装方式 → 常见坑给你梳理一份实用清单。

一、先确认这些“大前提”

1. 系统版本

• 推荐：Debian 11 (Bullseye) / Debian 12 (Bookworm)
• 内核建议 ≥ 5.x
• 不要用太老的 Debian（如 9/10 已不推荐）

cat /etc/os-release
uname -a

2. 节点规划

• Master：至少 2C2G（生产建议 2C4G+）
• Worker：按需
• 不要在主节点跑业务 Pod（生产环境）

二、系统层必须做的事（非常关键）

1. 关闭 swap（K8s 强制要求）

sudo swapoff -a
sudo sed -i '/swap/d' /etc/fstab

验证：

free -h

2. 关闭防火墙或放通端口

测试环境（最简单）：

sudo ufw disable

生产环境需放通：

• 6443（API）
• 2379-2380（etcd）
• 10250（kubelet）
• 30000-32767（NodePort）

3. 内核参数 & 模块（很重要）

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

4. 时间同步（集群必备）

sudo apt install -y chrony
sudo systemctl enable --now chrony

三、容器运行时（重点）

K8s 已弃用 Docker 作为运行时，推荐：

方案 A：containerd（最推荐）

sudo apt install -y containerd
sudo containerd config default > /etc/containerd/config.toml
sudo systemctl restart containerd

⚠️ 注意：

• SystemdCgroup = true 要开启（否则 kubelet 起不来）

四、安装 K8s 组件

1. 添加 apt 源

sudo apt install -y apt-transport-https ca-certificates curl
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.29/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.29/deb/ /" | sudo tee /etc/apt/sources.list.d/kubernetes.list

sudo apt update

2. 安装 kubelet / kubeadm / kubectl

sudo apt install -y kubelet kubeadm kubectl
sudo apt-mark hold kubelet kubeadm kubectl

五、初始化集群（Master）

sudo kubeadm init \
  --pod-network-cidr=10.244.0.0/16

初始化完成后：

mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

六、网络插件（必装）

推荐 Calico 或 Flannel

Flannel 示例

kubectl apply -f https://github.com/flannel-io/flannel/releases/latest/download/kube-flannel.yml

七、常见坑（Debian 专属）

❌ 1. cgroup 驱动不一致

• kubelet 和 containerd 必须一致（推荐 systemd）

❌ 2. Debian 12 + 老教程

• 很多旧教程用 docker + kubeadm
• 现在已不适用

❌ 3. hostname 不规范

hostnamectl set-hostname master01

• 不能是 localhost
• 建议小写 + 数字

❌ 4. IPv6 问题

如不用 IPv6：

sysctl -w net.ipv6.conf.all.disable_ipv6=1

八、快速检查清单 ✅

• [ ] swap 已关
• [ ] 防火墙处理
• [ ] 内核参数已配
• [ ] 时间同步
• [ ] containerd 正常
• [ ] kubeadm 版本一致
• [ ] 网络插件已装

如果你愿意，我可以：

• 给你一套 Debian 12 + containerd + Calico 的完整脚本
• 或针对 单机 / 生产 / 云服务器 分别说明

你现在是 学习 / 测试 / 生产 环境？