トップ > Ansible > Ansibleのモジュールやプラグインを修正したいあなたへ(2024年版)

Ansibleのモジュールやプラグインを修正したいあなたへ(2024年版)

Ansible

Ansible Advent Calendar 2024の4日目の記事です｡

みなさんメリークリスマス｡Red Hatのさいとうです｡

日々Ansibleを使って自動化を推進しているみなさん､｢Ansibleのモジュールやプラグインにオプションを追加してほしい｣､ ｢実行結果の戻り値に自分が必用とする情報を追加してほしい｣､ ｢不具合を修正してほしい｣ といったことを七夕の短冊に書いてお祈りしたり､サンタさんにお願いしたり､IssueとしてCollectionのリポジトリにファイルしたりしたことがありますよね｡僕はよくあります｡

そして最後に､｢もういっそ自分で修正しちゃったほうが楽だわ｣という境地に達するはずです｡そんなあなたに向けて､今日は､Ansible Collectionに対するコードコミットのお作法について書いてみようと思います｡

その1: 最初にIssueとしてファイルしよう

ちょっと面倒かもしれませんが､Issueとして最初にファイルしておくことをお勧めします｡ レポートする際のIssueの種類は､ community.general や ansible.posix などのCollectionでは､大きく3つ分けられています｡

  1. Bug report: Create a report to help us improve
  2. Documentation Report: Ask us about docs
  3. Feature request: Suggest an idea for this project

バグの場合は1を､ansible-docで参照できるオプションの説明などドキュメントに関する報告は2を､オプションなどの機能追加の場合は3を選択して､あなたのリクエストをIssueとしてファイルしてください｡

最終的に自分でPull Requestを送って修正する場合でも､修正内容の説明は書かなければなりません｡あらかじめIssueとして詳細を説明してファイルしておけば､Pull Requestのコメントではfixes #NのようにIssue番号だけ参照できるので､Pull Request作成時の説明で楽ができます

その2: コードを修正しましょう

Ansible Collectionsには､Contributing to Ansible-maintained Collectionsというコントリビューター用のガイドラインが公開されているので､目を通しておいてください｡

修正対象となるアップストリームのCollectionのリポジトリをforkして､作業用ブランチを作成して修正に入ります｡例えばこんな感じです｡ 僕の場合､ブランチ名はissue_NNNとしてIssue番号にしてしまって｢良い感じの名前ないかな｣と悩まないようにしてます｡そういう面でもIssueを先に作っておくと楽ができます｡いくつもPull Requestを作っていると良い感じの名前も枯渇します :)

% git clone [email protected]:<YOUR_ACCOUNT>/ansible.posix.git posix
% cd posix
% git checkout -b issue_NNN

その3: changelog fragmentファイルを作りましょう

changelog fragmentファイルを作成して､Pull Requestの種別と概要を書きます｡ここにもIssueのURLを含めるとメンテナに喜ばれます｡このchangelog fragmentファイル､すくなくともansible.posixにPull Requestを送ってくれる人の9割くらいが含めるのを忘れてます｡

※含めてくる1割の人は､だいたいコレクションのメンテナです(笑)｡

ファイルの命名方法は _<PRを端的に表す短いファイル名>.yml です｡ファイルは changelogs/fragments/ の配下に配置してください｡以下にcommunity.generalのPull Request #9188の例をあげます｡

このとき､Issue番号をファイル名のインデックスに指定できるので､やはりあらかじめIssueをオープンしておくと便利です｡Pull Request番号でもかまいませんが､この時点でまだPull Requestは作成されていないので､Pull Request番号は採番されていません｡ファイル名のインデックスにPull Request番号を使用する場合は､最新の Issue/Pull Request番号+1 という面倒な確認をしなければなりません｡

% cat changelogs/fragments/9188-jira-attachment-validation.yml

