mirror of
https://github.com/ansible-collections/community.general.git
synced 2024-09-14 20:13:21 +02:00
373b1dcf59
* Docs refactor as outlined in https://github.com/ansible/proposals/issues/79. Moves content into 'guides'; refactors TOC; fixes CSS; design tweaks to layout and CSS; fixes generated plugin, CLI and module docs to fix links accodingly; more. * Adding extra blank line for shippable
424 lines
14 KiB
ReStructuredText
424 lines
14 KiB
ReStructuredText
Playbook Keywords
|
|
=================
|
|
|
|
These are the keywords available on common playbook objects.
|
|
|
|
.. note:: Please note:
|
|
|
|
* Aliases for the directives are not reflected here, nor are mutable one. For example,
|
|
:term:`action` in task can be substituted by the name of any Ansible module.
|
|
* The keywords do not have ``version_added`` information at this time
|
|
* Some keywords set defaults for the objects inside of them rather than for the objects
|
|
themselves
|
|
|
|
|
|
.. contents::
|
|
:local:
|
|
:depth: 1
|
|
|
|
|
|
Play
|
|
----
|
|
.. glossary::
|
|
|
|
always_run
|
|
*DEPRECATED*, forces a task to run even in check mode. Use :term:`check_mode` directive instead.
|
|
|
|
any_errors_fatal
|
|
Force any un-handled task errors on any host to propagate to all hosts and end the play.
|
|
|
|
become
|
|
Boolean that controls if privilege escalation is used or not on :term:`Task` execution.
|
|
|
|
become_flags
|
|
A string of flag(s) to pass to the privilege escalation program when :term:`become` is True.
|
|
|
|
become_method
|
|
Which method of privilege escalation to use (such as sudo or su).
|
|
|
|
become_user
|
|
User that you 'become' after using privilege escalation. The remote/login user must have permissions to become this user.
|
|
|
|
check_mode
|
|
A boolean that controls if a task is executed in 'check' mode
|
|
|
|
.. seealso:: :ref:`check_mode_dry`
|
|
|
|
connection
|
|
Allows you to change the connection plugin used for tasks to execute on the target.
|
|
|
|
.. seealso:: :ref:`using_connection`
|
|
|
|
debugger
|
|
UNDOCUMENTED!!
|
|
|
|
diff
|
|
Toggle to make tasks return 'diff' information or not.
|
|
|
|
environment
|
|
A dictionary that gets converted into environment vars to be provided for the task upon execution.
|
|
|
|
fact_path
|
|
Set the fact path option for the fact gathering plugin controlled by :term:`gather_facts`.
|
|
|
|
force_handlers
|
|
Will force notified handler execution for hosts even if they failed during the play. Will not trigger if the play itself fails.
|
|
|
|
gather_facts
|
|
A boolean that controls if the play will automatically run the 'setup' task to gather facts for the hosts.
|
|
|
|
gather_subset
|
|
Allows you to pass subset options to the fact gathering plugin controlled by :term:`gather_facts`.
|
|
|
|
gather_timeout
|
|
Allows you to set the timeout for the fact gathering plugin controlled by :term:`gather_facts`.
|
|
|
|
handlers
|
|
A section with tasks that are treated as handlers, these won't get executed normally, only when notified after each section of tasks is complete.
|
|
|
|
hosts
|
|
A list of groups, hosts or host pattern that translates into a list of hosts that are the play's target.
|
|
|
|
ignore_errors
|
|
Boolean that allows you to ignore task failures and continue with play. It does not affect connection errors.
|
|
|
|
max_fail_percentage
|
|
can be used to abort the run after a given percentage of hosts in the current batch has failed.
|
|
|
|
name
|
|
Identifier. Can be used for documentation, in or tasks/handlers.
|
|
|
|
no_log
|
|
Boolean that controls information disclosure.
|
|
|
|
order
|
|
Controls the sorting of hosts as they are used for executing the play. Possible values are inventory (default), sorted, reverse_sorted, reverse_inventory and shuffle.
|
|
|
|
port
|
|
Used to override the default port used in a connection.
|
|
|
|
post_tasks
|
|
A list of tasks to execute after the :term:`tasks` section.
|
|
|
|
pre_tasks
|
|
A list of tasks to execute before :term:`roles`.
|
|
|
|
remote_user
|
|
User used to log into the target via the connection plugin.
|
|
|
|
roles
|
|
List of roles to be imported into the play
|
|
|
|
run_once
|
|
Boolean that will bypass the host loop, forcing the task to execute on the first host available and will also apply any facts to all active hosts.
|
|
|
|
serial
|
|
Explicitly define how Ansible batches the execution of the current play on the play's target
|
|
|
|
.. seealso:: :ref:`rolling_update_batch_size`
|
|
|
|
strategy
|
|
Allows you to choose the connection plugin to use for the play.
|
|
|
|
tags
|
|
Tags applied to the task or included tasks, this allows selecting subsets of tasks from the command line.
|
|
|
|
tasks
|
|
Main list of tasks to execute in the play, they run after :term:`roles` and before :term:`post_tasks`.
|
|
|
|
vars
|
|
Dictionary/map of variables
|
|
|
|
vars_files
|
|
List of files that contain vars to include in the play.
|
|
|
|
vars_prompt
|
|
list of variables to prompt for.
|
|
|
|
vault_password
|
|
Secret used to decrypt vaulted files or variables.
|
|
|
|
|
|
Role
|
|
----
|
|
.. glossary::
|
|
|
|
always_run
|
|
*DEPRECATED*, forces a task to run even in check mode. Use :term:`check_mode` directive instead.
|
|
|
|
any_errors_fatal
|
|
Force any un-handled task errors on any host to propagate to all hosts and end the play.
|
|
|
|
become
|
|
Boolean that controls if privilege escalation is used or not on :term:`Task` execution.
|
|
|
|
become_flags
|
|
A string of flag(s) to pass to the privilege escalation program when :term:`become` is True.
|
|
|
|
become_method
|
|
Which method of privilege escalation to use (such as sudo or su).
|
|
|
|
become_user
|
|
User that you 'become' after using privilege escalation. The remote/login user must have permissions to become this user.
|
|
|
|
check_mode
|
|
A boolean that controls if a task is executed in 'check' mode
|
|
|
|
.. seealso:: :ref:`check_mode_dry`
|
|
|
|
connection
|
|
Allows you to change the connection plugin used for tasks to execute on the target.
|
|
|
|
.. seealso:: :ref:`using_connection`
|
|
|
|
debugger
|
|
UNDOCUMENTED!!
|
|
|
|
delegate_facts
|
|
Boolean that allows you to apply facts to a delegated host instead of inventory_hostname.
|
|
|
|
delegate_to
|
|
Host to execute task instead of the target (inventory_hostname). Connection vars from the delegated host will also be used for the task.
|
|
|
|
diff
|
|
Toggle to make tasks return 'diff' information or not.
|
|
|
|
environment
|
|
A dictionary that gets converted into environment vars to be provided for the task upon execution.
|
|
|
|
ignore_errors
|
|
Boolean that allows you to ignore task failures and continue with play. It does not affect connection errors.
|
|
|
|
name
|
|
Identifier. Can be used for documentation, in or tasks/handlers.
|
|
|
|
no_log
|
|
Boolean that controls information disclosure.
|
|
|
|
port
|
|
Used to override the default port used in a connection.
|
|
|
|
remote_user
|
|
User used to log into the target via the connection plugin.
|
|
|
|
run_once
|
|
Boolean that will bypass the host loop, forcing the task to execute on the first host available and will also apply any facts to all active hosts.
|
|
|
|
tags
|
|
Tags applied to the task or included tasks, this allows selecting subsets of tasks from the command line.
|
|
|
|
vars
|
|
Dictionary/map of variables
|
|
|
|
when
|
|
Conditional expression, determines if an iteration of a task is run or not.
|
|
|
|
|
|
Block
|
|
-----
|
|
.. glossary::
|
|
|
|
always
|
|
List of tasks, in a block, that execute no matter if there is an error in the block or not.
|
|
|
|
always_run
|
|
*DEPRECATED*, forces a task to run even in check mode. Use :term:`check_mode` directive instead.
|
|
|
|
any_errors_fatal
|
|
Force any un-handled task errors on any host to propagate to all hosts and end the play.
|
|
|
|
become
|
|
Boolean that controls if privilege escalation is used or not on :term:`Task` execution.
|
|
|
|
become_flags
|
|
A string of flag(s) to pass to the privilege escalation program when :term:`become` is True.
|
|
|
|
become_method
|
|
Which method of privilege escalation to use (such as sudo or su).
|
|
|
|
become_user
|
|
User that you 'become' after using privilege escalation. The remote/login user must have permissions to become this user.
|
|
|
|
block
|
|
List of tasks in a block.
|
|
|
|
check_mode
|
|
A boolean that controls if a task is executed in 'check' mode
|
|
|
|
.. seealso:: :ref:`check_mode_dry`
|
|
|
|
connection
|
|
Allows you to change the connection plugin used for tasks to execute on the target.
|
|
|
|
.. seealso:: :ref:`using_connection`
|
|
|
|
debugger
|
|
UNDOCUMENTED!!
|
|
|
|
delegate_facts
|
|
Boolean that allows you to apply facts to a delegated host instead of inventory_hostname.
|
|
|
|
delegate_to
|
|
Host to execute task instead of the target (inventory_hostname). Connection vars from the delegated host will also be used for the task.
|
|
|
|
diff
|
|
Toggle to make tasks return 'diff' information or not.
|
|
|
|
environment
|
|
A dictionary that gets converted into environment vars to be provided for the task upon execution.
|
|
|
|
ignore_errors
|
|
Boolean that allows you to ignore task failures and continue with play. It does not affect connection errors.
|
|
|
|
name
|
|
Identifier. Can be used for documentation, in or tasks/handlers.
|
|
|
|
no_log
|
|
Boolean that controls information disclosure.
|
|
|
|
port
|
|
Used to override the default port used in a connection.
|
|
|
|
remote_user
|
|
User used to log into the target via the connection plugin.
|
|
|
|
rescue
|
|
List of tasks in a :term:`block` that run if there is a task error in the main :term:`block` list.
|
|
|
|
run_once
|
|
Boolean that will bypass the host loop, forcing the task to execute on the first host available and will also apply any facts to all active hosts.
|
|
|
|
tags
|
|
Tags applied to the task or included tasks, this allows selecting subsets of tasks from the command line.
|
|
|
|
vars
|
|
Dictionary/map of variables
|
|
|
|
when
|
|
Conditional expression, determines if an iteration of a task is run or not.
|
|
|
|
|
|
Task
|
|
----
|
|
.. glossary::
|
|
|
|
action
|
|
The 'action' to execute for a task, it normally translates into a C(module) or action plugin.
|
|
|
|
always_run
|
|
*DEPRECATED*, forces a task to run even in check mode. Use :term:`check_mode` directive instead.
|
|
|
|
any_errors_fatal
|
|
Force any un-handled task errors on any host to propagate to all hosts and end the play.
|
|
|
|
args
|
|
*DEPRECATED*, A secondary way to add arguments into a task. Takes a dictionary in which keys map to options and values.
|
|
|
|
async_val
|
|
UNDOCUMENTED!!
|
|
|
|
become
|
|
Boolean that controls if privilege escalation is used or not on :term:`Task` execution.
|
|
|
|
become_flags
|
|
A string of flag(s) to pass to the privilege escalation program when :term:`become` is True.
|
|
|
|
become_method
|
|
Which method of privilege escalation to use (such as sudo or su).
|
|
|
|
become_user
|
|
User that you 'become' after using privilege escalation. The remote/login user must have permissions to become this user.
|
|
|
|
changed_when
|
|
Conditional expression that overrides the task's normal 'changed' status.
|
|
|
|
check_mode
|
|
A boolean that controls if a task is executed in 'check' mode
|
|
|
|
.. seealso:: :ref:`check_mode_dry`
|
|
|
|
connection
|
|
Allows you to change the connection plugin used for tasks to execute on the target.
|
|
|
|
.. seealso:: :ref:`using_connection`
|
|
|
|
debugger
|
|
UNDOCUMENTED!!
|
|
|
|
delay
|
|
Number of seconds to delay between retries. This setting is only used in combination with :term:`until`.
|
|
|
|
delegate_facts
|
|
Boolean that allows you to apply facts to a delegated host instead of inventory_hostname.
|
|
|
|
delegate_to
|
|
Host to execute task instead of the target (inventory_hostname). Connection vars from the delegated host will also be used for the task.
|
|
|
|
diff
|
|
Toggle to make tasks return 'diff' information or not.
|
|
|
|
environment
|
|
A dictionary that gets converted into environment vars to be provided for the task upon execution.
|
|
|
|
failed_when
|
|
Conditional expression that overrides the task's normal 'failed' status.
|
|
|
|
ignore_errors
|
|
Boolean that allows you to ignore task failures and continue with play. It does not affect connection errors.
|
|
|
|
local_action
|
|
Same as action but also implies ``delegate_to: localhost``
|
|
|
|
loop
|
|
Takes a list for the task to iterate over, saving each list element into the ``item`` variable (configurable via loop_control)
|
|
|
|
loop_control
|
|
Several keys here allow you to modify/set loop behaviour in a task.
|
|
|
|
.. seealso:: :ref:`loop_control`
|
|
|
|
loop_with
|
|
UNDOCUMENTED!!
|
|
|
|
name
|
|
Identifier. Can be used for documentation, in or tasks/handlers.
|
|
|
|
no_log
|
|
Boolean that controls information disclosure.
|
|
|
|
notify
|
|
List of handlers to notify when the task returns a 'changed=True' status.
|
|
|
|
poll
|
|
Sets the polling interval in seconds for async tasks (default 10s).
|
|
|
|
port
|
|
Used to override the default port used in a connection.
|
|
|
|
register
|
|
Name of variable that will contain task status and module return data.
|
|
|
|
remote_user
|
|
User used to log into the target via the connection plugin.
|
|
|
|
retries
|
|
Number of retries before giving up in a :term:`until` loop. This setting is only used in combination with :term:`until`.
|
|
|
|
run_once
|
|
Boolean that will bypass the host loop, forcing the task to execute on the first host available and will also apply any facts to all active hosts.
|
|
|
|
tags
|
|
Tags applied to the task or included tasks, this allows selecting subsets of tasks from the command line.
|
|
|
|
until
|
|
This keyword implies a ':term:`retries` loop' that will go on until the condition supplied here is met or we hit the :term:`retries` limit.
|
|
|
|
vars
|
|
Dictionary/map of variables
|
|
|
|
when
|
|
Conditional expression, determines if an iteration of a task is run or not.
|
|
|
|
with_<lookup_plugin>
|
|
DEPRECATED: use ``loop`` instead, ``with_`` used to be how loops were defined,
|
|
|