You are reading an unmaintained version of the Ansible documentation. Unmaintained Ansible versions can contain unfixed security vulnerabilities (CVE). Please upgrade to a maintained version. See the latest Ansible documentation.
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,
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
- accelerate
- DEPRECATED, set to True to use accelerate connection plugin.
- accelerate_ipv6
- DEPRECATED, set to True to force accelerate plugin to use ipv6 for its connection.
- accelerate_port
- DEPRECATED, set to override default port use for accelerate connection.
- always_run
- DEPRECATED, forces a task to run even in check mode. Use 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 Task execution.
- become_flags
- A string of flag(s) to pass to the privilege escalation program when 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
- connection
Allows you to change the connection plugin used for tasks to execute on the target.
See also
using_connection
- 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 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 gather_facts.
- gather_timeout
- Allows you to set the timeout for the fact gathering plugin controlled by 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 tasks section.
- pre_tasks
- A list of tasks to execute before 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
- 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 roles and before 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.
- always_run
- DEPRECATED, forces a task to run even in check mode. Use 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 Task execution.
- become_flags
- A string of flag(s) to pass to the privilege escalation program when 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
- connection
Allows you to change the connection plugin used for tasks to execute on the target.
See also
using_connection
- 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.
- 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.
- 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 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 Task execution.
- become_flags
- A string of flag(s) to pass to the privilege escalation program when 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
- connection
Allows you to change the connection plugin used for tasks to execute on the target.
See also
using_connection
- 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 block that run if there is a task error in the main 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.
- 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 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
- Run a task asyncronouslly if the C(action) supports this.
- become
- Boolean that controls if privilege escalation is used or not on Task execution.
- become_flags
- A string of flag(s) to pass to the privilege escalation program when 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
- connection
Allows you to change the connection plugin used for tasks to execute on the target.
See also
using_connection
- delay
- Number of seconds to delay between retries. This setting is only used in combination with 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_control
Several keys here allow you to modify/set loop behaviour in a task.
- 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 until loop. This setting is only used in combination with 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 ‘retries loop’ that will go on until the condition supplied here is met or we hit the retries limit.
- vars
- Dictionary/map of variables
- when
- Conditional expression, determines if an iteration of a task is run or not.
- with_<lookup_plugin>
- with_ is how loops are defined, it can use any available lookup plugin to generate the item list
