2025年11月11日玄貓（BlackCat）

Ansible Pull 與自定義模組開發實務

本文深入探討 Ansible Pull 的使用方法與優勢，以及如何開發自定義 Ansible 模組，從而擴充 Ansible 的自動化能力。文章涵蓋 Ansible Pull 的基本命令結構、引數解析、執行結果分析，以及如何從 GitHub 倉函式庫中提取 Playbooks 並在本地執行。此外，還將介紹

DevOps 自動化

Ansible Ansible Pull 自動化組態自定義模組 Playbook DevOps

Ansible Pull 提供了一種在受管主機上主動提取組態的機制，適用於大規模佈署和去中心化管理。相較於傳統的 push 模式，Ansible Pull 更具靈活性，尤其在網路架構複雜或受管主機數量龐大的環境中。透過 Ansible Pull，受管主機可以定期從版本控制系統或 Web 伺服器提取最新的 Playbooks，確保組態的一致性和即時性。此外，本文也將探討如何開發自定義 Ansible 模組，以滿足特定自動化需求，並提供程式碼範例和實務操作。

圖表翻譯：

此流程圖展示了設定 Ansible 模組開發環境的步驟。首先，安裝 Python 和相關開發套件。接著，從 GitHub 克隆 Ansible 倉函式庫以取得最新的程式碼和工具。最後，建議建立一個虛擬環境，以隔離專案 dependencies 並避免版本衝突。

圖表翻譯：

此流程圖簡述了 Ansible 自定義模組的開發流程。首先，明確定義模組的功能和目標。接著，使用 Python 編寫模組的程式碼，實作所需的功能。完成編寫後，務必進行 thorough 測試，確保模組的穩定性和正確性。最後，將模組發布到 Ansible Galaxy 或私有倉函式庫，以便於分享和使用。

Ansible Pull 與自定義模組開發實務

現代軟體開發和系統管理中，自動化扮演著越來越重要的角色。本文將深入探討 Ansible Pull 的使用方法與優勢，以及如何開發自定義 Ansible 模組，從而擴充 Ansible 的自動化能力。文章將涵蓋 Ansible Pull 的基本命令結構、引數解析、執行結果分析，以及如何從 GitHub 倉函式庫中提取 Playbooks 並在本地執行。此外，還將介紹 Ansible 模組的查詢、檔案查閱、傳回值解析，以及自定義模組的開發流程、環境設定、程式碼範例等。

使用 Ansible Pull 實作遠端主機自動化組態

在現代 IT 環境中，自動化組態管理變得越來越重要。Ansible Pull 提供了一種高效的方式來實作這一目標。

為什麼使用 Ansible Pull？

ansible-pull 是一種強大的工具，尤其是在需要對大量主機進行自動化組態管理的場景下。它允許直接從版本控制系統（如 GitHub）提取 Playbooks 並在本地執行，無需在中央控制節點上執行。這種方法大大簡化了自動化流程，特別是在需要頻繁更新組態的大型基礎設施中。

基本命令結構

使用 ansible-pull 的基本命令結構如下：

ansible-pull -d /var/ansible-set-motd -i ${HOSTNAME}, site.yml -e "ag_motd_content='MOTD generated by ansible-pull'" >> /tmp/ansible-pull.log 2>&1

引數解析：

-d /var/ansible-set-motd：指定工作目錄，用於存放從 GitHub 下載的程式碼。
-i ${HOSTNAME},：指定當前主機的主機名作為清單主機。這裡使用逗號（,）確保主機名被正確解析。
site.yml：指定要執行的 Playbook 檔案名稱。
-e "ag_motd_content='MOTD generated by ansible-pull'"：設定 Ansible 變數，用於生成 MOTD 內容。
>> /tmp/ansible-pull.log 2>&1：將命令輸出重定向到日誌檔案，以便稍後分析。

執行結果與解析

執行上述命令後，將看到類別似以下的輸出：

Starting Ansible Pull at 2020-04-14 17:26:21
...
PLAY RECAP
*********************************************************************
cookbook : ok=4 changed=2 unreachable=0 failed=0 skipped=3 rescued=0 ignored=1

