Ansibleのplaybookで使用できるアトリビュートの一覧

はじめに

本資料は多数のドキュメントにバラバラに書かれているAnsibleのplaybookに指定可能なアトリビュートの一覧とそれぞれの簡単な解説である。

アトリビュートとは、playbookに記述することのできる各種のディクショナリキーのことである。と言っても現在のところこれが定まった呼び方というわけではない。Ansible v2のソースにAttributeと書かれているのでここでもそう呼ぶことにしたものである。

アトリビュートにはplayに指定できるもの、taskに指定できるもの、どちらにも指定できるものがある。
playあるいはtaskって何？ って話は http://docs.ansible.com/glossary.html を参照のこと。
要はplaybookはplayのリストで構成されており、playの中のtasksアトリビュートやhandlersアトリビュートなどに記述するのがtaskのリストである。

以下の内容はAnsible 1.9.1現在のものである。
v2以降は細かいところはそれなりに変化がありそうなので留意されたし。

一覧に入る前に補足説明を行っておく。

• True/Falseを指定する場合、true, t, y, 1, yesのいずれか（一部あるいは全部を大文字にしても良い）であればTrue、それ以外の値を指定すればFalseになる。
• 条件式を指定できる場合は条件式のリストも指定でき、リストの各要素の条件式がすべて真の場合に真となる。リストが入れ子になっている場合でもすべて真ならば真となる。またTrue/Falseも指定できるが上記のルールとは多少違い、Trueはtrue, yes, 0以外の数字のいずれか、Falseはfalse, no, 0のいずれかとなる（1文字目あるいは全部を大文字にしても良い）。
• ホスト名としてlocalhostはinventoryに定義していなくても指定でき、指定すると接続方式がlocalになる。127.0.0.1も同義である。
• taskには一覧に書いたもの以外に"モジュール名"や"with_(lookup plugin名)"も指定できる。

アトリビュートの一覧

name

指定可能な場所

play, task

指定可能な値

文字列

デフォルト値

hostsの値(play) / actionの値(task)

playやtaskに付ける名前。
taskの名前はnotifyや--start-at-taskオプションで指定する値として使用できる。

hosts

指定可能な場所

play

指定可能な値

"localhost"およびinventoryに定義されたホスト名あるいはグループ名、またはそのパターン

操作対象のホスト。
パターンについては関連ドキュメントを参照。
--limit(-l)オプションを指定した場合、hostsと--limitオプションとの両方で指定されたホストのみ操作対象となる。

関連ドキュメント

• http://docs.ansible.com/intro_patterns.html

tasks

指定可能な場所

play

指定可能な値

taskのリスト

このplayで実行したいtaskのリスト。

pre_tasks

指定可能な場所

play

指定可能な値

taskのリスト

このplayで真っ先に実行したいtaskのリスト。

• pre_tasks
• pre_tasksによって呼ばれたhandlers
• roles
• rolesによって呼ばれたhandlers
• tasks
• tasksによって呼ばれたhandlers
• post_tasks
• post_tasksによって呼ばれたhandlers

の順に実行される。

関連ドキュメント

• http://docs.ansible.com/guide_rolling_upgrade.html

post_tasks

指定可能な場所

play

指定可能な値

taskのリスト

このplayで最後に実行したいtaskのリスト。
実行順の詳細はpre_tasksの項を参照。

関連ドキュメント

• http://docs.ansible.com/guide_rolling_upgrade.html

handlers

指定可能な場所

play

指定可能な値

taskのリスト

notifyによって呼び出し可能なtaskのリストを定義する。
handlersに定義されたtaskは、それが未実行のうちに複数回呼び出されても一度しか実行されない。
flush_handlers（metaの項参照）されるなどで実行された場合、その後に再度同じhandlersのtaskが呼び出されればまたその次の実行タイミングで実行される。

関連ドキュメント

• http://docs.ansible.com/playbooks_intro.html

notify

指定可能な場所

task

指定可能な値

