Python
Ansible

Jupyter notebookで最強のAnsibleモジュール開発者向け教育ドキュメントを作る

Ansibleのモジュール開発用に教育ドキュメントをどうしようか悩んでいたのですが Jupyter notebookJupyter Ansible Kernel を使えばJupyterで動かしてイメージができるものができるのではないか?と思い試しにやったら(自分の中で)最強の環境になったので書いておきます。

1. 目的

Ansibleのモジュール開発用に module_utils にあるメソッドの説明及び動作確認、実装方法を学んでもらえるようなドキュメントを作る。

2. 教材イメージ

以下はAnsibleのmodule_utilsにあるVMwareの find_obj メソッドについて書いたドキュメントです。
「百聞は一見に如かず」と言う事で以下はイメージ動画です。

上のイメージが表示されない場合は、以下の画像(リンク)をクリックしてください。

image.png

以下は試しに作ったJupyter notebookのファイルです。

https://github.com/sky-joker/ore-ore-ansible/blob/master/doc/ansible/module_utils/vmware/find_obj.ipynb

3. 説明

ドキュメントには find_obj の説明を書いて 引数戻り値 のイメージを持ってもらいます。
次に find_obj の動作を確認するためのpythonスクリプトを作って実際に動かします。
find_obj の動作イメージが付いたら find_obj を使ったAnsibleモジュール例のファイルを作成します。
ここではソースが書いてあるので実際にどうコーディングしているか分かります。
Ansibleモジュールの作成ができたら実際に動かせるよう Ansible Kernel に変更します。
Ansible用の設定を環境に合わせてしてもらった後に実行すれば、作成したモジュールの動作確認ができます。

4. 触って動かす

静的なドキュメント(WordとかWikiとか)だとなかなかイメージしづらいですが、Jupyterを使うことで実際に触って動かしながら学んでもらえそうです :)
Jupyterであれば、動画ファイルを埋め込んだりもできるしGitで管理することもできて夢が広がりそうです :)

5. 参考

Jupyter Ansible Kernelのvenv環境への導入方法は以下にまとめてみました。

venv環境にAnsible Jupyter Kernelの導入でハマったため備忘録としてメモを残しておく