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