handlersに定義されたtaskのname、あるいはそのリスト

taskがchangedになった場合に、handlersに定義されたtaskのうち指定したものを呼び出し実行する。
handlersの実行タイミングはpre_tasks、およびmetaの項を参照。

関連ドキュメント

• http://docs.ansible.com/playbooks_intro.html

force_handlers

指定可能な場所

play

指定可能な値

True/False

デフォルト値

False

failedで処理が終了した場合でも、そこまでの処理で呼び出されたhandlersを実行するかどうか。

マイナーバージョンである1.9.1のタイミングで珍しく追加されたアトリビュートであり、設定ファイルを書き換えた後にansible-playbookがfailedで終了してhandlersに書いた設定反映を行う部分が実行されず、ansible-playbookを再実行しても今度は設定ファイルの変更がもう終わっていてchangedにならないのでhandlersが呼ばれず設定が反映されない、という問題に対する解決策である。
handlersを使っている時はTrueにした方が大抵は幸せになるのではないだろうか。

--force-handlersオプションが指定されている場合は通常すべてのplayにこの効果が現れるが、「force_handlers: False」を指定したplayについてはこの効果を打ち消すことができる。そんなことをする理由があるかはともかく。

関連ドキュメント

• http://docs.ansible.com/playbooks_error_handling.html

meta

指定可能な場所

task

指定可能な値

"flush_handlers"

他のアトリビュートと違い、これを指定した場合他のアトリビュートは無視される。
今のところ値にはflush_handlersしか指定できず、flush_handlersを指定した場合呼び出し済みで未実行のhandlersが実行される。

pre_tasksに記述した通り、pre_tasks, roles, tasks, post_tasksの各フェーズ完了時には未実行のhandlersが実行されるが、これはこの「meta: flush_handlers」が各フェーズの終わりに実行されたのに相当する。

roleのmetaディレクトリはたぶん関係ない。

関連ドキュメント

• http://docs.ansible.com/playbooks_intro.html

include

指定可能な場所

play, task

指定可能な値

YAMLファイルのパス

対象のYAMLファイルをplayで指定するとplayのリストとして、taskで指定するとtaskのリストとして取り込む。
他のアトリビュートと違い、これを指定した場合他の多数のアトリビュートは無視される。
taskで使用した場合、includeと同じレベルで指定したキーと値のセットは次に示す特殊なキーを除き、includeで取り込んだtaskのリストに渡される変数名とその値とのセットとなる。

• tags
• sudo
• sudo_user
• become
• become_method
• become_user
• su
• su_user
• when
• vars
• role_params
• default_vars
• role_name

同名のアトリビュートがあるものは効果はそれと同じである。
同名のアトリビュートがないものについては次の通り。

role_params, vars, default_varsはいずれもincludeで取り込んだtaskのリストに渡される変数を指定する。
優先順位はrole_params, vars, (特殊キー以外によるもの), default_varsの順で高い。

role_nameを指定すると、まるでこれがroleであるかのように、ログ出力されたり--start-at-taskオプションで使えたりするrole名が付く。
role_nameを指定した場合varsの中に値が文字列であるuuidというキーも指定する必要がある。（何に使われているのかは不明）

「when: 0」は何故か真になるようなので注意。

playで使用した場合、includeとともに指定できるのはvarsだけである。
意味はtaskのものと同じである。

関連ドキュメント

• http://docs.ansible.com/playbooks_roles.html

roles

指定可能な場所

play

指定可能な値

role名かroleをキーに含むディクショナリのどちらかを要素とするリスト

指定したリストの要素がスカラーの場合はそれと同じ名前のroleを、ディクショナリの場合はroleキーの値と同じ名前のroleを取り込む。
リストの要素がディクショナリの場合、キーと値のセットは次に示す特殊なキーを除き、roleに渡される変数名とその値とのセットとなる。

• role
• tags
• when
• sudo
• sudo_user
• su
• su_user
• become
• become_user

