lookup プラグイン

lookup プラグインの有効化

Ansibleは、検出したすべての lookup プラグインを有効にします。カスタム lookup を有効にするには、プレイに隣接する lookup_plugins ディレクトリー、インストールしたコレクションの plugins/lookup/ ディレクトリー、スタンドアロンロール、または ansible.cfg で設定したルックアップディレクトリソースのいずれかに置きます。

lookup プラグインの使用

lookup プラグインは、Ansible でテンプレートを使用できる場所で使用できます。これはプレイ、変数ファイル、または template モジュールの Jinja2 テンプレートで使用できます。lookup プラグインの使用の詳細は、ルックアップ (lookup) を参照してください。

vars:
  file_contents: "{{ lookup('file', 'path/to/file.txt') }}"

lookup はループには欠かせない要素です。with_ と表示される場合は、アンダースコアの後の部分が lookup の名前になります。このような理由から、lookup はリストを出力することが想定されます。たとえば、with_items は items lookup を使用します。

tasks:
  - name: count to 3
    debug: msg={{ item }}
    with_items: [1, 2, 3]

lookup と filters、tests、またはそれぞれを組み合わせて複雑なデータ生成やデータ操作が可能です。以下に例を示します。

tasks:
  - name: valid but useless and over complicated chained lookups and filters
    debug: msg="find the answer here:\n{{ lookup('url', 'https://google.com/search/?q=' + item|urlencode)|join(' ') }}"
    with_nested:
      - "{{ lookup('consul_kv', 'bcs/' + lookup('file', '/the/question') + ', host=localhost, port=2000')|shuffle }}"
      - "{{ lookup('sequence', 'end=42 start=2 step=2')|map('log', 4)|list) }}"
      - ['a', 'c', 'd', 'c']

errors を ignore、warn、または strict に設定して、すべての lookup プラグインでエラーの動作を制御できます。デフォルト設定は strict で、lookup がエラーを返すとタスクは失敗します。以下に例を示します。

lookup エラーを無視するには、以下を行います。

- name: if this file does not exist, I do not care .. file plugin itself warns anyway ...
  debug: msg="{{ lookup('file', '/nosuchfile', errors='ignore') }}"

[WARNING]: Unable to find '/nosuchfile' in expected paths (use -vvvvv to see paths)

ok: [localhost] => {
    "msg": ""
}

失敗させるのではなく警告を出すには、以下を使用します。

- name: if this file does not exist, let me know, but continue
  debug: msg="{{ lookup('file', '/nosuchfile', errors='warn') }}"

[WARNING]: Unable to find '/nosuchfile' in expected paths (use -vvvvv to see paths)

[WARNING]: An unhandled exception occurred while running the lookup plugin 'file'. Error was a <class 'ansible.errors.AnsibleError'>, original message: could not locate file in lookup: /nosuchfile

ok: [localhost] => {
    "msg": ""
}

致命的なエラーを取得する (デフォルト) には、以下を行います:

- name: if this file does not exist, FAIL (this is the default)
  debug: msg="{{ lookup('file', '/nosuchfile', errors='strict') }}"

[WARNING]: Unable to find '/nosuchfile' in expected paths (use -vvvvv to see paths)

fatal: [localhost]: FAILED! => {"msg": "An unhandled exception occurred while running the lookup plugin 'file'. Error was a <class 'ansible.errors.AnsibleError'>, original message: could not locate file in lookup: /nosuchfile"}

ルックアップが強制的にリストを返すようにする： query および wantlist=True

Ansible 2.5 では、lookup プラグインを呼び出すために query と呼ばれる新しい Jinja2 関数が追加されました。lookup と query の相違点は、query が常にリストを返すことです。lookup のデフォルト動作は、コンマ区切りの値の文字列を返すことです。lookup は、wantlist=True を使用してリストを返すように明示的に設定できます。

この機能により、新しい loop キーワードを操作するための、より簡単で一貫性のあるインターフェースが提供され、同時に lookup の他の使い方との後方互換性も維持されます。

以下の例はどちらも同等の操作ができます。

lookup('dict', dict_variable, wantlist=True)

query('dict', dict_variable)

上記の例のように、query を使用する場合、wantlist=True の動作は暗黙的になります。

また、query の短縮形となる q が導入されました。

q('dict', dict_variable)

プラグイン一覧

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