返回文章列表
玄貓（BlackCat）

Ansible模組開發與貢獻

本文探討 Ansible 模組開發、測試、貢獻流程，以及如何建立與使用 Ansible 外掛程式，涵蓋提交 GitHub Pull Request、本地開發技巧、例外處理、常見問題等導向，提供開發者完整，有效提升 Ansible 的功能和適用性。

DevOps 自動化
Ansible 模組開發 Pull Request GitHub 外掛程式 自動化工具

Ansible 模組開發流程需要著重於程式碼品質、相容性測試和例外處理機制。開發完成後，貢獻模組至 Ansible 上游專案，需 fork 官方儲存函式庫、提交 Pull Request，並遵循 Ansible 的貢獻與程式碼規範。Ansible 外掛程式型別眾多，包含連線、快取、回撥等，可透過 Ansible 命令列工具查詢內建外掛程式，並參考官方檔案瞭解其功能與使用方法，進一步客製化開發以滿足特定需求，擴充套件 Ansible 的功能與應用性。

開發與貢獻 Ansible 模組

建立與測試 Ansible 模組

開發 Ansible 模組需要具備一定的技術能力和測試流程。提交模組程式碼時，務必執行 Ansible 整合測試，以確保模組的品質和相容性。有關整合測試的更多資訊，請參閱官方檔案：https://docs.ansible.com/ansible/latest/dev_guide/testing_integration.html。

在撰寫模組程式碼時，適當地加入例外處理是非常重要的，這可以避免許多潛在的問題。此外，除非絕對必要，否則在 Windows 模組中應避免使用 PSCustomObjects。

貢獻給上游專案 - 提交 GitHub Pull Request

當你完成了一個模組的開發、測試和檔案編寫後，你可能會希望將其提交給 Ansible 專案。首先，你需要在 GitHub 上 fork 官方的 Ansible 儲存函式庫。具體步驟如下：

  1. 登入你的 GitHub 帳戶，並導航到官方 Ansible 儲存函式庫的網址：https://github.com/ansible/ansible.git。
  2. 點選右上角的「Fork」按鈕，將儲存函式庫 fork 到你的帳戶下。

將模組程式碼新增到 fork 的儲存函式庫

  1. 將你 fork 的 devel 分支 clone 到本地機器：
    $ git clone https://github.com/你的GitHub帳戶名稱/ansible.git
  2. 將你的模組程式碼複製到適當的模組目錄下。例如，如果你的模組屬於 files 分類別，可以執行：
    $ cd ansible
$ cp ~/ansible-development/moduledev/remote_filecopy.py ./lib/ansible/modules/files/
  3. 使用 git add 將新檔案加入 Git 管理，並提交變更：
    $ git add lib/ansible/modules/files/remote_filecopy.py
$ git commit -m '新增 remote_filecopy.py 模組用於 pull request'
  4. 將變更推播到你的 fork 儲存函式庫：
    $ git push

建立 Pull Request

  1. 回到 GitHub 網頁，導航到你的儲存函式庫頁面，點選「Pull Requests」標籤，然後點選「New pull request」按鈕。
  2. 按照 GitHub 的指引完成 pull request 的建立。

成功提交 pull request 後，你可以在官方 Ansible 儲存函式庫的 pull requests 列表中找到你的提交。由於 Ansible 專案收到大量的 pull requests，因此審核過程可能需要一些時間。在此期間，你仍然可以在本地使用你的模組程式碼，將其放在 library/ 目錄下即可。有關本地開發的更多資訊，請參閱：https://docs.ansible.com/ansible/latest/dev_guide/developing_locally.html。

重點提示

  • 在提交模組前，務必進行完整的測試和檔案編寫。
  • 確保遵循 Ansible 的貢獻和程式碼規範。
  • 即使你的模組未被合併到官方 Ansible 程式碼函式庫，你仍然可以透過本地安裝使用它。

透過遵循上述步驟和，你可以有效地為 Ansible 社群貢獻你的模組，並提升 Ansible 的功能和適用性。

深入探索Ansible的外掛程式