同名のアトリビュートがあるものは効果はそれと同じである。
同名のアトリビュートがないroleは説明済み。取り込み対象のrole名である。

includeと同じく「when: 0」は何故か真になるようなので注意。

--start-at-taskオプションをrole内のtaskを指定する場合、「(role名) | (task名)」と「(task名)」のどちらでも良い。
「(task名)」と指定した場合は同じnameのtaskがある場合、それらのうち一番最初に実行されるtaskから処理が開始される。

関連ドキュメント

• http://docs.ansible.com/playbooks_roles.html

role_names

指定可能な場所

play

おそらくdeprecatedになったアトリビュートで、使い方不明。

serial

指定可能な場所

play

指定可能な値

整数、あるいは整数の後に"%"

デフォルト値

0（つまり、全台を表す）

hostsのうち何台ごとにplayの処理を区切るか。数値の最後に%をつけた場合はhosts全台数に対する割合の台数となる（小数点以下切捨て）。
この台数分のplayで実行されるtaskの処理がすべて、つまりpre_tasksからpost_tasksのhandlersまで終わったら、次の同じ台数に対して処理が行われる。最後の1回は残った台数に対する処理となる。
小数部を含む数値を指定すると%をつけてもつけなくてもエラーになる。%をつけた結果0台以下になると1台に修正される。%をつけず0以下を指定すると処理が区切られずhostsに指定された全台が対象になる。

--forks(-f)オプションと近いが、serialでは設定台数ごとに別々のtask扱いとなるのが違い、serialが適用されてからそれとは別に--forksオプションも適用される。

gather_factsはserialの影響を受けない。

serialを指定した状態で--start-at-taskオプションを使うと一回り目の指定したtaskから始まり、二回り目以降は最初のtaskから実行される。

関連ドキュメント

• http://docs.ansible.com/playbooks_delegation.html

max_fail_percentage

指定可能な場所

play

指定可能な値

整数

デフォルト値

100

taskの操作対象ホストのうちfailedになった割合が、この設定値%を超えていた場合には次の処理に移らない。
設定値の小数点以下は切り捨てられ、割合を計算した結果の台数の小数点以下も切り捨てられ、その数字がfailedを許容する台数になる。つまりfailedだったホスト数と同数の場合は次の処理に移る。
ただし100以上を指定しても、操作対象ホストすべてでfailedになった場合は次の処理に移らない。

serialとともに指定すると、serialの設定台数に対してmax_fail_percentageの設定値%を超えているかで判断される。

関連ドキュメント

• http://docs.ansible.com/playbooks_delegation.html

any_errors_fatal

指定可能な場所

play, task

指定可能な値

True/False

デフォルト値

False

taskにも指定できること以外は「max_fail_percentage: 0」と同じ。

delegate_to

指定可能な場所

task

指定可能な値

inventoryに定義された単一のホスト名、あるいは接続可能な単一のホスト名やIPアドレス

taskの実行を、指定したホスト上で行う。
何気にinventoryに定義されていない対象も指定できる。

関連ドキュメント

• http://docs.ansible.com/playbooks_delegation.html

run_once

指定可能な場所

task

指定可能な値

True/False

デフォルト値

False

操作対象ホストが何台あっても1台かつ1回しか実行されないようにするかどうか。
delegate_toとともに使用するとdelegate_toに指定したホストで実行される。
delegate_toを指定していなければ配列上一番最初になっているホストで実行される。

関連ドキュメント

• http://docs.ansible.com/playbooks_delegation.html

action

指定可能な場所

task

指定可能な値

モジュール名とそのオプション

実行したいモジュール名とそのオプション。
「(モジュール名): (オプション)」と同じ意味で、通常はactionを使わずそちらを使うことが推奨されている。内部的にはactionを使った記述に直されるようで、taskのnameのデフォルト値はactionを使った記述にした時の値である。

あとモジュール名に変数を使いたい場合はactionを使った記述にすれば良い。一例としてansible_pkg_mgr変数でOSごとにパッケージマネージャを変えてパッケージのインストールを行うなど。

