在 Debian 12 上搭建单主 Kubernetes 集群
一 环境与准备
- 节点规划：至少准备1 台主节点 + 1 台工作节点；推荐硬件为≥2 核 CPU、≥2 GB RAM、≥20 GB 磁盘（生产环境建议更高）。系统建议使用Debian 12（Bookworm），并确保节点间网络互通、主机名可解析。所有节点需关闭 Swap并开启时间同步（如 NTP）。如使用防火墙，需放行相关端口（如 6443、10250、10251、10252、8472/udp 等，具体取决于组件与网络插件）。
二 安装容器运行时与系统参数
- 安装 containerd（推荐）：
- 安装与内核模块：
- sudo apt update && sudo apt install -y containerd
- 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
EOF
- sudo sysctl --system
- 生成默认配置并启用服务：
- sudo mkdir -p /etc/containerd
- containerd config default | sudo tee /etc/containerd/config.toml
- sudo systemctl daemon-reload && sudo systemctl enable --now containerd
- 可选 Docker（如更熟悉 Docker 生态）：
- 安装与启动：
- sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release
- curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor | sudo tee /usr/share/keyrings/docker.gpg >/dev/null
- echo “deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker.gpg] https://download.docker.com/linux/debian $(lsb_release -cs) stable” | sudo tee /etc/apt/sources.list.d/docker.list >/dev/null
- sudo apt update && sudo apt install -y docker-ce docker-ce-cli containerd.io
- sudo systemctl enable --now docker
- 关闭 Swap（所有节点）：
- sudo swapoff -a
- sudo sed -i ‘/ swap / s/^(.*)$/#\1/g’ /etc/fstab
三 安装 kubeadm kubelet kubectl
- 添加 Kubernetes APT 源并安装组件（所有节点）：
- curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo gpg --dearmor | sudo tee /usr/share/keyrings/kubernetes-archive-keyring.gpg >/dev/null
- 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 >/dev/null
- sudo apt update
- sudo apt install -y kubelet kubeadm kubectl
- sudo apt-mark hold kubelet kubeadm kubectl
- 说明：上述源为当前主流写法；如遇到签名或源变更，请以官方发布为准。
四 初始化控制平面与配置 kubectl
- 在主节点初始化（单主最简示例）：
- sudo kubeadm init --pod-network-cidr=10.244.0.0/16
- 如在国内或镜像拉取较慢，可使用国内镜像仓库并指定版本，例如：
- sudo kubeadm init --image-repository registry.aliyuncs.com/google_containers --kubernetes-version v1.23.6 --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 输出）：
- sudo kubeadm join :6443 --token --discovery-token-ca-cert-hash sha256:
- 验证（主节点）：
- kubectl cluster-info
- kubectl get nodes
五 常见问题与优化
- 镜像拉取慢或失败：使用国内镜像仓库（如 registry.aliyuncs.com/google_containers）并固定版本；必要时在 kubeadm 配置中指定 imageRepository。
- 端口与防火墙：确保 6443（API Server）、10250（kubelet）、10251/10252（kube-scheduler/controller-manager）、以及 8472/udp（Flannel VXLAN） 等端口放通；云厂商安全组同样需要放行。
- 时间同步：所有节点启用 NTP/chrony，避免证书校验与组件通信异常。
- 版本选择与稳定性：选择与你的需求匹配的 Kubernetes 版本；安装后用 kubeadm 升级策略进行后续升级。
- 生产建议：至少2 核/4 GB RAM 起步，使用静态 Pod CIDR 与可靠网络插件（如 Calico/Flannel），并配置 RBAC、准入控制、审计日志、持久化存储 等。
