From 6e34e844171f5811461b4c13bda226263d974c03 Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Wed, 2 Sep 2015 16:38:23 -0400 Subject: [PATCH 1/4] documenting var precedence made new sections for vars, started explaining scope, gave example on command line override of connection vars added some formatting changes and clarifications --- docsite/rst/playbooks_variables.rst | 67 ++++++++++++++++++++++++----- 1 file changed, 56 insertions(+), 11 deletions(-) diff --git a/docsite/rst/playbooks_variables.rst b/docsite/rst/playbooks_variables.rst index 39bd9c335ea..19a74ba57fb 100644 --- a/docsite/rst/playbooks_variables.rst +++ b/docsite/rst/playbooks_variables.rst @@ -722,7 +722,7 @@ Variable Precedence: Where Should I Put A Variable? A lot of folks may ask about how variables override another. Ultimately it's Ansible's philosophy that it's better you know where to put a variable, and then you have to think about it a lot less. -Avoid defining the variable "x" in 47 places and then ask the question "which x gets used". +Avoid defining the variable "x" in 47 places and then ask the question "which x gets used". Why? Because that's not Ansible's Zen philosophy of doing things. There is only one Empire State Building. One Mona Lisa, etc. Figure out where to define a variable, and don't make @@ -731,19 +731,64 @@ it complicated. However, let's go ahead and get precedence out of the way! It exists. It's a real thing, and you might have a use for it. -If multiple variables of the same name are defined in different places, they win in a certain order, which is:: +If multiple variables of the same name are defined in different places, they get overwrriten in a certain order. +The order of precedence is (last one wins): - * extra vars (``-e`` in the command line) always win - * then comes connection variables defined in inventory (``ansible_user``, etc) - * then comes "most everything else" (command line switches, vars in play, included vars, role vars, etc) - * then comes the rest of the variables defined in inventory - * then comes facts discovered about a system - * then "role defaults", which are the most "defaulty" and lose in priority to everything. + * role defaults [1]_ + * inventory vars [2]_ + * inventory group_vars + * inventory host_vars + * playbook group_vars + * playbook host_vars + * host facts + * registered vars + * set_facts + * play vars + * play vars_prompt + * play vars_files + * role and include vars + * block vars (only for tasks in block) + * task vars (only for the task) + * extra vars +.. rubric:: Footnotes + +.. [1] Tasks in each role will see their own role's defaults tasks outside of roles will the last role's defaults +.. [2] Variables defined in inventory file or provided by dynamic inventory + +.. note:: Within a any section, redefining a var will overwrite the previous instance. + If multiple groups have the same variable, the last one loaded wins. + If you define a variable twice in a play's vars: section, the 2nd one wins. +.. note:: the previous describes the default config `hash_behavior=replace`, switch to 'merge' to only partially overwrite. .. note:: In versions prior to 1.5.4, facts discovered about a system were in the "most everything else" category above. -That seems a little theoretical. Let's show some examples and where you would choose to put what based on the kind of -control you might want over values. +Another important thing to consider is that connection spedific variables override config, command line and play specific options and directives. For example:: + + ansible_ssh_user will override `-u ` and `remote_user: ` + +This is done so host specific settings can override the general settings. These variables are normally defined per host or group in inventory, +but they behave like other variables, so if you really want to override the remote user globally even over inventory you can use extra vars:: + + ansible... -e "ansible_ssh_user=" + + +.. _variable_scopes: + +Variable Scopes +``````````````` + +Ansible has 3 main scopes: + + * Global: this is set by config, environment variables and the command line + * Play: each play and contained structures, vars entries, include_vars, role defaults and vars. + * Host: variables directly associated to a host, like inventory, facts or registered task outputs + +.. _variable_examples: + +Variable Examples +````````````````` + +That seems a little theoretical. Let's show some examples and where you would choose to put what based on the kind of control you might want over values. First off, group variables are super powerful. @@ -760,7 +805,7 @@ Regional information might be defined in a ``group_vars/region`` variable. If t --- # file: /etc/ansible/group_vars/boston - ntp_server: boston-time.example.com + ntp_server: boston-time.example.com If for some crazy reason we wanted to tell just a specific host to use a specific NTP server, it would then override the group variable!:: From 7f52d909c48f646ab6a2ae475b0ed1babdd1d257 Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Tue, 15 Sep 2015 11:00:38 -0400 Subject: [PATCH 2/4] rewrote 1.x section of precedence to prevent promissing specificity to those reading docs for earlier versions --- docsite/rst/playbooks_variables.rst | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/docsite/rst/playbooks_variables.rst b/docsite/rst/playbooks_variables.rst index 19a74ba57fb..e268c8a215a 100644 --- a/docsite/rst/playbooks_variables.rst +++ b/docsite/rst/playbooks_variables.rst @@ -732,7 +732,20 @@ However, let's go ahead and get precedence out of the way! It exists. It's a r a use for it. If multiple variables of the same name are defined in different places, they get overwrriten in a certain order. -The order of precedence is (last one wins): + +In 1.x the precedence is: + + * extra vars (``-e`` in the command line) always win + * then come connection variables (``ansible_user``, etc) + * then comes "most everything else" (command line switches, vars in play, included vars, role vars, etc) + * then come the variables defined in inventory + * then come the facts discovered about a system + * then "role defaults", which are the most "defaulty" and lose in priority to everything. + +.. note:: In versions prior to 1.5.4, facts discovered about a system were in the "most everything else" category above. + + +In 2.x we have made the order of precedence more specific (last one wins): * role defaults [1]_ * inventory vars [2]_ @@ -760,9 +773,9 @@ The order of precedence is (last one wins): If multiple groups have the same variable, the last one loaded wins. If you define a variable twice in a play's vars: section, the 2nd one wins. .. note:: the previous describes the default config `hash_behavior=replace`, switch to 'merge' to only partially overwrite. -.. note:: In versions prior to 1.5.4, facts discovered about a system were in the "most everything else" category above. -Another important thing to consider is that connection spedific variables override config, command line and play specific options and directives. For example:: + +Another important thing to consider (for all versions) is that connection spedific variables override config, command line and play specific options and directives. For example:: ansible_ssh_user will override `-u ` and `remote_user: ` From 4241df41aafb50462f0915dec60b5f7e2200067a Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Tue, 15 Sep 2015 11:45:55 -0400 Subject: [PATCH 3/4] fixed typoe (thanks @resmo) --- docsite/rst/playbooks_variables.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docsite/rst/playbooks_variables.rst b/docsite/rst/playbooks_variables.rst index e268c8a215a..66640999869 100644 --- a/docsite/rst/playbooks_variables.rst +++ b/docsite/rst/playbooks_variables.rst @@ -731,7 +731,7 @@ it complicated. However, let's go ahead and get precedence out of the way! It exists. It's a real thing, and you might have a use for it. -If multiple variables of the same name are defined in different places, they get overwrriten in a certain order. +If multiple variables of the same name are defined in different places, they get overwritten in a certain order. In 1.x the precedence is: From 0aeaacb947c624ba1a90171e7dc5ed2c6fde85ba Mon Sep 17 00:00:00 2001 From: Brian Coca Date: Tue, 15 Sep 2015 12:06:40 -0400 Subject: [PATCH 4/4] fixed zpellings --- docsite/rst/playbooks_variables.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docsite/rst/playbooks_variables.rst b/docsite/rst/playbooks_variables.rst index 66640999869..d88327adcf7 100644 --- a/docsite/rst/playbooks_variables.rst +++ b/docsite/rst/playbooks_variables.rst @@ -775,7 +775,7 @@ In 2.x we have made the order of precedence more specific (last one wins): .. note:: the previous describes the default config `hash_behavior=replace`, switch to 'merge' to only partially overwrite. -Another important thing to consider (for all versions) is that connection spedific variables override config, command line and play specific options and directives. For example:: +Another important thing to consider (for all versions) is that connection specific variables override config, command line and play specific options and directives. For example:: ansible_ssh_user will override `-u ` and `remote_user: `