関連ドキュメント

• http://docs.ansible.com/playbooks_intro.html

local_action

指定可能な場所

task

指定可能な値

モジュール名とそのオプション

「action: (値), delegate_to: localhost」と同じ。

関連ドキュメント

• http://docs.ansible.com/playbooks_delegation.html

gather_facts

指定可能な場所

play

指定可能な値

True/False

対応するansible.cfgの設定項目

[defaults] gathering

操作対象hostsのプラットフォーム情報(facts)を収集して変数を参照することで利用できるようにするかどうか。
Falseにしておくとその分playbook全体の実行時間が短縮されるが、私は間違ってplaybookを実行してすぐに気付いてgather_factsの段階で中止して事なきを得たことが複数回あるので、基本切ることはない。

関連ドキュメント

• http://docs.ansible.com/playbooks_variables.html

register

指定可能な場所

task

指定可能な値

変数名となる文字列

このtaskの実行結果を保存する変数。
スコープはplaybookである。

この変数をfailed, changed, success, skippedでフィルタ(|)可能である。
それ以外の値の取り出し方はまとまったドキュメントがあるわけではなく、結局--verbose(-v)オプションで変数の内容が表示されるのでそれを見て取り出し方を考えることになる。

関連ドキュメント

• http://docs.ansible.com/playbooks_conditionals.html

vars

指定可能な場所

play

指定可能な値

ディクショナリ

playスコープで使用可能な変数の定義。

各種の変数の優先順位は関連ドキュメントの http://docs.ansible.com/playbooks_variables.html#variable-precedence-where-should-i-put-a-variable を参照のこと。

関連ドキュメント

• http://docs.ansible.com/playbooks_variables.html

vars_files

指定可能な場所

play

指定可能な値

内容がディクショナリであるYAMLファイルのパスのリスト

playスコープで使用可能な変数名をキーとするディクショナリが書かれたYAMLファイルのリスト。リストが入れ子になっていてもすべて読み込み対象になる。

関連ドキュメント

• http://docs.ansible.com/playbooks_variables.html

vars_prompt

指定可能な場所

play

指定可能な値

ディクショナリ、あるいはディクショナリのリスト

ansible-playbook実行時に値をユーザに入力させる変数を指定する。
スコープはvarsと同様playだが2回以上同じ入力をさせられるのはつらいので、playbookスコープにしたければset_factモジュールを「set_fact: var1={{ var1 }}」（var1はvars_promptでユーザに入力させた変数とする）のように使用してからhostvars変数から取り出すなどする。

ディクショナリで指定した場合、各キーが入力させる変数名であり、そのキーの値は入力時にプロンプト表示させる文字列である（省略時はNone）。

ディクショナリのリストで指定した場合、リストの各要素のnameキーの値が入力させる変数名である。
その他に次のようなキーを使用できる。

prompt

入力時にプロンプト表示させる文字列。省略時はnameと同じ。

private

入力した文字を画面に表示させないようにするかどうかをTrue/Falseで指定する。省略時はTrue。なおvars_promptをディクショナリで指定した場合はこれはFalseになっている。

confirm

確認のために2回入力させるかどうかをTrue/Falseで指定する。省略時はFalse。

また、操作する側にpython-passlibがインストールされていれば値をハッシュ化するためにさらに次のようなキーも使用できる。

encrypt

値をハッシュ化するハッシュ化アルゴリズム。利用可能なアルゴリズムの種類は関連ドキュメント参照。省略時はハッシュ化しない。

salt_size

指定した文字数のsaltをランダムに生成する。省略時はアルゴリズムによって違う文字数のsaltをランダムに生成する。

salt

saltをランダムに生成せず指定した文字列を使用する。salt_sizeが指定されていない時のみ有効。

関連ドキュメント

• http://docs.ansible.com/playbooks_prompts.html

args

指定可能な場所

task

指定可能な値

ディクショナリ

