運(yùn)維DevOpsIaC【免費(fèi)下載鏈接】puppetServer automation framework and application項(xiàng)目地址https://gitcode.com/gh_mirrors/pu/puppet點(diǎn)擊查看免費(fèi)下載導(dǎo)讀puppet device是 Puppet 項(xiàng)目中專門用于管理遠(yuǎn)程網(wǎng)絡(luò)設(shè)備交換機(jī)、路由器等無法直接運(yùn)行 agent 的設(shè)備的子命令。它通過在普通 Puppet agent 上作為代理運(yùn)行為遠(yuǎn)程設(shè)備完成證書申請、事實(shí)收集、目錄獲取/應(yīng)用與報(bào)告上報(bào)的完整閉環(huán)。讀完本文你將掌握 device.conf 的編寫語法、puppet device全部命令行參數(shù)與退出碼語義、四種工作模式常規(guī)運(yùn)行 / --facts / --resource / --apply的用法并從源碼層面理解每個(gè)行為背后的實(shí)現(xiàn)原理。本文基于當(dāng)前倉庫中由源碼自動(dòng)生成的官方手冊 references/man/device.md并對照 lib/puppet/application/device.rb、lib/puppet/util/network_device/config.rb 等源碼與 spec/unit/application/device_spec.rb 測試用例展開。一、概述為什么要用 proxy agent 管理網(wǎng)絡(luò)設(shè)備puppet-device的功能一句話概括是Retrieves catalogs from the Puppet master and applies them to remote devices——從 Puppet 主服務(wù)器獲取目錄catalog并將它們應(yīng)用到遠(yuǎn)程設(shè)備上。絕大多數(shù)網(wǎng)絡(luò)設(shè)備如 Cisco IOS、華為等設(shè)備無法安裝完整的 Puppet agent。因此 Puppet 設(shè)計(jì)了代理 agent模式一臺可以訪問這些設(shè)備的普通 Puppet agent 節(jié)點(diǎn)充當(dāng) proxy代表設(shè)備與 Puppet 主服務(wù)器通信。文檔原文明確說明了這一架構(gòu)Devices require a proxy Puppet agent to request certificates, collect facts, retrieve and apply catalogs, and store reports.也就是說proxy agent 為每臺設(shè)備承擔(dān)四類工作request certificates—— 以設(shè)備的 certname 申請并維護(hù)證書每臺設(shè)備擁有獨(dú)立的 SSL 目錄collect facts—— 通過設(shè)備專屬的 facts terminusnetwork_device從設(shè)備采集事實(shí)retrieve and apply catalogs—— 從主服務(wù)器拉取目錄并應(yīng)用到設(shè)備store reports—— 把運(yùn)行報(bào)告回傳給主服務(wù)器。該子命令可以手動(dòng)運(yùn)行也可以借助 cron、計(jì)劃任務(wù)等工具周期性執(zhí)行This subcommand can be run manually; or periodically using cron, a scheduled task, or a similar tool.在源碼中l(wèi)ib/puppet/application/device.rb 通過app_defaults定義了該子命令的專屬默認(rèn)值從側(cè)面印證了上述架構(gòu)對應(yīng)測試見 spec/unit/application/device_spec.rb 中的 defaults the catalog_terminus setting to rest 等用例def app_defaults super.merge({ :catalog_terminus :rest, # 目錄從主服務(wù)器(REST)獲取 :catalog_cache_terminus :json, # 目錄本地 JSON 緩存 :node_terminus :rest, # 節(jié)點(diǎn)信息走 REST :facts_terminus :network_device, # 事實(shí)從網(wǎng)絡(luò)設(shè)備采集 }) end注意puppet device以:agent運(yùn)行模式啟動(dòng)run_mode :agent因此它繼承了 agent 的證書、目錄緩存等行為。二、USAGE完整命令行語法puppet device的完整用法如下與官方手冊及puppet device --help輸出一致puppet device [-h|--help] [-v|--verbose] [-d|--debug] [-l|--logdest syslog|file|console] [--detailed-exitcodes] [--deviceconfig file] [-w|--waitforcert seconds] [--libdir directory] [-a|--apply file] [-f|--facts] [-r|--resource type [name]] [-t|--target device] [--useruser] [-V|--version]一個(gè)最典型的最小化運(yùn)行示例$ puppet device --target remotehost --verbose這條命令的含義是只對device.conf中 certname 為remotehost的那臺設(shè)備執(zhí)行一次完整設(shè)備運(yùn)行拉取目錄、應(yīng)用配置、上報(bào)報(bào)告并開啟 verbose 日志。重要通用規(guī)則任何在配置文件puppet.conf中合法的設(shè)置項(xiàng)都可以作為長參數(shù)傳入例如server是合法配置參數(shù)因此可以直接寫--server servername。三、device.conf設(shè)備的注冊清單3.1 文件位置與格式被puppet device管理的設(shè)備配置在device.conf中默認(rèn)路徑$confdir/device.conf可通過--deviceconfig file參數(shù)或$deviceconfig設(shè)置項(xiàng)覆蓋。對應(yīng)設(shè)置項(xiàng)定義在 lib/puppet/defaults.rbsettings 分組:devicesettings.define_settings(:device, :devicedir { :default $vardir/devices, :type :directory, :mode 0750, :owner service, :group service, :desc The root directory of devices $vardir., }, :deviceconfig { :default $confdir/device.conf, :desc Path to the device config file for puppet device., } )device.conf 是一個(gè)INI 風(fēng)格文件每個(gè)設(shè)備一個(gè) section格式如下[DEVICE_CERTNAME] type TYPE url URL debug各部分語義行含義[DEVICE_CERTNAME]section 名即該設(shè)備的certname證書名稱type TYPE設(shè)備類型provider對應(yīng)具體的網(wǎng)絡(luò)設(shè)備實(shí)現(xiàn)url URL設(shè)備訪問地址type與url的具體取值隨設(shè)備類型而異debug可選屬性開啟傳輸層調(diào)試僅 telnet 與 ssh 傳輸可用3.2 解析器源碼語法細(xì)節(jié)與校驗(yàn)邏輯lib/puppet/util/network_device/config.rb 實(shí)現(xiàn)了 device.conf 的解析其parse方法揭示了若干容易被忽略的細(xì)節(jié)注釋與空行以#開頭的行和空行會(huì)被跳過section 匹配只接受形如^\[([\w.-])\]$的 section 名單詞字符、點(diǎn)、連字符重復(fù)定義同一設(shè)備會(huì)直接報(bào)錯(cuò)Duplicate device found at ...指令白名單每一行只允許type、url、debug三種指令正則^\s*(type|url|debug)(\s(.)\s*)*$其他內(nèi)容一律報(bào) Invalid entry at ...url 校驗(yàn)url指令的值會(huì)先經(jīng)過URI.parse校驗(yàn)非法 URL 會(huì)報(bào) ...is an invalid urldebug 開關(guān)debug指令會(huì)把device.options[:debug]置為true見parse_directive。解析結(jié)果被包裝為OpenStruct包含namecertname、providertype 值、url、options等字段。3.3 type 與 url 的語義從設(shè)備基類看傳輸層解析type的值決定了加載哪個(gè)設(shè)備實(shí)現(xiàn)。在 lib/puppet/util/network_device.rb 的init方法中def self.init(device) require puppet/util/network_device/#{device.provider}/device current Puppet::Util::NetworkDevice.const_get(device.provider.capitalize).const_get(:Device).new(device.url, device.options) rescue detail raise detail, _(Cant load %{provider} for %{device}: %{detail}) % { provider: device.provider, device: device.name, detail: detail } end即type直接對應(yīng)puppet/util/network_device/type/device下的實(shí)現(xiàn)類加載失敗時(shí)會(huì)明確提示 Cant load for 。設(shè)備基類 lib/puppet/util/network_device/base.rb 則展示了url的完整解析約定url按URI解析scheme決定傳輸類型ssh、telnet 等通過 Autoloader 加載對應(yīng)transport/scheme實(shí)現(xiàn)端口默認(rèn)值未顯式指定端口時(shí)ssh默認(rèn) 22、telnet默認(rèn) 23用戶名與密碼從 URL 的user:passwordhost部分提取用于建立傳輸連接。典型的url形如ssh://user:passtesthost或https://user:passtesthost/some/path后者可見于測試用例 spec/unit/application/device_spec.rb 的 device_hash 定義。四、OPTIONS全部命令行參數(shù)詳解通用規(guī)則再強(qiáng)調(diào)一次任何在配置文件里合法的設(shè)置項(xiàng)都可以作為長參數(shù)傳給本命令例如--server servername。參數(shù)說明--help, -h打印幫助信息--verbose, -v開啟 verbose 報(bào)告--debug, -d開啟完整調(diào)試輸出--logdest, -l日志去向syslogPOSIX syslog 服務(wù)、console或日志文件路徑支持逗號分隔多目的地如/path/file1,console,/path/file2。開啟 debug/verbose 時(shí)默認(rèn)console否則默認(rèn)syslog。以.json結(jié)尾的路徑接收 JSON 結(jié)構(gòu)化日志由于日志是追加寫入文件末尾不會(huì)自動(dòng)補(bǔ)]需手動(dòng)追加以構(gòu)成合法 JSON--detailed-exitcodes通過退出碼攜帶事務(wù)信息見下文退出碼語義--deviceconfig設(shè)備配置文件路徑默認(rèn)$confdir/device.conf--waitforcert, -w僅對尚未持有證書的目標(biāo)生效默認(rèn)啟用且值為 120秒即每 2 分鐘輪詢主服務(wù)器請求簽署證書設(shè)為 0 可關(guān)閉等待。適用于目標(biāo)設(shè)備的初始配置--libdir用本地目錄覆蓋每設(shè)備的 libdir指定 libdir 同時(shí)會(huì)禁用 pluginsync適合測試場景。以.jsonl結(jié)尾的路徑接收 JSON Lines 結(jié)構(gòu)化輸出--apply針對遠(yuǎn)程目標(biāo)應(yīng)用一份 manifest必須同時(shí)指定--target--facts顯示遠(yuǎn)程目標(biāo)的事實(shí)必須同時(shí)指定--target--resource以 Puppet 代碼形式顯示資源狀態(tài)功能近似于puppet resource可按 title 過濾必須同時(shí)指定--target--target指定 device.conf 中的某臺設(shè)備/證書只對這臺設(shè)備執(zhí)行設(shè)備運(yùn)行--to_yaml以 YAML 格式輸出發(fā)現(xiàn)的資源適合配合 Hiera 與create_resources使用--user以指定用戶身份運(yùn)行4.1 參數(shù)校驗(yàn)邏輯源碼確認(rèn)lib/puppet/application/device.rb 的main方法開頭對參數(shù)組合做了強(qiáng)校驗(yàn)對應(yīng)測試見 spec/unit/application/device_spec.rb--resource未指定--target→ 報(bào)錯(cuò)resource command requires target--facts未指定--target→ 報(bào)錯(cuò)facts command requires target--apply未指定--target→ 報(bào)錯(cuò)missing argument: --target is required when using --apply--apply指定的 manifest 文件不存在 → 報(bào)錯(cuò)file does not exist, cannot apply--target指定的設(shè)備不在 device.conf 中 → 報(bào)錯(cuò)Target device / certificate name not found in deviceconfigdevice.conf 中沒有任何設(shè)備 → 輸出錯(cuò)誤并exit(1)。4.2 各參數(shù)在源碼中的對應(yīng)實(shí)現(xiàn)--target、--waitforcert、--apply、--resource、--facts、--to_yaml、--libdir、--logdest、--detailed-exitcodes均在option聲明中注冊見lib/puppet/application/device.rb的option(...)區(qū)塊--waitforcert的值被轉(zhuǎn)為整數(shù)存入options[:waitforcert]隨后在setup_context中傳給Puppet::SSL::StateMachine.new(waitforcert: ...)用于證書簽發(fā)等待測試 defaults waitforcert to 0、uses a default value for waitforcert when --onetime and --waitforcert are not specified 驗(yàn)證了默認(rèn) 120 秒的行為運(yùn)行--resource/--facts/--apply三種模式時(shí)setup方法會(huì)把日志目的地強(qiáng)制設(shè)為:console因?yàn)樗鼈儽举|(zhì)是交互式查詢。五、四種工作模式puppet device依據(jù)參數(shù)組合進(jìn)入四種不同模式5.1 常規(guī)設(shè)備運(yùn)行默認(rèn)模式不帶--resource/--facts/--apply時(shí)對所有或--target指定的設(shè)備執(zhí)行完整運(yùn)行為設(shè)備創(chuàng)建專屬目錄并設(shè)置隔離的ssldir/confdir/libdir/vardir/certname見下文多設(shè)備隔離調(diào)用setup_context建立 SSL 上下文必要時(shí)等待證書簽發(fā)未指定--libdir時(shí)執(zhí)行 pluginsync下載設(shè)備插件通過Puppet::Util::NetworkDevice.init(device)初始化設(shè)備單例創(chuàng)建Puppet::Configurer并調(diào)用configurer.run(:network_device true, :pluginsync false)完成目錄獲取、應(yīng)用與報(bào)告上報(bào)。啟動(dòng)日志會(huì)打印目標(biāo)與連接信息形如starting applying configuration to device1 at ssh://testhost5.2 --facts查看遠(yuǎn)程設(shè)備事實(shí)$ puppet device --target remotehost --facts通過Puppet::Node::Facts.indirection.find從設(shè)備采集事實(shí)并以:console渲染器輸出。事實(shí)的采集實(shí)現(xiàn)位于 lib/puppet/indirector/facts/network_device.rbdef find(request) result Puppet::Node::Facts.new(request.key, Puppet::Util::NetworkDevice.current.facts) result.add_local_facts result.sanitize result end即從當(dāng)前設(shè)備單例的facts方法取得事實(shí)再補(bǔ)充本地事實(shí)并做清洗處理。該 terminus 明確禁止遠(yuǎn)程請求allow_remote_requests?返回false且destroy/save都會(huì)拋出DevError——它只負(fù)責(zé)從遠(yuǎn)程設(shè)備讀取事實(shí)。5.3 --resource查看設(shè)備資源狀態(tài)$ puppet device --target remotehost --resource user $ puppet device --target remotehost --resource user jim用法與puppet resource類似可指定類型與可選的 title指定 name →Puppet::Resource.indirection.find(type/name)查找單個(gè)資源不指定 name →Puppet::Resource.indirection.search(type/, {})搜索該類型全部資源。輸出為 Puppet 代碼形式的資源聲明如user { jim: ensure absent }。配合--to_yaml時(shí)輸出 YAML形如--- user: title: ensure: absent適用于 Hiera 數(shù)據(jù)與create_resources。注意未指定類型時(shí)直接報(bào)錯(cuò)You must specify the type to display類型不存在時(shí)報(bào)Could not find type type。5.4 --apply直接把 manifest 應(yīng)用到設(shè)備$ puppet device --target remotehost --apply site.pp針對遠(yuǎn)程目標(biāo)應(yīng)用本地 manifest。從源碼看該模式會(huì)把報(bào)告 terminus 改為:yaml避免向服務(wù)器上報(bào)純本地應(yīng)用關(guān)閉目錄緩存catalog_cache_terminus nil將node_terminus設(shè)為:plain、catalog_terminus設(shè)為:compiler本地編譯目錄保持facts_terminus :network_device事實(shí)仍從設(shè)備采集在:network_device true覆蓋下復(fù)用puppet apply的執(zhí)行邏輯Puppet::Application::Apply.new(...).run_command。六、退出碼語義--detailed-exitcodes啟用--detailed-exitcodes后退出碼攜帶完整的事務(wù)信息退出碼含義1至少一臺設(shè)備發(fā)生編譯失敗2至少一臺設(shè)備發(fā)生資源變更4至少一臺設(shè)備發(fā)生資源失敗3/5/6/7上述退出碼的按位組合例如31|2既有編譯失敗又有資源變更71|2|4三類情況同時(shí)發(fā)生。源碼實(shí)現(xiàn)lib/puppet/application/device.rb的main結(jié)尾每臺設(shè)備的運(yùn)行結(jié)果被收集后在--detailed-exitcodes下用按位或合并exit(returns.compact.reduce(:|))。測試用例也覆蓋了這些語義例如 exits 6 when --detailed-exitcodes and failed run6 2|4與 exits 1 when --detailed-exitcodes and failed parse7 1|2|4。未啟用--detailed-exitcodes時(shí)任一設(shè)備返回 1 則整體退出 1否則退出 0。七、多設(shè)備隔離機(jī)制每設(shè)備獨(dú)立的目錄與證書這是puppet device區(qū)別于普通 agent 的關(guān)鍵設(shè)計(jì)。在 lib/puppet/application/device.rb 的main中處理每臺設(shè)備時(shí)會(huì)臨時(shí)覆蓋本地設(shè)置并在ensure中恢復(fù)設(shè)置每設(shè)備取值說明ssldir$deviceconfdir/設(shè)備certname/ssl設(shè)備獨(dú)立的 SSL 目錄confdir$devicedir/設(shè)備certname設(shè)備獨(dú)立的 conf 目錄libdir--libdir指定值或$devicedir/設(shè)備certname/lib設(shè)備插件目錄vardir$devicedir/設(shè)備certname設(shè)備獨(dú)立的數(shù)據(jù)目錄certname設(shè)備 section 名設(shè)備身份其中$devicedir默認(rèn)$vardir/devices$deviceconfdir默認(rèn)$confdir/devices見 lib/puppet/defaults.rb 中的:devicedir與:deviceconfdir定義兩者目錄模式均為0750。對應(yīng)測試用例 sets ssldir relative to the global confdir、sets vardir to the device vardir、sets certname to the device certname 等對此做了逐一驗(yàn)證。兩點(diǎn)實(shí)現(xiàn)細(xì)節(jié)值得注意SSL 目錄符號鏈接PUP-8736 的 workaroundSSL 證書實(shí)際存放在緩存目錄之外并在$confdir/設(shè)備/ssl保留符號鏈接防止緩存清理時(shí)誤刪證書運(yùn)行后恢復(fù)全局設(shè)置每臺設(shè)備處理完含異常路徑都會(huì)在ensure塊中把libdir/vardir/confdir/ssldir/certname恢復(fù)為初始值確保多臺設(shè)備之間互不污染測試 resets the vardir setting after the run、resets the certname setting after the run 驗(yàn)證了這一行為。八、networking 與 Provider 機(jī)制從資源到設(shè)備的調(diào)用鏈設(shè)備 provider 的基類位于 lib/puppet/provider/network_device.rb它定義了從設(shè)備讀取資源 → 與 catalog 期望對比 → 生成變更的抽象骨架prefetch(resources)批量預(yù)取——對每個(gè)資源通過Puppet::Util::NetworkDevice.current當(dāng)前設(shè)備單例或device(resource[:device_url])取得設(shè)備再調(diào)用lookup(device, name)查詢真實(shí)狀態(tài)據(jù)此為資源裝配 provider存在則ensure :present否則ensure :absentcreate/destroy/flush在property_hash中維護(hù)期望狀態(tài)最終由具體 provider 實(shí)現(xiàn)落盤到設(shè)備instances默認(rèn)為空實(shí)現(xiàn)具體設(shè)備 provider 需自行實(shí)現(xiàn)。結(jié)合 lib/puppet/util/network_device.rb 的單例初始化與 lib/puppet/indirector/facts/network_device.rb 的事實(shí) terminus整個(gè)數(shù)據(jù)流可以概括為puppet device └─ Puppet::Util::NetworkDevice.init(device) # 按 type 加載設(shè)備實(shí)現(xiàn)并建立傳輸 ├─ facts terminus (network_device) # 設(shè)備事實(shí) → catalog 編譯輸入 └─ provider 基類 prefetch/lookup # 設(shè)備實(shí)時(shí)狀態(tài) → 資源對賬即事實(shí)經(jīng) network_device terminus 進(jìn)入目錄編譯資源狀態(tài)經(jīng) provider 基類的 prefetch 機(jī)制與目錄期望對比最終由設(shè)備實(shí)現(xiàn)把變更寫回設(shè)備。九、與 puppet agent 的關(guān)系及適用場景適用場景網(wǎng)絡(luò)設(shè)備如交換機(jī)、路由器、防火墻無法承載完整 agent需要通過一臺可達(dá)這些設(shè)備的 proxy agent 代為管理puppet device正是這一場景的標(biāo)準(zhǔn)入口周期性運(yùn)行文檔明確指出可用 cron、計(jì)劃任務(wù)等方式周期調(diào)用實(shí)現(xiàn)設(shè)備的持續(xù)配置管理證書生命周期--waitforcert默認(rèn) 120 秒的輪詢機(jī)制專門服務(wù)于新設(shè)備首次接入CSR 等待主服務(wù)器簽署簽署完成后即可正常執(zhí)行測試友好--libdir覆蓋本地目錄并禁用 pluginsync便于在不依賴插件分發(fā)的情況下調(diào)試設(shè)備 provider。十、常見問題速查現(xiàn)象原因與處理resource command requires target--resource/--facts必須與--target搭配missing argument: --target is required when using --apply--apply必須指定--targetTarget device / certificate xxx not found in ...device.conf 中不存在該 certname檢查 section 名與--deviceconfig路徑Duplicate device found at ...device.conf 中重復(fù)定義了同一設(shè)備 sectionCant load type for devicetype值沒有對應(yīng)的設(shè)備實(shí)現(xiàn)puppet/util/network_device/type/device退出碼3/5/6/7--detailed-exitcodes下按位組合1編譯失敗、2資源變更、4資源失敗首次接入設(shè)備一直等待--waitforcert 120默認(rèn)每 2 分鐘輪詢一次請求簽署證書可去主服務(wù)器側(cè)簽署或設(shè)-w 0跳過等待延伸閱讀倉庫內(nèi)命令入口與全部模式實(shí)現(xiàn)lib/puppet/application/device.rbdevice.conf 解析器INI 語法、校驗(yàn)、報(bào)錯(cuò)信息lib/puppet/util/network_device/config.rb設(shè)備單例初始化與 provider 按 type 加載lib/puppet/util/network_device.rb設(shè)備實(shí)現(xiàn)基類URL/傳輸解析約定lib/puppet/util/network_device/base.rb設(shè)備事實(shí) terminuslib/puppet/indirector/facts/network_device.rb網(wǎng)絡(luò)設(shè)備 provider 基類lib/puppet/provider/network_device.rb相關(guān)設(shè)置項(xiàng)devicedir/deviceconfig/deviceconfdirlib/puppet/defaults.rb單元測試參數(shù)、隔離、退出碼、四種模式的行為驗(yàn)證spec/unit/application/device_spec.rb官方手冊原文references/man/device.md本文依據(jù)倉庫內(nèi) references/man/device.md 編寫相關(guān)實(shí)現(xiàn)與行為均對照 lib/puppet/application/device.rb 等源碼及 spec/unit/application/device_spec.rb 測試用例核實(shí)。贊分享運(yùn)維DevOpsIaC【免費(fèi)下載鏈接】puppetServer automation framework and application項(xiàng)目地址https://gitcode.com/gh_mirrors/pu/puppet點(diǎn)擊查看免費(fèi)下載相關(guān)推薦Developer Device Platform通過 Device Catalog 查詢設(shè)備詳情Describe Device并預(yù)留遠(yuǎn)程 Android 設(shè)備實(shí)戰(zhàn)Developer Device Platform通過 Device Catalog 查詢設(shè)備詳情Describe Device并預(yù)留遠(yuǎn)程 AndroidAI 技能人工智能大模型Salt Delta Proxy Minion 安裝與配置實(shí)戰(zhàn)指南用單個(gè) minion 管理海量網(wǎng)絡(luò)設(shè)備Salt Delta Proxy Minion 安裝與配置實(shí)戰(zhàn)指南用單個(gè) minion 管理海量網(wǎng)絡(luò)設(shè)備 本指南是 Salt 項(xiàng)目官方文檔 doc/ref/運(yùn)維配置管理后端終極指南如何使用Netmiko實(shí)現(xiàn)網(wǎng)絡(luò)設(shè)備配置的批量自動(dòng)化管理終極指南如何使用Netmiko實(shí)現(xiàn)網(wǎng)絡(luò)設(shè)備配置的批量自動(dòng)化管理 Netmiko作為一款多廠商網(wǎng)絡(luò)設(shè)備SSH連接管理庫能夠幫助網(wǎng)絡(luò)工程師輕松實(shí)現(xiàn)對Cisco、網(wǎng)絡(luò)通信后端上一篇深入解析Graphtage結(jié)構(gòu)化數(shù)據(jù)的語義比較與合并工具下一篇MinIO 使用 KMS 加密 IAM 與配置數(shù)據(jù)MINIO_KMS_SECRET_KEY 靜態(tài)密鑰與 KES 接入實(shí)戰(zhàn)創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考