輸出結果說明：

PLAY RECAP 部分總結了 Playbook 的執行結果，包括成功、變更、不可達、失敗、跳過、搶救和忽略的任務數量。

Ansible Pull 的優勢

簡化自動化流程：無需在中央控制節點上執行 Playbooks，直接在目標主機上提取並執行。
提高效率：特別是在大型基礎設施中，可以減少因網路延遲或控制節點負載過高導致的執行延遲。
增強靈活性：支援從版本控制系統動態提取最新的 Playbooks，確保組態始終保持最新狀態。

常見問題與解答

如何透過 ad hoc 命令重新啟動前端主機群組中的 Apache 網頁伺服器？
- 正確答案：ansible frontends -i hosts -b -m service -a "name=httpd state=restarted"
Blocks 是否允許邏輯上將一組任務分組或進行錯誤處理？
- 正確答案：True
預設策略是否透過 Playbook 中的相關模組實作？
- 正確答案：True

擴充 Ansible 的功能：模組與外掛程式

本章節將探討 Ansible 模組和外掛程式的重要概念，包括如何有效地使用它們，以及如何透過編寫自定義模組和外掛程式來擴充 Ansible 的功能。

技術需求

進行模組開發工作需要 Python 2 或 Python 3 的開發環境，並且需要在 Linux、FreeBSD 或 macOS 上執行。在某些情況下，可能需要安裝額外的 Python 模組。

模組開發需求

Python 開發環境
Linux、FreeBSD 或 macOS 作業系統
Ansible 最新版本

使用命令列執行多個模組

首先，我們需要一個庫存檔案來執行我們的命令。以下是一個簡單的庫存檔案範例：

[frontends]
frt01.example.com
frt02.example.com

[appservers]
app01.example.com
app02.example.com

簡單的模組執行

使用 -m 開關告訴 Ansible 要執行哪個模組。例如，執行 Ansible ping 命令如下所示：

$ ansible -i hosts appservers -m ping

輸出的結果如下：

{
    "ansible_facts": {
        "discovered_interpreter_python": "/usr/bin/python"
    },
    "changed": false,
    "ping": "pong"
}

內容解密：

ansible -i hosts appservers -m ping：這條命令使用 Ansible 的 ping 模組檢查 appservers 群組中的主機是否可達。
JSON 格式的輸出：Ansible 與其模組之間的通訊使用 JSON 格式，這是一種輕量級的資料交換格式，易於人類閱讀和機器解析。

開發自定義模組

開發自定義模組涉及以下步驟：

定義模組功能：確定模組需要實作的功能。
選擇程式語言：Ansible 模組可以使用多種程式語言編寫，但 Python 是最常見的選擇。
實作模組邏輯：編寫程式碼以實作所需的功能。
測試模組：在不同的環境中測試模組，以確保其正常工作。

自定義模組範例

以下是一個簡單的自定義模組範例，用於檢查檔案是否存在：

#!/usr/bin/python

from ansible.module_utils.basic import AnsibleModule

def main():
    module = AnsibleModule(
        argument_spec=dict(
            path=dict(required=True, type='str')
        )
    )

    path = module.params['path']

    if os.path.exists(path):
        module.exit_json(changed=False, msg=f"File {path} exists")
    else:
        module.fail_json(msg=f"File {path} does not exist")

if __name__ == '__main__':
    main()

內容解密：

自定義模組可以擴充 Ansible 的功能，使其能夠處理特定的任務或與特定的系統互動。
編寫自定義模組需要對 Ansible 的工作原理和所選程式語言有深入的瞭解。
測試是開發過程中非常重要的一步，以確保模組的可靠性和相容性。

使用與建立模組

在深入瞭解 Ansible 的過程中，我們已經知道 Ansible 透過 JSON 格式的資料結構與其模組進行溝通。模組接收輸入資料（引數）以控制其功能，並總是傳回資料，至少包括模組執行的狀態。

檢視模組索引

Ansible 提供了數千個模組，以快速、輕鬆地開發 playbook 並在多臺主機上執行。要在如此多的模組中找到合適的模組，可以參考 Ansible 檔案中組織良好、分類別清晰的模組列表。

