簡介這份 Puppet 管理模塊面向配置管理與 DevOps 工程師用于安裝和管理 Puppet Master、The Foreman 與 smart-proxy并支持一體機aio、目錄服務(wù)catalog和 CA 服務(wù)ca三種 Master 角色可按需單獨部署目錄或證書節(jié)點。與常見基于 yum 包和系統(tǒng) Ruby 的同類方案不同它使用 RVM、git 倉庫與 gem 管理整套軟件棧模塊化程度更高升級和 Ruby 安全補丁維護也更可控。壓縮包為 zip 格式共 60 個文件、約 64KB主要包括 Puppet 清單.pp、ERB 模板.erb、Ruby 腳本.rb和 YAML 配置前兩類分別用于聲明資源狀態(tài)與生成服務(wù)配置適合直接改造成自己的部署基線。目錄按 foreman、smartproxy、puppet 等角色組織附帶 spec 測試、Rakefile 與 Gemfile可串聯(lián)自動化測試和依賴管理已有 133 人學(xué)習(xí)下載適合希望擺脫系統(tǒng) Ruby 限制、對 Puppet 棧做精細化版本控制的團隊參考。1. puppet_stack 這個名字為什么把三件套放在一起才有意義puppet_stack 把 Puppet Master、The Foreman 和 smart-proxy 三個詞綁在同一個標題里很多人第一反應(yīng)是“裝一個 Master 就夠了”。真到生產(chǎn)環(huán)境里批量加節(jié)點、區(qū)分開發(fā)與生產(chǎn)環(huán)境、處理證書續(xù)期時你會發(fā)現(xiàn)光有一個會編譯目錄的 Master 遠遠不夠。這套棧真正提供的是一條完整鏈路配置能發(fā)出去、證書有人簽、節(jié)點有人管、基礎(chǔ)設(shè)施操作有統(tǒng)一出口。下面從組件職責講到安裝命令再落到日常維護和幾個高頻事故適合手上已經(jīng)有三五十臺到上千臺 Linux 主機、正在為配置管理工具本身發(fā)愁的從業(yè)者。2. 職責邊界Puppet Master、The Foreman、smart-proxy 各自在管什么2.1 Puppet Master 負責配置編譯但不是管理入口Puppet Master有些部署方式下叫 Puppet Server是整個棧里唯一真正編譯目錄、給 Agent 下發(fā)的角色。它不面向運維人員提供操作界面也不負責審批本質(zhì)上是一個后端服務(wù)。Agent 按約定時間來找它請求 catalogMaster 編譯后返回Agent 在本地執(zhí)行并回傳報表。這個模型的好處是冪等壞處是運維對“誰來了、誰還沒來、證書是否有效”沒有任何直觀感受。Master 端口固定是 8140日志一般在 /var/log/puppetlabs/puppetserver/ 下。針對 Master 的資源我的建議是單獨準備一臺機器內(nèi)存視節(jié)點規(guī)模決定。節(jié)點數(shù)到幾百臺之后編譯線程數(shù)和 JVM 堆需要按比例調(diào)。我一般會把 puppetserver 的-Xmx和-Xms設(shè)成同一個值避免運行中反復(fù)調(diào)整堆大小帶來額外停頓。節(jié)點的請求頻率也要控制默認 30 分鐘一個周期是常見配置不要為了“實時生效”把所有 Agent 的runinterval調(diào)成 1 分鐘那會把 Master 編譯隊列直接打滿。2.2 The Foreman把主機生命周期和證書審批收口到網(wǎng)頁The Foreman 不是一個來和 Puppet 搶活的配置引擎它是管理控制面。Foreman 提供主機登記、主機組歸類、組織與位置劃分、用戶權(quán)限、以及最關(guān)鍵的報表查看。所謂“組織與位置”你可以理解成頂層隔離同一個 Foreman 里可以同時放多個客戶或機房主機按組織歸屬主機組按位置歸屬互不串數(shù)據(jù)。還有一個能力在大量使用后會非常剛需它和 Puppet 的 CA 集成讓證書審批可以在頁面上點擊完成不用在每個 Master 上都保留一批命令行活。幾十臺實驗機的情況不裝 Foreman 也能活著。節(jié)點一旦過百或者需要分環(huán)境、分團隊讓非核心運維也能自助看報表和觸發(fā)任務(wù)Foreman 的價值就非常明顯。它的 Web 服務(wù)走 443 端口和 Master 的 8140 分開API 也走同一套 HTTPS日常自動化腳本都可以直接對接。它解決的其實是一個很原始的問題配置管理原本的入口近乎為零而 Foreman 把入口補上了。2.3 smart-proxy 是 Foreman 的“手”不是網(wǎng)絡(luò)出口這個組件是標題里最容易被誤解的部分。smart-proxy 是 Foreman 的一組擴展服務(wù)用來操作 DNS、DHCP、TFTP 等基礎(chǔ)設(shè)施同時承擔證書簽發(fā)的 relay 功能。比如在 Foreman 頁面上給新主機分配網(wǎng)段并讓它從 TFTP 啟動這些動作最終通過 smart-proxy 在對應(yīng)服務(wù)器上真實執(zhí)行。它的 API 端口通常是 8443和 Foreman 的 443、Master 的 8140 并立。官方默認的安裝器會按模塊把證書、DHCP、DNS、TFTP 拆開。實操中我建議先只開證書模塊跑通后續(xù)真需要 DHCP/DNS 聯(lián)動再逐個模塊打開。很多人的頁面一片紅就是因為默認把全部模塊啟用但底層服務(wù)根本沒有或權(quán)限不合報警滾成一片反而掩蓋了真問題。還要注意smart-proxy 可以直接和 Foreman 裝在同一臺機器上也可以放在某個目標網(wǎng)段的服務(wù)器上關(guān)鍵是它必須能被 Foreman 用可信的證書或 token 訪問。2.4 選型考量單獨 Master 與完整 puppet_stack 的邊界能力單獨 Puppet Master完整 puppet_stack配置下發(fā)有有證書簽發(fā)入口命令行Foreman 頁面 API主機與主機組管理沒有有報表與歷史檢索沒有有多環(huán)境切換的操作入口手動改目錄主機組映射DHCP/DNS/TFTP 聯(lián)動做不到smart-proxy 對應(yīng)模塊由此可以得出一個比較簡單的判斷只有幾臺實驗機、不區(qū)分環(huán)境單獨 Master 更快生產(chǎn)環(huán)境里“證書到期”“環(huán)境切換”“新節(jié)點上線”這三件事會反復(fù)出現(xiàn)靠命令行處理每一次都做不干凈累積成本會隨時間上升。還建議不要在同一個組織里混用兩套方案否則 Master 上手工操作的證書記錄和 Foreman 的管理記錄會脫節(jié)后面排查會懷疑人生。2.5 組件之間的信任關(guān)系決定了很多坑的根源Puppet Agent 找 Master 要目錄時采用的是 Puppet 自己的 CA 體系證書在 Agent 首次運行后生成必須經(jīng)過 Master 或 Foreman 簽名才有效。Foreman 和 Master 之間的通信用的是同一臺機器上安裝器自動生成的本地證書靠配置里的 SSL 參數(shù)互相校驗Foreman 訪問 smart-proxy 時則依賴代理側(cè)預(yù)先注冊的證書或 token。這三層信任鏈互相獨立又彼此糾纏是后續(xù)絕大多數(shù)證書類報錯的根源。實際排查時腳本里遇到的“connection reset”“certificate verify failed”“http 401”都不是同一個層面的問題需要先判斷是 Agent 與 Master 的 CA 信任斷了還是 Foreman 訪問 smart-proxy 的憑證失效。這一步判斷錯了后面所有處理都是白做。3. 空服務(wù)器上跑通 puppet_stack安裝步驟與第一個 Agent 上線3.1 環(huán)境準備主機名、DNS、時間約束安裝前我會先處理三個基礎(chǔ)項這三項不做好后面證書大概率出問題。第一是主機名必須固定為完整 FQDN 格式最好把 IP 也寫進 /etc/hosts第二是每臺機器都要啟用時間同步第三是放行 8140、443、8443 三個端口。# 設(shè)置 FQDN 主機名改為你規(guī)劃的正式名稱 hostnamectl set-hostname master01.example.internal echo 192.0.2.10 master01.example.internal /etc/hosts # 啟用時間同步證書簽發(fā)強依賴時鐘偏差不能太大 systemctl enable --now chronyd chronyc tracking | head -5 # 放行核心端口按實際使用的防火墻管理方式調(diào)整 firewall-cmd --permanent --add-port{8140/tcp,443/tcp,8443/tcp} firewall-cmd --reload主機名寫在 hosts 里是保底方案避免內(nèi)網(wǎng) DNS 解析不可用時 Agent 找不到 Master。時間同步常被忽略但證書有效期判斷和請求時間戳都建立在對時之上偏差超過幾分鐘就會看到各種難以理解的握手失敗。3.2 添加軟件源并安裝 foreman-installer安裝這套棧的入口不是分別裝三個包而是裝 foreman-installer由它在最后統(tǒng)一生成配置并拉起服務(wù)。先確認當前發(fā)行版支持哪種軟件源方式再用包管理器安裝安裝器本體。# 先安裝擴展包部分依賴組件在擴展源里 sudo dnf install -y epel-release # 添加對應(yīng)發(fā)行版的 foreman 軟件源并刷新緩存 sudo dnf install -y foreman-release sudo dnf update -y這里要強調(diào)的是官方安裝器只負責把 Foreman、Puppet Master、smart-proxy 組合起來它不負責替你決定哪些模塊要開。如果你在前面沒有想清楚證書、DHCP、DNS 哪些要啟用安裝后大概率要往回改配置那時候每一步都牽一發(fā)動全身。3.3 執(zhí)行安裝器最小化參數(shù)先跑通首次安裝一定要做最小化。把組織、位置定了再顯式關(guān)閉用不到的基礎(chǔ)設(shè)施模塊。sudo foreman-installer \ --foreman-initial-organization myorg \ --foreman-initial-location myloc \ --puppet-server true \ --foreman-proxy-puppet true \ --foreman-proxy-register-in-foreman true \ --enable-foreman-proxy-plugin-dhcp false \ --enable-foreman-proxy-plugin-dns false \ --enable-foreman-proxy-plugin-tftp falseorganization 和 location 是 Foreman 的頂層隔離維度后面可以在頁面里繼續(xù)建但初始值最好一次寫對。puppet-server true 讓本機把 Master 一起拉起來三個 plugin 全 false是因為這一階段目標是證明鏈路能走通。安裝過程通常要幾分鐘到十幾分鐘結(jié)束時會打印默認 admin 密碼和訪問地址先保存好再關(guān)窗口。提示安裝完成后不要立刻重啟機器等證書全部生成、服務(wù)先跑一遍正常了再做重啟驗證。3.4 首次登錄與健康檢查安裝器結(jié)束后第一步是先看服務(wù)狀態(tài)而不是急著打開頁面。# 分別查看三個核心服務(wù)的狀態(tài) systemctl status httpd --no-pager -l systemctl status puppetserver --no-pager -l systemctl status foreman-proxy --no-pager -l # 確認三個端口都在監(jiān)聽 ss -lntp | grep -E :(8140|8443|443)\b如果 8140 沒出現(xiàn)說明 puppetserver 沒有正常起來大概率是 JVM 內(nèi)存參數(shù)或主機名解析問題。8443 缺失則去查 foreman-proxy 的日志最直觀的判斷方式就是這三個端口必須同時存在。頁面訪問用 https://master01.example.internal/首次登錄時用安裝器打印的 admin 賬號密碼系統(tǒng)會要求改掉初始密碼這一步在自動化腳本里經(jīng)常被落下導(dǎo)致后面所有 API 調(diào)用一直返回 401 認證失敗。3.5 接入第一個 Agent從證書請求到完成首次運行Agent 端的接入套路是從安裝 puppet-agent 包開始先配好 server 地址再觸發(fā)一次預(yù)演。# 在目標節(jié)點上安裝并指向 Master sudo dnf install -y puppet-agent sudo vim /etc/puppetlabs/puppet/puppet.conf # [main] # server master01.example.internal # 第一次運行用預(yù)演模式目的是觸發(fā)證書請求 sudo /opt/puppetlabs/bin/puppet agent -t --noop第一次運行大概率會卡在“等待證書簽發(fā)”的狀態(tài)這很正常因為服務(wù)端還沒有放行。此時回到 Master 端查看待簽列表并完成簽發(fā)# 查看待簽名證書確認識別出真實節(jié)點 /opt/puppetlabs/bin/puppet cert list # 確認無誤后簽發(fā)對應(yīng)名稱的證書 /opt/puppetlabs/bin/puppet cert sign agent01.example.internal簽發(fā)完成后再次執(zhí)行puppet agent -t應(yīng)該就能拿到 catalog 并按目錄完成預(yù)演。這里的 agent 名稱默認取自節(jié)點主機名所以主機名在安裝前就固化下來非常關(guān)鍵臨時換過名的節(jié)點證書簽發(fā)后往往出現(xiàn)名稱不匹配只能清掉重簽。4. 日常管理證書、環(huán)境、主機組和 smart-proxy 健康檢查4.1 用一組命令管理 Agent 證書的完整生命周期證書是這個棧里最不能靠感覺處理的資產(chǎn)。日常無非四類操作查看、簽發(fā)、撤銷、清理重簽我習(xí)慣全部用命令行兜底雖然 Foreman 頁面也能做但腳本和自查時命令行更快。# 查看所有證書帶 --all 才會同時顯示已簽發(fā)和待簽發(fā) /opt/puppetlabs/bin/puppet cert list --all # 撤銷并移除某節(jié)點的證書記錄 /opt/puppetlabs/bin/puppet cert clean agent01.example.internal # 重新簽發(fā)節(jié)點端必須先清空舊證書 /opt/puppetlabs/bin/puppet cert sign agent01.example.internalcert clean刪除的是服務(wù)端記錄節(jié)點端還握著舊證書和私鑰如果不去清節(jié)點端 SSLDir下一次請求會報出各種驗證失敗。常見做法是登錄節(jié)點后刪除 /etc/puppetlabs/puppet/ssl 整個目錄再重新跑puppet agent -t生成新請求。較新版本也可以直接用puppet ssl bootstrap重置但舊路徑同樣可行優(yōu)先用目錄清理法最穩(wěn)。4.2 Foreman 里的主機組和環(huán)境劃分Foreman 的管理基本單元是主機組。常見做法是建一個 base 主機組放通用配置再在它下面派生 dev、staging、production 子組把 Puppet environment 映射到各子組。這樣新增節(jié)點時只要選對主機組環(huán)境歸屬就自動正確不需要在 Agent 端手動改配置文件。# 用 API 建主機時指定主機組和環(huán)境示例結(jié)構(gòu) curl -k -u admin:password \ -H Content-Type: application/json \ -d {host:{name:app01,hostgroup_id:9,environment_id:3}} \ https://master01.example.internal/api/hosts在頁面操作時主機組和環(huán)境都是下拉選項。要注意 Agent 端 /etc/puppetlabs/puppet/puppet.conf 里的 environment 必須和主機組一致否則會陷入“我明明改了環(huán)境節(jié)點跑完還是舊配置”的困惑。API 里的環(huán)境字段實際上對應(yīng) environment id這個 id 可以在頁面或 API 里查。4.3 分清 puppetserver、foreman、foreman-proxy 三類日志服務(wù)日志路徑常見問題puppetserver/var/log/puppetlabs/puppetserver/編譯報錯、CA 異常foreman/var/log/foreman/production.log頁面報錯、API 401foreman-proxy/var/log/foreman-proxy/proxy.log證書 relay、DHCP/DNS 操作失敗遇到 Agent 報錯時先看 Agent 端日志再往 Master 側(cè)看這個順序不能反。大多數(shù)時候服務(wù)端其實是正常的問題出在證書或環(huán)境名不匹配?？焖俅_認 smart-proxy 狀態(tài)可以用# 輸出各模塊啟用狀態(tài)和監(jiān)聽情況比頁面上的紅色警告更快定位 sudo foreman-proxy status這套棧的三段日志里foreman-proxy 的日志最容易被忽略。它的報錯大多會有明確的 timeout 或 connection refused先看它能迅速把問題邊界從“Foreman 壞了”縮小到“某個模塊沒起來”。4.4 用 runinterval 控制 Agent 的請求節(jié)奏Agent 默認每 30 分鐘連接一次 Master我在生產(chǎn)上不會把這個值調(diào)得太小。瞬時大量節(jié)點同時來請求Master 的編譯線程會被占滿表現(xiàn)是頁面正常但節(jié)點全部超時。# Agent 端配置示例 [agent] runinterval 1800 splay true splaylimit 300runinterval 單位是秒1800 就是半小時。splay 讓各節(jié)點在區(qū)間內(nèi)隨機分散啟動避免所有機器在同一秒發(fā)起請求splaylimit 限制隨機范圍的上限。不要圖省事在高峰期大批量手動觸發(fā)puppet agent -t一定要分批次比如拆成每批五十臺間隔幾分鐘。Foreman 頁面的遠程執(zhí)行功能在設(shè)計上是按主機組或主機列表分發(fā)的適合定向操作不適合全量刷。5. 上線后最常見的五個坑現(xiàn)象、原因、排查順序5.1 證書過期后 Agent 重簽不生效現(xiàn)象Agent 報證書過期運維在 Master 端執(zhí)行 clean 后重新 sign節(jié)點仍然報無法連接。原因服務(wù)端記錄刪了但節(jié)點端 SSLDir 里還是舊證書和舊私鑰。節(jié)點再次請求時拿著舊身份Master 按新簽發(fā)的記錄校驗不通過。處理先清理節(jié)點端舊證書再觸發(fā)新請求。# 節(jié)點端先清順序不能反 rm -rf /etc/puppetlabs/puppet/ssl /opt/puppetlabs/bin/puppet agent -t執(zhí)行完再回 Master 端 sign 一次。順序是關(guān)鍵先節(jié)點端清理、再服務(wù)端清理、最后重簽。反過來操作時表面上每次都能“簽成功”但節(jié)點一直用舊身份連接問題會反復(fù)出現(xiàn)。5.2 頁面一片紅smart-proxy 模塊全開但服務(wù)沒起來現(xiàn)象Foreman 頁面里 Smart Proxies 列表大面積紅色只有證書模塊正常。原因安裝時沒有顯式關(guān)閉用不到的模塊默認把 DHCP、DNS、TFTP 相關(guān)模塊全部啟用了但對應(yīng)服務(wù)或權(quán)限并未準備。處理編輯 /etc/foreman-proxy/settings.d/ 下對應(yīng)模塊的配置文件把 enabled 改為 false再重啟 foreman-proxy。用不到的模塊一定要關(guān)干凈半關(guān)閉狀態(tài)會讓頁面持續(xù)報警反而掩蓋證書模塊之外的真實故障。5.3 改了 Foreman 里的環(huán)境節(jié)點卻不動現(xiàn)象在頁面把節(jié)點從 dev 主機組切到 prod 主機組Agent 跑完后節(jié)點配置還是 dev 的。原因environment 最終以 Agent 配置文件里的 environment 字段為準主機組只是管理側(cè)標注并不會自動改寫 Agent 端的配置。處理在節(jié)點上打開 /etc/puppetlabs/puppet/puppet.conf把 environment 改成和主機組一致改完再驗證 /etc/puppetlabs/code/environments/ 下是否存在對應(yīng)名稱的目錄。目錄不存在時 Master 會退回 production 環(huán)境這也是環(huán)境切換無效的另一半原因。5.4 報表不更新但 Agent run 是成功的現(xiàn)象節(jié)點配置生效Agent 運行也報 Completed但 Foreman 的 Reports 頁面已經(jīng)幾天沒新數(shù)據(jù)。原因報表上報鏈路上出了問題。常見是 Master 的 report 配置仍指向 localhost沒有指向 Foreman或者 report 功能被關(guān)掉了。處理# 在 Master 上檢查 report 與上報地址 /opt/puppetlabs/bin/puppet config print report report_server如果 report 不是 true或者 report_server 是 localhost、空值就修改 puppet.conf 的 [master] 段把 report 打開并指向 Foreman 的 FQDN然后重啟 puppetserver。報表功能恢復(fù)后歷史數(shù)據(jù)一般會陸續(xù)補回不用手工干預(yù)。5.5 服務(wù)重啟順序有講究現(xiàn)象維護或升級后Agent 全部連接失敗Foreman 頁面也登錄不上但逐個查看服務(wù)狀態(tài)又是正常。原因三個服務(wù)之間互相依賴啟動順序錯了會陷入證書與注冊狀態(tài)互相等不到的局面。最常見的是把 Web 服務(wù)放在最前導(dǎo)致 Foreman 啟動時以錯誤的憑證去訪問 smart-proxy。處理按我這個順序重啟一次。systemctl restart foreman-proxy systemctl restart puppetserver systemctl restart httpd先讓 smart-proxy 的證書通道就緒再拉起 Master最后讓 Foreman 通過 Web 端口對外服務(wù)。這是我在某內(nèi)部管理項目里連續(xù)踩了兩次跟頭才固定的順序之后每次維護都按它執(zhí)行沒有再出現(xiàn)過“服務(wù)全正常但整體癱瘓”的怪狀態(tài)。6. 進階一步把環(huán)境劃分和代碼入庫做成常規(guī)流程6.1 環(huán)境目錄與主機組靜態(tài)映射多環(huán)境的基礎(chǔ)是目錄不是配置文件。我在 Master 上維護 /etc/puppetlabs/code/environments/ 下的 dev、staging、production 三個目錄每個目錄里都有獨立的 manifests/site.pp 和 hieradataForeman 的主機組名與它們一一對應(yīng)。新增節(jié)點的動作就收斂為兩步在 Foreman 建主機、選主機組。第一次 run 會自動進入對應(yīng)環(huán)境人工干預(yù)點只?！敖ńM、選組”兩個地方。6.2 發(fā)布前先做三層檢查改代碼不能直接丟進生產(chǎn)目錄。我一般先做語法校驗再做預(yù)演最后才同步。cd /etc/puppetlabs/code/environments/staging /opt/puppetlabs/bin/puppet parser validate manifests/site.pp /opt/puppetlabs/bin/puppet apply --noop manifests/site.pp --modulepath modulesparser validate 負責語法層預(yù)演模式會列出將要變更的資源?？搭A(yù)演結(jié)果時如果只有一兩個操作說明改動可控如果顯示要動幾十甚至上百處文件必須回到代碼里找原因。版本控制工具可以按團隊習(xí)慣選關(guān)鍵是生產(chǎn)目錄不能被直接手改。我曾因為貪圖省事把 dev 目錄的代碼直接軟鏈到 production第二天所有生產(chǎn)節(jié)點都跑上了未驗證配置。從那以后我堅持目錄分離和預(yù)演并希望幫到你。本文還有配套的精品資源點擊獲取