使用Ansible開發遠端檔案複製模組

– 9 分鐘閱讀

Ansible 模組是擴充套件 Ansible 功能的根本，賦予你根據特定需求建立自動化任務的能力。本文將帶領你探索 Ansible 模組開發的精髓，從基礎環境設定到實際程式碼撰寫，逐步開發你的專屬自動化工具，以遠端檔案複製為例，展現 Ansible 模組的強大威力。

開發環境藍圖

首先，確保你的開發環境已安裝 Ansible 和 Python。接著，設定 Ansible 模組開發環境，包含必要的環境變數和目錄結構。以下是一個簡化的設定流程：

export PATH=/home/user/ansible/bin:$PATH  # 將 Ansible 路徑加入 PATH 環境變數
export PYTHONPATH=/home/user/ansible/lib:$PYTHONPATH # 設定 Python 路徑，確保 Ansible 能找到你的模組
# 設定 MANPATH，方便查閲 Ansible 檔案 (可選)
export MANPATH=/home/user/ansible/docs/man:$MANPATH

你的第一個 Ansible 模組：remote_filecopy

我們將建立一個名為 remote_filecopy.py 的模組，用於複製遠端檔案。以下是一個基礎的 Python 程式碼範例：

#!/usr/bin/env python

import shutil
from ansible.module_utils.basic import AnsibleModule

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

    source = module.params['source']
    dest = module.params['dest']

    try:
        shutil.copy2(source, dest)  # 使用 shutil.copy2 保留檔案 metadata
        module.exit_json(changed=True, msg="檔案複製成功")
    except FileNotFoundError:
        module.fail_json(msg=f"來源檔案 {source} 不存在")
    except Exception as e:
        module.fail_json(msg=f"檔案複製失敗: {e}")

if __name__ == '__main__':
    main()

這段程式碼定義了一個 Ansible 模組，接受 source 和 dest 兩個引數，分別代表來源檔案和目標檔案路徑，並確保這兩個引數都是必填的字串。它使用 shutil.copy2 函式進行檔案複製，這個函式會保留檔案的 metadata，例如修改時間和許可權。透過 module.exit_json 和 module.fail_json 回傳執行結果和訊息給 Ansible，讓使用者更容易理解模組的執行狀態。

模組測試：驗證你的成果

在 moduledev 環境下，使用 args.json 檔案傳遞引數來測試模組：

python remote_filecopy.py args.json

args.json 檔案內容如下：

{
    "invocation": {
        "module_args": {
            "dest": "/tmp/bar",
            "source": "/tmp/foo"
        }
    }
}

Playbook 整合：讓模組發揮作用

將模組放置於 playbook 目錄下的 library/ 資料夾，即可在 playbook 中使用：

---
- name: 測試客製化模組
  hosts: all
  tasks:
    - name: 執行檔案複製模組
      remote_filecopy:
        source: /tmp/foo
        dest: /tmp/bar
      register: testresult

    - name: 顯示測試結果
      ansible.builtin.debug:
        msg: "{{ testresult }}"

這個 playbook 呼叫了我們自定義的 remote_filecopy 模組，並將結果儲存至 testresult 變數中，最後透過 debug 模組顯示結果，方便我們檢視模組的執行情況。

錯誤處理：開發穩健的模組

完善的錯誤處理機制至關重要。程式碼範例中已包含錯誤處理：

這個版本針對 FileNotFoundError 進行了特殊處理，提供更明確的錯誤訊息，例如「來源檔案 /tmp/foo 不存在」。此外，它也捕捉其他可能的異常，並提供通用的錯誤訊息，方便排查問題。

玄貓的錦囊妙計

  • 善用 try...except 區塊捕捉不同型別的錯誤，並提供清晰的錯誤訊息，提升模組的穩健性。
  • 在模組中加入 check_mode 支援，讓使用者可以在不實際執行的情況下預覽模組的行為，避免意外修改。
  • 撰寫完善的模組檔案，方便其他使用者理解和使用你的模組，提升模組的可維護性。
  graph LR
    A[設定開發環境] --> B{建立模組 remote_filecopy.py};
    B --> C[使用 args.json 測試模組];
    C --> D{整合至 Playbook};
    D --> E[錯誤處理與最佳實踐];

深入檔案與測試：讓你的模組更上一層樓

Ansible 提供了強大的工具來測試和檔案化你的模組，確保模組的品質和易用性。

ansible-test：你的模組健檢工作者

ansible-test 工具可以對你的模組程式碼執行一系列的健全性檢查，確保你的程式碼符合 Ansible 的標準，並且檔案格式正確。

# 在 Ansible 原始碼目錄下執行
ansible-test sanity --test validate-modules remote_filecopy

ansible-doc：你的模組檔案瀏覽器

ansible-doc 命令可以讓你方便地檢視模組的檔案，確認檔案內容的正確性和完整性。

# 指定模組路徑
ansible-doc -M /path/to/your/module/ remote_filecopy

建置 HTML 檔案：讓你的模組閃亮登場

你可以使用 make webdocs 命令來建置 HTML 格式的模組檔案，方便在網頁上瀏覽和分享。