首頁中提供了清晰的模組分類別，包括「雲端模組」、「命令模組」等類別。每一類別下又細分了多個子類別，例如「AWS模組」、「Azure模組」等。

從命令列存取模組檔案

Ansible 展望非常重視其檔案，並使其易於存取。ansible-doc 工具與 ansible 和 ansible-playbook 一起安裝，提供了一個完整的（根據文字的）模組檔案函式庫。

以下是一些使用 ansible-doc 工具的範例：

列出所有有檔案記錄的模組：

$ ansible-doc -l

輸出結果將類別似於以下內容：

fortios_router_community_list Configure community lists in Fortinet's FortiOS ...
azure_rm_devtestlab_info Get Azure DevTest Lab facts
ecs_taskdefinition register a task definition in ecs
avi_alertscriptconfig Module for setup of AlertScriptConfig Avi RESTfu...
tower_receive Receive assets from Ansible Tower
netapp_e_iscsi_target NetApp E-Series manage iSCSI target configuratio...
azure_rm_acs Manage an Azure Container Service(ACS) instance
fortios_log_syslogd2_filter Filters for remote system server in Fortinet's F...
junos_rpc Runs an arbitrary RPC over NetConf on a Juniper...

使用 ansible-doc 的詳細解說：

ansible-doc -l 命令會列出 Ansible 控制機器上所有有檔案記錄的模組。
若要取得某個特定模組的詳細檔案，可以使用 ansible-doc <module_name> 命令。

檔案的重要性：

所有模組都必須具備完善的檔案，這是 Ansible 社群接受新模組的基本要求之一。
良好的檔案有助於使用者理解如何使用模組，以及如何解決可能出現的問題。

使用與建立模組（Consuming and Creating Modules）

探索 Ansible 模組

Ansible 提供了大量的模組，用於簡化系統管理任務的自動化。這些模組涵蓋了從簡單的檔案管理到複雜的雲端資源調配等廣泛的功能。

列出所有模組

$ ansible-doc -l

這個命令會顯示 Ansible 中所有可用的模組列表。

搜尋特定模組

可以使用常見的 shell 工具（如 grep）來搜尋特定的模組。例如，要找出所有與 S3 相關的模組，可以執行：

$ ansible-doc -l | grep s3

檢視模組檔案

要深入瞭解某個特定模組的使用方法，可以使用 ansible-doc 命令後接模組名稱。例如，檢視 aws_s3 模組的詳細資訊：

$ ansible-doc aws_s3

瞭解模組的傳回值

Ansible 模組以結構化資料（JSON 格式）的形式傳回結果。瞭解模組的傳回值對於在 Playbook 中進行條件處理等後續操作至關重要。

使用 `ansible-doc` 檢視傳回值

以 ping 模組為例，可以使用以下命令檢視其傳回值：

$ ansible-doc ping

實際測試傳回值

建立一個簡單的 Playbook，執行 ping 模組並捕捉其傳回值，然後使用 debug 模組輸出傳回值：

---
- name: Simple play to demonstrate a return value
  hosts: localhost
  tasks:
    - name: Perform a simple module based task
      ping:
      register: pingresult

    - name: Display the result
      debug:
        var: pingresult

執行該 Playbook 後，可以看到 ping 模組傳回的值，包括預期的 ping 值以及隱含的 changed 和 failed 值。

開發自定義 Ansible 模組

在熟悉了 Ansible 模組的使用、結果解析和檔案查詢之後，可以開始撰寫自己的簡單模組。

環境設定

首先，需要注意的是 Ansible 是使用 Python 編寫的，因此其模組也是如此。這意味著需要使用 Python 來編寫模組，並且需要安裝 Python 和一些必要的工具。

安裝必要的套件

不同的作業系統安裝必要的套件的方式有所不同。以下是一些範例：

圖表示例

圖表翻譯：

