■ はじめに
Ansible 2.9 から Ansible Collection という新しいコンテンツ配布形式が始まりました。（Ansible 2.8では実験的サポート）
ロールのほかにも、モジュールやプラグインを含めて配布できるのが特徴です。
Collection でインストールするものは、Ansible 本家リポジトリ ansible/ansible の管理下ではないので、公式ドキュメントには掲載されません。
そのため、ansible-doc コマンドを利用して表示することになりますが、モジュール名の指定方法が標準モジュールとは若干異なり、名前空間を含めて指定します。
この記事では簡単な例をもとに説明します。
- 検証環境
- Ansible 2.9.1
■ 基本書式
標準モジュールでは、 ansible-doc モジュール名 でモジュールのドキュメントを表示できます。Collection モジュールでは、モジュール名の代わりに FQCN でモジュール名指定します。
ansible-doc FQCN
FQCN というのは、Fully Qualified Collection Name の略です。Collection の名前空間、Collection名、モジュール名をドットでつなげたものです。（本当にモジュール名まで含めるのかちょっと自信なし）
たとえば、fragmentedpacket.netbox_modules という Collection 内の netbox_manufacturer モジュールのドキュメントを表示する場合は、以下のコマンドを実行します。
ansible-doc fragmentedpacket.netbox_modules.netbox_manufacturer
■ おためし
例として、fragmentedpacket.netbox_modules という Collection 内の netbox_manufacturer モジュールのドキュメントを表示してみます。
ここでは、対象の Collection のインストールから始めます。
$ ansible-galaxy collection install fragmentedpacket.netbox_modules Process install dependency map Starting collection install process Installing 'fragmentedpacket.netbox_modules:0.1.0' to '/home/ansible/.ansible/collections/ansible_collections/fragmentedpacket/netbox_modules'
netbox_manufacturer モジュールのドキュメントを表示します。
$ ansible-doc fragmentedpacket.netbox_modules.netbox_manufacturer
> NETBOX_MANUFACTURER (/home/asible/.ansible/collections/ansible_collections/fragmentedpacket/netbox_modules/plugins/modules/netbox_manufacturer.py)
Creates or removes manufacturers from Netbox
* This module is maintained by The Ansible Community
OPTIONS (= is mandatory):
- data
Defines the manufacturer configuration
[Default: (null)]
suboptions:
name:
description:
- The name of the manufacturer
required: true
= netbox_token
The token created within Netbox to authorize API access
= netbox_url
URL of the Netbox instance resolvable by Ansible control host
- state
Use `present' or `absent' for adding or removing.
(Choices: absent, present)[Default: present]
- validate_certs
If `no', SSL certificates will not be validated. This should only be used on personally controlled sites using self-signed certificates.
[Default: yes]
type: bool
NOTES:
* Tags should be defined as a YAML list
* This should be ran with connection `local' and hosts `localhost'
REQUIREMENTS: pynetbox
AUTHOR: Mikhail Yohman (@FragmentedPacket)
METADATA:
status:
- preview
supported_by: community
EXAMPLES:
- name: "Test Netbox modules"
connection: local
hosts: localhost
gather_facts: False
tasks:
- name: Create manufacturer within Netbox with only required information
netbox_manufacturer:
netbox_url: http://netbox.local
netbox_token: thisIsMyToken
data:
name: Test Manufacturer
state: present
- name: Delete manufacturer within netbox
netbox_manufacturer:
netbox_url: http://netbox.local
netbox_token: thisIsMyToken
data:
name: Test Manufacturer
state: absent
RETURN VALUES:
manufacturer:
description: Serialized object as created or already existent within Netbox
returned: success (when I(state=present))
type: dict
msg:
description: Message indicating failure or info about what has been achieved
returned: always
type: str
無事に表示できました。
netbox_token、netbox_url が必須オプションで、その他にも data や state などのオプションがあることが確認できます。その他、EXAMPLES も確認できます。
なお、Collection のインストール先や読み込み先は COLLECTIONS_PATHS という設定に基づきます。デフォルトは ~/.ansible/collections と /usr/share/ansible/collections です。
■ まとめ
Collection モジュールのドキュメントは ansible-doc FQCN で表示できることをご紹介しました。
これから Collection を含めたコンテンツ配信が活性化されると、Collection を利用し、ドキュメントを表示する機会も増えるかもしれませんので、表示方法を覚えておくと良さそうです。
