Quick reference
Quick reference to parameters and special variables.
Facts
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
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 | Alias for user. |
| role_names | ย |
| roles | List of roles. |
| serial | Integer that indicates how many hosts Ansible should manage at a single |
| su | ย |
| su_user | ย |
| 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) |
| no_log | ย |
| 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. |
| vault_password | ย |
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 |
Complex args
There are three ways to specify complex arguments:
just pass them:
- ec2_tag:
resource: vol-abcdefg
tags:
Name: my-volume
action/module parameter:
- action:
module: ec2_tag
resource: vol-abcdefg
tags:
Name: my-volume
args parameter:
- ec2_tag: resource=vol-abcdefg
args:
tags:
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 }}
with_items:
- 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": [
"echo",
"foo"
],
"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": [
"echo",
"bar"
],
"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": [
"echo",
"baz"
],
"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"
}
]
}