Quick reference¶
- Forked from ansible-quickref
- Thanks, Lorin
Quick reference to parameters and special variables.
Topics
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"} |
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 | |
sudo | Boolean that indicates whether ansible should use sudo (e.g., True ). |
sudo_user | 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. |
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 . |
user | User to ssh as for this task |
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 |
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"
}
]
}