Misleading statement about "defaults" and "vars" sub-folders of roles

[mikhailknyazev]

Summary

Hi all, there is misleading statement in https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_reuse_roles.html : " Directories defaults and vars may also include nested directories. If your variables file is a directory, Ansible reads all variables files and directories inside in alphabetical order. " It is misleading because that holds true ONLY for "defaults/main/" and "vars/main/" subdirectories.

Please find the detailed description and the test project attached.

Issue Type

Documentation Report

Component Name

https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_reuse_roles.html

Ansible Version

$ ansible --version
ansible [core 2.14.9]
  config file = /etc/ansible/ansible.cfg
  configured module search path = ['/home/ec2-user/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /usr/lib/python3.9/site-packages/ansible
  ansible collection location = /home/ec2-user/.ansible/collections:/usr/share/ansible/collections
  executable location = /usr/bin/ansible
  python version = 3.9.18 (main, Jan  4 2024, 00:00:00) [GCC 11.4.1 20230605 (Red Hat 11.4.1-2)] (/usr/bin/python3)
  jinja version = 3.1.2
  libyaml = True

Configuration

# if using a version older than ansible-core 2.12 you should omit the '-t all'
$ ansible-config dump --only-changed -t all
CONFIG_FILE() = /etc/ansible/ansible.cfg

OS / Environment

cat /etc/os-release

NAME="Red Hat Enterprise Linux" VERSION="9.3 (Plow)"

Additional Information

playbook_and_role_variables_test_MK_18Aug2025.pdf

playbook_variables_test.zip

Code of Conduct

• [x] I agree to follow the Ansible Code of Conduct

[ansibot]

Files identified in the description:

None

If these files are incorrect, please update the component name section of the description or use the component bot command.

[flowerysong]

No, it's also true for other names. main is just the only one that's loaded automatically (the "variables file" referenced in the text you quoted.)

[s-hertel]

The way to use alternative files is just above the section you quoted:

You can add other YAML files in some directories, but they won’t be used by default. They can be included/imported directly or specified when using include_role/import_role. For example, you can place platform-specific tasks in separate files and refer to them in the tasks/main.yml file:

Here's the playbook (please upload reproducers inline instead of using attachments):

- name: Demonstrate Ansible variable precedence
  hosts: localhost
  connection: local
  gather_facts: false

  vars:
    service_port: 9000
    playbook_var: "Defined in the playbook"

  roles:
    - test_vars

The roles: keyword will always use defaults. You can use import_role or include_role instead:

  tasks:
    - import_role:
        vars_from: ./  # override default (main) and include ALL variables recursively in alphabetical order
        name: test_vars

[mikhailknyazev]

While there are different ways to approach this, adding clarity to the documentation would be very valuable. Ansible practitioners often have limited time and can be easily confused when reading fragments — they expect concise, self-contained statements.

[ansible-documentation-bot[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.

[samccann]

Notes on what's misleading in the docs:

The paragraph makes it sound like anything in vars/ or defaults/ will get read automatically but you have to either nest under /main/ or else include other files/directories explicitly, per the paragraph above.

Possible fix:

• Clarify that Ansible only automatically picks up from /vars/main/ and /defaults/main/.
• Point to section above on how to get playbooks to pick up other yaml files outside of these.