Rewrite precedence rules for more clarify

[amarao]

I found existing explanation of precedence rules a bit confusing and not giving enough information.

1. I added one more layer of precedence, 'all' vars looses to 'group-specific' variables within inventory file or script.

- #. inventory file or script group vars [2]_
+ #. variables for group "all" defined inside of an inventory file or script [2]_
+ #. other group vars defined inside of an inventory file or script [2]_

This is true and it wasn't reflected in the documentation.

Proof: For an inventory inv.yaml:

---
testgroup:
  hosts:
    test:
  vars:
    foo: testgroup

all:
  vars:
    foo: allgroup

Result is:

ansible -i inv.yaml -c local -m debug -a var=foo all
test | SUCCESS => {
    "foo": "testgroup"
}

2. Clarify that inventory group_vars/all is about files (notation group_vars/all is ambiguous and can be interpreted as group_vars.all within file, also). It also allow to understand better difference between playbook and inventory group vars.

-  #. inventory group_vars/all [3]_
-  #. playbook group_vars/all [3]_
-  #. inventory group_vars/* [3]_
-  #. playbook group_vars/* [3]_
+  #. inventory group_vars/all (a file in the directory group_vars/ adjacent to the inventory) [3]_
+  #. playbook group_vars/all (a file in the directory group_vars/ adjacent to the playbook) [3]_
+  #. inventory group_vars/* (a file in the directory group_vars/ adjacent to the inventory) [3]_
+  #. playbook group_vars/* (a file in the directory group_vars/ adjacent to the playbook) [3]_

3. Clarification for hostvars inside an inventory file.

-  #. inventory file or script host vars [2]_
+  #. host vars defined in an inventory file or script [2]_

4. Clarification for host_vars (same as for 2)

-  #. inventory host_vars/* [3]_
-  #. playbook host_vars/* [3]_
+  #. inventory host_vars/* (a file in the directory host_vars/ adjacent to the inventory) [3]_
+  #. playbook host_vars/* (a file in the directory host_vars/ adjacent to the inventory) [3]_

5. Explain 'play vars'

-  #. play vars
+  #. play vars (defined in the section vars for the play)

6. An additional clarification for the special (but very popular) case, when host_group_vars plugin scan the same group_vars/ twice, this happens when an inventory and a playbook are in the same directory, and there is group_vars/ directory there.

+If inventory file is located in the same directory as a playbook, adjacent group_vars/ are interpreted twice both as inventory group_vars/ and playbook group_vars/, therefore, getting precedence of the playbook group_vars.
+

There is also change for example yaml, removing trailing white spaces, done by my editor, but I think, it's correct:

    vars:
      list1:
      - apple
      - banana
      - fig
      list2:
      - peach
      - plum
      - pear
-
+    
    tasks:
    - name: Combine list1 and list2 into a merged_list var
      ansible.builtin.set_fact:

[ansible-documentation-bot]

Thanks for your Ansible docs contribution! We talk about Ansible documentation on Matrix at #docs:ansible.im if you ever want to join us and chat about the docs! We meet on Matrix every Tuesday. See the Ansible calendar for meeting details. We welcome additions to our weekly agenda items too. You can add the dawgs-meeting tag to a forum topic to bring it up at the next meeting.

[SteveRodrigue]

The changes looks to me. I would argue the problem with the precedence isn't the documentation but the fact it is very complex and convoluted. But this is out of scope.

Maybe the "... adjacent to..." could be defined outside the list to keep the list clean and avoid repetition.

[amarao]

@SteveRodrigue, I may be slightly odd, but every time I read group_vars/all, I can't understand what it means, there is an ambiguity between file path and logical path in the inventory.

I understand that I bring a lot of verbosity, but I want to make it absolutely non-ambiguous, because of my personal bad experience when I tried to internalize those rules. You read the line, and it describes what it is beyond any doubts.

[oraNod]

made a few suggestions to wording and added backticks for formatting. I know some of the wording was in there before the suggested changes but might as well try and improve that while we're in here.

Thanks for the contribution @amarao

[oraNod]

Suggested change

	If inventory file is located in the same directory as a playbook, adjacent group_vars/ are interpreted twice both as inventory group_vars/ and playbook group_vars/, therefore, getting precedence of the playbook group_vars.
	If an inventory file is located in the same directory as a playbook, adjacent ``group_vars/`` are interpreted twice, both as inventory ``group_vars/`` and playbook ``group_vars/``. As a result, the ``group_vars/`` from the inventory file get precedence over the playbook ``group_vars``.

[bcoca]

This is incorrect, at no point does the inventory file get precedence over the playbook's group_vars.

What happens is that since the file is processed x2, it ends up with the highest precedence, that of the playbook relative file.

[amarao]

Hello, thank you for suggestion I accept it, but correct for playbook been 'stronger'.

[oraNod]

Suggested change

	#. play vars (defined in the section vars for the play)
	#. play vars (defined in the ``vars`` section for the play)

[bcoca]

there are also vars_prompt and vars_files

[amarao]

It was added by Don Naro

[bcoca]

The text shows precedence by source, there is a separate text for 'group' precedence rules https://docs.ansible.com/ansible/latest/inventory_guide/intro_inventory.html#how-variables-are-merged.

A change is needed, but mostly should be about vars plugins vs 'host_vars/group_vars' which are specific to the default vars plugin (host_group_vars) which is shipped with core.

[amarao]

I understand about rewriting, but within this change, should I change something? @bcoca?

[bcoca]

I would remove mentions of 'all' and either change the group_vars/host_vars to instances of vars plugin per group/host or make note that this is the case but using host_group_vars as an example