inventory プラグイン

inventory プラグインの有効化

Ansible に同梱されるほとんどの inventory プラグインはデフォルトで有効になっているか、auto プラグインで使用することができます。

たとえば、インベントリープラグインが YAML 設定ファイルを使用しない場合は、特定のプラグインを有効にする必要があります。これを行うには、[inventory] セクションの ansible.cfg ファイルで enable_plugins を設定します。これを変更すると、有効化されたプラグインのデフォルト一覧が上書きされます。以下は、Ansible に同梱される有効なプラグインのデフォルト一覧です。

[inventory]
enable_plugins = host_list, script, auto, yaml, ini, toml

プラグインがコレクションにあり、auto ステートメントで取得されていない場合は、完全修飾名を追加できます。

[inventory]
enable_plugins = host_list, script, auto, yaml, ini, toml, namespace.collection_name.inventory_plugin_name

または、ローカルのプラグインdで、DEFAULT_INVENTORY_PLUGIN_PATH で設定されたパスに保存されている場合には、以下のように参照できます。

[inventory]
enable_plugins = host_list, script, auto, yaml, ini, toml, my_plugin

YAML 設定ソースをサポートするプラグインを使用する場合は、名前がインベントリーソースファイルの plugin エントリーで指定された名前と一致していることを確認してください。

inventory プラグインの使用

inventory プラグインを使用するには、インベントリーソースを指定する必要があります。そのほとんどは、プラグインのオプションを持つホスト情報または YAML 設定ファイルを含むファイルです。-i フラグを使用してインベントリーソースを提供するか、デフォルトのインベントリーパスを設定することができます。

ansible hostname -i inventory_source -m ansible.builtin.ping

YAML 設定ソースで inventory プラグインの使用を開始するには、該当するプラグインで文書化されている受け入れ可能なファイル名のスキーマでファイルを作成し、そのファイルに plugin: plugin_name を追加します。プラグインがコレクションにある場合は、完全修飾名を使用します。

# demo.aws_ec2.yml
plugin: amazon.aws.aws_ec2

各プラグインは命名制限について記載する必要があります。また、YAML 設定ファイルは、auto プラグインでデフォルトで有効にする拡張子 yml または yaml で終了する必要があります (同様に、プラグインを有効にする際の上記のセクションを参照してください)。

必要なオプションを指定したら、ansible-inventory -i demo.aws_ec2.yml --graph で設定され追加されたインベントリーを表示できます。

@all:
  |--@aws_ec2:
  |  |--ec2-12-345-678-901.compute-1.amazonaws.com
  |  |--ec2-98-765-432-10.compute-1.amazonaws.com
  |--@ungrouped:

Playbook に隣接するコレクションで inventory プラグインを使用して、ansible-inventory で設定をテストするには、--playbook-dir フラグを使用する必要があります。

インベントリーソースは、インベントリー設定ファイルのディレクトリーである場合があります。構築した inventory プラグインは、インベントリーにすでに存在するホストでのみ動作するため、特定のタイミング (「最後」など) で構築したインベントリー設定を解析してください。Ansible は、ディレクトリーを再帰的にアルファベットで解析します。解析アプローチは設定できないため、想定通りに機能するように、ファイルの名前を指定します。構築した機能を直接拡張した inventory プラグインは、inventory プラグインのオプションに構築したオプションを追加し、制約を回避して機能させることができます。それ以外の場合は、複数ソースに -i を使用して特定の順番を指定します (例: -i demo.aws_ec2.yml -i clouds.yml -i constructed.yml)。

構築した keyed_groups オプションとホスト変数を使用して、動的なグループを作成できます。groups オプションを使用してグループを作成し、compose でホスト変数を作成して変更できます。以下は、構築した機能を使用する aws_ec2 のサンプルです。

# demo.aws_ec2.yml
plugin: amazon.aws.aws_ec2
regions:
  - us-east-1
  - us-east-2
keyed_groups:
  # add hosts to tag_Name_value groups for each aws_ec2 host's tags.Name variable
  - key: tags.Name
    prefix: tag_Name_
    separator: ""
  # If you have a tag called "Role" which has the value "Webserver", this will add the group
  # role_Webserver and add any hosts that have that tag assigned to it.
  - key: tags.Role
    prefix: role
groups:
  # add hosts to the group development if any of the dictionary's keys or values is the word 'devel'
  development: "'devel' in (tags|list)"
  # add hosts to the "private_only" group if the host doesn't have a public IP associated to it
  private_only: "public_ip_address is not defined"
compose:
  # use a private address where a public one isn't assigned
  ansible_host: public_ip_address|default(private_ip_address)
  # alternatively, set the ansible_host variable to connect with the private IP address without changing the hostname
  # ansible_host: private_ip_address
  # if you *must* set a string here (perhaps to identify the inventory source if you have multiple
  # accounts you want to use as sources), you need to wrap this in two sets of quotes, either ' then "
  # or " then '
  some_inventory_wide_string: '"Yes, you need both types of quotes here"'

これで、ansible-inventory -i demo.aws_ec2.yml --graph の出力が表示されます。

@all:
  |--@aws_ec2:
  |  |--ec2-12-345-678-901.compute-1.amazonaws.com
  |  |--ec2-98-765-432-10.compute-1.amazonaws.com
  |  |--...
  |--@development:
  |  |--ec2-12-345-678-901.compute-1.amazonaws.com
  |  |--ec2-98-765-432-10.compute-1.amazonaws.com
  |--@role_Webserver
  |  |--ec2-12-345-678-901.compute-1.amazonaws.com
  |--@tag_Name_ECS_Instance:
  |  |--ec2-98-765-432-10.compute-1.amazonaws.com
  |--@tag_Name_Test_Server:
  |  |--ec2-12-345-678-901.compute-1.amazonaws.com
  |--@ungrouped

上記の設定でホストに変数がない場合には (つまり tags.Name、tags、private_ip_address)、ホストは inventory プラグインが作成したグループ以外には追加されず、また ansible_host のホスト変数も変更されません。

キャッシュをサポートする inventory プラグインは、ansible.cfg ファイルの [defaults] セクションに定義されたファクトキャッシュの一般設定を使用するか、[inventory] セクションにインベントリー固有の設定を定義することができます。個々のプラグインは、設定ファイルでプラグイン固有のキャッシュ設定を定義できます。

# demo.aws_ec2.yml
plugin: amazon.aws.aws_ec2
cache: true
cache_plugin: ansible.builtin.jsonfile
cache_timeout: 7200
cache_connection: /tmp/aws_inventory
cache_prefix: aws_ec2

以下は、ansible.cfg ファイルに、使用する chache プラグインにデフォルト設定されているファクトキャッシュの一部を使用したインベントリーキャッシュと、タイムアウトを設定する例です。

[defaults]
fact_caching = ansible.builtin.jsonfile
fact_caching_connection = /tmp/ansible_facts
cache_timeout = 3600

[inventory]
cache = yes
cache_connection = /tmp/ansible_inventory

プラグイン一覧

ansible-doc -t inventory -l を使用して、利用可能なプラグインの一覧を表示します。ansible-doc -t inventory <plugin name> を使用して、プラグイン固有のドキュメントと例を参照してください。