在前面的章節中，我們深入瞭解了Ansible模組的重要性和自定義模組的開發。現在，我們將進一步探索Ansible的另一個核心元件——外掛程式（Plugins）。外掛程式在Ansible中扮演著至關重要的角色，它們為Ansible提供了多樣化的功能和擴充套件性。

發現外掛程式的型別

Ansible支援多種不同型別的外掛程式，每種型別都有其特定的用途。例如，連線外掛程式（Connection Plugins）負責管理Ansible與遠端主機之間的連線，像是SSH連線。瞭解不同型別的外掛程式有助於我們更好地利用Ansible的功能。

查詢內建的外掛程式

Ansible內建了許多外掛程式，瞭解這些外掛程式的功能和使用方法可以幫助我們更有效地使用Ansible。我們可以透過查閱官方檔案或使用Ansible的命令列工具來發現和了解這些外掛程式。

建立自定義外掛程式

就像自定義模組一樣，Ansible也允許我們建立自己的外掛程式。這為我們提供了無限的可能性，以滿足特定的需求或擴充套件Ansible的功能。在本章中，我們將學習如何建立自定義外掛程式，並將其應用於我們的Ansible專案中。

重點回顧：使用與建立模組

在深入探索外掛程式之前，讓我們先回顧一下前一章的重點內容。我們學習瞭如何使用和建立Ansible模組，包括：

  • 如何透過命令列執行多個模組
  • 如何查詢當前模組索引和取得模組檔案
  • 如何建立自定義模組並將其貢獻給Ansible專案

這些知識為我們奠定了堅實的基礎，使我們能夠更好地理解和利用Ansible的功能。

常見問題與解答

  1. 如何透過命令列將引數傳遞給模組？

    • 正確答案是：D) ansible dbservers -m command -a "/bin/echo 'hello modules'"

  2. 建立自定義模組時，不推薦的做法是什麼？

    • 正確答案是：E) 刪除導致錯誤的playbook，然後從頭開始重新建立。

  3. 要貢獻給Ansible上游專案，是否需要將程式碼提交到devel分支？

    • 正確答案是：A) True

在本章中，我們將深入探索Ansible的外掛程式世界，瞭解其重要性和多樣性，並學習如何建立自定義的外掛程式。這將進一步擴充套件我們對Ansible的理解和應用能力，為我們的自動化之旅開啟新的可能性。

探索Ansible外掛的世界

Ansible的強大功能之一在於其模組化的設計，而外掛（plugins）正是實作這一設計的重要組成部分。無論是透過模組執行任務還是透過外掛擴充套件功能，Ansible的模組化架構使其變得極為靈活和強大。本章將探討Ansible外掛的型別、如何使用它們，以及如何建立自己的外掛。

發現外掛型別

Ansible的程式碼一直被設計為模組化的，這是其核心優勢之一。無論是透過使用模組執行任務還是透過外掛（如我們即將看到的），Ansible的模組化設計使其變得像本文迄今為止所展示的那樣多才多藝和強大。與模組一樣，Ansible外掛都是用Python編寫的，並且需要以某種明確定義的格式接收和傳回資料（稍後會詳細介紹）。Ansible的外掛在其功能中往往是不可見的，因為您很少在命令或劇本中按名稱呼叫它們，但是它們負責Ansible提供的一些i最重要功能，包括SSH連線、解析庫存檔案（以INI格式、YAML或其他格式）的能力，以及在您的資料上執行jinja2過濾器的能力。

首先，讓我們驗證一下測試機器上是否安裝了合適版本的Ansible：

$ ansible-doc --version
ansible-doc 2.9.6
config file = /etc/ansible/ansible.cfg
configured module search path = [u'/root/.ansible/plugins/modules',
u'/usr/share/ansible/plugins/modules']
ansible python module location = /usr/lib/python2.7/site-packages/ansible
executable location = /usr/bin/ansible-doc
python version = 2.7.5 (default, Aug 7 2019, 00:51:29) [GCC 4.8.5
20150623 (Red Hat 4.8.5-39)]