# 在 Ansible docs/docsite/ 目錄下執行
make webdocs MODULES=remote_filecopy

透過 ansible-test、ansible-doc 和 make webdocs 等工具，你可以更有效率地開發、測試和檔案化你的 Ansible 模組，讓你的自動化任務更加完善和專業。

透過以上步驟，你已成功建立並測試了你的第一個 Ansible 模組。Ansible 模組開發充滿無限可能，讓你的自動化任務更加靈活和高效。

Ansible 模組開發的藝術：開發你的自動化利器

在自動化世界裡，Ansible 模組就像精巧的工具，讓你能輕鬆操控各種系統。玄貓將帶你探索如何使用 Python 開發自定義 Ansible 模組，並分享開發過程中的最佳實踐，以及如何將你的成果貢獻給 Ansible 社群。

Ansible 模組開發入門：從探索到理解

在開始編寫自定義模組之前，讓我們先了解如何執行現有模組，以及如何查詢模組的説明檔案。這些步驟能幫助我們評估模組的適用性，無論是否有網路連線。

ansible dbservers -m command -a "/bin/echo 'hello modules'"

這段程式碼使用 command 模組在 dbservers 群組的主機上執行 /bin/echo 'hello modules' 命令。-m 選項指定要使用的模組，-a 選項指定模組的引數。這個例子展示了 Ansible 模組的基本使用方法，也説明瞭如何透過簡單的命令在遠端主機上執行操作。

接下來，我們將探討模組資料及其 JSON 格式，這有助於理解模組的輸入和輸出。

開發高品質 Ansible 模組：實踐與技巧

以下是一些開發高品質 Ansible 模組的實務技巧，讓你的模組更容易被 Ansible 社群接受：

  • 全面測試： 盡可能在各種情況下測試你的模組，包括成功和失敗案例。可以使用 JSON 資料或測試劇本來進行測試。
  • 最小化依賴： 盡量減少 Python 依賴項。雖然有時無法避免額外的依賴（例如 AWS 模組的 boto 需求），但通常依賴越少越好。
  • 避免快取資料： 由於 Ansible 跨不同主機的執行策略，快取資料不太可能產生良好結果。每次執行都應重新收集所需資料。
  • 單一檔案： 模組應包含在單個 Python 檔案中，不應分散在多個檔案中。
  • 例外處理： 在模組程式碼的適當位置加入例外處理，以防止問題發生。
  • 整合測試： 在提交模組程式碼之前，務必研究並執行 Ansible 整合測試。
try:
    # 嘗試執行某些操作
    result = some_function()
except SomeException as e:
    # 處理異常
    module.fail_json(msg="發生錯誤: %s" % str(e))

這段程式碼示範瞭如何使用 try...except 區塊來處理異常。如果 some_function() 丟擲 SomeException，程式碼將會捕捉異常並使用 module.fail_json() 回報錯誤訊息。妥善的例外處理能提升模組的穩定性和可靠性。

回饋社群：提交 GitHub Pull Request

當你完成模組開發、測試和檔案編寫後，就可以將它提交到 Ansible 專案，與社群分享你的成果。這需要在官方 Ansible 儲存函式庫上建立一個 Pull Request (PR)。

以下是如何提交模組程式碼到 Ansible 專案的簡要步驟：

  1. Fork 儲存函式庫： 在 GitHub 上 Fork 你想要貢獻的 collection 儲存函式庫。
  2. 複製到本地： 將 Fork 的儲存函式庫複製到你的本地機器。
  3. 新增上游儲存函式庫： 在你的本地儲存函式庫中新增上游儲存函式庫。
  4. 更新本地分支： 更新你的本地分支以保持與上游同步。
  5. 建立分支： 為你的 PR 建立一個新的分支。
  6. 修改程式碼： 在新的分支中修改程式碼。
  7. 提交 PR： 提交你的 Pull Request。
  8. 審查與合併： Ansible 社群會審查你的 PR，如果沒有問題，就會將其合併到主分支。

除了建立自定義模組之外，還有許多其他方式可以為 Ansible 專案做出貢獻，例如審查檔案、參與 Ansible 社群活動等等。

視覺化你的 Ansible 模組架構

  graph LR
    A[Ansible 控制節點] --> B{模組}
    B --> C[受管主機]
    C --> D[任務結果]
    D --> A

圖表説明： 此流程圖展示了 Ansible 控制節點、模組和受管主機之間的互動關係。Ansible 控制節點透過模組在受管主機上執行任務，並接收任務結果。

透過清楚的流程圖，我們可以更容易理解 Ansible 的運作機制，以及模組在其中的角色。

Ansible Collection 的進化：從單體到模組化的轉變

在 Ansible 2.9 版本之前，所有功能都集中在一個龐大的程式碼函式庫中。這種架構限制了 Ansible 的擴充套件性和社群貢獻的效率。Collection 的出現解決了這個問題，讓開發者可以獨立開發、測試和釋出 Ansible 功能，而無需受限於 Ansible 核心程式碼的釋出週期。

Collection 提供了一種機制來封裝和分發角色、外掛、模組、劇本和檔案。它們讓 Ansible 的生態系統更加模組化和靈活。