モジュールに渡すパラメタ。
すべてのモジュールは(パラメタ名)=(値)でモジュールに渡すことができるが、これを使用するのはディクショナリ形式で渡したい場合である。

とはいえ大抵のモジュールではargsがなくてもディクショナリ形式で渡すことができる。
argsが必要になるのはactionやlocal_actionを使う、あるいはcommandモジュールやshellモジュールのようにコマンドをパラメタ名なしでモジュールに渡す部分とディクショナリ形式で渡す部分が混在している場合である。

environment

指定可能な場所

play, task

指定可能な値

ディクショナリ

task（playに指定しているならplay内で定義されているすべてのtask）を実行する際に操作対象に与える環境変数。

関連ドキュメント

• http://docs.ansible.com/playbooks_environment.html

connection

指定可能な場所

play, task

指定可能な値

connection pluginの名前、あるいは"smart"

デフォルト値

"smart"

操作対象にどのconnection pluginを使用して接続するか。
値がsmartの場合、操作する側がOS Xか「ssh -o ControlPersist」がエラーになる場合はparamiko、そうでなければsshとなる。

inventoryでansible_connectionが指定されている場合はそちらが優先される。localhostは暗黙的にansible_connection=localであるため、connectionを指定しても変更できないので注意。

transport

指定可能な場所

task

指定可能な値

connection pluginの名前、あるいは"smart"

デフォルト値

"smart"

おそらくconnectionに置き換えられた古いアトリビュート。
playに指定できないこと以外はconnectionと同じ。

remote_user

指定可能な場所

play, task

指定可能な値

文字列

デフォルト値

ansible-playbookの実行ユーザ名

対応するansible.cfgの設定項目

[defaults] remote_user

操作対象にどのユーザで接続するか。
inventoryでansible_ssh_userが指定されている場合はそちらが優先される。
--user(-u)オプションで指定されている場合はremote_userの値の方が優先される。

関連ドキュメント

• http://docs.ansible.com/playbooks_intro.html

user

指定可能な場所

play

指定可能な値

文字列

デフォルト値

ansible-playbookの実行ユーザ名

対応するansible.cfgの設定項目

[defaults] remote_user

remote_userに置き換えられた古いアトリビュート。
taskに指定できないこと以外はremote_userと同じ。

Ansible 1.4にてuserモジュールと混同するからリネームした、と関連ドキュメントに書かれている。

関連ドキュメント

• http://docs.ansible.com/playbooks_intro.html

port

指定可能な場所

play

指定可能な値

ポート番号として利用可能な数値

デフォルト値

なし（事実上22）

対応するansible.cfgの設定項目

[defaults] remote_port

操作対象にどのポート番号で接続するか。
inventoryでansible_ssh_portが指定されている場合はそちらが優先される。

accelerate

指定可能な場所

play

指定可能な値

True/False

デフォルト値

False

accelerated modeを有効にするかどうか。
有効にする場合、操作される側にpython-keyczarをインストールしている必要がある。

関連ドキュメントによると速度は、pipelining有効時のSSH接続、accelerated modeでの接続、pipelining無効時のSSH接続、paramikoでの接続の順に速いようなので、pipeliningを有効にしてSSH接続できるならaccelerated modeを使う必要はないだろう。

なおpipeliningはplayなどのアトリビュートで設定できずansible.cfgで設定する（pipelining=True）か環境変数を使う（ANSIBLE_SSH_PIPELINING=True）。
pipeliningを有効にするとsudo利用時にrequirettyを無効にしなければならない、と書かれているがこれはaccelerated modeでも同じである。
また、操作する側がCentOS 6.5以下などでtransport=smartの場合にparamiko接続が選ばれる場合でも強制的にSSH接続にしてやればpipeliningで高速化するように見える。

結局のところaccelerated modeを使う局面は、Ansibleのバージョンがaccelerated modeが導入された1.3以上、pipeliningが導入された1.5未満であるか、playごとに制御したい場合になるだろうか。

