You write a role, add it to a playbook and run it. Ansible stops before the first task. It says the role was not found and prints a list of folders. The role is on the disk, so why can Ansible not see it?
Ansible does not search the whole disk for roles. It checks a short list of places: collections, if you use them, then a roles/ folder next to the playbook, then the folders in roles_path, and then the folder of the playbook itself. A role that you created in your home folder, or inside another project, is not in any of these places.
The simple fix is to create the role in the right place from the start. ansible-galaxy builds the standard folder layout for you, and --init-path tells it where to put that layout:
mkdir -p roles ansible-galaxy role init --init-path roles chrony ansible-playbook -i inventory site.yml Here site.yml is in the same folder as roles/, and it lists chrony under roles:. If you keep shared roles in another folder, add that folder to roles_path in ansible.cfg. Then you do not need to move them.
The full guide explains what each folder in the layout is for. It builds a small working role that installs chrony, writes its config from a template and restarts the service with a handler. It shows how to change a role setting for one play. It explains why a value in vars/ wins over group_vars, while a value in defaults/ loses to almost everything. It also compares roles:, import_role and include_role, and shows when each one runs.
Read the full guide: https://learnitlessons.com/articles/ansible-roles-explained/
Written with AI assistance and checked by the author.
