モジュールのグループを送信する情報¶

トピック

モジュールのグループの送信
コーディングを開始する前に
命名規則
お問い合わせ
サポートを受ける場所
最初のプル要求
その後の PR
モジュールのメンテナンス
git または GitHub をはじめて使用する場合

モジュールのグループの送信 ¶

本セクションでは、複数の関連モジュールを Ansible に組み込む方法を説明します。

本ガイドは、自社製品のモジュールを追加することを希望する企業と、Ansible 機能を追加したいサードパーティー製品のユーザーの両方を対象としています。

これは、Ansible コアチームおよびコミュニティーが蓄積したモジュール開発のヒントおよびテクニックに基づいています。

Note

LICENSING REQUIREMENTS Ansible enforces the following licensing requirements:

Utilities (files in lib/ansible/module_utils/) may have one of two licenses:
- A file in module_utils used only for a specific vendor’s hardware, provider, or service may be licensed under GPLv3+. Adding a new file under module_utils with GPLv3+ needs to be approved by the core team.
- All other module_utils must be licensed under BSD, so GPL-licensed third-party and Galaxy modules can use them.
- If there’s doubt about the appropriate license for a file in module_utils, the Ansible Core Team will decide during an Ansible Core Community Meeting.
All other files shipped with Ansible, including all modules, must be licensed under the GPL license (GPLv3 or later).

コーディングを開始する前に ¶

コーディングを始める前に、注意すべき点がいくつかあります。この前提条件の一覧は、レビュープロセスを簡単に終わらせ、より早く Ansible に組み込まれる高品質のモジュールを開発できるように設計されています。