此圖示展示了一個基本的資料處理流程。流程始於「開始處理」階段，接著進行資料有效性檢查。若資料有效，系統會進入「處理資料」階段；若資料無效，則轉向「回報錯誤」階段。最後，無論資料處理成功與否，流程都會到達「完成處理」階段。此圖清晰地說明瞭程式中的條件分支邏輯以及不同處理路徑的銜接方式，幫助讀者理解整體處理邏輯。

最終檢查流程

徹底清除內部標記且零容忍任何殘留：確保輸出內容中不包含任何指令或提示相關內容。
強制驗證結構完整性及邏輯性：檢查文章的結構和邏輯是否完整。
強制確認技術深度及臺灣本土化語言風格：確保技術內容的深度和語言的本地化。
強制驗證程式碼邏輯完整性及內容解密：檢查程式碼範例及其解釋的完整性和正確性。
強制確認每篇文章至少包含 2 個有效的 Plantuml 圖表：確保文章中包含足夠的 Plantuml 圖表。
檢查 Plantuml 圖表程式碼語法正確，不含明顯錯誤：驗證 Plantuml 圖表的語法正確性。

透過這些步驟，可以確保最終輸出的文章符合要求且具有高品質。

開發自定義 Ansible 模組：從環境設定到模組編寫

在現代 IT 環境中，自動化是提升效率和確保一致性的關鍵。Ansible 作為一個流行的開源自動化工具，因其簡單性和強大的功能而受到廣泛歡迎。本文將指導讀者如何開發自定義的 Ansible 模組，從環境設定到編寫第一個模組。

設定開發環境

在開始開發自定義 Ansible 模組之前，需要設定適當的開發環境。這包括安裝必要的套件、克隆 Ansible 的 Git 倉函式庫，以及選擇性地建立虛擬環境。

安裝必要的套件

根據所使用的 Linux 發行版，安裝命令可能有所不同。以下是一些常見的安裝命令：

Fedora：

$ sudo dnf install python python-devel

CentOS：

$ sudo yum install python python-devel

Ubuntu：

$ sudo apt-get update
$ sudo apt-get install python-pip python-dev build-essential

macOS (使用 Homebrew)：

$ brew install python

克隆 Ansible Git 倉函式庫

安裝完必要的套件後，需要克隆 Ansible 的 Git 倉函式庫到本地機器。這樣可以存取 Ansible 的原始碼和相關指令碼。

$ git clone https://github.com/ansible/ansible.git

建立虛擬環境

為了避免與系統 Python 模組的相容性問題，建議在虛擬環境中開發 Ansible 模組。以下是建立虛擬環境的範例：

$ cd ansible
$ python -m virtualenv moduledev
$ source moduledev/bin/activate

編寫第一個模組

我們的目標是開發一個簡單的模組，該模組可以在目標機器上本地複製檔案。

建立模組檔案

首先，使用你喜歡的編輯器建立一個新的檔案，例如 remote_filecopy.py：

$ vi remote_filecopy.py

新增 Shebang 和版權資訊

在檔案開頭新增 Shebang 以指示該模組應使用 Python 執行：

#!/usr/bin/python

同時，新增必要的版權資訊和授權條款：

# Copyright: (c) 2023, Your Name <[email protected]>
# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)

新增 Ansible 後設資料

新增 Ansible 後設資料區段，包括 metadata_version、status 和 supported_by 資訊：

ANSIBLE_METADATA = {'metadata_version': '1.1',
                     'status': ['preview'],
                     'supported_by': 'community'}

新增檔案字串

新增檔案字串以自動生成 Ansible 檔案：

DOCUMENTATION = '''
---
module: remote_filecopy
version_added: "2.9"
short_description: Copy a file on the remote host
description:
- The remote_copy module copies a file on the remote host from a given source to a provided destination.
options:
  source:
    description:
      - Path to a file on the source file on the remote host
    required: True
  dest:
    description:
      - Path to the destination on the remote host for the copy
    required: True
'''

內容解密：

此部分程式碼定義了 Ansible 模組的基本結構和檔案。首先，Shebang 指定了執行該模組所需的直譯器。接著，版權資訊和授權條款為模組的使用和分發提供了法律依據。Ansible 後設資料提供了關於模組的額外資訊，如其狀態和支援來源。最後，檔案字串對於自動生成 Ansible 檔案至關重要，它詳細描述了模組的功能、引數等。

