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