完整 Collection 名稱 (FQCN) 的重要性

為了避免模組名稱衝突，Ansible 引入了 FQCN (Fully Qualified Collection Name) 的概念。FQCN 的組成結構如下：

<namespace>.<collection_name>.<module_name>
  • namespace: 用於識別 collection 開發者的唯一名稱空間。
  • collection_name: 每個名稱空間中可以包含一個或多個 collection。
  • module_name: 模組名稱在 collection 內必須是唯一的。

使用 FQCN 可以確保模組的唯一性，避免名稱衝突造成的混淆和錯誤。

- name: 顯示除錯訊息
  ansible.builtin.debug:
    msg: "Hello World!"

這段程式碼使用了 ansible.builtin.debug 這個 FQCN 來指定 debug 模組，確保了程式碼的清晰性和正確性。

  graph LR
    A[Ansible 2.8] --> B{模組名稱};
    B --> C[ios_bgp];
    B --> D[eos_bgp];
    B --> E[fortios_router_bgp];
    F[Ansible Collection] --> G{模組名稱};
    G --> H[bgp];

上面的 圖表展示了 Ansible 2.8 和 Ansible Collection 在模組命名上的差異。在 Ansible 2.8 中，模組名稱需要加入裝置名稱以確保唯一性。而 Ansible Collection 則簡化了命名，可以直接使用 bgp 作為模組名稱，避免了冗長的名稱。

透過理解 Ansible 模組開發的流程、最佳實踐和 Collection 的概念，你可以更有效地使用 Ansible，並為 Ansible 社群做出貢獻。

深入 Ansible Collection：擴充套件自動化能力的利器

Ansible 的核心力量之一在於它的模組化設計，允許使用者透過擴充套件模組來滿足各種自動化需求。而 Ansible Collection 正是實作這種擴充套件性的關鍵機制，它將模組、外掛、角色和其他 Ansible 內容封裝在一起，方便分享和管理。

當您安裝 Ansible 時，系統會預載一組預設的 collection，提供與 Ansible 2.x 版本相容的功能，確保向下相容性。這些 collection 會隨著 Ansible 版本更新而自動更新，讓您隨時使用最新功能。

然而，Ansible 的真正魅力在於它的靈活性。如果內建 collection 無法滿足您的特定需求，您可以輕鬆安裝額外的 community collection 或自行開發專屬 collection。

Ansible Collection 的安裝路徑

Collection 的安裝路徑是可以自定義的。預設情況下，Ansible 會在以下兩個路徑搜尋 collection：

  1. ~/.ansible/collections：位於使用者家目錄下的 .ansible 資料夾中。
  2. /usr/share/ansible/collections：系統全域路徑，所有使用者皆可存取。

Ansible 會依序搜尋以上路徑，直到找到指定的 collection。您也可以透過設定 COLLECTIONS_PATHS 環境變數或修改 ansible.cfg 設定檔中的 collections_paths 引數來自定義搜尋路徑。

安裝 community.general Collection 範例

以下示範如何安裝 community.general collection，這個 collection 提供許多常用的 Ansible 模組：

ansible-galaxy collection install community.general

執行此命令後，ansible-galaxy 會顯示 collection 的安裝路徑。預設情況下，collection 會安裝在當前使用者的家目錄下。如果其他使用者需要使用相同的 collection，他們也需要各自安裝。

上述程式碼使用了 ansible-galaxy collection install 命令來安裝 community.general collection。community.general 是 collection 的完整名稱，稱為 Fully Qualified Collection Name (FQCN)，它包含了名稱空間（community）和 collection 名稱（general）。

  graph LR
    A[您的電腦] --> B{執行 ansible-galaxy collection install community.general}
    B --> C[下載 community.general collection]
    C --> D{安裝至 ~/.ansible/collections/}

圖表説明:

此流程圖展示了安裝 community.general collection 的過程。首先，您的電腦執行安裝命令。接著，Ansible Galaxy 會下載指定的 collection。最後，collection 會被安裝到使用者家目錄下的 .ansible/collections 資料夾中。

善用 Collection 擴充套件 Ansible 功能

安裝 collection 後，您就可以在 Ansible Playbook 中使用其中包含的模組、外掛和角色。透過使用 FQCN，您可以精確指定要使用的模組，避免命名衝突，並確保程式碼的可讀性和可維護性。

  graph LR
    A[Ansible Playbook] --> B{使用 FQCN 呼叫 community.general 模組}
    B --> C[執行特定自動化任務]

圖表説明:

此流程圖展示了在 Ansible Playbook 中使用 FQCN 呼叫 community.general collection 中模組的過程。Playbook 會使用 FQCN 來指定要使用的模組，然後執行特定的自動化任務。

Ansible Collection 是組織和分享 Ansible 內容的有效方式，讓您可以輕鬆擴充套件 Ansible 的功能，並建構更強大的自動化解決方案。透過理解 collection 的安裝和使用方式，您可以更有效地管理 Ansible 環境，並提升自動化效率。

玄貓

玄貓

技術愛好者，專注於分享程式開發、雲端技術與 AI 應用的心得體會。