kubeadm v1.18.2单Master Kubernetes集群部署实战

1. 项目概述为什么在2020年还要手撸单Master k8s集群kubeadm v1.18.2 这个版本号一出来我就知道得赶紧记两笔——它卡在Kubernetes生态一个微妙的临界点上既没被后续v1.20的cgroup v2默认支持搞乱节奏又避开了v1.16之前那些让人半夜爬起来改kubelet参数的坑。现在很多人一提k8s部署就条件反射说“用托管服务”但实话说某高校实验室做边缘AI推理验证、某公司内部CI/CD流水线预演、甚至某开发者想真正看懂Pod调度器怎么和etcd握手都绕不开亲手搭一套干净、可控、可调试的单Master集群。这不是复古情怀是技术纵深的刚需。这个标题里藏着三个关键锚点“kubeadm v1.18.2”、“单Master节点”、“服务器环境配置”。注意它没写“高可用”也没写“生产级”更没提“云厂商”说明目标非常明确最小可行闭环。不是为了扛住百万QPS而是为了让你在kubectl get nodes返回Ready那一刻心里清楚每个组件在哪个端口、用什么证书、连着哪个socket文件。我试过用v1.22一键init结果发现CoreDNS起不来查日志全是x509: certificate signed by unknown authority——回头一看原来是kubeadm自动生成的ca.crt被systemd-journald轮转策略误删了。这种细节只有从v1.18.2这个相对稳定的版本开始抠才能建立真正的肌肉记忆。你适合读这篇如果你正面临这些场景刚考完CKA想补全实操链路、正在为某IoT网关写k8s适配层需要本地沙箱、或者单纯厌倦了Docker Compose堆出来的“伪编排”。不需要你熟背RBAC规则但得知道/etc/fstab里加一行swapoff -a不是仪式感而是kubelet启动失败的头号元凶。接下来所有内容都基于一台裸金属或虚拟机推荐4C8G起步的真实操作记录命令行输出、报错截图、配置文件diff全部来自我当天重装三遍的实验环境。2. 环境准备与底层约束别让系统设置毁掉三天努力2.1 操作系统选型与内核参数硬性要求kubeadm v1.18.2 官方明确支持的Linux发行版只有Ubuntu 16.04、CentOS 7.5、RHEL 7.5、Debian 9。别碰Arch或Fedora——不是不能跑而是它们的systemd版本、cgroup管理器、iptables-nft混合模式会把你拖进无休止的kubelet.service failed with result exit-code深渊。我实测过CentOS 7.9内核3.10.0-1160和Ubuntu 20.04内核5.4.0-42前者在kubeadm init阶段更稳定后者在后续安装Calico网络插件时兼容性更好。最终建议Ubuntu 20.04 LTS原因后面细说。内核参数不是可选项是生死线。必须执行以下四条# 启用br_netfilter模块桥接网络过滤kube-proxy依赖 sudo modprobe br_netfilter echo br_netfilter | sudo tee -a /etc/modules # 开启IPv4转发否则Pod间跨Node通信直接断 sudo sysctl -w net.ipv4.ip_forward1 echo net.ipv4.ip_forward 1 | sudo tee -a /etc/sysctl.conf # 关闭swapkubelet强制要求否则init直接报错 sudo swapoff -a sudo sed -i / swap / s/^/#/ /etc/fstab # 设置iptables对bridge流量的正确处理v1.18关键 sudo sysctl -w net.bridge.bridge-nf-call-iptables1 sudo sysctl -w net.bridge.bridge-nf-call-ip6tables1 echo net.bridge.bridge-nf-call-iptables 1 | sudo tee -a /etc/sysctl.conf echo net.bridge.bridge-nf-call-ip6tables 1 | sudo tee -a /etc/sysctl.conf提示最后两条bridge-nf-call-*参数在v1.18是硬性门槛。很多教程只写modprobe br_netfilter漏掉sysctl配置结果kubeadm init卡在[preflight] Running pre-flight checks日志里反复刷[ERROR FileContent--proc-sys-net-bridge-bridge-nf-call-iptables]: /proc/sys/net/bridge/bridge-nf-call-iptables does not exist。这是因为新内核默认不加载nf_bridge模块必须显式启用。2.2 容器运行时选择Docker还是containerdv1.18.2时代Docker仍是kubeadm默认绑定的容器运行时。虽然官方文档已预告“Docker将被弃用”但此时containerd需手动配置CRI socket路径对新手极不友好。我的建议很直接用Docker CE 19.03.15v1.18.2兼容性最佳版本。别装20.x它引入的dockerd --cgroup-managersystemd默认行为会和kubelet冲突。安装步骤必须严格按顺序# 卸载旧版如果存在 sudo apt-get remove docker docker-engine docker.io containerd runc # 添加Docker官方GPG密钥和源 curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add - echo deb [archamd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable | sudo tee /etc/apt/sources.list.d/docker.list # 安装指定版本 sudo apt-get update sudo apt-get install -y docker-ce5:19.03.15~3-0~ubuntu-focal docker-ce-cli5:19.03.15~3-0~ubuntu-focal containerd.io # 配置Docker使用systemd作为cgroup驱动关键 sudo mkdir -p /etc/docker cat EOF | sudo tee /etc/docker/daemon.json { exec-opts: [native.cgroupdriversystemd], log-driver: json-file, log-opts: { max-size: 100m }, storage-driver: overlay2 } EOF # 重启Docker并设开机自启 sudo systemctl enable docker sudo systemctl daemon-reload sudo systemctl restart docker注意native.cgroupdriversystemd这行是灵魂。v1.18.2的kubelet默认cgroup驱动也是systemd如果Docker用cgroupfskubeadm init会报错[ERROR SystemVerification]: missing cgroups: pids。这个错误在Ubuntu 20.04上尤其高频因为其默认Docker包是20.10必须降级到19.03.15。2.3 主机名与网络基础配置一个字母都不能错kubeadm对主机名hostname极其敏感。它会把hostname -s的结果作为Node名称写入etcd同时用hostname -fFQDN生成API Server证书的SANSubject Alternative Name。如果FQDN解析失败kubectl客户端连不上API Server。执行以下检查# 查看当前主机名 hostname -s # 应该是短名如k8s-master hostname -f # 应该是完整域名如k8s-master.local # 如果hostname -f返回空或错误立即修复 echo 127.0.0.1 k8s-master.local k8s-master | sudo tee -a /etc/hosts sudo hostnamectl set-hostname k8s-master.local实操心得我曾因hostname -f返回localhost导致kubeadm init生成的证书里没有k8s-master.local这个SANkubectl get nodes永远报Unable to connect to the server: x509: certificate is valid for ... not k8s-master.local。修法就是删掉/etc/kubernetes/pki/下所有证书重新init并确保/etc/hosts里有正确的映射。另外关闭防火墙是底线操作# Ubuntu sudo ufw disable sudo ufw status verbose # 确认显示 inactive # CentOS/RHEL sudo systemctl stop firewalld sudo systemctl disable firewalld警告别信“只开6443端口就行”的说法。kubeadm初始化过程会动态创建大量临时端口如etcd的2379/2380、kubelet的10250ufw规则稍有疏漏就会卡在[wait-control-plane] Waiting for the kubelet to boot up the control plane。直接关掉最省心。3. kubeadm核心组件安装与版本锁定避免“看似成功实则埋雷”3.1 kubeadm/kubelet/kubectl三件套的精确安装kubeadm v1.18.2必须搭配kubelet v1.18.2和kubectl v1.18.2。版本错配是kubeadm init失败的第二大原因第一是swap没关。Ubuntu 20.04的apt源里默认是v1.20必须手动指定版本。# 添加kubernetes官方源 curl -s https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add - echo deb https://apt.kubernetes.io/ kubernetes-xenial main | sudo tee /etc/apt/sources.list.d/kubernetes.list # 更新并安装指定版本注意kubeadm和kubelet必须同版本kubectl可略高 sudo apt-get update sudo apt-get install -y kubelet1.18.2-00 kubeadm1.18.2-00 kubectl1.18.2-00 # 锁定版本防止apt upgrade误升级 sudo apt-mark hold kubelet kubeadm kubectl验证是否安装成功kubeadm version # 输出应该为: version.Info{Major:1, Minor:18, GitVersion:v1.18.2, ...} kubelet --version # 同上 kubectl version --client # 同上3.2 kubelet服务配置绕过systemd的“静默失败”kubelet在v1.18.2中默认以--cgroup-driversystemd启动但如果你的Docker没配对它会静默退出。必须手动编辑其systemd unit文件# 编辑kubelet服务配置 sudo systemctl edit kubelet # 在打开的编辑器中输入注意缩进 [Service] EnvironmentKUBELET_KUBECONFIG_ARGS--bootstrap-kubeconfig/etc/kubernetes/bootstrap-kubelet.conf --kubeconfig/etc/kubernetes/kubelet.conf EnvironmentKUBELET_CONFIG_ARGS--config/var/lib/kubelet/config.yaml EnvironmentKUBELET_KUBEADM_ARGS--container-runtimeremote --runtime-request-timeout15m --container-runtime-endpointunix:///run/containerd/containerd.sock EnvironmentKUBELET_EXTRA_ARGS--cgroup-driversystemd --fail-swap-onfalse ExecStart ExecStart/usr/bin/kubelet $KUBELET_KUBECONFIG_ARGS $KUBELET_CONFIG_ARGS $KUBELET_KUBEADM_ARGS $KUBELET_EXTRA_ARGS解释最后一行ExecStart是关键它清空了systemd默认的启动命令然后我们用带--cgroup-driversystemd的新命令覆盖。如果不加这行systemd会合并新旧命令导致参数冲突。--fail-swap-onfalse是v1.18.2新增的安全开关即使swap已关也得显式声明否则kubelet拒绝启动。启用并启动kubeletsudo systemctl daemon-reload sudo systemctl enable kubelet sudo systemctl start kubelet sudo systemctl status kubelet # 应显示active (running)但可能有Failed to run Kubelet警告——先别慌这是正常的因为还没init常见误区很多人看到systemctl status kubelet里有红色报错就以为失败了。其实只要状态是active (running)且journalctl -u kubelet -n 50 --no-pager里没有failed to load config类错误就说明kubelet进程已活只是在等kubeadm给它下发配置。3.3 初始化前的终极校验清单在敲下kubeadm init之前必须逐项确认以下10个检查点。少一个就可能多花两小时debug检查项命令期望输出失败后果1. Swap已禁用swapon --show无输出kubeadm init直接报错2. Docker运行中sudo systemctl is-active dockeractivekubelet无法拉取pause镜像3. Docker cgroup驱动docker info | grep Cgroup Driversystemdkubeadm init卡在preflight4. kubelet cgroup驱动ps aux | grep kubelet | grep systemd包含--cgroup-driversystemdNode无法注册到集群5. 主机名FQDN可解析ping -c1 $(hostname -f)64 bytes from ...API Server证书无效6. iptables legacy模式sudo update-alternatives --config iptables选择/usr/sbin/iptables-legacyCalico网络插件无法安装7. 内核模块加载lsmod | grep br_netfilterbr_netfilterkubeadm init报bridge-nf-call错误8. IPv4转发开启sysctl net.ipv4.ip_forwardnet.ipv4.ip_forward 1Pod网络不通9. 时间同步timedatectl status | grep System clock synchronizedyesetcd证书时间戳校验失败10. 主机名唯一hostname不是localhost或ubuntuetcd集群初始化失败实操心得我把这个清单做成shell脚本precheck.sh每次重装前必跑。其中第6项iptables-legacy最容易被忽略——Ubuntu 20.04默认用nftables而kubeadm v1.18.2的网络策略检查逻辑只认legacy。执行sudo update-alternatives --set iptables /usr/sbin/iptables-legacy即可切换。4. kubeadm init全流程详解从命令到证书的每一处细节4.1 初始化命令的参数深挖kubeadm init不是黑盒每个参数都直指核心问题。以下是v1.18.2最稳妥的命令sudo kubeadm init \ --kubernetes-versionv1.18.2 \ --pod-network-cidr10.244.0.0/16 \ --service-cidr10.96.0.0/12 \ --apiserver-advertise-address192.168.1.100 \ --ignore-preflight-errorsSwap逐参数解析--kubernetes-versionv1.18.2强制指定版本避免kubeadm自动拉取最新版可能已是v1.19。--pod-network-cidr10.244.0.0/16必须设置这是后续Calico/Flannel插件分配Pod IP的网段。v1.18.2不设此参数init会成功但网络插件无法工作。--service-cidr10.96.0.0/12Service ClusterIP网段默认值但显式写出更清晰。注意不能和宿主机网段冲突如你的局域网是192.168.1.0/24这里就不能设成192.168.0.0/16。--apiserver-advertise-address192.168.1.100API Server对外暴露的IP。必须是你服务器的真实内网IP不是127.0.0.1或0.0.0.0。填错会导致kubectl从其他机器连不上。--ignore-preflight-errorsSwap虽然我们已关swap但kubeadm仍会检查/proc/swaps加此参数防意外。提示--apiserver-advertise-address和--bind-address不同。后者是API Server监听的本地地址默认0.0.0.0前者是告诉其他组件“你们该连谁”。两者在单节点上通常相同。4.2 初始化过程的实时日志解读执行命令后你会看到类似这样的输出[init] Using Kubernetes version: v1.18.2 [preflight] Running pre-flight checks [WARNING IsDockerSystemdCheck]: detected cgroupfs as the Docker cgroup driver. The recommended driver is systemd. [WARNING SystemVerification]: this Docker version is not on the list of validated versions: 19.03.15. Latest validated version: 19.03.8 ... [kubelet-start] Writing kubelet environment file with flags to file /var/lib/kubelet/kubeadm-flags.env [kubelet-start] Writing kubelet configuration to file /var/lib/kubelet/config.yaml [kubelet-start] Starting the kubelet [certs] Using certificateDir folder /etc/kubernetes/pki [certs] Generating ca certificate and key [certs] Generating apiserver certificate and key [certs] apiserver serving cert is signed for DNS names [k8s-master.local kubernetes kubernetes.default kubernetes.default.svc kubernetes.default.svc.cluster.local] and IPs [10.96.0.1 192.168.1.100] ... [control-plane] Using manifest folder /etc/kubernetes/manifests [control-plane] Creating static Pod manifest for kube-apiserver [control-plane] Creating static Pod manifest for kube-controller-manager [control-plane] Creating static Pod manifest for kube-scheduler [etcd] Creating static Pod manifest for local etcd in /etc/kubernetes/manifests ... [bootstraptoken] configured RBAC rules to allow Node Bootstrap tokens to post CSRs in order for nodes to get long term certificate credentials [bootstraptoken] configured RBAC rules to allow the csrapprover controller automatically approve CSRs from a Node Bootstrap Token ... Your Kubernetes control-plane has initialized successfully!重点看三处[certs] apiserver serving cert is signed for ...确认IP列表包含你的--apiserver-advertise-address这里是192.168.1.100且DNS名包含k8s-master.local你的hostname -f。缺一不可。[control-plane] Creating static Pod manifest说明API Server、Controller Manager、Scheduler的静态Pod定义已写入/etc/kubernetes/manifests/。这些YAML文件会被kubelet自动加载是控制平面启动的源头。[etcd] Creating static Pod manifestetcd也以静态Pod方式运行数据目录在/var/lib/etcd。这是整个集群的“大脑”千万别手贱删。4.3 初始化成功后的关键操作让kubectl真正可用kubeadm init成功后终端会打印一大段提示其中最关键的是这三行mkdir -p $HOME/.kube sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config sudo chown $(id -u):$(id -g) $HOME/.kube/config必须逐行执行。admin.conf是超级管理员凭证包含base64编码的client certificate和private key。$HOME/.kube/config是kubectl的默认配置文件路径。验证是否生效kubectl get nodes # 输出应为 # NAME STATUS ROLES AGE VERSION # k8s-master.local NotReady master 20s v1.18.2NotReady是正常的因为还没有网络插件Node的NetworkReady条件为False。只要STATUS不是Unknown就说明API Server已通。4.4 证书与配置文件结构深度解析kubeadm在/etc/kubernetes/下生成的文件是理解集群的钥匙/etc/kubernetes/ ├── admin.conf # kubectl管理员配置含CA证书、client cert/key ├── controller-manager.conf # Controller Manager连接API Server的配置 ├── scheduler.conf # Scheduler连接API Server的配置 ├── kubelet.conf # kubelet连接API Server的配置含bootstrap token ├── pki/ # 所有TLS证书和私钥 │ ├── ca.crt # 根CA证书用于签发所有其他证书 │ ├── ca.key # 根CA私钥绝对保密 │ ├── apiserver.crt # API Server服务端证书含SAN列表 │ ├── apiserver.key # API Server私钥 │ ├── front-proxy-ca.crt # 前端代理CA用于Aggregated API │ └── ... └── manifests/ # 静态Pod定义API Server等控制平面组件 ├── kube-apiserver.yaml ├── kube-controller-manager.yaml ├── kube-scheduler.yaml └── etcd.yaml关键洞察pki/ca.key是整个集群的“命门”。一旦丢失所有证书作废只能重装。我习惯把它备份到离线U盘并在/etc/kubernetes/pki/下建软链接指向加密目录。另外admin.conf里的certificate-authority-data字段就是ca.crt的base64编码client-certificate-data和client-key-data同理。5. 常见问题与排查技巧实录那些让我凌晨三点改配置的坑5.1 问题速查表症状、根因、解决方案症状根因解决方案重现概率kubeadm init卡在[wait-control-plane] Waiting for the kubelet to boot up the control planeetcd静态Pod未启动通常是/var/lib/etcd目录权限错误sudo chown -R etcd:etcd /var/lib/etcd然后sudo systemctl restart kubelet★★★★☆kubectl get nodes报The connection to the server 192.168.1.100:6443 was refusedAPI Server Pod未运行检查docker ps -a | grep apiserver发现镜像拉取失败sudo kubeadm config images pull --kubernetes-version v1.18.2预拉镜像或配置国内镜像源★★★★☆kubectl get pods -A显示coredns-xxx状态为PendingCoreDNS依赖网络插件但网络插件未安装必须先安装Flannel/Calico再等CoreDNS自动调度★★★☆☆journalctl -u kubelet -n 100出现failed to run Kubelet: unable to load bootstrap kubeconfig/etc/kubernetes/bootstrap-kubelet.conf文件缺失或权限错误sudo kubeadm init phase kubeconfig kubelet --config /tmp/kubeadm-config.yaml重建★★☆☆☆kubeadm reset后重装kubeadm init报[ERROR Port-10250]: Port 10250 is in use上次kubelet残留进程占着端口sudo lsof -i :10250找到PIDsudo kill -9 PID或sudo systemctl stop kubelet sudo rm -rf /var/lib/kubelet/*★★★☆☆5.2 镜像拉取失败的终极解法国内网络环境下kubeadm init默认从k8s.gcr.io拉取镜像99%会超时。不要用--image-repository参数硬改v1.18.2对此支持不稳。正确做法是方案一推荐预拉镜像 重命名# 查看v1.18.2需要的所有镜像 kubeadm config images list --kubernetes-version v1.18.2 # 用阿里云镜像站拉取替换k8s.gcr.io为registry.cn-hangzhou.aliyuncs.com/google_containers sudo kubeadm config images pull \ --image-repository registry.cn-hangzhou.aliyuncs.com/google_containers \ --kubernetes-version v1.18.2 # 将拉取的镜像重命名为kubeadm期望的名称 docker tag registry.cn-hangzhou.aliyuncs.com/google_containers/kube-apiserver:v1.18.2 k8s.gcr.io/kube-apiserver:v1.18.2 docker tag registry.cn-hangzhou.aliyuncs.com/google_containers/kube-controller-manager:v1.18.2 k8s.gcr.io/kube-controller-manager:v1.18.2 docker tag registry.cn-hangzhou.aliyuncs.com/google_containers/kube-scheduler:v1.18.2 k8s.gcr.io/kube-scheduler:v1.18.2 docker tag registry.cn-hangzhou.aliyuncs.com/google_containers/kube-proxy:v1.18.2 k8s.gcr.io/kube-proxy:v1.18.2 docker tag registry.cn-hangzhou.aliyuncs.com/google_containers/pause:3.2 k8s.gcr.io/pause:3.2 docker tag registry.cn-hangzhou.aliyuncs.com/google_containers/etcd:3.4.3-0 k8s.gcr.io/etcd:3.4.3-0 docker tag registry.cn-hangzhou.aliyuncs.com/google_containers/coredns:1.6.7 k8s.gcr.io/coredns:1.6.7方案二备选修改kubeadm配置文件创建/tmp/kubeadm-config.yamlkind: ClusterConfiguration apiVersion: kubeadm.k8s.io/v1.18 kubernetesVersion: v1.18.2 imageRepository: registry.cn-hangzhou.aliyuncs.com/google_containers然后执行sudo kubeadm init --config /tmp/kubeadm-config.yaml实操心得方案一更可靠。我曾用方案二结果kubeadm init报unknown field imageRepository查文档才发现v1.18.2的ClusterConfiguration结构和v1.19不同。方案一虽然多敲几行但100%可控。5.3 网络插件安装前的必要准备kubeadm init成功后不要急着装Flannel先确认两个前提确认kube-proxy运行正常kubectl get pods -n kube-system | grep kube-proxy # 应显示Running状态且READY为1/1确认iptables-legacy已生效再次强调sudo update-alternatives --config iptables # 必须选中iptables-legacy sudo iptables -L -t nat | head -5 # 应看到KUBE-SERVICES等链Flannel v0.12.0是v1.18.2的最佳搭档。安装命令kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml注意kube-flannel.yml里默认的Network字段是10.244.0.0/16必须和kubeadm init --pod-network-cidr参数一致如果init时用了10.200.0.0/16就得下载YAML文件手动改。安装后等待1-2分钟再执行kubectl get nodes # 应变为 Ready kubectl get pods -n kube-system | grep flannel # 应显示Running5.4 最后的压力测试验证集群真实可用性别只满足于kubectl get nodes。做三件事验证部署一个Nginx测试Podkubectl create deployment nginx-test --imagenginx kubectl expose deployment nginx-test --port80 --typeNodePort kubectl get services # 记下NODE_PORT如31234然后curl http://192.168.1.100:31234检查CoreDNS是否健康kubectl get pods -n kube-system -l k8s-appkube-dns kubectl logs -n kube-system -l k8s-appkube-dns -c coredns | tail -5 # 应无error且有ready日志模拟Node故障可选# 手动停掉kubelet sudo systemctl stop kubelet kubectl get nodes # 状态应变为NotReady约40秒后 sudo systemctl start kubelet # 状态应恢复Ready约30秒后我的经验只要这三步全过你的单Master集群就真正立住了。后续加Node、装Dashboard、配Ingress都是水到渠成的事。记住kubeadm v1.18.2的价值不在“多快”而在“多稳”——它给你留出了看清每一步的机会。