「Ansible モジュールの開発: はじめに」からリンクされているすべてのページを読みます。特に、「Ansible へのモジュールの貢献」に注意してください。
新しいモジュールは PEP 8 に準拠している必要があります。詳細は、「PEP 8」を参照してください。
Ansible バージョン 2.7 以降では、新しいモジュールはすべて Python 2.7 以降および Python 3.5 以降に対応する必要があります。問題が解決しない場合はお問い合わせください (お問い合わせ方法は、本ガイドの後半の「お問い合わせ」セクションをご覧ください。
既存のモジュールで、特に同じ機能領域 (クラウド、ネットワーク、データベースなど) で All modules にどのように命名方法が採用されているかを確認してください。
共有コードは、lib/ansible/module_utils/ に置くことができます。
共有ドキュメント (共通引数の記述など) は、lib/ansible/plugins/doc_fragments/ に置くことができます。
大きな力には大きな責任が伴います。Ansible モジュールメンテナーには、モジュールを最新の状態に保つのを手伝う義務があります。モジュールメンテナーは、成功しているすべてのコミュニティープロジェクトと同様、報告された問題と貢献に注意を払う必要があります。
必須ではありませんが、ユニットテストや統合テストが強く推奨されます。ユニットテストは、外部リソース (クラウドやネットワークデバイスなど) が必要な場合に特に有効です。詳細は、「Ansible のテスト」および「Testing Working Group」を参照してください。 * Ansible 2.4 以降、すべての Network modules にはユニットテストが必要です。

命名規則 ¶

lib/ansible/modules/ を見ると気づかれるかもしれませんが、わたしたちがサポートするのはディレクトリーの 2 階層 (databases/mysql など) までです。これはディスク上のファイルをグループ化したり、関連するモジュールをモジュールインデックスのカテゴリーやトピックでグループ化したりするために使用されます (Database modules など)。

ディレクトリー名は、会社名ではなく、製品または OS の名前を表す必要があります。

各モジュールには上記 (または同様) の接頭辞が必要です。既存の例は、既存の「All modules」を参照してください。

**注記: **

ファイルおよびディレクトリーの名前は常に小文字です。
単語はアンダースコア (_) 記号で区切ります。
モジュール名は、複数形ではなく、単数形にする必要があります。たとえば、commands ではなく、command とします。

お問い合わせ ¶

コーディングを始める前にアイデアを循環させることは、正しい方向に進むのに役立つ良い方法です。

「コーディングを開始する前に」セクションを読むと、モジュールの構造について合理的に理解できるでしょう。

これまでに、提案されたモジュール名のリストとそのモジュールで実現できることを 1、2 行で説明し、それを Ansible がレビューすることが、モジュールがこれまで Ansible モジュールを使用してきた人の使い方に適しているかどうかを確認し、より使いやすくするための優れた方法であることが分かっています。

サポートを受ける場所 ¶

Ansible には、活発で知識が豊富なモジュール開発者のコミュニティーがあり、質問に答えるための素晴らしいリソースとなっています。

「Ansible コミュニティーガイド」では、以下の方法を確認できます。

メーリングリストをサブスクライブすること。「Ansible Development List」（codefreeze 情報用）および「Ansible Announce list」を提案します。
#ansible-devel - FreeNode の IRC ネットワーク #ansible-devel では、インタラクティブな対話を行うことができるため、モジュール開発者に最適なものであることが分かっています。
IRC ミーティング - 様々な IRC ミーティング (毎週) に参加する。「ミーティングスケジュールおよび議題ページ」を参照してください。

最初のプル要求 ¶

本ドキュメントを確認すれば、最初のプル要求を作成する準備が整うはずです。

最初の PR は、通常のものとは少し異なります。

名前空間を定義します。
今後の PR を構成するのに役立つ詳細レビューの基礎を提供します。
複数のモジュールが必要とする共有ドキュメント (doc_fragments) を含めることができます。
複数のモジュールが必要とする共有コード (module_utils) を含めることができます。

最初の PR には以下のファイルが含まれている必要があります。

lib/ansible/modules/$category/$topic/__init__.py - 名前空間を初期化し、Python がファイルをインポートできるようにする空のファイル。必要な新規ファイル
lib/ansible/modules/$category/$topic/$yourfirstmodule.py - 単一のモジュール。必要な新規ファイル
lib/ansible/plugins/doc_fragments/$topic.py - 一般的な引数の詳細などのコードのドキュメント。任意の新しいファイル
lib/ansible/module_utils/$topic.py - 一般的な引数などの、複数のモジュール間で共有されるコード。任意の新しいファイル

以上です。

PR を GitHub にプッシュする前に、「Ansible へのモジュールの貢献」を再度確認することが推奨されます。

PR を https://github.com/ansible/ansible に公開した後、Shippable CI テストが数分以内に実行されるはずです。結果 (PR ページの最後にあります) を読んで、合格している (緑色) ことを確認します。合格していない場合は、各結果を確認してください。エラーのほとんどは説明の必要がないもので、ドキュメントの形式が正しくない場合がほとんどです (「YAML 構文」を参照)。または、有効な Python 2.6 や Python 3.5 ではないコード (Ansible および Python 3 を参照) に関連しています。もし、Shippable テストメッセージが何を意味するのかわからない場合は、わたしたちが確認するため、コメントと一緒に PR にコピーしてください。

さらにアドバイスが必要な場合は、IRC チャンネル #ansible-devel に参加することを検討してください (「サポートを得る方法」を参照してください)。

GitHub Issue および PRS にコメントする ansibullbot ヘルパーがあります。重要な情報を強調表示します。

その後の PR ¶

この時点で、モジュールの名前空間を定義した最初の PR がマージされている必要があります。最初の PR から学んだ教訓を、残りのモジュールに適用できます。

残りのモジュールについては、モジュールごとに PR を1つだけ上げます。

長年にわたり、1 つのモジュールから数十にもなるモジュールまで、さまざまなサイズのモジュール PR を試してきましたが、それにより次のことがわかりました。

PR に含まれるファイルが 1 つの場合は、高品質のレビューが得られます。
PR に含まれるファイルが複数の場合は、すべてのフィードバックが適用されていることを作成者が確認するのがより困難になります。
PR に含まれるモジュールが多くなると、レビューに必要な作業も増えるため、レビューしやすい PR が選ばれる傾向があります。

最初の PR がマージされた後、最大 5 つの PR を一度に上げることができます (5 個の PR は 5 個の新規モジュールに相当)。これが、レビュープロセスをスムーズに進めるための適切なバッチサイズであることが分かりました。

モジュールのメンテナンス ¶

モジュールが統合されると、いくつかのハウスキーピング処理が必要になります。

ボットメタ Ansibullbot を更新して、作成したモジュールの BOTMETA.yml に対してバグまたは PR が発生したかどうか、発生した場合はいつ誰に通知するかを設定します。

通知するユーザーが複数の場合は、リストを作成します。これにより、1 人のユーザーが何らかの理由で対応できない場合に、その他の人がそのユーザーを待つ必要がなくなります。BOTMETA.yml では、ディレクトリー全体の所有権を取得できることに注意してください。

モジュール Web ドキュメントの確認 モジュールごとに自動生成されるモジュールドキュメントを確認してください。「モジュールドキュメント」でドキュメントが正しくフォーマットされていることを確認します。問題がある場合は、PR を 1 つ作成して修正してください。

モジュールのドキュメントが公開されていない場合は、IRC チャンネルの #ansible-devel で、Ansible Core Team のメンバーにご連絡ください。

Note

モジュールセットの使用方法についてシナリオガイドを追加することを検討してください。これを始めるには、「sample scenario guide rst file」が役に立ちます。ネットワークモジュールの詳細は、ドキュメンテーションの要件を「新しいネットワークプラットフォームのドキュメント化」でご確認ください。

git または GitHub をはじめて使用する場合 ¶

ここでは、Git または GitHub を初めて使用するユーザーを対象としています。次のガイドが参考になります。

Ansible Git リポジトリーでは、メインブランチは master ではなく devel と呼ばれます。これは、公式の GitHub ドキュメントで使用されています。

最初の PR がマージされると、以前作成したディレクトリー構造、および共有コードまたはドキュメントを取得できるように、ansible/ansible と「フォークを同期」させます。

GitHub ドキュメントに記載されているように、PR には常に機能ブランチを使用し、devel に直接コミットしないようにしてください。