內容解密：

此命令用於檢查Ansible的版本，以確保開發環境正確設定。輸出的資訊包括Ansible的版本、組態檔案路徑、模組搜尋路徑、Ansible Python模組的位置、可執行檔案的位置以及Python版本。這些資訊對於除錯和確保環境的一致性至關重要。

Ansible外掛類別

與檔案模組一樣，檔案外掛也需要大量工作，您會很高興地知道，在https://docs.ansible.com/ansible/latest/plugins/plugins.html上有一個外掛索引可供參考。

您還可以使用ansible-doc命令，就像我們之前所做的那樣，只不過這次需要新增-t開關。外掛總是根據其功能被放置在適當的類別中，因為不同類別之間的外掛功能差異很大。如果您不指定-t開關給ansible-doc，則最終會執行ansible-doc -t module，這將傳回可用模組的列表。

撰寫本文時，Ansible中可以找到以下外掛類別：

  • become：負責使Ansible獲得超級使用者存取許可權（例如，透過sudo）
  • cache：負責快取從後端系統檢索的事實，以提高自動化效能
  • callback：允許您在回應事件時新增新的行為——例如，更改Ansible劇本執行輸出中的資料列印格式
  • cliconf：為各種網路裝置的命令列介面提供抽象，使Ansible具有標準介面來操作
  • connection：提供從Ansible到遠端系統的連線（例如，透過SSH、WinRM、Docker等）
  • httpapi：告訴Ansible如何與遠端系統的API互動（例如，對於Fortinet防火牆）
  • inventory：為Ansible提供解析各種靜態和動態庫存格式的能力
  • lookup：允許Ansible從外部源查詢資料（例如，透過讀取平面文字檔案）
  • netconf：為Ansible提供抽象，使其能夠與啟用NETCONF的網路裝置一起工作
  • shell：為Ansible提供與不同系統上的各種shell一起工作的能力（例如，Windows上的powershell與Linux上的sh）
  • strategy：為Ansible提供具有不同執行策略的外掛（例如，我們在第4章《劇本和角色》中看到的除錯策略）
  • vars：為Ansible提供從某些源取得變數的能力，例如我們在第3章《定義您的庫存》中探索的host_vars和group_vars目錄

使用ansible-doc探索外掛

  1. 列出特定類別中的所有外掛

    $ ansible-doc -t connection -l

    此命令傳回連線外掛的文字索引，類別似於我們檢視模組檔案時的輸出。索引輸出的前幾行如下所示：

    kubectl 在Kubernetes上執行的pod中執行任務
napalm 使用NAPALM提供持久連線
qubes 與現有的QubesOS AppVM互動
libvirt_lxc 透過libvirt在lxc容器中執行任務
funcd 使用funcd連線到目標
chroot 與本地chroot互動
psrp 透過Microsoft PowerShell Remoting Protocol執行任務
zone 在區域例項中執行任務
winrm 透過Microsoft的WinRM執行任務
paramiko_ssh 透過python ssh（paramiko）執行任務

    內容解密：

    此命令用於列出特定類別（如連線類別）中的所有可用外掛。輸出的列表包含了外掛名稱及其簡要描述，有助於使用者瞭解可用的連線選項。

  2. 探索特定外掛的檔案 例如，如果我們想了解paramiko_ssh外掛，可以發出以下命令：

    $ ansible-doc -t connection paramiko_ssh

    您會發現外掛檔案採用非常熟悉的格式，類別似於我們在第5章《消費和建立模組》中看到的模組檔案。

    > PARAMIKO (/usr/lib/python2.7/site-packages/ansible/plugins/connection/paramiko)
使用python ssh實作（Paramiko）連線到目標...

    內容解密：

    此命令提供了有關特定外掛（如paramiko_ssh）的詳細檔案，包括其功能、使用方法以及相關組態選項。這有助於使用者瞭解如何使用該外掛以及它能提供的功能。

使用與建立外掛程式

深入瞭解Ansible外掛程式