bugfixes:
  - jira - remove unnecessary validation when attaching files (https://github.com/ansible-collections/community.general/pull/9188).

bugfixes は､このPull Requestのカテゴリを表しています｡このカテゴリはCIプロセスの中で有効なカテゴリかどうかが確認されています｡

以下によく見かけるカテゴリをご紹介します｡

  • breaking_changes: 既存のモジュールオプションの振る舞いを完全に変えるような修正です｡たとえば文字列指定だったパラメータをリスト指定に変えるといった､Playbookの記述に変更を加える必用があるような修正が該当します｡この修正は､メジャーバージョンアップのみ適用されます｡
  • major_changes: ansible-core側の変更や､collection自体が依存しているSDKの変更によって､大幅な改修が行われる場合に該当します｡モジュールやプラグインレベルでは通常は使いません｡
  • minor_changes: モジュールやプラグインに対する機能追加などがこれに当たります｡バグフィックス以外はだいたいコレです｡
  • removed_features: モジュールやプラグイン自体を削除する場合です｡たとえばansible.posixからskippyプラグインを削除するといった場合に指定します｡
  • bugfixes: モジュールやプラグインに対するバグフィックスがこれにあたります｡
  • trivial: これはCHANGELOG.rstには記載されないような修正です｡たとえばメンテナがCIプロセスの修正を行ったり､タブをホワイトスペースに修正したり､ドキュメント中のサンプルのモジュール指定をFQCNに変更したり...といった本筋とは無関係な修正がこれにあたります｡

だいたい､機能追加は minor_changes ､バグ修正は bugfixes を指定しておけば間違いないです｡間違っていたとしても､メンテナがコードレビューのときに指摘してくれるので､必用に応じて修正するくらいの軽い気持ちで指定してください｡changelog fragmentファイルを作るのが大事なのです｡

Collecionのメンテナは､リリースコミットの際に､このchangelog fragmentファイルからantsibull-changelogコマンドでの CHANGELOG.rst を自動生成しています｡ ですから､このchangelog fragmentファイルは､現在のCollectionに対するPull Requestでは必須のファイルとなっているのです｡

その4: 必用に応じてintegration testを書きましょう(Optional)

minor_changes などで機能追加を行う場合は､必ずintegration testを実装してください｡このテストはAnsible Playbookで書かれていて､tests/integration/targets/ 配下にモジュール名でディレクトリが作られていて､その中に置かれています｡

bugfixesなどでは不要なこともありますが､minor_changesなどの機能追加では基本的に必用です｡テストカバレッジなどの問題があればレビューで指摘してもらえるのでご安心を｡

その5: Pull Requestを送るときの心得

Pull Requestを送るときには､以下の2点に注意してください｡

その5-1: Pull Requestは､まずは Draft Pull Request で作りましょう

Ansible CollectionsのPull Requestは自動でテストされます｡原則的には､このテストが全て通ってはじめて人間がレビューします｡テストがすべて通るまでは､Draft Pull Requestにしておいて､テストに通らなければ修正して､まずはテストを通しましょう｡

自動テストに全てパスしたら､Ready for Reviewボタンをポチッと押して､Draft Pull Requestから通常のPull Requestに切り替えてください｡あなたのPull Requestは､これでレビュアからのレビュー待ち状態となります｡

その5-2: Maintainers are allowed to edit this pull request を確認しましょう

コンフリクトの修正などの支援をメンテナから受けるためには､ Maintainers are allowed to edit this pull requestのチェックボックスはONする必用があります｡みなさん自身の判断でON･OFFを設定してください｡

その6: コミットを1つにまとめる(Optional)

レビューの中で､change requestを受けることもあるでしょう｡修正が複数回にわたるとコミットメッセージの見通しが悪くなるので､複数のコミットは必用に応じてまとめるようにしています｡

まとめ

AnsibleのモジュールがCollectionsとして切り出された当初は､ガイドラインが整備されておらず､Collection毎になんとなくメンテナがルールを作って運用していました｡しかし､現在はAnsible Communityからコントリビューターやメンテナのための統一されたガイドラインが提供されて､随分と見通しがよくなってきています｡

メンテナがこれを守っていないと怒られます(怒られた)から､このガイドラインのおかげで､ずいぶんと利用者からのコードコントリビュートがしやすくなっているように感じます｡みなさんも､このクリスマスにおひとつおかがでしょうか? Happy Automation :)

* 各記事は著者の見解によるものでありその所属組織を代表する公式なものではありません。その内容については非公式見解を含みます。