1.. _general_precedence_rules:
2
3Controlling how Ansible behaves: precedence rules
4=================================================
5
6To give you maximum flexibility in managing your environments, Ansible offers many ways to control how Ansible behaves: how it connects to managed nodes, how it works once it has connected.
7If you use Ansible to manage a large number of servers, network devices, and cloud resources, you may define Ansible behavior in several different places and pass that information to Ansible in several different ways.
8This flexibility is convenient, but it can backfire if you do not understand the precedence rules.
9
10These precedence rules apply to any setting that can be defined in multiple ways (by configuration settings, command-line options, playbook keywords, variables).
11
12.. contents::
13   :local:
14
15Precedence categories
16---------------------
17
18Ansible offers four sources for controlling its behavior. In order of precedence from lowest (most easily overridden) to highest (overrides all others), the categories are:
19
20 * Configuration settings
21 * Command-line options
22 * Playbook keywords
23 * Variables
24
25Each category overrides any information from all lower-precedence categories. For example, a playbook keyword will override any configuration setting.
26
27Within each precedence category, specific rules apply. However, generally speaking, 'last defined' wins and overrides any previous definitions.
28
29Configuration settings
30^^^^^^^^^^^^^^^^^^^^^^
31
32:ref:`Configuration settings<ansible_configuration_settings>` include both values from the ``ansible.cfg`` file and environment variables. Within this category, values set in configuration files have lower precedence. Ansible uses the first ``ansible.cfg`` file it finds, ignoring all others. Ansible searches for ``ansible.cfg`` in these locations in order:
33
34 * ``ANSIBLE_CONFIG`` (environment variable if set)
35 * ``ansible.cfg`` (in the current directory)
36 * ``~/.ansible.cfg`` (in the home directory)
37 * ``/usr/local/etc/ansible/ansible.cfg``
38
39Environment variables have a higher precedence than entries in ``ansible.cfg``. If you have environment variables set on your control node, they override the settings in whichever ``ansible.cfg`` file Ansible loads. The value of any given environment variable follows normal shell precedence: the last value defined overwrites previous values.
40
41Command-line options
42^^^^^^^^^^^^^^^^^^^^
43
44Any command-line option will override any configuration setting.
45
46When you type something directly at the command line, you may feel that your hand-crafted values should override all others, but Ansible does not work that way. Command-line options have low precedence - they override configuration only. They do not override playbook keywords, variables from inventory or variables from playbooks.
47
48You can override all other settings from all other sources in all other precedence categories at the command line by  :ref:`general_precedence_extra_vars`, but that is not a command-line option, it is a way of passing a :ref:`variable<general_precedence_variables>`.
49
50At the command line, if you pass multiple values for a parameter that accepts only a single value, the last defined value wins. For example, this :ref:`ad-hoc task<intro_adhoc>` will connect as ``carol``, not as ``mike``::
51
52      ansible -u mike -m ping myhost -u carol
53
54Some parameters allow multiple values. In this case, Ansible will append all values from the hosts listed in inventory files inventory1 and inventory2::
55
56   ansible -i /path/inventory1 -i /path/inventory2 -m ping all
57
58The help for each :ref:`command-line tool<command_line_tools>` lists available options for that tool.
59
60Playbook keywords
61^^^^^^^^^^^^^^^^^
62
63Any :ref:`playbook keyword<playbook_keywords>` will override any command-line option and any configuration setting.
64
65Within playbook keywords, precedence flows with the playbook itself; the more specific wins against the more general:
66
67- play (most general)
68- blocks/includes/imports/roles (optional and can contain tasks and each other)
69- tasks (most specific)
70
71A simple example::
72
73   - hosts: all
74     connection: ssh
75     tasks:
76       - name: This task uses ssh.
77         ping:
78
79       - name: This task uses paramiko.
80         connection: paramiko
81         ping:
82
83In this example, the ``connection`` keyword is set to ``ssh`` at the play level. The first task inherits that value, and connects using ``ssh``. The second task inherits that value, overrides it, and connects using ``paramiko``.
84The same logic applies to blocks and roles as well. All tasks, blocks, and roles within a play inherit play-level keywords; any task, block, or role can override any keyword by defining a different value for that keyword within the task, block, or role.
85
86Remember that these are KEYWORDS, not variables. Both playbooks and variable files are defined in YAML but they have different significance.
87Playbooks are the command or 'state description' structure for Ansible, variables are data we use to help make playbooks more dynamic.
88
89.. _general_precedence_variables:
90
91Variables
92^^^^^^^^^
93
94Any variable will override any playbook keyword, any command-line option, and any configuration setting.
95
96Variables that have equivalent playbook keywords, command-line options, and configuration settings are known as :ref:`connection_variables`. Originally designed for connection parameters, this category has expanded to include other core variables like the temporary directory and the python interpreter.
97
98Connection variables, like all variables, can be set in multiple ways and places. You can define variables for hosts and groups in :ref:`inventory<intro_inventory>`. You can define variables for tasks and plays in ``vars:`` blocks in :ref:`playbooks<about_playbooks>`. However, they are still variables - they are data, not keywords or configuration settings. Variables that override playbook keywords, command-line options, and configuration settings follow the same rules of :ref:`variable precedence <ansible_variable_precedence>` as any other variables.
99
100When set in a playbook, variables follow the same inheritance rules as playbook keywords. You can set a value for the play, then override it in a task, block, or role::
101
102   - hosts: cloud
103     gather_facts: false
104     become: yes
105     vars:
106       ansible_become_user: admin
107     tasks:
108       - name: This task uses admin as the become user.
109         dnf:
110           name: some-service
111           state: latest
112       - block:
113           - name: This task uses service-admin as the become user.
114             # a task to configure the new service
115           - name: This task also uses service-admin as the become user, defined in the block.
116             # second task to configure the service
117         vars:
118           ansible_become_user: service-admin
119       - name: This task (outside of the block) uses admin as the become user again.
120         service:
121           name: some-service
122           state: restarted
123
124Variable scope: how long is a value available?
125""""""""""""""""""""""""""""""""""""""""""""""
126
127Variable values set in a playbook exist only within the playbook object that defines them. These 'playbook object scope' variables are not available to subsequent objects, including other plays.
128
129Variable values associated directly with a host or group, including variables defined in inventory, by vars plugins, or using modules like :ref:`set_fact<set_fact_module>` and :ref:`include_vars<include_vars_module>`, are available to all plays. These 'host scope' variables are also available via the ``hostvars[]`` dictionary.
130
131.. _general_precedence_extra_vars:
132
133Using ``-e`` extra variables at the command line
134^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
135
136To override all other settings in all other categories, you can use extra variables: ``--extra-vars`` or ``-e`` at the command line. Values passed with ``-e`` are variables, not command-line options, and they will override configuration settings, command-line options, and playbook keywords as well as variables set elsewhere. For example, this task will connect as ``brian`` not as ``carol``::
137
138   ansible -u carol -e 'ansible_user=brian' -a whoami all
139
140You must specify both the variable name and the value with ``--extra-vars``.
141