部署的坑)
簡(jiǎn)介面向需要快速搭建Kubernetes集群的運(yùn)維與開(kāi)發(fā)人員這份下載包提供一套基于Docker容器化的K8s一鍵部署Shell腳本。腳本中預(yù)置了Docker 24.0.7、cri-dockerd 0.3.9以及K8s v1.28.2等關(guān)鍵版本信息使用者只需按實(shí)際環(huán)境修改集群節(jié)點(diǎn)規(guī)劃與軟件版本將壓縮包上傳至主節(jié)點(diǎn)和工作節(jié)點(diǎn)的家目錄再執(zhí)行一鍵安裝命令即可自動(dòng)完成整套集群環(huán)境的搭建不再需要逐一手動(dòng)部署和配置各類插件。資源共包含7個(gè)文件以三類Shell腳本為核心分別負(fù)責(zé)安裝、卸載與公共環(huán)境初始化同時(shí)附帶Kubernetes初始化所需的YAML清單、Flannel網(wǎng)絡(luò)插件配置、cri-dockerd的RPM安裝包以及簡(jiǎn)明使用說(shuō)明整體壓縮包大小為10.67MB目錄結(jié)構(gòu)清晰適合快速二次定制。目前已有952人學(xué)習(xí)下載非常適合具備一定Linux基礎(chǔ)、希望提升K8s集群部署效率的工程師用于本地測(cè)試環(huán)境或作為生產(chǎn)環(huán)境初始化基線。1. 寫一份能救命的 K8s 一鍵部署腳本別再手動(dòng)敲 kubeadm 了很多人第一次部署 K8s 集群都是這么翻車的照著教程敲 kubeadm init等兩三分鐘最后看到the api server is not healthy after 4m0.00747357s然后整個(gè)人就愣住了。這個(gè)問(wèn)題不是個(gè)例而是所有新手甚至不少熟手都會(huì)撞上的坎——報(bào)錯(cuò)信息不算友好排查鏈路又長(zhǎng)從 kubelet 日志翻到容器運(yùn)行時(shí)狀態(tài)再?gòu)?CNI 插件查到網(wǎng)絡(luò)策略沒(méi)兩三個(gè)小時(shí)根本定位不了。我給你的這份一鍵部署 shell 腳本解決的就是這個(gè)痛點(diǎn)。它把 Docker 容器化環(huán)境準(zhǔn)備、K8s 組件安裝、master 節(jié)點(diǎn)初始化和 worker 節(jié)點(diǎn)接入全部揉進(jìn)了一個(gè)腳本里你只需要改幾個(gè)變量敲一條命令等幾分鐘就能得到一個(gè)可用的集群。它的核心思路不是省那幾行命令而是把容易出錯(cuò)的操作順序固定下來(lái)把版本對(duì)齊、鏡像拉取、網(wǎng)絡(luò)插件的配置都做成參數(shù)化讓復(fù)制粘貼不再靠運(yùn)氣。適合正在學(xué) K8s 的入門者、要在內(nèi)網(wǎng)環(huán)境快速搭集群的運(yùn)維以及被各種玄學(xué)報(bào)錯(cuò)搞到頭大的開(kāi)發(fā)者。2. 容器運(yùn)行時(shí)與版本對(duì)齊為什么我這里強(qiáng)制用 Docker2.1 Docker 和 K8s 的關(guān)系比你想象中更微妙很多人分不清 Docker 和 K8s 的關(guān)系覺(jué)得既然 K8s 是管容器的那 Docker 裝了就行。實(shí)際上 K8s 通過(guò)容器運(yùn)行時(shí)接口CRI來(lái)操作容器而 Docker 本身并不直接兼容 CRI需要 dockershim 做中間層。雖然新版本 K8s 已經(jīng)默認(rèn)用 containerd 作為運(yùn)行時(shí)但在一鍵部署腳本里我仍然優(yōu)先推薦 Docker原因很現(xiàn)實(shí)Docker 的生態(tài)最成熟鏡像加速配置簡(jiǎn)單排障手段豐富尤其是當(dāng)你需要在集群里額外跑一些非 K8s 管理的容器時(shí)Docker 直接用docker ps就能看到而 containerd 的crictl命令還需要單獨(dú)配置。這份腳本里我做得最保守的一件事就是固定版本。K8s 的版本和 Docker 的版本不是隨便組合都能跑的v1.24 之前的 K8s 和 Docker 的兼容性還算穩(wěn)定v1.24 之后雖然默認(rèn)走 containerd但如果你用 Docker 作為運(yùn)行時(shí)kubelet 的啟動(dòng)參數(shù)里要顯式指定--container-runtimeremote --container-runtime-endpointunix:///var/run/dockershim.sock。腳本里我默認(rèn)寫的是 K8s 1.23.17 Docker 20.10.x 的組合這是經(jīng)過(guò)大量環(huán)境驗(yàn)證過(guò)的穩(wěn)定搭配你在生產(chǎn)環(huán)境也盡量用固定版本別追新。2.2 環(huán)境準(zhǔn)備腳本主機(jī)名、防火墻、Swap 一次性搞定先看腳本里最前面的環(huán)境初始化函數(shù)這部分解決的是部署前最容易被忽略的系統(tǒng)級(jí)配置。代碼塊如下prepare_system() { echo System Preparation # 設(shè)置主機(jī)名變量 HOSTNAME_PREFIX 需要提前定義 hostnamectl set-hostname ${HOSTNAME_PREFIX}-$(hostname -I | awk {print $1} | cut -d. -f4) # 關(guān)閉 firewall 并禁用 SELinux避免網(wǎng)絡(luò)策略干擾 systemctl stop firewalld systemctl disable firewalld setenforce 0 sed -i s/^SELINUXenforcing/SELINUXdisabled/ /etc/selinux/config # 關(guān)閉 swapK8s 強(qiáng)制要求 swap 關(guān)閉才能運(yùn)行 kubelet swapoff -a sed -i / swap / s/^/#/ /etc/fstab # 加載內(nèi)核模塊并配置 sysctl cat EOF /etc/sysctl.d/k8s.conf net.bridge.bridge-nf-call-iptables 1 net.bridge.bridge-nf-call-ip6tables 1 net.ipv4.ip_forward 1 vm.swappiness 0 EOF modprobe br_netfilter sysctl --system /dev/null 21 # 寫入 hosts 解析避免 IP 變更導(dǎo)致集群失聯(lián) cat /etc/hosts HOSTS_EOF $(hostname -I | awk {print $1}) ${HOSTNAME_PREFIX}-master HOSTS_EOF }這段代碼做了四件關(guān)鍵事。hostnamectl set-hostname根據(jù)當(dāng)前 IP 的最后一位生成主機(jī)名這樣你在一臺(tái)新機(jī)器上跑腳本時(shí)不需要手動(dòng)想名字腳本自動(dòng)按 IP 段取名比如 192.168.1.21 就會(huì)變成 node-21。關(guān)閉防火墻和 SELinux 是硬性要求雖然我不建議生產(chǎn)環(huán)境關(guān)防火墻但在集群搭建階段不關(guān)的話后續(xù) kubelet 和 api server 的通信會(huì)經(jīng)常性抽風(fēng)報(bào)錯(cuò)連你都摸不著頭腦。swap 關(guān)閉是 K8s 的死規(guī)矩kubelet 檢測(cè)到 swap 開(kāi)啟會(huì)直接拒絕啟動(dòng)。/etc/sysctl.d/k8s.conf里的參數(shù)主要是為了 bridge 網(wǎng)絡(luò)的流量能被 iptables 正確處理net.ipv4.ip_forward開(kāi)啟讓 Pod 之間的轉(zhuǎn)發(fā)生效。最后寫入/etc/hosts保證了 master 節(jié)點(diǎn)的主機(jī)解析這一步能避免后面初始化時(shí)主機(jī)名解析到 127.0.0.1 的坑——這個(gè)坑我踩過(guò)排錯(cuò)排到懷疑人生最后發(fā)現(xiàn)是 hosts 文件里沒(méi)有映射。2.3 Docker 安裝的腳本化思路檢測(cè)、安裝、加速一氣呵成Docker 安裝的腳本部分不能無(wú)腦執(zhí)行需要處理一種常見(jiàn)情況機(jī)器上已經(jīng)裝了舊版 Docker。腳本里我用了一個(gè)函數(shù)來(lái)做這件事install_docker() { # 如果已有 docker 命令先檢查版本滿足要求就跳過(guò) if command -v docker /dev/null; then DOCKER_VER$(docker --version | grep -oE [0-9]\.[0-9] | head -n1) if [[ $DOCKER_VER ~ ^(19|20)\. ]]; then echo Docker already installed: $(docker --version) return fi # 版本不匹配就卸載重裝 yum remove -y docker docker-client docker-common docker-engine 2/dev/null fi # 安裝依賴 yum install -y yum-utils device-mapper-persistent-data lvm2 # 添加 Docker 官方源 yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo # 安裝指定版本 yum install -y docker-ce-20.10.24 docker-ce-cli-20.10.24 containerd.io # 創(chuàng)建 daemon.json 并配置鏡像加速 mkdir -p /etc/docker cat /etc/docker/daemon.json EOF { exec-opts: [native.cgroupdriversystemd], log-driver: json-file, log-opts: {max-size: 100m, max-file: 3}, exec-opts: [native.cgroupdriversystemd], registry-mirrors: [https://docker.m.daocloud.io], storage-driver: overlay2 } EOF systemctl daemon-reload systemctl enable docker --now }這里有幾個(gè)值得注意的設(shè)計(jì)。版本檢測(cè)用了正則匹配抓住大版本號(hào)比如 19.x 和 20.x 都保留但如果裝的是 18.x 或者 24.x 就會(huì)走重裝流程。為什么固守 19/20 這兩個(gè)大版本因?yàn)樵?CentOS 7 和 Rocky 8 上這兩個(gè)版本配合 overlay2 存儲(chǔ)驅(qū)動(dòng)最穩(wěn)定新版 Docker 的 iptables 規(guī)則變了在 K8s 1.23 環(huán)境下偶爾會(huì)出奇奇怪的網(wǎng)絡(luò)問(wèn)題。daemon.json里的cgroupdriversystemd這個(gè)配置極其重要。Docker 默認(rèn)的 cgroup driver 是 cgroupfs但 kubelet 默認(rèn)用的是 systemd兩不一致時(shí) kubelet 會(huì)直接報(bào)錯(cuò)需要把 kubelet 改成 cgroupfs 或者統(tǒng)一成 systemd。我把這個(gè)坑提前在 Docker 配置階段就解決了后面 K8s 初始化就不會(huì)出現(xiàn)cgroup driver不匹配的問(wèn)題。鏡像加速我寫了一個(gè)通用地址你要根據(jù)自己網(wǎng)絡(luò)環(huán)境替換內(nèi)網(wǎng)環(huán)境可以留空。3. K8s 組件安裝與鏡像預(yù)拉取網(wǎng)絡(luò)問(wèn)題提前暴露3.1 yum 源、組件版本統(tǒng)一從源頭減少詭異問(wèn)題K8s 的組件安裝是集群部署的第二大坑源。官方 yum 源有時(shí)候不穩(wěn)定國(guó)內(nèi)鏡像源又參差不齊腳本里我用了一個(gè)變量來(lái)控制倉(cāng)庫(kù)地址install_k8s_components() { # 如果 yum 源變量為空默認(rèn)使用阿里云鏡像 local K8S_REPO${K8S_REPO:-https://mirrors.aliyun.com/kubernetes/yum/repos/kubernetes-el7-x86_64} cat EOF /etc/yum.repos.d/kubernetes.repo [kubernetes] nameKubernetes baseurl${K8S_REPO} enabled1 gpgcheck0 EOF yum makecache # 安裝 kubelet kubeadm kubectl版本固定不追新 yum install -y kubelet-1.23.17 kubeadm-1.23.17 kubectl-1.23.17 # kubelet 需要設(shè)置開(kāi)機(jī)自啟但先不要啟動(dòng)等 kubeadm init 完成后再啟 systemctl enable kubelet /dev/null 21 }我在這段代碼里特意用了gpgcheck0而不是像很多教程里那樣導(dǎo)入 GPG key。原因很現(xiàn)實(shí)在內(nèi)網(wǎng)或者網(wǎng)絡(luò)受限的環(huán)境GPG key 拉取失敗會(huì)導(dǎo)致整個(gè)安裝直接報(bào)錯(cuò)而且這個(gè)報(bào)錯(cuò)信息跟依賴缺失一模一樣會(huì)讓你白排查很久。關(guān)閉 GPG 檢查在集群搭建階段是可接受的因?yàn)槟阌玫氖枪潭ㄔ床皇请S便一個(gè)第三方源。版本固定寫死在這個(gè)函數(shù)里我不用變量因?yàn)閗ubelet、kubeadm、kubectl三個(gè)必須同版本任何不一致都會(huì)導(dǎo)致 token 校驗(yàn)失敗或者kubectl get nodes顯示異常。很多模板腳本喜歡把版本做成變量好處是靈活壞處是你一旦改了版本沒(méi)改全三個(gè)組件版本錯(cuò)位那排錯(cuò)體驗(yàn)非常酸爽。3.2 鏡像預(yù)拉取讓錯(cuò)誤提前暴露K8s 集群部署中 90% 的失敗都發(fā)生在鏡像拉取環(huán)節(jié)而且拉取失敗不等于整個(gè)流程立刻失敗它會(huì)在kubeadm init到一半的時(shí)候才爆出來(lái)這時(shí)候前面所有配置都生效了一半回滾非常麻煩。腳本的做法是提前用kubeadm config images list拉出鏡像清單然后逐個(gè)檢查prepull_images() { # 列出 kubeadm 需要的鏡像不帶版本號(hào)的話會(huì)輸出默認(rèn)版本 # 使用 docker 直接拉取這里用了別名的方式加速 local IMAGES$(kubeadm config images list --kubernetes-version 1.23.17) echo Prepulling Images local REGISTRY_PREFIXregistry.k8s.io # 國(guó)內(nèi)環(huán)境可以換成鏡像源例如 registry.cn-hangzhou.aliyuncs.com/google_containers for IMAGE in ${IMAGES}; do # 將 registry.k8s.io 前綴替換為加速源 local TARGET_IMAGE${IMAGE/${REGISTRY_PREFIX}/${IMAGE_MIRROR:-registry.cn-hangzhou.aliyuncs.com/google_containers}} echo Pulling: ${TARGET_IMAGE} docker pull ${TARGET_IMAGE} # 重新打 tag 為原始名稱這樣 kubeadm 能正常找到 docker tag ${TARGET_IMAGE} ${IMAGE%%:*}:${IMAGE##*:} done echo All Images Pulled }這段腳本的核心思路是把registry.k8s.io前綴的鏡像地址替換成國(guó)內(nèi)可訪問(wèn)的鏡像源拉取成功后重新打上原始 tag。因?yàn)閗ubeadm init內(nèi)部的鏡像列表是用默認(rèn)地址去本地 docker 里找的如果不打回原 tagK8s 初始化時(shí)會(huì)再次嘗試從遠(yuǎn)端拉取白費(fèi)功夫。預(yù)拉取的好處不止是提速更重要的是把網(wǎng)絡(luò)問(wèn)題提前到部署一開(kāi)始就暴露出來(lái)。如果你的環(huán)境沒(méi)有外網(wǎng)權(quán)限鏡像源不通那這一步就會(huì)直接卡住而不是等kubeadm init跑到一半才報(bào)failed to pull image。這種前置檢查的設(shè)計(jì)在以后的排障中能省掉大量時(shí)間這也是這份腳本跟很多一次性 shell 腳本最大的區(qū)別。4. kubeadm 初始化與 Worker 節(jié)點(diǎn)接入?yún)?shù)化讓復(fù)制粘貼不再出錯(cuò)4.1 Master 初始化配置文件代替一堆命令行參數(shù)kubeadm init的參數(shù)又長(zhǎng)又多直接在命令行寫容易出現(xiàn)拼寫錯(cuò)誤和版本不匹配。腳本里我推薦用配置文件的方式來(lái)做初始化配置文件里可以顯式指定 Pod 網(wǎng)段、API Server 地址和控制面端口。來(lái)看這段代碼init_master() { # 創(chuàng)建初始化配置文件用當(dāng)前 IP 替換 API Server 地址 local MASTER_IP$(hostname -I | awk {print $1}) cat /tmp/kubeadm-config.yaml EOF apiVersion: kubeadm.k8s.io/v1beta3 kind: InitConfiguration localAPIEndpoint: advertiseAddress: ${MASTER_IP} bindPort: 6443 --- apiVersion: kubeadm.k8s.io/v1beta3 kind: ClusterConfiguration kubernetesVersion: 1.23.17 controlPlaneEndpoint: ${MASTER_IP}:6443 networking: podSubnet: 10.244.0.0/16 serviceSubnet: 10.96.0.0/12 dnsDomain: cluster.local --- apiVersion: kubelet.config.k8s.io/v1beta1 kind: KubeletConfiguration cgroupDriver: systemd EOF # 執(zhí)行初始化配置文件方式比命令行參數(shù)更可控 kubeadm init --config /tmp/kubeadm-config.yaml /tmp/kubeadm-init.log 21 # 檢查是否成功失敗時(shí)輸出日志最后 30 行 if ! grep -q Your Kubernetes control-plane has initialized /tmp/kubeadm-init.log; then echo kubeadm init failed. Last 30 lines: tail -30 /tmp/kubeadm-init.log return 1 fi # 配置 kubectl 認(rèn)證文件 mkdir -p $HOME/.kube cp -i /etc/kubernetes/admin.conf $HOME/.kube/config chown $(id -u):$(id -g) $HOME/.kube/config }配置文件比命令行參數(shù)強(qiáng)在兩點(diǎn)一是你可以把配置文件留檔以后要重建集群或者加控制面節(jié)點(diǎn)直接用不用再去翻歷史命令二是InitConfiguration里顯式指定了advertiseAddress避免了多網(wǎng)卡環(huán)境下 K8s 選擇錯(cuò)誤網(wǎng)卡的問(wèn)題。很多教程直接跑kubeadm init不帶參數(shù)如果你機(jī)器上有 docker0、ens33、eth0 等多個(gè)網(wǎng)卡K8s 可能選到 docker0 的 IP導(dǎo)致 API Server 地址錯(cuò)誤后面所有節(jié)點(diǎn)都加入不了。controlPlaneEndpoint指定了集群的統(tǒng)一入口地址這個(gè)配置在生產(chǎn)環(huán)境非常有用。哪怕你只有一個(gè)控制面節(jié)點(diǎn)顯式寫上 IP 和端口也會(huì)讓后續(xù)增加高可用控制面的時(shí)候少很多改動(dòng)。Pod 網(wǎng)段我用的10.244.0.0/16這是 Flannel 網(wǎng)絡(luò)插件默認(rèn)使用的網(wǎng)段如果你后面要用 Calico請(qǐng)改成 Calico 默認(rèn)的192.168.0.0/16。這里如果不統(tǒng)一CNI 插件里的 IP 池和 K8s 劃分的網(wǎng)段對(duì)不上Pod 之間網(wǎng)絡(luò)直接不通是個(gè)很隱蔽的問(wèn)題。4.2 Worker 節(jié)點(diǎn)接入Token 傳遞與 CA 證書(shū)哈希的處理技巧Master 初始化完成后會(huì)輸出一段kubeadm join命令里面包含了 token 和 CA 證書(shū)哈希。腳本需要把這個(gè)信息保存下來(lái)方便 worker 節(jié)點(diǎn)使用。這里有個(gè)坑token 有效期是 24 小時(shí)CA 哈希在 master 重啟后可能變化所以腳本里做了一層自動(dòng)提取和校驗(yàn)save_join_info() { # 從 init 日志中提取 join 命令和 token # 如果 token 過(guò)期就重新生成 local TOKEN$(kubeadm token list | awk NR2{print $1}) if [ -z $TOKEN ] || [ $TOKEN TOKEN ]; then # 生成新的永久 token實(shí)際上最長(zhǎng)有效 24 小時(shí) TOKEN$(kubeadm token create) fi # 重新計(jì)算 CA 證書(shū)哈希避免重啟后哈希過(guò)期 local CA_HASH$(openssl x509 -pubkey -in /etc/kubernetes/pki/ca.crt | openssl rsa -pubin -outform der 2/dev/null | openssl dgst -sha256 -hex | sed s/^.* //) CA_HASHsha256:${CA_HASH} # 拼接完整的 join 命令 cat /tmp/kubeadm-join.sh EOF #!/bin/bash kubeadm join ${MASTER_IP}:6443 --token ${TOKEN} --discovery-token-ca-cert-hash ${CA_HASH} EOF chmod x /tmp/kubeadm-join.sh echo Join 命令已保存到 /tmp/kubeadm-join.sh }很多人在 worker 節(jié)點(diǎn)報(bào)錯(cuò)couldnt validate the identity of the API Server原因就是不匹配的 CA 哈希。master 的/etc/kubernetes/pki/ca.crt文件不會(huì)變但當(dāng)你復(fù)制 join 命令時(shí)可能復(fù)制錯(cuò)了哈希值或者你用的是之前舊集群的信息。腳本這里直接現(xiàn)場(chǎng)重新計(jì)算哈希永遠(yuǎn)取當(dāng)前 CA 證書(shū)的真實(shí)值徹底消除了這個(gè)隱患。token 過(guò)期是另一個(gè)常見(jiàn)坑。如果你在 master init 之后沒(méi)有立刻把 join 命令傳給 worker等第二天再執(zhí)行就已經(jīng)晚了。腳本里檢測(cè)到 token 列表為空或失效時(shí)會(huì)用kubeadm token create重新生成新 token 同樣有效 24 小時(shí)。從我實(shí)際經(jīng)驗(yàn)看這部分是腳本最實(shí)用的功能之一因?yàn)楹苌儆腥水?dāng)天就把所有 worker 節(jié)點(diǎn)都加完。4.3 CNI 插件部署Flannel 還是 Calico 的選擇網(wǎng)絡(luò)插件直接決定了 Pod 之間的通信方式腳本默認(rèn)用 Flannel因?yàn)樗С?VXLAN 模式對(duì)網(wǎng)絡(luò)環(huán)境和內(nèi)核要求低幾乎不會(huì)因?yàn)榈讓泳W(wǎng)絡(luò)限制而失敗。部署命令如下setup_cni() { echo Installing Flannel # 下載 Flannel 的 manifest 文件修改其中的網(wǎng)段為 podSubnet curl -o /tmp/kube-flannel.yml https://raw.githubusercontent.com/flannel-io/flannel/master/Documentation/kube-flannel.yml # 如果網(wǎng)段不是 10.244.0.0/16需要修改配置文件 if ! grep -q 10.244.0.0/16 /tmp/kube-flannel.yml; then sed -i s|10.244.0.0/16|10.244.0.0/16|g /tmp/kube-flannel.yml fi # 應(yīng)用 Flannel DaemonSet kubectl apply -f /tmp/kube-flannel.yml # 等待 Flannel Pod 全部運(yùn)行 echo Waiting for Flannel pods to be ready... sleep 30 kubectl get pods -n kube-flannel }Flannel 部署失敗的典型表現(xiàn)是kubectl get nodes顯示NotReadykubectl get pods -n kube-system里 Flannel Pod 顯示CrashLoopBackOff。Flannel 鏡像拉取失敗最常見(jiàn)你可以把鏡像預(yù)拉取的機(jī)制延伸到這里。如果團(tuán)隊(duì)里要用 Calico 的網(wǎng)絡(luò)策略功能直接換成kubectl apply -f https://docs.projectcalico.org/manifests/calico.yaml就行但要記住同步修改 kubeadm 初始化配置里的podSubnet。5. 避坑排查kubeadm init 報(bào)錯(cuò)與集群故障的定位路徑5.1 API Server not healthy最經(jīng)典、坑最多的報(bào)錯(cuò)現(xiàn)象執(zhí)行kubeadm init之后等 4 分鐘左右報(bào)錯(cuò)the api server is not healthy after 4m0.00747357s查看systemctl status kubelet顯示 kubelet 一直在重啟journalctl -u kubelet循環(huán)輸出連接 refused。原因這個(gè)報(bào)錯(cuò)背后可能有四種情況。第一是 kubelet 的 cgroup driver 和 Docker 不一致第二是鏡像沒(méi)有預(yù)拉取初始化過(guò)程中拉鏡像超時(shí)第三是 API Server 的 advertiseAddress 配置了不可達(dá) IP導(dǎo)致健康檢查失敗第四是swap沒(méi)有關(guān)閉kubelet 啟動(dòng)時(shí)直接退出。解決第一步檢查 Docker 的 cgroup driver 是否 systemd確認(rèn)無(wú)誤后查看kubelet日志定位更具體的錯(cuò)誤。如果日志顯示node xxx not found那是因?yàn)?API Server 還沒(méi)起來(lái)kubelet 無(wú)法注冊(cè)等一等就行如果是連接 refused那說(shuō)明 API Server 進(jìn)程根本沒(méi)拉起檢查docker ps -a | grep apiserver如果容器處于 Exit 狀態(tài)用docker logs查看容器輸出。我這邊的經(jīng)驗(yàn)是90% 的 API Server not healthy 都指向鏡像拉取失敗而不是真正的配置問(wèn)題。5.2 Worker 節(jié)點(diǎn)狀態(tài) NotReadyFlannel 鏡像導(dǎo)致的連鎖反應(yīng)現(xiàn)象master 節(jié)點(diǎn)正常kubectl get nodes顯示 worker 節(jié)點(diǎn)已經(jīng)注冊(cè)但狀態(tài)一直是NotReadykubectl describe node顯示kubelet is posting ready status但底下還有一條runtime network not ready的錯(cuò)誤。原因worker 節(jié)點(diǎn)加入集群后kubelet 會(huì)嘗試啟動(dòng) CNI 插件容器這里需要拉取 Flannel 或 Calico 的鏡像。如果 worker 節(jié)點(diǎn)沒(méi)有預(yù)先拉取這些鏡像它會(huì)臨時(shí)拉取一旦網(wǎng)絡(luò)慢或者鏡像源不可用CNI 插件一直起不來(lái)kubelet 就無(wú)法上報(bào) Ready 狀態(tài)。解決在 worker 節(jié)點(diǎn)上手動(dòng)執(zhí)行kubectl get pods -n kube-system -o wide查看 Flannel Pod 是否在該節(jié)點(diǎn)上然后執(zhí)行docker pull手動(dòng)拉取對(duì)應(yīng)鏡像。另一種做法是在腳本的 worker 部署函數(shù)里加上鏡像預(yù)拉取邏輯把 Flannel 的鏡像提前用ctr或docker pull拉好。這個(gè)問(wèn)題我踩了不止一次每次都是因?yàn)橹型緭Q了網(wǎng)絡(luò)環(huán)境才發(fā)現(xiàn)的。5.3 /etc/hosts 配置缺失master 節(jié)點(diǎn)名稱解析回環(huán)現(xiàn)象初始化過(guò)程中報(bào)failed to set up init node: unable to resolve hostname或者kubelet日志里頻繁出現(xiàn)Failed to get node info。原因/etc/hosts里沒(méi)有把 master 的 IP 和主機(jī)名映射起來(lái)K8s 的很多組件直接使用主機(jī)名進(jìn)行通信解析不到正確 IP 時(shí)就會(huì)退回到 127.0.0.1導(dǎo)致所有跨節(jié)點(diǎn)通信都失敗。解決按前面腳本里的方法在初始化前就把 hostname 和 IP 寫入 hosts 文件。這個(gè)坑很隱蔽的原因是系統(tǒng)層面可能不報(bào)錯(cuò)只有 K8s 內(nèi)部組件會(huì)默默出錯(cuò)表現(xiàn)出來(lái)就是節(jié)點(diǎn)狀態(tài)異常但所有服務(wù)看著都活著。如果你發(fā)現(xiàn)集群狀態(tài)不穩(wěn)定且查不到明確錯(cuò)誤先檢查 hosts 文件這是第一步。5.4 Docker 重啟導(dǎo)致 K8s 服務(wù)異?，F(xiàn)象集群跑了幾天后某個(gè)節(jié)點(diǎn)上kubectl get nodes顯示該節(jié)點(diǎn)NotReady但systemctl status kubelet又是 active 狀態(tài)docker ps看到所有容器都不在了。原因Docker 服務(wù)被重啟后容器重新拉起但容器的 IP 地址變了kubelet 的端口映射和容器 ID 都沒(méi)有同步導(dǎo)致 Kubelet 和 API Server 之間的連接失效。也可能是 Docker 的 cgroup driver 配置被意外改動(dòng)導(dǎo)致 kubelet 無(wú)法訪問(wèn)容器的 cgroup 信息。解決重啟 Docker 后一定要重新啟動(dòng) kubelet并檢查 kubelet 的--cgroup-driver參數(shù)是否與 Docker 一致。更保險(xiǎn)的做法是修改 docker.service 的啟動(dòng)命令加入--live-restore參數(shù)讓 Docker 在自身重啟時(shí)保持容器不停止。這個(gè)參數(shù)在部署時(shí)就寫好避免后續(xù)運(yùn)維中誤重啟 Docker 導(dǎo)致連鎖故障。我后來(lái)在腳本里統(tǒng)一加上了這個(gè)參數(shù)從那以后再也沒(méi)有因?yàn)?Docker 重啟引發(fā)集群?jiǎn)栴}。6. 集群驗(yàn)證與生產(chǎn)環(huán)境的一個(gè)關(guān)鍵小習(xí)慣集群部署完成后不能直接當(dāng)黑匣子用先跑一遍驗(yàn)證流程確認(rèn)核心組件都在正常工作。我的習(xí)慣是三步檢查節(jié)點(diǎn)狀態(tài)、核心 Pod 狀態(tài)、一個(gè)測(cè)試應(yīng)用。用一個(gè)快速命令清單來(lái)執(zhí)行# 第一步節(jié)點(diǎn)必須全部 Ready kubectl get nodes # 第二步核心組件必須 Running kubectl get pods -n kube-system # 第三步跑一個(gè)測(cè)試 Pod 驗(yàn)證調(diào)度和網(wǎng)絡(luò) kubectl run test-nginx --imagenginx --restartNever --port80 kubectl wait --forconditionReady pod/test-nginx --timeout60s kubectl expose pod test-nginx --typeNodePort --port80 --nametest-svc # 拿到端口號(hào)后從集群外訪問(wèn) master_IP:NodePort確認(rèn)返回 200驗(yàn)證通過(guò)后我建議立刻給集群安裝 Kubernetes Dashboard這不是炫技而是生產(chǎn)環(huán)境管理集群的基本能力。Dashboard 可以直接在 Web 上查看節(jié)點(diǎn)狀態(tài)、Pod 日志和應(yīng)用拓?fù)浔让钚兄庇^太多。安裝命令很簡(jiǎn)單# 安裝最新版 Dashboard kubectl apply -f https://raw.githubusercontent.com/kubernetes/dashboard/v2.7.0/aio/deploy/recommended.yaml # 創(chuàng)建管理員賬號(hào)并獲取 token kubectl create serviceaccount admin-user -n kubernetes-dashboard kubectl create clusterrolebinding admin-user --clusterrolecluster-admin --serviceaccountkubernetes-dashboard:admin-user kubectl get secret -n kubernetes-dashboard $(kubectl get serviceaccount admin-user -n kubernetes-dashboard -o jsonpath{.secrets[0].name}) -o jsonpath{$.data.token} | base64 -d在生產(chǎn)環(huán)境里我最在意的一個(gè)習(xí)慣是永遠(yuǎn)不要把kubeadm-join.sh這個(gè)臨時(shí)文件留在/tmp 下不管。token 雖然 24 小時(shí)就過(guò)期但如果泄露給不該看到的人攻擊者可以在有效期內(nèi)把節(jié)點(diǎn)加入你的集群。從那以后我每次部署完都強(qiáng)制走一遍rm -f /tmp/kubeadm-join.sh同時(shí)用kubeadm token delete把已用過(guò)的 token 清掉。這個(gè)動(dòng)作已經(jīng)變成腳本末尾的固定步驟了希望你也能養(yǎng)成這個(gè)習(xí)慣。這份一鍵部署腳本的思路是把常見(jiàn)踩坑都前置于部署階段解決而不是等報(bào)錯(cuò)了再排查。Docker 版本固定、cgroup driver 統(tǒng)一、鏡像提前預(yù)拉取、join 信息自動(dòng)提取這四個(gè)維度基本涵蓋了新手部署時(shí)遇到的大部分問(wèn)題。希望幫到你后續(xù)遇到集群故障時(shí)先按這幾步檢查一遍能省下不少時(shí)間。本文還有配套的精品資源點(diǎn)擊獲取 K8s一鍵部署腳本：告別kubeadm手動(dòng)部署的坑
簡(jiǎn)介面向需要快速搭建Kubernetes集群的運(yùn)維與開(kāi)發(fā)人員這份下載包提供一套基于Docker容器化的K8s一鍵部署Shell腳本。腳本中預(yù)置了Docker 24.0.7、cri-dockerd 0.3.9以及K8s v1.28.2等關(guān)鍵版本信息使用者只需按實(shí)際環(huán)境修改集群節(jié)點(diǎn)規(guī)劃與軟件版本將壓縮包上傳至主節(jié)點(diǎn)和工作節(jié)點(diǎn)的家目錄再執(zhí)行一鍵安裝命令即可自動(dòng)完成整套集群環(huán)境的搭建不再需要逐一手動(dòng)部署和配置各類插件。資源共包含7個(gè)文件以三類Shell腳本為核心分別負(fù)責(zé)安裝、卸載與公共環(huán)境初始化同時(shí)附帶Kubernetes初始化所需的YAML清單、Flannel網(wǎng)絡(luò)插件配置、cri-dockerd的RPM安裝包以及簡(jiǎn)明使用說(shuō)明整體壓縮包大小為10.67MB目錄結(jié)構(gòu)清晰適合快速二次定制。目前已有952人學(xué)習(xí)下載非常適合具備一定Linux基礎(chǔ)、希望提升K8s集群部署效率的工程師用于本地測(cè)試環(huán)境或作為生產(chǎn)環(huán)境初始化基線。1. 寫一份能救命的 K8s 一鍵部署腳本別再手動(dòng)敲 kubeadm 了很多人第一次部署 K8s 集群都是這么翻車的照著教程敲 kubeadm init等兩三分鐘最后看到the api server is not healthy after 4m0.00747357s然后整個(gè)人就愣住了。這個(gè)問(wèn)題不是個(gè)例而是所有新手甚至不少熟手都會(huì)撞上的坎——報(bào)錯(cuò)信息不算友好排查鏈路又長(zhǎng)從 kubelet 日志翻到容器運(yùn)行時(shí)狀態(tài)再?gòu)?CNI 插件查到網(wǎng)絡(luò)策略沒(méi)兩三個(gè)小時(shí)根本定位不了。我給你的這份一鍵部署 shell 腳本解決的就是這個(gè)痛點(diǎn)。它把 Docker 容器化環(huán)境準(zhǔn)備、K8s 組件安裝、master 節(jié)點(diǎn)初始化和 worker 節(jié)點(diǎn)接入全部揉進(jìn)了一個(gè)腳本里你只需要改幾個(gè)變量敲一條命令等幾分鐘就能得到一個(gè)可用的集群。它的核心思路不是省那幾行命令而是把容易出錯(cuò)的操作順序固定下來(lái)把版本對(duì)齊、鏡像拉取、網(wǎng)絡(luò)插件的配置都做成參數(shù)化讓復(fù)制粘貼不再靠運(yùn)氣。適合正在學(xué) K8s 的入門者、要在內(nèi)網(wǎng)環(huán)境快速搭集群的運(yùn)維以及被各種玄學(xué)報(bào)錯(cuò)搞到頭大的開(kāi)發(fā)者。2. 容器運(yùn)行時(shí)與版本對(duì)齊為什么我這里強(qiáng)制用 Docker2.1 Docker 和 K8s 的關(guān)系比你想象中更微妙很多人分不清 Docker 和 K8s 的關(guān)系覺(jué)得既然 K8s 是管容器的那 Docker 裝了就行。實(shí)際上 K8s 通過(guò)容器運(yùn)行時(shí)接口CRI來(lái)操作容器而 Docker 本身并不直接兼容 CRI需要 dockershim 做中間層。雖然新版本 K8s 已經(jīng)默認(rèn)用 containerd 作為運(yùn)行時(shí)但在一鍵部署腳本里我仍然優(yōu)先推薦 Docker原因很現(xiàn)實(shí)Docker 的生態(tài)最成熟鏡像加速配置簡(jiǎn)單排障手段豐富尤其是當(dāng)你需要在集群里額外跑一些非 K8s 管理的容器時(shí)Docker 直接用docker ps就能看到而 containerd 的crictl命令還需要單獨(dú)配置。這份腳本里我做得最保守的一件事就是固定版本。K8s 的版本和 Docker 的版本不是隨便組合都能跑的v1.24 之前的 K8s 和 Docker 的兼容性還算穩(wěn)定v1.24 之后雖然默認(rèn)走 containerd但如果你用 Docker 作為運(yùn)行時(shí)kubelet 的啟動(dòng)參數(shù)里要顯式指定--container-runtimeremote --container-runtime-endpointunix:///var/run/dockershim.sock。腳本里我默認(rèn)寫的是 K8s 1.23.17 Docker 20.10.x 的組合這是經(jīng)過(guò)大量環(huán)境驗(yàn)證過(guò)的穩(wěn)定搭配你在生產(chǎn)環(huán)境也盡量用固定版本別追新。2.2 環(huán)境準(zhǔn)備腳本主機(jī)名、防火墻、Swap 一次性搞定先看腳本里最前面的環(huán)境初始化函數(shù)這部分解決的是部署前最容易被忽略的系統(tǒng)級(jí)配置。代碼塊如下prepare_system() { echo System Preparation # 設(shè)置主機(jī)名變量 HOSTNAME_PREFIX 需要提前定義 hostnamectl set-hostname ${HOSTNAME_PREFIX}-$(hostname -I | awk {print $1} | cut -d. -f4) # 關(guān)閉 firewall 并禁用 SELinux避免網(wǎng)絡(luò)策略干擾 systemctl stop firewalld systemctl disable firewalld setenforce 0 sed -i s/^SELINUXenforcing/SELINUXdisabled/ /etc/selinux/config # 關(guān)閉 swapK8s 強(qiáng)制要求 swap 關(guān)閉才能運(yùn)行 kubelet swapoff -a sed -i / swap / s/^/#/ /etc/fstab # 加載內(nèi)核模塊并配置 sysctl cat EOF /etc/sysctl.d/k8s.conf net.bridge.bridge-nf-call-iptables 1 net.bridge.bridge-nf-call-ip6tables 1 net.ipv4.ip_forward 1 vm.swappiness 0 EOF modprobe br_netfilter sysctl --system /dev/null 21 # 寫入 hosts 解析避免 IP 變更導(dǎo)致集群失聯(lián) cat /etc/hosts HOSTS_EOF $(hostname -I | awk {print $1}) ${HOSTNAME_PREFIX}-master HOSTS_EOF }這段代碼做了四件關(guān)鍵事。hostnamectl set-hostname根據(jù)當(dāng)前 IP 的最后一位生成主機(jī)名這樣你在一臺(tái)新機(jī)器上跑腳本時(shí)不需要手動(dòng)想名字腳本自動(dòng)按 IP 段取名比如 192.168.1.21 就會(huì)變成 node-21。關(guān)閉防火墻和 SELinux 是硬性要求雖然我不建議生產(chǎn)環(huán)境關(guān)防火墻但在集群搭建階段不關(guān)的話后續(xù) kubelet 和 api server 的通信會(huì)經(jīng)常性抽風(fēng)報(bào)錯(cuò)連你都摸不著頭腦。swap 關(guān)閉是 K8s 的死規(guī)矩kubelet 檢測(cè)到 swap 開(kāi)啟會(huì)直接拒絕啟動(dòng)。/etc/sysctl.d/k8s.conf里的參數(shù)主要是為了 bridge 網(wǎng)絡(luò)的流量能被 iptables 正確處理net.ipv4.ip_forward開(kāi)啟讓 Pod 之間的轉(zhuǎn)發(fā)生效。最后寫入/etc/hosts保證了 master 節(jié)點(diǎn)的主機(jī)解析這一步能避免后面初始化時(shí)主機(jī)名解析到 127.0.0.1 的坑——這個(gè)坑我踩過(guò)排錯(cuò)排到懷疑人生最后發(fā)現(xiàn)是 hosts 文件里沒(méi)有映射。2.3 Docker 安裝的腳本化思路檢測(cè)、安裝、加速一氣呵成Docker 安裝的腳本部分不能無(wú)腦執(zhí)行需要處理一種常見(jiàn)情況機(jī)器上已經(jīng)裝了舊版 Docker。腳本里我用了一個(gè)函數(shù)來(lái)做這件事install_docker() { # 如果已有 docker 命令先檢查版本滿足要求就跳過(guò) if command -v docker /dev/null; then DOCKER_VER$(docker --version | grep -oE [0-9]\.[0-9] | head -n1) if [[ $DOCKER_VER ~ ^(19|20)\. ]]; then echo Docker already installed: $(docker --version) return fi # 版本不匹配就卸載重裝 yum remove -y docker docker-client docker-common docker-engine 2/dev/null fi # 安裝依賴 yum install -y yum-utils device-mapper-persistent-data lvm2 # 添加 Docker 官方源 yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo # 安裝指定版本 yum install -y docker-ce-20.10.24 docker-ce-cli-20.10.24 containerd.io # 創(chuàng)建 daemon.json 并配置鏡像加速 mkdir -p /etc/docker cat /etc/docker/daemon.json EOF { exec-opts: [native.cgroupdriversystemd], log-driver: json-file, log-opts: {max-size: 100m, max-file: 3}, exec-opts: [native.cgroupdriversystemd], registry-mirrors: [https://docker.m.daocloud.io], storage-driver: overlay2 } EOF systemctl daemon-reload systemctl enable docker --now }這里有幾個(gè)值得注意的設(shè)計(jì)。版本檢測(cè)用了正則匹配抓住大版本號(hào)比如 19.x 和 20.x 都保留但如果裝的是 18.x 或者 24.x 就會(huì)走重裝流程。為什么固守 19/20 這兩個(gè)大版本因?yàn)樵?CentOS 7 和 Rocky 8 上這兩個(gè)版本配合 overlay2 存儲(chǔ)驅(qū)動(dòng)最穩(wěn)定新版 Docker 的 iptables 規(guī)則變了在 K8s 1.23 環(huán)境下偶爾會(huì)出奇奇怪的網(wǎng)絡(luò)問(wèn)題。daemon.json里的cgroupdriversystemd這個(gè)配置極其重要。Docker 默認(rèn)的 cgroup driver 是 cgroupfs但 kubelet 默認(rèn)用的是 systemd兩不一致時(shí) kubelet 會(huì)直接報(bào)錯(cuò)需要把 kubelet 改成 cgroupfs 或者統(tǒng)一成 systemd。我把這個(gè)坑提前在 Docker 配置階段就解決了后面 K8s 初始化就不會(huì)出現(xiàn)cgroup driver不匹配的問(wèn)題。鏡像加速我寫了一個(gè)通用地址你要根據(jù)自己網(wǎng)絡(luò)環(huán)境替換內(nèi)網(wǎng)環(huán)境可以留空。3. K8s 組件安裝與鏡像預(yù)拉取網(wǎng)絡(luò)問(wèn)題提前暴露3.1 yum 源、組件版本統(tǒng)一從源頭減少詭異問(wèn)題K8s 的組件安裝是集群部署的第二大坑源。官方 yum 源有時(shí)候不穩(wěn)定國(guó)內(nèi)鏡像源又參差不齊腳本里我用了一個(gè)變量來(lái)控制倉(cāng)庫(kù)地址install_k8s_components() { # 如果 yum 源變量為空默認(rèn)使用阿里云鏡像 local K8S_REPO${K8S_REPO:-https://mirrors.aliyun.com/kubernetes/yum/repos/kubernetes-el7-x86_64} cat EOF /etc/yum.repos.d/kubernetes.repo [kubernetes] nameKubernetes baseurl${K8S_REPO} enabled1 gpgcheck0 EOF yum makecache # 安裝 kubelet kubeadm kubectl版本固定不追新 yum install -y kubelet-1.23.17 kubeadm-1.23.17 kubectl-1.23.17 # kubelet 需要設(shè)置開(kāi)機(jī)自啟但先不要啟動(dòng)等 kubeadm init 完成后再啟 systemctl enable kubelet /dev/null 21 }我在這段代碼里特意用了gpgcheck0而不是像很多教程里那樣導(dǎo)入 GPG key。原因很現(xiàn)實(shí)在內(nèi)網(wǎng)或者網(wǎng)絡(luò)受限的環(huán)境GPG key 拉取失敗會(huì)導(dǎo)致整個(gè)安裝直接報(bào)錯(cuò)而且這個(gè)報(bào)錯(cuò)信息跟依賴缺失一模一樣會(huì)讓你白排查很久。關(guān)閉 GPG 檢查在集群搭建階段是可接受的因?yàn)槟阌玫氖枪潭ㄔ床皇请S便一個(gè)第三方源。版本固定寫死在這個(gè)函數(shù)里我不用變量因?yàn)閗ubelet、kubeadm、kubectl三個(gè)必須同版本任何不一致都會(huì)導(dǎo)致 token 校驗(yàn)失敗或者kubectl get nodes顯示異常。很多模板腳本喜歡把版本做成變量好處是靈活壞處是你一旦改了版本沒(méi)改全三個(gè)組件版本錯(cuò)位那排錯(cuò)體驗(yàn)非常酸爽。3.2 鏡像預(yù)拉取讓錯(cuò)誤提前暴露K8s 集群部署中 90% 的失敗都發(fā)生在鏡像拉取環(huán)節(jié)而且拉取失敗不等于整個(gè)流程立刻失敗它會(huì)在kubeadm init到一半的時(shí)候才爆出來(lái)這時(shí)候前面所有配置都生效了一半回滾非常麻煩。腳本的做法是提前用kubeadm config images list拉出鏡像清單然后逐個(gè)檢查prepull_images() { # 列出 kubeadm 需要的鏡像不帶版本號(hào)的話會(huì)輸出默認(rèn)版本 # 使用 docker 直接拉取這里用了別名的方式加速 local IMAGES$(kubeadm config images list --kubernetes-version 1.23.17) echo Prepulling Images local REGISTRY_PREFIXregistry.k8s.io # 國(guó)內(nèi)環(huán)境可以換成鏡像源例如 registry.cn-hangzhou.aliyuncs.com/google_containers for IMAGE in ${IMAGES}; do # 將 registry.k8s.io 前綴替換為加速源 local TARGET_IMAGE${IMAGE/${REGISTRY_PREFIX}/${IMAGE_MIRROR:-registry.cn-hangzhou.aliyuncs.com/google_containers}} echo Pulling: ${TARGET_IMAGE} docker pull ${TARGET_IMAGE} # 重新打 tag 為原始名稱這樣 kubeadm 能正常找到 docker tag ${TARGET_IMAGE} ${IMAGE%%:*}:${IMAGE##*:} done echo All Images Pulled }這段腳本的核心思路是把registry.k8s.io前綴的鏡像地址替換成國(guó)內(nèi)可訪問(wèn)的鏡像源拉取成功后重新打上原始 tag。因?yàn)閗ubeadm init內(nèi)部的鏡像列表是用默認(rèn)地址去本地 docker 里找的如果不打回原 tagK8s 初始化時(shí)會(huì)再次嘗試從遠(yuǎn)端拉取白費(fèi)功夫。預(yù)拉取的好處不止是提速更重要的是把網(wǎng)絡(luò)問(wèn)題提前到部署一開(kāi)始就暴露出來(lái)。如果你的環(huán)境沒(méi)有外網(wǎng)權(quán)限鏡像源不通那這一步就會(huì)直接卡住而不是等kubeadm init跑到一半才報(bào)failed to pull image。這種前置檢查的設(shè)計(jì)在以后的排障中能省掉大量時(shí)間這也是這份腳本跟很多一次性 shell 腳本最大的區(qū)別。4. kubeadm 初始化與 Worker 節(jié)點(diǎn)接入?yún)?shù)化讓復(fù)制粘貼不再出錯(cuò)4.1 Master 初始化配置文件代替一堆命令行參數(shù)kubeadm init的參數(shù)又長(zhǎng)又多直接在命令行寫容易出現(xiàn)拼寫錯(cuò)誤和版本不匹配。腳本里我推薦用配置文件的方式來(lái)做初始化配置文件里可以顯式指定 Pod 網(wǎng)段、API Server 地址和控制面端口。來(lái)看這段代碼init_master() { # 創(chuàng)建初始化配置文件用當(dāng)前 IP 替換 API Server 地址 local MASTER_IP$(hostname -I | awk {print $1}) cat /tmp/kubeadm-config.yaml EOF apiVersion: kubeadm.k8s.io/v1beta3 kind: InitConfiguration localAPIEndpoint: advertiseAddress: ${MASTER_IP} bindPort: 6443 --- apiVersion: kubeadm.k8s.io/v1beta3 kind: ClusterConfiguration kubernetesVersion: 1.23.17 controlPlaneEndpoint: ${MASTER_IP}:6443 networking: podSubnet: 10.244.0.0/16 serviceSubnet: 10.96.0.0/12 dnsDomain: cluster.local --- apiVersion: kubelet.config.k8s.io/v1beta1 kind: KubeletConfiguration cgroupDriver: systemd EOF # 執(zhí)行初始化配置文件方式比命令行參數(shù)更可控 kubeadm init --config /tmp/kubeadm-config.yaml /tmp/kubeadm-init.log 21 # 檢查是否成功失敗時(shí)輸出日志最后 30 行 if ! grep -q Your Kubernetes control-plane has initialized /tmp/kubeadm-init.log; then echo kubeadm init failed. Last 30 lines: tail -30 /tmp/kubeadm-init.log return 1 fi # 配置 kubectl 認(rèn)證文件 mkdir -p $HOME/.kube cp -i /etc/kubernetes/admin.conf $HOME/.kube/config chown $(id -u):$(id -g) $HOME/.kube/config }配置文件比命令行參數(shù)強(qiáng)在兩點(diǎn)一是你可以把配置文件留檔以后要重建集群或者加控制面節(jié)點(diǎn)直接用不用再去翻歷史命令二是InitConfiguration里顯式指定了advertiseAddress避免了多網(wǎng)卡環(huán)境下 K8s 選擇錯(cuò)誤網(wǎng)卡的問(wèn)題。很多教程直接跑kubeadm init不帶參數(shù)如果你機(jī)器上有 docker0、ens33、eth0 等多個(gè)網(wǎng)卡K8s 可能選到 docker0 的 IP導(dǎo)致 API Server 地址錯(cuò)誤后面所有節(jié)點(diǎn)都加入不了。controlPlaneEndpoint指定了集群的統(tǒng)一入口地址這個(gè)配置在生產(chǎn)環(huán)境非常有用。哪怕你只有一個(gè)控制面節(jié)點(diǎn)顯式寫上 IP 和端口也會(huì)讓后續(xù)增加高可用控制面的時(shí)候少很多改動(dòng)。Pod 網(wǎng)段我用的10.244.0.0/16這是 Flannel 網(wǎng)絡(luò)插件默認(rèn)使用的網(wǎng)段如果你后面要用 Calico請(qǐng)改成 Calico 默認(rèn)的192.168.0.0/16。這里如果不統(tǒng)一CNI 插件里的 IP 池和 K8s 劃分的網(wǎng)段對(duì)不上Pod 之間網(wǎng)絡(luò)直接不通是個(gè)很隱蔽的問(wèn)題。4.2 Worker 節(jié)點(diǎn)接入Token 傳遞與 CA 證書(shū)哈希的處理技巧Master 初始化完成后會(huì)輸出一段kubeadm join命令里面包含了 token 和 CA 證書(shū)哈希。腳本需要把這個(gè)信息保存下來(lái)方便 worker 節(jié)點(diǎn)使用。這里有個(gè)坑token 有效期是 24 小時(shí)CA 哈希在 master 重啟后可能變化所以腳本里做了一層自動(dòng)提取和校驗(yàn)save_join_info() { # 從 init 日志中提取 join 命令和 token # 如果 token 過(guò)期就重新生成 local TOKEN$(kubeadm token list | awk NR2{print $1}) if [ -z $TOKEN ] || [ $TOKEN TOKEN ]; then # 生成新的永久 token實(shí)際上最長(zhǎng)有效 24 小時(shí) TOKEN$(kubeadm token create) fi # 重新計(jì)算 CA 證書(shū)哈希避免重啟后哈希過(guò)期 local CA_HASH$(openssl x509 -pubkey -in /etc/kubernetes/pki/ca.crt | openssl rsa -pubin -outform der 2/dev/null | openssl dgst -sha256 -hex | sed s/^.* //) CA_HASHsha256:${CA_HASH} # 拼接完整的 join 命令 cat /tmp/kubeadm-join.sh EOF #!/bin/bash kubeadm join ${MASTER_IP}:6443 --token ${TOKEN} --discovery-token-ca-cert-hash ${CA_HASH} EOF chmod x /tmp/kubeadm-join.sh echo Join 命令已保存到 /tmp/kubeadm-join.sh }很多人在 worker 節(jié)點(diǎn)報(bào)錯(cuò)couldnt validate the identity of the API Server原因就是不匹配的 CA 哈希。master 的/etc/kubernetes/pki/ca.crt文件不會(huì)變但當(dāng)你復(fù)制 join 命令時(shí)可能復(fù)制錯(cuò)了哈希值或者你用的是之前舊集群的信息。腳本這里直接現(xiàn)場(chǎng)重新計(jì)算哈希永遠(yuǎn)取當(dāng)前 CA 證書(shū)的真實(shí)值徹底消除了這個(gè)隱患。token 過(guò)期是另一個(gè)常見(jiàn)坑。如果你在 master init 之后沒(méi)有立刻把 join 命令傳給 worker等第二天再執(zhí)行就已經(jīng)晚了。腳本里檢測(cè)到 token 列表為空或失效時(shí)會(huì)用kubeadm token create重新生成新 token 同樣有效 24 小時(shí)。從我實(shí)際經(jīng)驗(yàn)看這部分是腳本最實(shí)用的功能之一因?yàn)楹苌儆腥水?dāng)天就把所有 worker 節(jié)點(diǎn)都加完。4.3 CNI 插件部署Flannel 還是 Calico 的選擇網(wǎng)絡(luò)插件直接決定了 Pod 之間的通信方式腳本默認(rèn)用 Flannel因?yàn)樗С?VXLAN 模式對(duì)網(wǎng)絡(luò)環(huán)境和內(nèi)核要求低幾乎不會(huì)因?yàn)榈讓泳W(wǎng)絡(luò)限制而失敗。部署命令如下setup_cni() { echo Installing Flannel # 下載 Flannel 的 manifest 文件修改其中的網(wǎng)段為 podSubnet curl -o /tmp/kube-flannel.yml https://raw.githubusercontent.com/flannel-io/flannel/master/Documentation/kube-flannel.yml # 如果網(wǎng)段不是 10.244.0.0/16需要修改配置文件 if ! grep -q 10.244.0.0/16 /tmp/kube-flannel.yml; then sed -i s|10.244.0.0/16|10.244.0.0/16|g /tmp/kube-flannel.yml fi # 應(yīng)用 Flannel DaemonSet kubectl apply -f /tmp/kube-flannel.yml # 等待 Flannel Pod 全部運(yùn)行 echo Waiting for Flannel pods to be ready... sleep 30 kubectl get pods -n kube-flannel }Flannel 部署失敗的典型表現(xiàn)是kubectl get nodes顯示NotReadykubectl get pods -n kube-system里 Flannel Pod 顯示CrashLoopBackOff。Flannel 鏡像拉取失敗最常見(jiàn)你可以把鏡像預(yù)拉取的機(jī)制延伸到這里。如果團(tuán)隊(duì)里要用 Calico 的網(wǎng)絡(luò)策略功能直接換成kubectl apply -f https://docs.projectcalico.org/manifests/calico.yaml就行但要記住同步修改 kubeadm 初始化配置里的podSubnet。5. 避坑排查kubeadm init 報(bào)錯(cuò)與集群故障的定位路徑5.1 API Server not healthy最經(jīng)典、坑最多的報(bào)錯(cuò)現(xiàn)象執(zhí)行kubeadm init之后等 4 分鐘左右報(bào)錯(cuò)the api server is not healthy after 4m0.00747357s查看systemctl status kubelet顯示 kubelet 一直在重啟journalctl -u kubelet循環(huán)輸出連接 refused。原因這個(gè)報(bào)錯(cuò)背后可能有四種情況。第一是 kubelet 的 cgroup driver 和 Docker 不一致第二是鏡像沒(méi)有預(yù)拉取初始化過(guò)程中拉鏡像超時(shí)第三是 API Server 的 advertiseAddress 配置了不可達(dá) IP導(dǎo)致健康檢查失敗第四是swap沒(méi)有關(guān)閉kubelet 啟動(dòng)時(shí)直接退出。解決第一步檢查 Docker 的 cgroup driver 是否 systemd確認(rèn)無(wú)誤后查看kubelet日志定位更具體的錯(cuò)誤。如果日志顯示node xxx not found那是因?yàn)?API Server 還沒(méi)起來(lái)kubelet 無(wú)法注冊(cè)等一等就行如果是連接 refused那說(shuō)明 API Server 進(jìn)程根本沒(méi)拉起檢查docker ps -a | grep apiserver如果容器處于 Exit 狀態(tài)用docker logs查看容器輸出。我這邊的經(jīng)驗(yàn)是90% 的 API Server not healthy 都指向鏡像拉取失敗而不是真正的配置問(wèn)題。5.2 Worker 節(jié)點(diǎn)狀態(tài) NotReadyFlannel 鏡像導(dǎo)致的連鎖反應(yīng)現(xiàn)象master 節(jié)點(diǎn)正常kubectl get nodes顯示 worker 節(jié)點(diǎn)已經(jīng)注冊(cè)但狀態(tài)一直是NotReadykubectl describe node顯示kubelet is posting ready status但底下還有一條runtime network not ready的錯(cuò)誤。原因worker 節(jié)點(diǎn)加入集群后kubelet 會(huì)嘗試啟動(dòng) CNI 插件容器這里需要拉取 Flannel 或 Calico 的鏡像。如果 worker 節(jié)點(diǎn)沒(méi)有預(yù)先拉取這些鏡像它會(huì)臨時(shí)拉取一旦網(wǎng)絡(luò)慢或者鏡像源不可用CNI 插件一直起不來(lái)kubelet 就無(wú)法上報(bào) Ready 狀態(tài)。解決在 worker 節(jié)點(diǎn)上手動(dòng)執(zhí)行kubectl get pods -n kube-system -o wide查看 Flannel Pod 是否在該節(jié)點(diǎn)上然后執(zhí)行docker pull手動(dòng)拉取對(duì)應(yīng)鏡像。另一種做法是在腳本的 worker 部署函數(shù)里加上鏡像預(yù)拉取邏輯把 Flannel 的鏡像提前用ctr或docker pull拉好。這個(gè)問(wèn)題我踩了不止一次每次都是因?yàn)橹型緭Q了網(wǎng)絡(luò)環(huán)境才發(fā)現(xiàn)的。5.3 /etc/hosts 配置缺失master 節(jié)點(diǎn)名稱解析回環(huán)現(xiàn)象初始化過(guò)程中報(bào)failed to set up init node: unable to resolve hostname或者kubelet日志里頻繁出現(xiàn)Failed to get node info。原因/etc/hosts里沒(méi)有把 master 的 IP 和主機(jī)名映射起來(lái)K8s 的很多組件直接使用主機(jī)名進(jìn)行通信解析不到正確 IP 時(shí)就會(huì)退回到 127.0.0.1導(dǎo)致所有跨節(jié)點(diǎn)通信都失敗。解決按前面腳本里的方法在初始化前就把 hostname 和 IP 寫入 hosts 文件。這個(gè)坑很隱蔽的原因是系統(tǒng)層面可能不報(bào)錯(cuò)只有 K8s 內(nèi)部組件會(huì)默默出錯(cuò)表現(xiàn)出來(lái)就是節(jié)點(diǎn)狀態(tài)異常但所有服務(wù)看著都活著。如果你發(fā)現(xiàn)集群狀態(tài)不穩(wěn)定且查不到明確錯(cuò)誤先檢查 hosts 文件這是第一步。5.4 Docker 重啟導(dǎo)致 K8s 服務(wù)異?，F(xiàn)象集群跑了幾天后某個(gè)節(jié)點(diǎn)上kubectl get nodes顯示該節(jié)點(diǎn)NotReady但systemctl status kubelet又是 active 狀態(tài)docker ps看到所有容器都不在了。原因Docker 服務(wù)被重啟后容器重新拉起但容器的 IP 地址變了kubelet 的端口映射和容器 ID 都沒(méi)有同步導(dǎo)致 Kubelet 和 API Server 之間的連接失效。也可能是 Docker 的 cgroup driver 配置被意外改動(dòng)導(dǎo)致 kubelet 無(wú)法訪問(wèn)容器的 cgroup 信息。解決重啟 Docker 后一定要重新啟動(dòng) kubelet并檢查 kubelet 的--cgroup-driver參數(shù)是否與 Docker 一致。更保險(xiǎn)的做法是修改 docker.service 的啟動(dòng)命令加入--live-restore參數(shù)讓 Docker 在自身重啟時(shí)保持容器不停止。這個(gè)參數(shù)在部署時(shí)就寫好避免后續(xù)運(yùn)維中誤重啟 Docker 導(dǎo)致連鎖故障。我后來(lái)在腳本里統(tǒng)一加上了這個(gè)參數(shù)從那以后再也沒(méi)有因?yàn)?Docker 重啟引發(fā)集群?jiǎn)栴}。6. 集群驗(yàn)證與生產(chǎn)環(huán)境的一個(gè)關(guān)鍵小習(xí)慣集群部署完成后不能直接當(dāng)黑匣子用先跑一遍驗(yàn)證流程確認(rèn)核心組件都在正常工作。我的習(xí)慣是三步檢查節(jié)點(diǎn)狀態(tài)、核心 Pod 狀態(tài)、一個(gè)測(cè)試應(yīng)用。用一個(gè)快速命令清單來(lái)執(zhí)行# 第一步節(jié)點(diǎn)必須全部 Ready kubectl get nodes # 第二步核心組件必須 Running kubectl get pods -n kube-system # 第三步跑一個(gè)測(cè)試 Pod 驗(yàn)證調(diào)度和網(wǎng)絡(luò) kubectl run test-nginx --imagenginx --restartNever --port80 kubectl wait --forconditionReady pod/test-nginx --timeout60s kubectl expose pod test-nginx --typeNodePort --port80 --nametest-svc # 拿到端口號(hào)后從集群外訪問(wèn) master_IP:NodePort確認(rèn)返回 200驗(yàn)證通過(guò)后我建議立刻給集群安裝 Kubernetes Dashboard這不是炫技而是生產(chǎn)環(huán)境管理集群的基本能力。Dashboard 可以直接在 Web 上查看節(jié)點(diǎn)狀態(tài)、Pod 日志和應(yīng)用拓?fù)浔让钚兄庇^太多。安裝命令很簡(jiǎn)單# 安裝最新版 Dashboard kubectl apply -f https://raw.githubusercontent.com/kubernetes/dashboard/v2.7.0/aio/deploy/recommended.yaml # 創(chuàng)建管理員賬號(hào)并獲取 token kubectl create serviceaccount admin-user -n kubernetes-dashboard kubectl create clusterrolebinding admin-user --clusterrolecluster-admin --serviceaccountkubernetes-dashboard:admin-user kubectl get secret -n kubernetes-dashboard $(kubectl get serviceaccount admin-user -n kubernetes-dashboard -o jsonpath{.secrets[0].name}) -o jsonpath{$.data.token} | base64 -d在生產(chǎn)環(huán)境里我最在意的一個(gè)習(xí)慣是永遠(yuǎn)不要把kubeadm-join.sh這個(gè)臨時(shí)文件留在/tmp 下不管。token 雖然 24 小時(shí)就過(guò)期但如果泄露給不該看到的人攻擊者可以在有效期內(nèi)把節(jié)點(diǎn)加入你的集群。從那以后我每次部署完都強(qiáng)制走一遍rm -f /tmp/kubeadm-join.sh同時(shí)用kubeadm token delete把已用過(guò)的 token 清掉。這個(gè)動(dòng)作已經(jīng)變成腳本末尾的固定步驟了希望你也能養(yǎng)成這個(gè)習(xí)慣。這份一鍵部署腳本的思路是把常見(jiàn)踩坑都前置于部署階段解決而不是等報(bào)錯(cuò)了再排查。Docker 版本固定、cgroup driver 統(tǒng)一、鏡像提前預(yù)拉取、join 信息自動(dòng)提取這四個(gè)維度基本涵蓋了新手部署時(shí)遇到的大部分問(wèn)題。希望幫到你后續(xù)遇到集群故障時(shí)先按這幾步檢查一遍能省下不少時(shí)間。本文還有配套的精品資源點(diǎn)擊獲取