Debian上Kubernetes安装的最佳实践指南

Debian 上 Kubernetes 安装最佳实践指南

一 环境与前置准备

• 操作系统建议使用 Debian 12（Bookworm），内核保持最新稳定版。
• 硬件基线：控制平面至少 2 核 CPU / 4 GB RAM / 20 GB 磁盘；工作节点至少 2 核 CPU / 2 GB RAM / 20 GB 磁盘，并确保节点间网络互通、时间同步（NTP）。
• 主机标识：为每个节点设置唯一 hostname，并在 /etc/hosts 中配置 IP 与主机名映射，便于内网解析与故障排查。
• 关闭 Swap：临时与永久关闭，避免 kubelet 异常。
• 容器运行时：使用 containerd 作为默认运行时（推荐），也可选择 Docker（需额外配置 CRI 支持）。

二 系统内核与网络参数

• 加载内核模块并开启桥接与转发，为 Pod 网络与 kube-proxy 提供基础转发能力。
• 建议将 kubelet 使用 systemd cgroup 驱动，与主流发行版服务管理保持一致。

示例配置（所有节点执行）：

# 加载模块
sudo tee /etc/modules-load.d/containerd.conf <<EOF
overlay
br_netfilter
EOF
sudo modprobe overlay
sudo modprobe br_netfilter

# 开启桥接与转发
sudo tee /etc/sysctl.d/99-kubernetes-k8s.conf <<EOF
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward                 = 1
EOF
sudo sysctl --system

上述内核与网络设置是 Kubernetes 在 Linux 上的通用前置条件，能确保网桥流量进入 iptables 规则链并实现跨节点转发。

三 安装容器运行时 containerd

• 安装与启用 containerd，生成默认配置并启用 SystemdCgroup = true，然后重启服务。

示例步骤（所有节点执行）：

sudo apt-get update
sudo apt-get install -y containerd
sudo mkdir -p /etc/containerd
containerd config default | sudo tee /etc/containerd/config.toml
# 启用 systemd cgroup
sudo sed -i 's/SystemdCgroup \= false/SystemdCgroup \= true/g' /etc/containerd/config.toml
sudo systemctl restart containerd
sudo systemctl enable --now containerd

说明：Kubernetes 自 v1.24 起默认使用 containerd；若使用 Docker，需安装 cri-dockerd 并配置 kubelet 使用其 CRI 端点。

四 安装 kubeadm kubelet kubectl

• 添加 Kubernetes APT 仓库并安装组件，完成后将 kubelet/kubeadm/kubectl 标记为 hold，避免被系统升级意外替换。

示例步骤（所有节点执行）：

sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl gnupg
curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor -o /usr/share/keyrings/kubernetes-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/kubernetes-archive-keyring.gpg] https://apt.kubernetes.io/ kubernetes-xenial main" | 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 systemctl enable --now kubelet

说明：上述仓库与安装方式适用于 Debian 10+ 的 x86_64 环境；安装完成后 kubelet 会处于“等待控制平面就绪”的状态。

五 初始化控制平面与网络插件

• 初始化控制平面（仅在 master 节点执行）：指定 Pod 网络 CIDR（与所选网络插件匹配），并记录生成的 kubeadm join 命令用于工作节点加入。
• 安装网络插件：常见选择为 Flannel 或 Calico，二者择一部署即可。
• 配置 kubectl：将 admin.conf 拷贝至用户目录，便于本地管理集群。

示例步骤（master 节点执行）：

# 初始化（示例 Pod CIDR，Flannel 使用 10.244.0.0/16；Calico 常见 192.168.0.0/16）
sudo kubeadm init --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

# 验证
kubectl get nodes
kubectl get pods -A

说明：初始化命令的输出包含用于工作节点加入的完整命令，请妥善保存；网络插件必须在控制平面就绪后部署，否则节点会一直处于 NotReady 状态。

六 加入工作节点与防火墙端口

• 在工作节点执行 kubeadm join，使用 master 初始化时生成的 token 与 CA 证书哈希 加入集群。
• 若启用防火墙（如 UFW），放行必要端口；如使用云厂商安全组，亦需放通相同端口范围。

常用端口清单（示例）：

• 控制平面：6443/TCP（API Server）
• etcd：2379-2380/TCP
• kubelet：10250/TCP
• 调度器与控制器管理器：10251/TCP、10252/TCP
• 节点可观测性（可选）：10255/TCP

UFW 示例（按需开启）：

sudo ufw allow 6443/tcp
sudo ufw allow 2379:2380/tcp
sudo ufw allow 10250/tcp
sudo ufw allow 10251/tcp
sudo ufw allow 10252/tcp
sudo ufw allow 10255/tcp
sudo ufw reload

说明：端口放行范围与具体网络插件、云环境相关，生产环境建议采用最小暴露面策略并结合网络策略（NetworkPolicy）进行细粒度控制。