てくなべ (tekunabe)

ansible / network automation / 学習メモ

[Ansible] ansible-doc コマンドで Collection のモジュールのドキュメントを表示する

ansible

■ はじめに

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 を利用し、ドキュメントを表示する機会も増えるかもしれませんので、表示方法を覚えておくと良さそうです。