関連ドキュメント

• http://docs.ansible.com/playbooks_acceleration.html

accelerate_ipv6

指定可能な場所

play

指定可能な値

True/False

デフォルト値

False

ドキュメントに説明がない上、効果を得られたこともないため良くわからないが、accelerated modeでIPv6を有効にするかどうか、という設定のはずである。

accelerate_port

指定可能な場所

play

指定可能な値

ポート番号として利用可能な数値

デフォルト値

5099

対応するansible.cfgの設定項目

[accelerate] accelerate_port

accelerated mode使用時に操作される側で開くポートの番号。

関連ドキュメント

• http://docs.ansible.com/playbooks_acceleration.html

become

指定可能な場所

play, task

指定可能な値

True/False

デフォルト値

False

対応するansible.cfgの設定項目

[privilege_escalation] become

接続ユーザ以外で対象ホストを操作するかどうか。

become, su, sudoは同時に指定できるのは1つだけである。

関連ドキュメント

• http://docs.ansible.com/become.html

become_method

指定可能な場所

play, task

指定可能な値

"sudo", "su", "pbrun", "pfexec", "runas"のどれか

デフォルト値

"sudo"

対応するansible.cfgの設定項目

[privilege_escalation] become_method

接続ユーザ以外で対象ホストを操作するために使用するコマンド。
--become-methodオプションの値を上書きする。

関連ドキュメント

• http://docs.ansible.com/become.html

become_user

指定可能な場所

play, task

指定可能な値

操作対象ホストに存在するユーザ名

対応するansible.cfgの設定項目

[privilege_escalation] become_user

接続ユーザ以外で対象ホストを操作するのにどのユーザを使用するか。
--become-userオプションの値を上書きする。

関連ドキュメント

• http://docs.ansible.com/become.html

become_pass

指定可能な場所

task

指定可能な値

パスワード文字列

接続ユーザ以外で対象ホストを操作するのに使用するユーザのパスワード。
何故かplayでは指定できない。

sudo

指定可能な場所

play, task

指定可能な値

True/False

デフォルト値

False

対応するansible.cfgの設定項目

[defaults] sudo

Ansible 1.9にてbecomeなどに置き換えられたアトリビュートで、「become: True, become_method: sudo」と同じ。

sudo_user

指定可能な場所

play, task

指定可能な値

操作対象ホストに存在するユーザ名

デフォルト値

"root"

対応するansible.cfgの設定項目

[defaults] sudo_user

Ansible 1.9にてbecome_userに置き換えられたアトリビュート。
become_userと同じく接続ユーザ以外で対象ホストを操作するのにどのユーザを使用するか。

sudo_pass

指定可能な場所

task

指定可能な値

パスワード文字列

Ansible 1.9にてbecome_passに置き換えられたアトリビュート。
become_passと同じく接続ユーザ以外で対象ホストを操作するのに使用するユーザのパスワード。
何故かplayでは指定できない。

su

指定可能な場所

play, task

指定可能な値

True/False

デフォルト値

False

対応するansible.cfgの設定項目

[defaults] su

Ansible 1.9にてbecomeなどに置き換えられたアトリビュートで、「become: True, become_method: su」と同じ。

su_user

指定可能な場所

play, task

指定可能な値

操作対象ホストに存在するユーザ名

デフォルト値

"root"

対応するansible.cfgの設定項目

[defaults] su_user

Ansible 1.9にてbecome_userに置き換えられたアトリビュート。
become_userと同じく接続ユーザ以外で対象ホストを操作するのにどのユーザを使用するか。

su_pass

指定可能な場所

task

指定可能な値

パスワード文字列

Ansible 1.9にてbecome_passに置き換えられたアトリビュート。
become_passと同じく接続ユーザ以外で対象ホストを操作するのに使用するユーザのパスワード。
何故かplayでは指定できない。

changed_when

指定可能な場所

task

指定可能な値

条件式、あるいはそのリスト

