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