この記事は Ansible Advent Calendar 2023 の15日目の記事です。

はじめに

今年、Ansible Galaxy のサイトがリニューアルしました。

各コレクションのバージョンごとのドキュメントが参照できるようになりました。

Red Hat 社提供の Automation Hub で見れていたような感じです。

これまで困ってた経緯を含めてご紹介します。

Ansible 自身のドキュメントではコレクションのバージョン指定できない

（Ansible Community Package に含まれる）コレクションのドキュメントを参照したい場合、Ansible 自身のドキュメントを参照するケースが多いかもしれません。ググったときも割と上の方に表示されます。

たとえば、 ansible.netcommon コレクションであれば以下のページです。

このページはあくまでも Ansible Community Package （pip install ansible でインストールされるもの）のバージョン単位で管理されています。

現状（2023年12月現在）では、Ansible 9 に含まれるコレクションのバージョンのドキュメントが表示されます。

上図でいうと、この時点では Ansible 9 系には ansible.netcommon 5.3.0 が含まれるので、ansible.netcommon 5.3.0 の情報が表示されているという状態です。

このように、 Ansible Community Package のバージョン単位でのドキュメントの切り替えなので、コレクションのバージョン単位で切り替えられません。そのため、見たいバージョンのドキュメントが見れないこともこともありました。

また、旧 Ansible Galaxy のサイトでもコレクションのバージョン指定したドキュメントが参照できませんでした（バージョン指定できるのはダウンロード対象バージョンだった）。

もしコレクションのバージョンを指定してドキュメントを参照したい場合は、GitHub リポジトリのタグを頼りにする必要がありました。

例: ansible.netcommon リポジトリの v5.3.0 タグ

この方法は、少し探すのが手間という面と、自分が見る分にはいいけど人にやや紹介しにくいという面がありました。

新しい Ansible Galaxy のサイトでは、コレクションのバージョンを指定してドキュメントを参照できます。

例えば、ansible.netcommon コレクションは以下のページです。

バージョンのコンボボックスでバージョンを指定できます。便利です。

たとえば、バージョン 5.3.0 に切り替えて、モジュール一覧を眺めると、ansible.netcommon.cli_backup モジュールのドキュメントもあります。このモジュールは 5.3.0 で追加されたものです。

一方、バージョン 5.2.0に切り替えて、モジュール一覧を眺めても、ansible.netcommon.cli_backup モジュールは見つかりません。このバージョンには無いためです。

これで、コレクションのバージョンに対応したドキュメントが表示されていることが分かります。

参照するバージョンを間違えると、不都合が生じることがあるので、バージョンを指定できるのはありがたいです。

もっとも、手元で動いてる実環境で ansible-doc したり、VS Code の Ansible の拡張使ってもよいですね。