指定した条件式が真の場合にのみ、taskの実行結果をchangedにする。
with_*でループしている場合itemを条件式に使用できる。また、このtaskでregisterで代入した変数も条件式に使用できるが、set_factモジュールで代入した変数はそれをregisterしていなければまだ使えない。

関連ドキュメント

• http://docs.ansible.com/playbooks_error_handling.html

failed_when

指定可能な場所

task

指定可能な値

条件式、あるいはそのリスト

指定した条件式が真の場合にのみ、taskの実行結果をfailedにする。
changed_whenと同じく、ループ時のitemやregisterで代入した変数を条件式に使用できる。

ちなみにchanged_whenの条件にもfailed_whenの条件にも一致した場合はchangedかつfailedになる。

関連ドキュメント

• http://docs.ansible.com/playbooks_error_handling.html

ignore_errors

指定可能な場所

task

指定可能な値

条件式、あるいはそのリスト

taskの実行結果がfailedの場合でも処理を次に進めるかどうか。
自然にfailedになった場合でもfailed_whenでfailedになった場合でも同じく次へ進む。
ignore_errorsが有効な場合、max_fail_percentageやany_errors_fatalの効果を打ち消す。

「failed_when: False」との違いはregisterすると「(変数) | failed」が真になることである。

関連ドキュメント

• http://docs.ansible.com/playbooks_error_handling.html

when

指定可能な場所

task

指定可能な値

条件式、あるいはそのリスト

指定した条件式が真の場合にのみ、taskを実行する。
with_*でループしている場合itemを条件式に使用できるが、当然だがregisterより判断タイミングが早いのでregisterで代入しようとしている変数は使えない。

関連ドキュメント

• http://docs.ansible.com/playbooks_conditionals.html

always_run

指定可能な場所

task

指定可能な値

条件式、あるいはそのリスト

チェックモードの時にこのtaskを予行(dry run)ではなく実際に動作させるかどうか。
チェックモードはtaskを予行させるモードで、--check(-C)オプションを指定すると入る。

commandモジュールやshellモジュールのようなチェックモードに対応していないモジュールはチェックモードの時は予行ではなくskipされるが、そのような場合でもalways_runが真なら実際に動作する。

関連ドキュメント

• http://docs.ansible.com/playbooks_checkmode.html

tags

指定可能な場所

play, task

指定可能な値

文字列、あるいは文字列のリスト

このtaskを動作させるかを制御するタグ。playに指定するとplay内のすべてのtaskにそれらのタグが追加される。

--tags(-t)オプションで指定したタグ（カンマ区切りで複数指定できる）のどれかとtaskのタグのどれかが一致した場合のみこのtaskは実行される。
また--skip-tagsオプションで指定したタグ（こちらもカンマ区切りで複数指定できる）のどれかとtaskのタグのどれかが一致した場合にはこのtaskは実行されない。
--tagsオプションにも--skip-tagsオプションにもtaskのタグのどれかが一致した場合は実行されない。

taskのタグとして特殊なタグであるalwaysを指定した場合、--tagsオプションに指定したタグが何だろうと実行される。
関連ドキュメントに書かれている仕様上は「--skip-tags always」の場合のみ実行されない、と書かれているが実際には--skip-tagsオプションのタグのどれかとtaskのタグのどれかが一致した場合には実行されない。

また--tagsや--skip-tagsに指定できる特殊なタグとしてtagged, untagged, allがある。
taggedは1つ以上のタグが設定されたtaskすべてに一致する。
untaggedはタグが1つも設定されていないtaskすべてに一致する。ただし、「--tags untagged」の時にもalwaysタグの付いたtaskは実行される。
allはすべてのtaskに一致する。「--tags all」は--tagsオプションを省略した場合に等しい。

handlersのtaskにはタグを付けても無意味なようだ。

関連ドキュメント

• http://docs.ansible.com/playbooks_tags.html

until

指定可能な場所

task

指定可能な値

条件式、あるいはそのリスト