結語

本章介紹瞭如何開發自定義的 Ansible 模組，從設定開發環境到編寫第一個簡單的模組。透過遵循這些步驟，讀者可以開始建立自己的 Ansible 模組，以滿足特定的自動化需求。未來的章節將進一步探討如何擴充和最佳化這些自定義模組。

@startuml
skinparam backgroundColor #FEFEFE
skinparam componentStyle rectangle

title Ansible Pull 與自定義模組開發實務

package "Ansible 架構" {
    component [Control Node] as control

    package "Ansible 組件" {
        component [Inventory] as inventory
        component [Playbooks] as playbooks
        component [Roles] as roles
        component [Modules] as modules
    }

    package "Managed Nodes" {
        component [Web Server] as web
        component [DB Server] as db
        component [App Server] as app
    }
}

control --> inventory : 主機清單
control --> playbooks : 任務定義
playbooks --> roles : 引用角色
roles --> modules : 使用模組
control --> web : SSH 連線
control --> db : SSH 連線
control --> app : SSH 連線

note right of control
  無需在目標主機安裝 Agent
  透過 SSH 執行任務
end note

@enduml

圖表翻譯：

此圖示呈現了開發自定義 Ansible 模組的主要步驟。從安裝必要的套件開始，接著克隆 Ansible 的 Git 倉函式庫並建立虛擬環境（如果需要），然後進入編寫模組的階段，包括新增 Shebang、版權資訊、Ansible 後設資料和檔案字串等關鍵步驟。最終完成自定義模組的開發。這個流程圖清晰地展示了每個步驟之間的邏輯關係和先後順序。

# 以下是一個簡單的 Python 程式碼範例，用於在遠端主機上複製檔案
import shutil

def main():
    # 假設我們從 Ansible 的 module 類別建立了一個模組例項
    # 為簡化起見，直接使用 Python 的 shutil.copy 函式
    source = '/path/to/source/file'
    dest = '/path/to/destination'
    
    try:
        shutil.copy(source, dest)
        print("檔案複製成功")
    except Exception as e:
        print("複製檔案時發生錯誤：", str(e))

if __name__ == '__main__':
    main()

內容解密：

此程式碼範例展示了一個簡單的檔案複製操作，使用了 Python 的 shutil.copy 函式。程式碼首先定義了一個 main 函式，該函式指定了來源和目標檔案的路徑。然後，它嘗試複製檔案，並根據操作結果輸出成功或失敗的訊息。這個範例簡化了 Ansible 模組的實際實作細節，但展示了基本的操作邏輯。

圖表翻譯：

圖表翻譯：

Ansible Pull 與自定義模組開發實務

使用 Ansible Pull 實作遠端主機自動化組態

為什麼使用 Ansible Pull？

基本命令結構

引數解析：

執行結果與解析

輸出結果說明：

Ansible Pull 的優勢

常見問題與解答

擴充 Ansible 的功能：模組與外掛程式

技術需求

模組開發需求

使用命令列執行多個模組

簡單的模組執行

內容解密：

開發自定義模組

自定義模組範例

內容解密：

使用與建立模組

檢視模組索引

從命令列存取模組檔案

使用 ansible-doc 的詳細解說：

檔案的重要性：

使用與建立模組（Consuming and Creating Modules）

探索 Ansible 模組

列出所有模組

搜尋特定模組

檢視模組檔案

瞭解模組的傳回值

使用 ansible-doc 檢視傳回值

實際測試傳回值

開發自定義 Ansible 模組

環境設定

安裝必要的套件

圖表示例

圖表翻譯：

最終檢查流程

開發自定義 Ansible 模組：從環境設定到模組編寫

設定開發環境

安裝必要的套件

克隆 Ansible Git 倉函式庫

建立虛擬環境

編寫第一個模組

建立模組檔案

新增 Shebang 和版權資訊

新增 Ansible 後設資料

新增檔案字串

內容解密：

結語

圖表翻譯：

內容解密：

使用 `ansible-doc` 檢視傳回值