Ansible variables quick reference

Quick reference to parameters and special variables.

Built-in variables

These are variables that are always defined by ansible.

Parameter	Description
hostvars	A dict whose keys are Ansible host names and values are dicts that map variable names to values
group_names	A list of all groups that the current host is a member of
groups	A dict whose keys are Ansible group names and values are list of hostnames that are members of the group. Includes all and ungrouped groups: {"all": [...], "web": [...], "ungrouped": [...]}
inventory_hostname	Name of the current host as known by ansible.
play_hosts	A list of inventory hostnames that are active in the current play (or current batch if running serial)
ansible_version	A dict with ansible version info: {"full": 1.8.1", "major": 1, "minor": 8, "revision": 1, "string": "1.8.1"}
role_path	The current role’s pathname (available only inside a role)

These can be useful if you want to use a variable associated with a different host. For example, if you are using the EC2 dynamic inventory and have a single host with the tag “Name=foo”, and you want to access the instance id in a different play, you can do something like this:

- hosts: tag_Name_foo
  tasks:
    - action: ec2_facts

  ...

- hosts: localhost
  vars:
    instance_id: {{ hostvars[groups['tag_Name_foo'][0]]['ansible_ec2_instance_id'] }}
  tasks:
    - name: print out the instance id for the foo instance
      debug: msg=instance-id is {{ instance_id }}

Internal variables

These are used internally by Ansible.

Variable	Description
playbook_dir	Directory that contains the playbook being executed
inventory_dir	Directory that contains the inventory
inventory_file	Host file or script path (?)

Play parameters

Parameter	Description
any_errors_fatal
gather_facts	Specify whether to gather facts or not
handlers	List of handlers
hosts	Hosts in the play (e.g., webservers).
include	Include a playbook defined in another file
max_fail_percentage	When serial is set on a play, and some hosts fail on a task, if the percentage of hosts that fail exceeds this number, Ansible will fail the whole play. (e.g., 20).
name	Name of the play, displayed when play runs (e.g., Deploy a foo).
pre_tasks	List of tasks to execute before roles.
port	Remote ssh port to connect to
post_tasks	List of tasks to execute after roles.
remote_user role_names	Alias for user.
roles	List of roles.
serial su su_user	Integer that indicates how many hosts Ansible should manage at a single
become	Boolean that indicates whether ansible should become another user (e.g., True).
become_user	If become'ing, user to become as. Defaults: root.
sudo	(deprecated, use become) Boolean that indicates whether ansible should use sudo (e.g., True).
sudo_user	(deprecated, use become_uesr) If sudo'ing, user to sudo as. Defaults: root.
tasks	List of tasks.
user no_log	User to ssh as. Default: root (unless overridden in config file)
vars	Dictionary of variables. this is the holy grail of variables, it will output everything!
vars_files	List of files that contain dictionary of variables.
vars_prompt vault_password	Description of vars that user will be prompted to specify.

Task parameters

Parameter	Description
name	Name of the task, displayed when task runs (e.g., Ensure foo is present).
action	Name of module to specify. Legacy format, prefer specifying module name directly instead
args	A dictionary of arguments. See docs for ec2_tag for an example.
include	Name of a separate YAML file that includes additional tasks.
register	Record the result to the specified variable (e.g., result)
delegate_to	Run task on specified host instead.
local_action	Equivalent to: delegate_to: 127.0.0.1.
remote_user	Alias for user.
user	User to ssh as for this task
become	Boolean that indicates whether ansible should become another user (e.g., True).
become_user	If become'ing, user to become as. Defaults: root.
sudo	Boolean that indicates whether ansible should use sudo on this task
sudo_user	If sudo'ing, user to sudo as.
when	Boolean. Only run task when this evaluates to True. Default: True
ignore_errors	Boolean. If True, ansible will treat task as if it has succeeded even if it returned an error, Default: False
module	More verbose notation for specifying module parameters. See docs for ec2 for an example.
environment	Mapping that contains environment variables to pass
failed_when	Specify criteria for identifying task has failed (e.g., "'FAILED' in command_result.stderr")
changed_when	Specify criteria for identifying task has changed server state
with_items	List of items to iterate over
with_nested	List of list of items to iterate over in nested fashion
with_fileglob	List of local files to iterate over, described using shell fileglob notation (e.g., /playbooks/files/fooapp/*)
with_first_found	Return the first file or path, in the given list, that exists on the control machine
with_together	Dictionary of lists to iterate over in parallel
with_random_choice	List of items to be selected from at random
with_dict	Loop through the elements of a hash
with_sequence	Loop over a range of integers
until	Boolean, task will retry until evaluates true or until retries
retries	Used with "until", number of times to retry. Default: 3
delay	Used with "until", seconds to wait between retries. Default: 10
run_once	If true, runs task on only one of the hosts
always_run	If true, runs task even when in --check mode

Host variables that modify ansible behavior

Parameter	Description
ansible_ssh_host	hostname to connect to for a given host
ansible_ssh_port	ssh port to connect to for a given host
ansible_ssh_user	ssh user to connect as for a given host
ansible_ssh_pass	ssh password to connect as for a given host
ansible_ssh_private_key_file	ssh private key file to connect as for a given host
ansible_connection	connection type to use for a given host (e.g. local)
ansible_python_interpreter	python interpreter to use
ansible_*_interpreter	interpreter to use

See also

• Ansible return values