指定した条件式が真になるかretriesの回数だけ試行を繰り返す。
registerが必須となる。

関連ドキュメント

• http://docs.ansible.com/playbooks_loops.html

retries

指定可能な場所

task

指定可能な値

1以上の整数

デフォルト値

3（untilが指定されている場合のみ）

untilの条件を満たすまでに最大何回まで試行するか。
untilが必須となる。
最初の試行は0回目ではなく1回目と数える。
小数部のある数字を指定すると挙動がおかしい（failedにならない）。0以下はエラーになる。

ちなみに、試行を繰り返してもwith_random_choiceやrandomフィルタで選ばれるものは変わらないようだ。

関連ドキュメント

• http://docs.ansible.com/playbooks_loops.html

delay

指定可能な場所

task

指定可能な値

0以上の数字

デフォルト値

5（untilが指定されている場合のみ）

untilの条件を満たすまでの試行の間に何秒間sleepするか。
untilが必須となる。
1回目にtaskを実行してからチェックするまでの間もsleepしている。
小数点以下も切り捨てられず有効である。0だと遅延なく繰り返される。マイナスだとエラーになる。

関連ドキュメント

• http://docs.ansible.com/playbooks_loops.html

async

指定可能な場所

task

指定可能な値

整数

デフォルト値

0（つまり、無効）

taskを非同期モードで実行し、何秒待つか。
小数点以下は切り捨てられる。0を指定した場合は非同期モードではなくなる。マイナスを指定した場合は事実上0秒待ちの非同期モードになる。

非同期モードとはtaskをデーモンとして実行することである。
バックグラウンドで実行するようなコマンドをtaskで実行させる場合は、taskがすぐに完了して次へ進んでしまいその時点で接続が切れるため、非同期モードにしないとそのtaskは停止する（ansible-playbookの処理はエラーにならずそのまま進む）。

taskが実行するモジュールと同名のaction pluginがある場合は非同期モードにはできずエラーになる。
またWinRM接続の場合もエラーになる。

関連ドキュメント

• http://docs.ansible.com/playbooks_async.html

poll

指定可能な場所

task

指定可能な値

0以上の整数

デフォルト値

10

asyncを使って非同期モードで実行しているtaskが完了しているかどうかを何秒ごとに確認するか。
小数点以下は切り捨てられる。0以下を指定した場合は0として扱われる。

0の場合は確認せずに完了したものとして次のtaskに進む。この場合このtaskに対してその後にasync_statusモジュールが使われない限りは、このtaskが完了したかどうかはansible側ではもはや感知しないのでasyncの数値は（非同期モードでなくなる0を除き）どれであっても変わらない。

バックグラウンドで実行するようなコマンドをtaskで実行させる場合はansible側では一瞬でtaskが完了したかのように見えるため、pollの数字はいくつであっても結果は変わらない。なので単純に待ち時間が無駄なのでpollは0にすれば良いだろう。

関連ドキュメント

• http://docs.ansible.com/playbooks_async.html

no_log

指定可能な場所

play, task

指定可能な値

True/False

デフォルト値

False

通常--verbose(-v)オプションで表示される実行結果の中にある変数の値を表示しないようにするかどうか。
具体的にはskipped, changed, failed, rc以外が隠される。
パスワードのような文字列が表示されるとまずい場合に使用する。
ansible.cfgの[defaults] log_path項でログ出力されるように設定している場合も同様に隠される。

関連ドキュメント

• http://docs.ansible.com/faq.html

first_available_file

指定可能な場所

task

指定可能な値

ファイルのパスのリスト

指定したリストの上位からファイルが存在するかを確認し、一番最初に見つかったファイルのパスをcopyモジュールやtemplateモジュールのsrcに渡す。

with_first_foundに似ているがcopyモジュールかtemplateモジュールでしか使えず、「src={{ item }}」のような記述ではなくsrcを省略できる。

vault_password

指定可能な場所

play

playに指定可能ではあるが、ソースを見る限りおそらく参照されておらず無意味。