kubeadm部署单节点Kubernetes集群：核心步骤与避坑指南-北京尧图网络

1. 部署前必须想清楚的事为什么单节点还要用 kubeadm先说个常被误解的点很多人觉得单节点集群直接用 minikube 或者 kind 就够了何必上 kubeadm 这种“生产级”工具。但实际工作中单节点 kubeadm 集群恰恰是性价比最高的学习环境——它和真实生产集群的部署流程完全一致你在这里敲的每一条命令将来扩成多节点时一条都不用改。我见过不少同学先在 minikube 上玩得飞起结果一到生产环境用 kubeadm 建集群就懵了证书怎么签发etcd 在哪配置kubelet 和 apiserver 之间怎么通信这些关键机制在 minikube 里全被隐藏了。而 kubeadm 的好处就在于它把 Kubernetes 的核心组件全部显式地暴露给你但又不像二进制部署那样需要你手动处理每一个证书和配置文件。另一个现实问题是很多人手头只有一台 4C8G 的服务器或者一台性能还不错的笔记本想搭个完整的 K8s 环境做测试。这时候单节点集群就是最优解——既能跑通全部核心工作负载Deployment、Service、Ingress、PVC又不需要额外找机器。kubeadm 部署单节点集群还有一个隐性好处升级路径平滑。K8s 官方从 1.24 开始把 kubeadm 作为唯一推荐的部署方式后续版本升级比如 1.27 - 1.28 - 1.29都能通过 kubeadm upgrade 命令完成。你在一开始就用 kubeadm等于给自己留好了将来扩展和升级的路。本文使用的版本是 Kubernetes 1.27这个版本有几个值得注意的特性正式移除了 docker 运行时支持cri-dockerd 除外、引入了 CEL 进行 CRD 校验、SeccompDefault 特性进入稳定版。我们的部署会用到 containerd 作为容器运行时这也是目前社区最主流的组合。2. 环境准备与前置条件检查一次配好后面少踩坑2.1 硬件与系统要求部署前先检查机器配置。K8s 官方要求最低 2C2G但我的实际体验是2C4G 是底线2C2G 跑起来 etcd 和 apiserver 会频繁 OOMpod 调度也慢。有条件的话建议直接 4C8G后面跑业务负载会从容很多。宿主机操作系统建议用 Ubuntu 22.04 LTS 或者 CentOS 7.9 / Rocky Linux 9这三套系统我都试过Ubuntu 22.04 遇到坑最少尤其是网络和 systemd 配置方面更省心。以下操作均以 Ubuntu 22.04 为例CentOS 系需要把 apt 换成 yum/dnfselinux 也要单独处理。磁盘空间这块要注意K8s 本身不占多少空间大约 2G 左右但镜像仓库里的镜像、etcd 数据、容器日志都会持续增长。建议系统盘至少 50G单独挂一个数据盘给 /var/lib/docker 和 /var/lib/containerd 用更好。2.2 系统初始化这些操作不做后面全是坑我的初始化顺序是固定的每一步都有明确目的不是为了照抄命令而照抄# 1. 关闭 swapkubelet 才能正常工作 swapoff -a sed -ri s/.*swap.*/#/ /etc/fstab # 2. 加载内核模块 cat EOF | tee /etc/modules-load.d/k8s.conf overlay br_netfilter EOF modprobe overlay modprobe br_netfilter # 3. 配置内核参数 cat EOF | 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 sysctl --system # 4. 配置主机名和 hosts hostnamectl set-hostname k8s-master echo 192.168.1.100 k8s-master /etc/hosts逐条解释一下为什么必须做关闭 swapkubelet 的 QoS 机制依赖 cgroup 管理内存如果宿主机开了 swapPod 的内存限额就会失效。K8s 官方从 1.22 开始直接禁止带 swap 运行 kubelet。加载 br_netfilterK8s 的 Service 依赖 iptables/IPVS 做流量转发而 bridge 网桥上的流量默认不经过 iptables不加载这个模块会导致 ClusterIP 访问不通。开启 ip_forwardPod 与外部通信需要宿主机做 IP 转发这个不开的话 Pod 访问外网会失败。hosts 解析单节点虽然不需要多节点通信的 DNS 解析但 apiserver 在生成证书时会用到主机名提前配好能避免后续证书 SAN 不匹配的问题。2.3 安装容器运行时 containerdK8s 1.24 之后不再直接支持 Docker但 containerd 作为行业标准运行时跟 K8s 的集成最顺滑。这里有两条路线直接装 containerd或者装 Docker自带 containerd然后用 cri-dockerd 适配。我推荐前者少一层转换问题更少。# 安装 containerd apt-get update apt-get install -y containerd.io # 生成默认配置 containerd config default | tee /etc/containerd/config.toml # 修改配置使用 systemd cgroup 驱动 sed -i s/SystemdCgroup false/SystemdCgroup true/ /etc/containerd/config.toml # 配置镜像加速国内环境必备实测有效 sed -i s#registry.k8s.io#registry.aliyuncs.com/google_containers# /etc/containerd/config.toml # 重启生效 systemctl restart containerd systemctl enable containerd这里的核心知识点是cgroup 驱动必须统一。K8s 从 1.26 开始强制要求 kubelet 和容器运行时使用相同的 cgroup 驱动否则节点会一直处于 NotReady 状态。我们的 kubelet 后面会用 systemd 驱动所以 containerd 也必须配成 SystemdCgroup true。镜像加速那行我用了阿里云的 mirror因为 k8s.gcr.io 和 registry.k8s.io 在国内访问极慢不行或者直接超时。这里的替换规则是把registry.k8s.io整体替换成registry.aliyuncs.com/google_containers配置后所有 K8s 核心组件的镜像都能正常拉取。2.4 安装 kubeadm、kubelet、kubectl这三个组件版本必须一致否则可能出现 kubeadm 初始化成功但 kubelet 起不来的问题。安装源用阿里云镜像站速度快且稳定apt-get update apt-get install -y apt-transport-https ca-certificates curl gpg # 添加 K8s 的 apt 源 curl -fsSL https://mirrors.aliyun.com/kubernetes/apt/doc/apt-key.gpg | gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg echo deb [signed-by/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://mirrors.aliyun.com/kubernetes/apt/ kubernetes-xenial main | tee /etc/apt/sources.list.d/kubernetes.list apt-get update apt-get install -y kubelet1.27.4-00 kubeadm1.27.4-00 kubectl1.27.4-00 # 锁定版本防止意外升级 apt-mark hold kubelet kubeadm kubectl版本号我特意选了 1.27.4这是一个比较稳定的 patch 版本。如果你不确定当前最新 patch 是多少可以用apt-cache policy kubeadm查看可用版本列表然后选最新的 1.27.x。锁定版本这一步非常重要。我在生产环境遇到过 kubelet 被意外升级导致整个集群版本不匹配的情况K8s 的版本跨越不能太大官方支持 n-2 以内的版本一旦某个组件跳了多个版本集群就废了。所以装完立刻 hold 住是标准操作。3. 使用 kubeadm 初始化单节点集群核心步骤与参数详解3.1 预拉取镜像一招避免初始化超时kubeadm init 过程中需要拉取 apiserver、etcd、scheduler、controller-manager 等核心组件镜像国内网络情况下经常卡在这一步。我的习惯是先手动拉一遍确认镜像都有了再执行 initkubeadm config images list --kubernetes-version v1.27.4这条命令会列出所有需要的镜像。看到列表后用kubeadm config images pull预拉取。如果你已经配置了 containerd 的镜像加速这一步应该比较快。如果还慢可以指定--image-repository参数kubeadm config images pull --image-repository registry.aliyuncs.com/google_containers3.2 kubeadm init 参数选择为什么要指定这些参数初始化命令如下kubeadm init \\ --kubernetes-versionv1.27.4 \\ --image-repositoryregistry.aliyuncs.com/google_containers \\ --apiserver-advertise-address192.168.1.100 \\ --pod-network-cidr10.244.0.0/16 \\ --service-cidr10.96.0.0/12 \\ --control-plane-endpointk8s-master参数逐一说明--kubernetes-version必须和你安装的 kubeadm 版本匹配否则会尝试从网络获取目标版本信息容易卡住。--image-repository镜像仓库地址指定为国内可达的镜像源。--apiserver-advertise-addressapiserver 对外通信的 IP 地址。如果你是单机部署且有多个网卡必须指定主网卡 IP否则 kubelet 可能连错地址。--pod-network-cidrPod 网段。这里用 10.244.0.0/16 是因为后面要装的 Flannel 网络插件默认使用这个网段。如果你计划用 Calico可以改成 192.168.0.0/16。这是个必须提前决定的选项一旦集群初始化完成再改网段会非常痛苦。--service-cidrService 网段一般保持默认 10.96.0.0/12 即可。--control-plane-endpoint控制面端点单节点就填主机名将来扩成多节点时这个字段就是 load balancer 的地址。3.3 初始化过程解读日志里都藏了什么信息执行上述命令后会有一段较长时间的等待期间 kubeadm 依次执行以下操作生成 PKI 证书和密钥CA、apiserver、etcd 等生成 kubeconfig 文件admin.conf、kubelet.conf 等配置 kubelet 的 systemd 服务将控制面组件以静态 Pod 方式启动注意apiserver 等组件是以 Pod 形式运行在 kubelet 下面的初始化 etcd安装 core DNS 和 kube-proxy初始化成功后会输出一段黄色的引导信息包括如何配置 kubectl 的 kubeconfig如何安装 Pod 网络插件如何添加 worker 节点join 命令如果你在本地虚拟机里做实验强烈建议把这段输出完整复制保存下来尤其是最后的kubeadm join命令——不过单节点集群不需要执行 join但那串 token 和 hash 在某些场景下还有用。配置 kubectl 的标准命令mkdir -p $HOME/.kube sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config sudo chown $(id -u):$(id -g) $HOME/.kube/config3.4 安装 Pod 网络插件单节点最容易忽略的一步很多新手在 init 成功后执行kubectl get nodes看到控制面节点是 NotReady 状态就慌。其实这是完全正常的因为缺少 Pod 网络插件CoreDNS 等其他核心组件的 Pod 也无法正常运行。网络插件是 K8s 集群的必需品它的作用是为每个 Pod 分配网络地址并在节点间打通网络。单节点集群虽然只有一个节点同样必须安装。这里用 Flannel因为它最简单、轻量适合单节点场景kubectl apply -f https://raw.githubusercontent.com/flannel-io/flannel/master/Documentation/kube-flannel.yml执行完等待大约 30 秒然后验证kubectl get pods -n kube-flannel kubectl get nodes当节点状态变成 Ready 时核心集群就算跑通了。如果卡在 NotReady先别急着查 Pod按这个顺序排查systemctl status kubelet journalctl -u kubelet -f kubectl get pods -A看日志永远是第一位的不要瞎猜。3.5 单节点集群去掉调度污点让工作负载能跑在主节点上默认情况下控制面节点带有一个 taint污点调度器不会把普通的业务 Pod 调度到主节点上。多节点集群里这很正常但单节点集群如果不去掉这个污点你会发现kubectl run创建的 Pod 一直处于 Pending 状态。kubectl taint nodes --all node-role.kubernetes.io/control-plane-这条命令把所有控制面节点上的污点移除命令最后的-表示移除该污点。执行完后调度器就可以把业务 Pod 放到这唯一的节点上运行了。这里有个小坑要提醒如果你后来又执行了kubeadm upgrade污点可能会被重新加上到时候需要再执行一次这个命令。4. 单节点集群的功能验证从 Pod 到 Ingress 全链路4.1 验证核心组件运行状态集群 Ready 后先做一轮基础体检确认所有核心组件都健康kubectl get nodes kubectl get pods -A kubectl get componentstatuses输出的重要内容节点状态为 Ready版本 1.27.4kube-system 命名空间下所有 Pod 都处于 Running 状态kube-apiserver、kube-scheduler、kube-controller-manager、etcd 都是 Healthy这里有个细节kubeadm 部署的集群里apiserver 等组件是以静态 Pod 形式运行的它们不在kubectl get pods默认显示的 namespace 里而是在 kube-system 下。如果某个组件状态异常可以直接看对应 Pod 的日志比翻 systemd journal 更方便一些。4.2 部署一个测试应用跑通集群后我用一个简单应用验证基本功能# 创建 deployment kubectl create deployment nginx-test --imagenginx:alpine # 暴露为 NodePort 服务 kubectl expose deployment nginx-test --typeNodePort --port80 # 查看服务情况 kubectl get svc nginx-test Kubectl get pods -o wideNodePort 服务默认分配的端口范围是 30000-32767如果你本机就是这台服务器直接访问http://localhost:端口能看到 nginx 欢迎页就说明整个链路通了。这个测试的意义是验证三件事调度器能否正常调度 Podkubelet 通过kube-proxy 能否正常配置 Service 转发规则容器运行时能否正常拉取并运行镜像4.3 验证 DNS 和服务发现K8s 集群的核心价值之一是服务发现。同一个命名空间内的服务相互访问可以直接用服务名——这不需要额外测试CoreDNS 会自动处理。但跨命名空间的访问要带 namespace 后缀。这里顺便给自己写一个小工具来验证 DNS 解析比如起一个 busybox Podkubectl run -it --rm test-pod --imagebusybox --restartNever -- nslookup nginx-test能解析出 ClusterIP 就说明 CoreDNS 和 kube-dns 工作正常。4.4 安装 Ingress Controller补上集群对外访问的最后一块拼图NodePort 虽然可以用但每次部署服务都要手动分配端口而且在云环境里暴露的端口不一定能在安全组里放行。生产环境更常用的是 Ingress统一入口管理 HTTP/HTTPS 路由。单节点集群装 Ingress 我推荐 Nginx Ingress Controller社区最成熟kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.8.1/deploy/static/provider/cloud/deploy.yaml等 Pod 启动后创建一个 Ingress 规则apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: nginx-test spec: ingressClassName: nginx rules: - host: test.local http: paths: - path: / pathType: Prefix backend: service: name: nginx-test port: number: 80如果你想在本地验证把/etc/hosts里加一行127.0.0.1 test.local然后访问http://test.local就能看到 nginx 页面了。单节点集群没有负载均衡器Nginx Ingress 默认用 hostNetwork 模式监听 80/443 端口这也是它能直接访问的原因。之前热词里提到的“k8s 原生管理页面”如果你需要的话可以在集群里部署 Kubernetes Dashboard作为图形化管理界面。不过我的建议是先把命令行玩熟再上 Dashboard否则出了问题连怎么查日志都不知道。5. 常见问题排查与避坑指南运维视角的实战总结5.1 排错框架先看组件状态再看日志最后重启K8s 集群出问题不可怕可怕的是没有排查思路。我总结了一套固定的排错顺序kubectl get nodes看节点状态NotReady 优先查 kubeletkubectl get pods -A看 Pod 状态非 Running 的先 describe 看事件kubectl describe pod name看调度、镜像拉取、容器启动的事件记录kubectl logs name看容器本身的应用日志journalctl -u kubelet看 kubelet 的日志这套顺序从底层到上层从平台到应用基本上能把大多数问题定位到具体层面。很多新手一上来就重启 kubelet这是错误的做法——有根因还挂着重启只是暂时掩盖问题。5.2 高频报错对照表下面是单节点部署中最高频的几个报错每个都是我自己踩过或帮人排过的现象根本原因解决方案kubeadm init卡在 pulling images网络原因无法访问镜像仓库配置镜像加速或手动先拉镜像节点一直是 NotReadycgroup 驱动不一致检查 containerd 配置是否设置了 SystemdCgroup truePod 一直 ContainerCreatingCNI 没有安装或配置异常安装 Flannel/Calico检查 kube-flannel Pod 日志Service 的 ClusterIP 无法访问br_netfilter 模块未加载modprobe br_netfilter并写入 /etc/modules-load.d调度 Pod 一直 Pending控制面污点未去除kubectl taint nodes --all node-role.kubernetes.io/control-plane-CoreDNS 一直 CrashLoopBackOff网络插件未就绪或版本不兼容重新 apply 最新的 Flannel 配置5.3 单节点集群的容量陷阱单节点集群有一个容易忽略的坑所有组件包括 etcd、apiserver、业务 Pod、监控采集器全部挤在同一台机器上。内存是最容易成为瓶颈的资源。我遇到过几次情况是 etcd 因为文件描述符耗尽导致 leader election 抖动表现为 apiserver 时而可用时而不可用非常诡异。两个建议提前在节点上配置好ulimit和fs.file-max不要在这台机器上同时跑大数据框架或编译任务5.4 重装注意事项一个动作救回你半天时间部署过程中经常需要推倒重来。如果 init 失败或者想换一个 CNI 方案需要彻底清理kubeadm reset -f rm -rf /etc/cni/net.d rm -rf $HOME/.kube iptables -F iptables -t nat -F iptables -t mangle -F ipvsadm -C 2/dev/null || truevc注意kubeadm reset会清理 etcd 和其他组件的数据但不会自动清理 CNI 配置文件。如果不删掉/etc/cni/net.d重新部署后网络插件可能看起来装好了但 Pod 间通信仍然异常这算是一个隐藏的雷。6. 单节点集群的后续扩展与生产化思考6.1 从单节点到多节点如何顺利扩容前面所有配置都按多节点标准做了所以扩容其实很简单准备第二台机器重复 2.2 到 2.4 的系统初始化步骤在第二台机器上执行类似下面的 join 命令从主节点的 kubeadm init 输出中复制kubeadm join 192.168.1.100:6443 --token token --discovery-token-ca-cert-hash sha256:hash如果把 worker 节点也加上--control-plane参数还能变成高可用控制面。不过这里的单节点集群里没有我一般是按纯 worker 节点加的。扩容后需要注意检查节点标签和污点确保业务负载按预期分布如果数据面流量变大要考虑给集群装 metrics-server 采集资源使用数据6.2 给单节点集群加装监控与运维设施集群搭完下一步必然是监控。轻量方案是部署 metrics-serverkubectl apply -f https://github.com/kubernetes-sigs/metrics-server/releases/latest/download/components.yaml然后配合kubectl top nodes查看资源使用。更完整的方案是 Prometheus Grafana直接在集群里用 Helm 一键部署这个就看你的需求了。热词里也有提到 k8s 集群搭建 prometheus确实一个只跑业务不带监控的 K8s 集群跟睁眼瞎没有区别。6.3 存储方案选型单节点也能实现持久化单节点集群不能直接使用云厂商的动态存储通常依赖多节点分布式存储但本地持久化还是必须配的不然 Pod 一重启数据就没了。我常用两个方案Local Path Provisioner轻量级基于宿主机目录做 PV适合单节点。一条命令就能装好kubectl apply -f https://raw.githubusercontent.com/rancher/local-path-provisioner/master/deploy/local-path-storage.yamlNFS Subdir External Provisioner如果有 NAS/NFS 存储可以用这个方案以后能平滑迁移到多节点。6.4 版本升级路线图K8s 的版本迭代一直很快1.27 已经有些年头了。如果你想要跟进新版本升级顺序是逐版本递进不能跳版本。建议先看一眼官方支持矩阵在 1.27 还在支持周期内时尽快规划升级路线。升级命令很简单apt-get update apt-get install -y kubeadm1.28.x-00 kubeadm upgrade plan kubeadm upgrade apply v1.28.x真正要花时间的是升级前的准备工作和升级后的验证别只看命令短。主要检查项包括备份 etcdetcdctl snapshot save确认所有 Pod 都在 Running无异常升级 kubelet 和 kubectl然后 drain 节点重启7. 从单节点到全栈这套环境的下一步还能做什么部署单节点集群只是第一步我个人最推荐继续折腾的方向有两个跑通一套微服务全链路把网关、注册中心、配置中心、业务服务全部容器化部署上来用热词里提到的若依这类常见项目做改造理解 K8s 在真实业务里的定位。这个挑战比单纯建集群大得多但收获也大得多。迁移上云单节点集群环境验证没问题后要考虑的就是怎么把你的整套环境从本地迁移到云上然后在云环境做压测验证。部署和运维思路是差不多的看你要选择什么服务而已。个人体会别小看这个单节点集群它是你理解 K8s 所有核心概念的“驾驶舱”。我就是在单节点上把 Pod、Service、Ingress、PV、PVC、ConfigMap、Secret 全玩熟之后再去学高可用集群、联邦集群那些进阶概念突然就通了。先把基础环境搭建扎实后面再在各种云环境里做生产化改造都会变得顺理成章。

kubeadm部署单节点Kubernetes集群：核心步骤与避坑指南

相关推荐

Agent Substrate术语表完全解析：从ActorTemplate到Uniform DNS Mesh的15个关键词

PaddleOCR 2.10 全景解析：12 个自研模型、4 条多模型产线与低代码全流程开发能力

周报任务交给 Claude Cowork，TaoToken 做统一出口再定时触发

更多资讯

git reset --hard 后悔药：用 reflog 和 fsck 找回丢失的代码

计算机专业生涯规划书：从Word文档到可验证技能路线图

Swift运算符速查清单：基础、位运算与自定义运算符全解析（Swift编程语言中文版）

OpenBCI脑电数据导入MNE：从CSV到脑地形图全流程

2026年AI编程工具全景：33款主流工具分类与实战选型指南

工业相机镜头选型全解析：从焦距计算到现场踩坑避雷指南

今日更新

AReaL 调试指南：从 Agent Workflow 验证到分布式训练死锁诊断

MATLAB实现GPS L1 C/A信号仿真与二维捕获验证

彻底搞懂ASCII、Unicode与UTF-8：从乱码根源到编码实战

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？