Quick reference for Ansible variables
Switch branches/tags
Nothing to show
Clone or download
Latest commit 5eee0e1 Apr 8, 2017
Failed to load latest commit information.
README.rst holy grail var Apr 8, 2017
docker.rst use rst-style indenting Dec 28, 2014
ec2.rst Don't quote bullets Jan 11, 2015
facts.rst instance -> machine Feb 15, 2015


Quick reference

Quick reference to parameters and special variables.


See facts.

EC2 stuff

See ec2.

Docker stuff

See docker.

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
    - action: ec2_facts


- hosts: localhost
    instance_id: {{ hostvars[groups['tag_Name_foo'][0]]['ansible_ec2_instance_id'] }}
    - 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
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 Alias for user.
roles List of roles.
serial 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 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 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:
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

Complex args

There are three ways to specify complex arguments:

just pass them:

- ec2_tag:
    resource: vol-abcdefg
      Name: my-volume

action/module parameter:

- action:
    module: ec2_tag
    resource: vol-abcdefg
      Name: my-volume

args parameter:

- ec2_tag: resource=vol-abcdefg
      Name: my-volume

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

Variables returned by setup

These are the same as the output of Facts described in a previous section. Currently, this just has one variable defined.

Parameter Description Example
ansible_date_time Dictionary that contains date info {"date": "2013-10-02", "day": "02", "epoch": "1380756810", "hour": "19","iso8601": "2013-10-02T23:33:30Z","iso8601_micro": "2013-10-02T23:33:30.036070Z","minute": "33","month": "10","second": "30","time": "19:33:30","tz": "EDT","year": "2013"}

Return value of a loop

If you register a variable with a task that has an iteration, e.g.:

- command: echo {{ item }}
    - foo
    - bar
    - baz
  register: echos

Then the result is a dictionary with the following values:

Field name Description
changed boolean, true if anything has changed
msg a message such as "All items completed"
results a list that contains the return value for each loop iteration

For example, the echos variable would have the following value:

    "changed": true,
    "msg": "All items completed",
    "results": [
            "changed": true,
            "cmd": [
            "delta": "0:00:00.002780",
            "end": "2014-06-08 16:57:52.843478",
            "invocation": {
                "module_args": "echo foo",
                "module_name": "command"
            "item": "foo",
            "rc": 0,
            "start": "2014-06-08 16:57:52.840698",
            "stderr": "",
            "stdout": "foo"
            "changed": true,
            "cmd": [
            "delta": "0:00:00.002736",
            "end": "2014-06-08 16:57:52.911243",
            "invocation": {
                "module_args": "echo bar",
                "module_name": "command"
            "item": "bar",
            "rc": 0,
            "start": "2014-06-08 16:57:52.908507",
            "stderr": "",
            "stdout": "bar"
            "changed": true,
            "cmd": [
            "delta": "0:00:00.003050",
            "end": "2014-06-08 16:57:52.979928",
            "invocation": {
                "module_args": "echo baz",
                "module_name": "command"
            "item": "baz",
            "rc": 0,
            "start": "2014-06-08 16:57:52.976878",
            "stderr": "",
            "stdout": "baz"