在前面的章節中，我們探討了Ansible模組的使用與建立。現在，讓我們進一步深入瞭解Ansible的外掛程式（plugins）。外掛程式是Ansible的重要組成部分，它們提供了模組以外的額外功能。

瞭解Paramiko傳輸外掛程式

首先，我們來瞭解paramiko傳輸外掛程式。這個外掛程式之所以存在，是因為許多Linux發行版，尤其是EL6及之前的版本，不支援SSH連線中的ControlPersist功能。這種功能對於Ansible控制機器的連線效率至關重要。因此，對於這些平台上的大多數使用者來說，使用paramiko會更快。

# paramiko_ssh.py 範例程式碼片段
from __future__ import (absolute_import, division, print_function)
__metaclass__ = type

DOCUMENTATION = """
author: Ansible Core Team
connection: paramiko
short_description: Run tasks via python ssh (paramiko)
description:
- 使用Python的SSH實作（Paramiko）連線到目標主機
- 許多Linux發行版不支援SSH連線中的ControlPersist，因此提供paramiko傳輸
"""

#### 內容解密：
- 這段程式碼定義了`paramiko_ssh`外掛程式的基本檔案，包括作者、連線型別和簡短描述。
- 描述部分解釋了使用Paramiko的原因和其主要功能。

尋找內建外掛程式

要找到Ansible內建的外掛程式，可以檢視安裝目錄或官方原始碼儲存函式庫。

  1. 檢視安裝目錄：如果您使用套件管理器（如RPM或DEB）安裝了Ansible，外掛程式的位置取決於您的作業系統。例如，在CentOS 7上，外掛程式位於/usr/lib/python2.7/site-packages/ansible/plugins/。

    $ ls /usr/lib/python2.7/site-packages/ansible/plugins/
action  cliconf  httpapi  inventory  lookup  terminal  become  connection  __init__.py  loader.py  netconf  test  cache  doc_fragments  __init__.pyc  loader.pyc  shell  vars  callback  filter  __init__.pyo  loader.pyo  strategy

    內容解密：

    • 這條命令列出了Ansible外掛程式的安裝目錄。
    • 外掛程式按類別組織在不同的子目錄中。

  2. 檢視官方原始碼：下載Ansible的官方原始碼儲存函式庫，可以在lib/ansible/plugins/目錄下找到所有外掛程式。

    $ git clone https://github.com/ansible/ansible.git
$ cd ansible/lib/ansible/plugins
$ ls -al connection/

    內容解密：

    • 這段操作演示瞭如何從GitHub下載Ansible原始碼。
    • connection/目錄包含了所有連線相關的外掛程式，如paramiko_ssh.py和ssh.py。

建立自定義外掛程式

透過檢視現有的外掛程式原始碼，我們可以學習如何建立自己的自定義外掛程式。在下一章節中，我們將透過實際範例學習如何建立簡單的外掛程式，並深入瞭解其結構和工作原理。

自定義外掛程式的基本結構

建立自定義外掛程式需要遵循特定的結構和規範。以下是一個簡單的步驟：

  1. 選擇外掛程式型別：根據您的需求，選擇合適的外掛程式型別，如連線、查詢或回撥外掛程式。
  2. 編寫Python程式碼：使用Python編寫您的外掛程式邏輯。確保遵循Ansible的外掛程式開發規範。
  3. 檔案和測試：為您的外掛程式編寫清晰的檔案，並進行充分的測試，以確保其正確性和穩定性。
# 自定義外掛程式範例
from ansible.plugins.callback import CallbackBase

class CallbackModule(CallbackBase):
    CALLBACK_VERSION = 2.0
    CALLBACK_TYPE = 'notification'
    CALLBACK_NAME = 'custom_callback'

    def v2_runner_on_ok(self, result):
        # 自定義處理邏輯
        print("Task executed successfully!")

#### 內容解密：
- 這段程式碼定義了一個簡單的回撥外掛程式，用於在任務成功執行時輸出自定義訊息。
- `v2_runner_on_ok`方法在任務成功完成時被呼叫，您可以在此新增自定義邏輯。