1. 先搞清楚這次要解決的問題helm安裝rancher這件事本身并不復(fù)雜跑過一遍的人都知道真正讓人頭疼的是后續(xù)證書維護(hù)。尤其是當(dāng)ingress證書快過期、或者你準(zhǔn)備從內(nèi)網(wǎng)測(cè)試證書切換到正式CA簽發(fā)的證書時(shí)更新流程里藏著不少坑。這篇文章就圍繞helm部署Rancher和更新ingress證書這兩條主線把方案選型、實(shí)操命令、踩坑記錄一次講清楚。適合正在用Rancher管理K8s集群、同時(shí)又自己維護(hù)證書的運(yùn)維同學(xué)參考也歡迎第一次接觸Rancher的朋友當(dāng)一篇入門指南來看。先說一個(gè)常見的誤區(qū)很多人以為“更新ingress證書”就是把tls secret里的證書換掉然后等ingress controller自動(dòng)生效。這個(gè)思路對(duì)一般的Nginx Ingress項(xiàng)目成立放到Rancher場(chǎng)景下就不夠了。Rancher的架構(gòu)里證書不只是給瀏覽器看的它還承擔(dān)著Rancher server和下游集群agent之間的信任校驗(yàn)。如果只換了門面、沒換內(nèi)部信任鏈后續(xù)擴(kuò)容集群、注冊(cè)新節(jié)點(diǎn)、甚至刷新已有集群的連接都會(huì)出問題。所以你要更新的不是一個(gè)secret而是一整條證書鏈路上的相關(guān)組件。這篇文章我會(huì)先講清楚Rancher里證書的層次結(jié)構(gòu)再給出一套從helm安裝到證書更新的完整操作流程。中間會(huì)穿插我自己實(shí)測(cè)過的命令和踩坑記錄最后整理一份問題排查速查表。內(nèi)容可能比一般教程啰嗦一點(diǎn)但每個(gè)命令背后的原因我都會(huì)解釋免得你照著抄完還是一頭霧水。2. 上手前先理清Rancher的證書層次2.1 Rancher里到底有幾層證書Rancher部署之后證書并不是只有一張。大概可以分成三個(gè)層次來看。第一層是用戶訪問Rancher UI時(shí)看到的ingress證書。你通過瀏覽器訪問https://rancher.example.com看到的證書就是這一層。它掛在cattle-system命名空間下的ingress資源上一般對(duì)應(yīng)一個(gè)名為tls-rancher-ingress的secret。第二層是Rancher內(nèi)部組件之間的通信證書。Rancher server內(nèi)部有多個(gè)組件比如cattle-controllers、api-server相關(guān)的模塊它們之間通過TLS通信。在開啟私有CA的場(chǎng)景下這層證書由一個(gè)內(nèi)部CA統(tǒng)一簽發(fā)相關(guān)secret在cattle-system命名空間里名字類似tls-rancher-internal-ca。這層證書一般不需要你手動(dòng)更新它們由Rancher自己管理但如果那個(gè)內(nèi)部CA的根證書變了麻煩就來了。第三層是Rancher server與下游集群agent之間建立信任所用的CA證書。每當(dāng)你把一個(gè)K8s集群導(dǎo)入Rancher集群里的agent會(huì)拿到一個(gè)“集群注冊(cè)令牌”其中包含一個(gè)CA證書agent用這個(gè)CA來校驗(yàn)Rancher server的身份。如果這臺(tái)server的CA變了已經(jīng)注冊(cè)的集群會(huì)失聯(lián)新增集群時(shí)也會(huì)失敗。搞清楚這三層之后你再回頭看“更新ingress證書”這個(gè)需求就會(huì)發(fā)現(xiàn)它其實(shí)有兩種情況。一種是證書確實(shí)是同一張只是快過期了換一張同CA簽發(fā)的新的這種情況簡(jiǎn)單換tls secret就完事。另一種是你換了整套CA比如從內(nèi)部測(cè)試CA切到公司正式CA那么上面三層全部要?jiǎng)由賱?dòng)一個(gè)都會(huì)出問題。很多線上事故就是這么來的。2.2 為什么證書方案會(huì)影響后續(xù)更新難度Rancher安裝時(shí)ingress.tls.source這個(gè)參數(shù)決定了ingress證書的來源。常用的有三個(gè)值rancher、secret、letsEncrypt。我先說說三者的區(qū)別因?yàn)檫@直接決定你后續(xù)更新證書的工作量。rancher模式是讓Rancher通過自身的證書管理功能來簽發(fā)證書需要配合cert-manager使用。這種模式下證書更新基本是自動(dòng)的你幾乎不用管但前提是你接受Rancher自己作為簽發(fā)方瀏覽器會(huì)給出不可信警告。letsEncrypt模式也依賴cert-manager適合有公網(wǎng)域名、且不想自己維護(hù)證書的場(chǎng)景。它會(huì)自動(dòng)申請(qǐng)和續(xù)期省心但是對(duì)網(wǎng)絡(luò)環(huán)境和域名所有權(quán)有要求。secret模式是最靈活也最顯示水平的一種。你把證書內(nèi)容做成secret放到命名空間里通過--set ingress.tls.sourcesecret讓Rancher的ingress去引用它。企業(yè)內(nèi)網(wǎng)環(huán)境或者有獨(dú)立CA團(tuán)隊(duì)的公司基本都會(huì)選這個(gè)模式。因?yàn)樽C書由你自己的CA體系簽發(fā)瀏覽器也信任合規(guī)審計(jì)也方便唯一的問題就是證書過期時(shí)你要手動(dòng)更新這正是本文重點(diǎn)要講的場(chǎng)景。如果你還沒裝Rancher我建議你現(xiàn)在就決定好采用哪種模式。因?yàn)檠b完之后再想從rancher模式切換成secret模式涉及的操作比裝的時(shí)候就選好要復(fù)雜得多不只是改一個(gè)values文件那么簡(jiǎn)單。我見過好幾個(gè)同事在測(cè)試環(huán)境隨手用rancher模式裝的后來要接公司統(tǒng)一證書體系只能整條鏈重新梳理一遍。3. 用Helm安裝Rancher的全過程3.1 前置條件與版本選型動(dòng)手之前先確認(rèn)幾件事。Helm要是v3版本helm version看一下v2雖然也能裝Rancher但現(xiàn)在已經(jīng)不是主流用法不建議在新環(huán)境里使用了。Kubernetes集群版本要按照Rancher官方支持矩陣來過早過晚的版本都會(huì)有兼容性問題我自己習(xí)慣裝比官方最低要求高一兩個(gè)小版本的K8s留出緩沖。域名需要提前準(zhǔn)備好并且DNS解析指向集群的ingress入口這個(gè)不提前搞定后面就算裝好了也訪問不了。還要提醒一句Rancher是有License機(jī)制的。雖然社區(qū)版可以免費(fèi)用但生產(chǎn)環(huán)境用的話建議了解清楚授權(quán)情況。我見過有公司裝完了才發(fā)現(xiàn)沒法激活又要回滾的場(chǎng)景。這不是技術(shù)問題但比技術(shù)問題更麻煩。組件版本之間別亂搭配。我自己測(cè)試過一套組合Helm 3.14配K8s 1.28配Rancher 2.8用下來很穩(wěn)。不是說老版本不行而是你遇到問題去查文檔時(shí)這種新組合的坑別人已經(jīng)踩得差不多了報(bào)錯(cuò)信息其實(shí)好找。3.2 添加Helm倉(cāng)庫(kù)與創(chuàng)建命名空間Helm倉(cāng)庫(kù)地址是官方charts倉(cāng)庫(kù)執(zhí)行下面兩條命令把倉(cāng)庫(kù)加進(jìn)來并同步索引helm repo add rancher-latest https://charts.rancher.io helm repo update注意倉(cāng)庫(kù)名的選擇我自己習(xí)慣用rancher-latest因?yàn)樗鼘?duì)應(yīng)的是最新穩(wěn)定版本。有些教程會(huì)讓人用rancher-stable其實(shí)兩個(gè)都是官方倉(cāng)庫(kù)只是更新策略不太一樣。如果你要裝指定版本先helm search repo rancher -l列出所有版本再通過--version參數(shù)指定。接著創(chuàng)建命名空間。Rancher默認(rèn)的命名空間是cattle-system這個(gè)強(qiáng)一致別改成別的名字否則后續(xù)很多命令和文檔就對(duì)不上了。kubectl create namespace cattle-system3.3 準(zhǔn)備證書Secret這一步是整個(gè)安裝過程里最容易埋雷的地方。準(zhǔn)備兩個(gè)文件證書文件fullchain.pem和私鑰文件key.pem。我用詞很嚴(yán)格是fullchain.pem不是單單一個(gè)cert.pem。如果你的證書鏈里有中間CA證書必須把站點(diǎn)證書和中間證書合并成一個(gè)fullchain文件順序是站點(diǎn)證書在前、中間證書在后。只傳一個(gè)站點(diǎn)證書的話很多瀏覽器會(huì)報(bào)“證書鏈不完整”特別是用了私有CA簽發(fā)的證書時(shí)這個(gè)問題幾乎必現(xiàn)。生成secret的命令kubectl -n cattle-system create secret tls tls-rancher-ingress \ --certfullchain.pem \ --keykey.pem這里我提一個(gè)備用方案如果后面證書更新頻繁建議用下面這種冪等寫法即使secret已存在也不會(huì)報(bào)錯(cuò)kubectl -n cattle-system create secret tls tls-rancher-ingress \ --certfullchain.pem \ --keykey.pem \ --dry-runclient -o yaml | kubectl apply -f -這個(gè)命令先通過dry-run生成secret的yaml再通過管道喂給apply如果secret不存在就創(chuàng)建如果存在就更新整個(gè)過程不會(huì)中斷服務(wù)。后面講證書更新的時(shí)候還會(huì)再用到這個(gè)思路。3.4 執(zhí)行helm install安裝命令如下我加了比較實(shí)用的參數(shù)并逐一說明它們的作用。helm install rancher rancher-latest/rancher \ --namespace cattle-system \ --set hostnamerancher.example.com \ --set bootstrapPasswordadmin123 \ --set replicas3 \ --set ingress.tls.sourcesecret \ --set privateCAtruereplicas3是生產(chǎn)環(huán)境建議值Rancher的controller組件支持多副本單副本在集群節(jié)點(diǎn)重啟時(shí)會(huì)短暫不可用三副本能扛住單個(gè)節(jié)點(diǎn)故障。如果只是測(cè)試環(huán)境1個(gè)副本就夠。bootstrapPassword是安裝后首次登錄的初始密碼安裝后第一件事建議改掉。privateCAtrue是配合私有CA證書用的如果你的證書是由私有CA簽的這個(gè)參數(shù)務(wù)必設(shè)為true讓Rancher內(nèi)部信任這個(gè)CA。如果你的證書是公網(wǎng)CA簽的那不要設(shè)這個(gè)參數(shù)。這個(gè)坑我踩過一次明明證書是公開信任的還設(shè)了privateCA結(jié)果Rancher內(nèi)部組件之間做校驗(yàn)時(shí)反而互相不認(rèn)賬。安裝過程大概兩三分鐘期間可以用以下命令觀察進(jìn)度kubectl -n cattle-system rollout status deploy/rancher看到deployment rancher successfully rolled out就說明裝好了。3.5 驗(yàn)證安裝結(jié)果與證書生效情況裝完之后別急著登錄先在命令行驗(yàn)證一下證書鏈?zhǔn)欠裾_。用openssl來驗(yàn)證最直接openssl s_client -connect rancher.example.com:443 -servername rancher.example.com /dev/null 2/dev/null | openssl x509 -noout -subject -issuer -dates這個(gè)命令會(huì)打印出服務(wù)器實(shí)際下發(fā)的證書主體、簽發(fā)者和有效期。檢查三件事簽發(fā)者和你的CA是否一致subject里的域名和hostname是否匹配有效期是否覆蓋當(dāng)前日期。如果這三項(xiàng)都正常再用瀏覽器訪問一下確認(rèn)沒有證書告警就可以繼續(xù)了。4. 更新ingress證書的核心操作流程4.1 什么場(chǎng)景下需要更新證書證書更新不是一個(gè)高頻操作但一旦需要往往是比較緊急的情況。我歸納一下常遇到的三種第一種是證書即將過期。這個(gè)是最常見的。公司內(nèi)部CA簽發(fā)的證書有效期一般是一年一年一到就得換。很多運(yùn)維沒有做證書到期監(jiān)控都是瀏覽器報(bào)警了才發(fā)現(xiàn)。第二種是換了CA簽發(fā)方。比如公司從自建CA切換到第三方商業(yè)CA或者從測(cè)試CA切到正式CA。這時(shí)候不只是證書文件變了整個(gè)信任鏈都變了。第三種是更換訪問域名。域名從rancher-old.example.com切到rancher.example.com新域名的證書也要同步替換。不管是哪種情況操作的核心都是更新ingress引用的那個(gè)TLS secret。不同的是換CA或者換域名時(shí)還要額外處理內(nèi)部信任鏈。4.2 更新TLS Secret的正確姿勢(shì)拿到新的fullchain和key之后用前面提到的冪等方式更新secretkubectl -n cattle-system create secret tls tls-rancher-ingress \ --certnew-fullchain.pem \ --keynew-key.pem \ --dry-runclient -o yaml | kubectl apply -f -執(zhí)行完成后先看secret里的內(nèi)容是不是新的kubectl -n cattle-system get secret tls-rancher-ingress -o jsonpath{.data.tls\.crt} | base64 -d | openssl x509 -noout -subject -dates這里有個(gè)細(xì)節(jié)需要提醒很多人在執(zhí)行create secret時(shí)遇到AlreadyExists報(bào)錯(cuò)就順手kubectl delete secret再重新create這個(gè)操作是有隱患的。刪除和重建之間有一個(gè)時(shí)間窗口如果此時(shí)有請(qǐng)求打進(jìn)來ingress會(huì)短暫找不到證書表現(xiàn)就是502或者TLS握手直接失敗。而dry-run管道方式可以做到原子替換雖然底層也是先刪后建但通過apply的方式對(duì)控制器來說是平滑過渡的。我的建議是養(yǎng)成這個(gè)習(xí)慣別在線上環(huán)境用delete加create。4.3 Ingress如何感知證書變化更新完secret接下來的問題是ingress什么時(shí)候生效如果集群里用的是標(biāo)準(zhǔn)的Nginx Ingress Controller它會(huì)監(jiān)聽Secret資源的變化。你更新secret的幾秒之內(nèi)controller會(huì)自動(dòng)重新加載配置新證書就會(huì)生效。這個(gè)過程一般不需要人工干預(yù)但也不是絕對(duì)的。如果你的Ingress Controller版本比較老或者部署時(shí)限制了監(jiān)聽范圍就可能出現(xiàn)不自動(dòng)加載的情況。為了方便排查更新secret之后可以這樣驗(yàn)證一下kubectl -n cattle-system get ingress rancher -o yaml | grep -A5 tls確認(rèn)ingress引用的是tls-rancher-ingress這個(gè)secret。然后稍等十幾秒再次用openssl驗(yàn)證線上證書。如果等了很久證書還是舊的可以主動(dòng)觸發(fā)一下Ingress Controller的Reload最保險(xiǎn)的方法是把對(duì)應(yīng)的controller pod刪掉重建。但生產(chǎn)環(huán)境刪pod之前先確認(rèn)有多個(gè)副本或者確認(rèn)重建不會(huì)導(dǎo)致服務(wù)中斷。Nginx Ingress Controller在滾動(dòng)重建的過程中會(huì)自動(dòng)加載最新的Secret內(nèi)容。如果是RKE2或者K3s自帶的Traefik作為Ingress Controller機(jī)制也類似它同樣會(huì)watch Secret變化。不過Traefik對(duì)證書更新的響應(yīng)時(shí)間可能稍慢我自己遇到時(shí)一般等30秒內(nèi)就會(huì)自動(dòng)生效如果超時(shí)就檢查Traefik日志。4.4 換CA時(shí)內(nèi)部信任鏈也要同步調(diào)整這一步是我最想強(qiáng)調(diào)的。如果你只是同一張CA下續(xù)期跳到本章結(jié)束不需要看這節(jié)。但如果你的CA換了也就是新證書的“issuer”和舊證書不一樣了那么你還需要做一件事把新的CA同步給Rancher內(nèi)部組件。先看一下當(dāng)前cattle-system里有哪些CA相關(guān)secretkubectl -n cattle-system get secret | grep -E tls-rancher|internal-ca以tls-rancher-internal-ca為代表Rancher內(nèi)部組件以及agent通信都會(huì)用到這些CA。換CA之后需要把新的根證書更新到這個(gè)secret里。這里沒有一鍵命令我的做法是先把新的CA文件準(zhǔn)備好然后更新對(duì)應(yīng)secretkubectl -n cattle-system create secret generic tls-rancher-internal-ca \ --from-fileca.pemnew-ca.pem \ --dry-runclient -o yaml | kubectl apply -f -注意secret類型和字段名要以你的實(shí)際環(huán)境為準(zhǔn)。這一步做完重啟Rancher的pod讓它用新的CA重新建立內(nèi)部信任kubectl -n cattle-system rollout restart deploy/rancher這里要特別謹(jǐn)慎如果你對(duì)Rancher的信任鏈機(jī)制不是很熟建議在維護(hù)窗口操作并且提前備份舊的secret。備份命令很簡(jiǎn)單kubectl -n cattle-system get secret tls-rancher-ingress -o yaml ingress-cert-backup.yaml kubectl -n cattle-system get secret tls-rancher-internal-ca -o yaml internal-ca-backup.yaml一旦操作出問題可以立刻kubectl apply -f恢復(fù)。另外換CA之后還有一個(gè)隱藏影響已經(jīng)導(dǎo)入Rancher的下游集群agent它們保存的是舊CA。Rancher server換了新CAagent在建立連接時(shí)會(huì)發(fā)現(xiàn)校驗(yàn)失敗。典型癥狀就是集群列表里所有集群都變成“Unavailable”agent pods反復(fù)CrashLoopBackOff。解決方式是對(duì)每個(gè)下游集群重新生成注冊(cè)命令并應(yīng)用agent manifest。這一步操作邏輯說起來簡(jiǎn)單實(shí)際執(zhí)行時(shí)要小心尤其不要影響到集群里正在運(yùn)行的工作負(fù)載。4.5 完整更新流程的時(shí)序圖我畫一個(gè)簡(jiǎn)化版的操作時(shí)序方便你執(zhí)行時(shí)心里有數(shù)備份現(xiàn)有secret保留回滾方案。更新ingress對(duì)應(yīng)的tls secret。驗(yàn)證ingress證書是否生效。檢查新證書的CA與舊證書是否一致。如果不一致進(jìn)入第5步。更新內(nèi)部CA相關(guān)secret。重啟Rancher deployment。檢查下游集群連接狀態(tài)如有異常重新生成集群注冊(cè)命令。5. 常見問題與排查技巧實(shí)錄5.1 證書顯示沒更新的排查順序有次我在測(cè)試環(huán)境更新證書后瀏覽器里看到的還是舊證書折騰半天才發(fā)現(xiàn)問題根本不在Rancher而在Ingress Controller的緩存。這里我按排查優(yōu)先級(jí)列一下先看secret內(nèi)容對(duì)不對(duì)。用前面提過的命令檢查secret里的證書日期。如果secret里的內(nèi)容已經(jīng)是新證書而瀏覽器看到的還是舊的說明問題在下一層。再看ingress代理層。測(cè)試時(shí)不要用瀏覽器用curl繞過緩存直接驗(yàn)證curl -vI https://rancher.example.com 21 | grep -i subject\|issuer如果curl顯示的證書是新的瀏覽器卻顯示舊證書那就是瀏覽器緩存了HSTS或者證書狀態(tài)。換個(gè)無(wú)痕窗口試試基本就解決了。如果curl顯示的也是舊證書再檢查Ingress Controller pod。查看它的日志看有沒有加載最新secret的記錄。如果一直是舊證書手動(dòng)刪掉controller pod強(qiáng)制重生一般能解決。還有一類低級(jí)問題你同時(shí)存在多個(gè)secretingress實(shí)際引用的不是你想更新的那一個(gè)。這種情況我會(huì)先把ingress的yaml里tls部分的secretName抄出來跟實(shí)際更新的secret名字對(duì)一遍。別笑真有人把證書更新到tls-rancheringress引用的卻是tls-rancher-ingress折騰半天毫無(wú)進(jìn)展。5.2 更新證書導(dǎo)致新增節(jié)點(diǎn)失敗的原因有次更新公司內(nèi)某套R(shí)ancher的證書后第二天運(yùn)維反饋說新增K8s節(jié)點(diǎn)一直失敗。排了半天發(fā)現(xiàn)就是CA信任鏈的問題。現(xiàn)象是這樣的新證書是新的CA簽發(fā)的ingress層面看起來一切正常瀏覽器訪問也正常。但是新節(jié)點(diǎn)的kubelet通過Rancher agent注冊(cè)時(shí)它拿到的CA還是舊的于是agent到Rancher server之間的TLS校驗(yàn)失敗表現(xiàn)為“certificate signed by unknown authority”。解決辦法就是我4.4節(jié)里說的同步更新內(nèi)部CA并且確保agent側(cè)拿到的是新CA。如果你是新增一個(gè)全新的集群直接在Rancher UI里重新生成集群注冊(cè)命令復(fù)制里面最新的CA字段粘貼到新集群執(zhí)行就沒有這個(gè)問題。5.3 證書更新后集群顯示Unavailable前面提到過這個(gè)坑往往不是立刻出現(xiàn)而是過了一段時(shí)間才暴露。因?yàn)閍gent和server之間的長(zhǎng)連接可能一直保持。等到連接斷開、agent重連的時(shí)候它發(fā)現(xiàn)自己不再信任這個(gè)server了才會(huì)報(bào)錯(cuò)。遇到這種情況先別慌先確認(rèn)Rancher pod里的CA是不是和集群agent里的CA一致。方法是在Rancher server pod里執(zhí)行命令查看內(nèi)部CA指紋再在出問題的集群里查看agent pod的CA指紋對(duì)不上就能確認(rèn)是這個(gè)問題。修復(fù)辦法到出問題的集群里查看agent相關(guān)的secret確認(rèn)它的ca.pem是不是新CA。如果不是把它換成新CA然后重啟agent相關(guān)pod。換的時(shí)候同樣建議備份。Rancher官方對(duì)這種情況有一個(gè)專門的說明文檔核心思路就是讓agent的CA和server保持一致。5.4 問題排查速查表我把上面遇到的問題整理成一個(gè)表方便你到時(shí)候直接對(duì)照癥狀可能原因處理方向?yàn)g覽器提示證書不信任證書鏈不完整secret里只有站點(diǎn)證書沒包含中間證書重新生成fullchain把中間證書拼進(jìn)去更新secret瀏覽器看到舊證書瀏覽器緩存或HSTS換無(wú)痕窗口驗(yàn)證清除瀏覽器緩存curl看到舊證書Ingress Controller沒有加載新secret查看controller日志刪除controller pod強(qiáng)制重載新增節(jié)點(diǎn)注冊(cè)失敗agent側(cè)的CA是舊的重新生成集群注冊(cè)命令應(yīng)用新manifest已有集群顯示Unavailableserver CA變了agent校驗(yàn)失敗手動(dòng)更新agent的CA再重啟agent podsecret更新時(shí)報(bào)AlreadyExistscreate時(shí)沒有加dry-run管道換成apply方式更新避免先刪后建證書合法但訪問502更新secret的瞬間有請(qǐng)求或controller的worker沒有準(zhǔn)備好稍后重試確認(rèn)controller pod正常這個(gè)表格基本上覆蓋了我從安裝到維護(hù)過程中遇到的絕大多數(shù)問題。如果你還有別的報(bào)錯(cuò)按“先驗(yàn)證內(nèi)容、再排查鏈路、最后看日志”這個(gè)順序走一遍通常能找到原因。最后分享兩個(gè)實(shí)在的體會(huì)。第一證書相關(guān)操作一定要在低峰期做并且手邊留好回滾方案。Rancher的證書鏈路涉及的不只是訪問入口還有agent注冊(cè)鏈路操作不當(dāng)影響面比你想的大。第二給證書到期做個(gè)監(jiān)控提醒不要等瀏覽器報(bào)警了再去處理。我在實(shí)際操作中最怕的就是半夜被電話叫起來?yè)Q證書那種狀態(tài)下很容易出錯(cuò)。提前在日歷上把證書到期日標(biāo)出來提前兩周準(zhǔn)備替換文件比什么技巧都管用。