Create And Share Your Own Role

You can write your own roles to perform repetitive tasks easily and efficiently but a whole ecosystem of already-written roles worth checking before writing your own from scratch. Ansible Galaxy as named “Galaxy” is indeed a “Galaxy of Roles”.

Generating A Role Skeleton With ansible-galaxy role init

ansible-galaxy role init myapp

This creates a properly-structured role directory automatically, with every standard subdirectory from earlier in this section already stubbed out with placeholder main.yml files. Beyond convenience, it protects against a real risk flagged earlier: a typo’d directory name would silently just never get auto-loaded, with no error telling you why — generating the structure removes that risk entirely.

What Gets Created

myapp/
  README.md
  defaults/
    main.yml
  files/
  handlers/
    main.yml
  meta/
    main.yml
  tasks/
    main.yml
  templates/
  tests/
    inventory
    test.yml
  vars/
    main.yml

Two things beyond what’s already been covered: README.md, a documentation placeholder genuinely worth filling in properly — a role with no explanation of what variables it expects is much harder for anyone (including future you) to actually use. And tests/, a minimal inventory and test playbook scaffold for verifying the role works correctly in isolation, before it’s ever used in a real deployment — a full testing discussion is its own topic, but the scaffold is there from the start either way.

Where Ansible Looks For Roles: The roles/ Directory Convention

By default, Ansible looks for roles in a directory literally named roles/, sitting alongside the playbook — exactly the structure every example in this section has used. roles:, import_role, and include_role all resolve a role’s name against this directory automatically, the same automatic-resolution spirit as templates//files/ resolving within a role itself.

A Brief Note On Ansible Galaxy

Galaxy is Ansible’s public registry for sharing and discovering roles (and collections) other people have already written and published. Rather than writing a role from scratch for something extremely common — setting up PostgreSQL, configuring a firewall — it’s often worth checking whether a well-tested community role already does exactly that.

Installing A Role From Galaxy

ansible-galaxy role install geerlingguy.postgresql

Downloads and installs a specific published role — named author.role_name by convention — into your local roles/ directory, ready to use in your own playbooks exactly like a role you wrote yourself, via roles:.

A Gotcha: Role Search Path Depends On Where You Run From

Like several path-resolution rules already covered in this course, Ansible’s default role search path is relative to the playbook’s own location — a roles/ directory sitting next to it. This can also be extended with additional search directories via ansible.cfg’s roles_path setting, from the configuration chapter back in the very first section of this course. If a role “can’t be found” unexpectedly, checking roles_path and confirming you’re running from the expected directory is the first thing to check — exactly the same “verify before assuming something’s broken” habit that chapter established for configuration in general.

Best Practices

• Use ansible-galaxy role init to scaffold new roles, rather than creating the directory structure by hand — it removes an entire class of silent, hard-to-diagnose typo mistakes.
• Check Ansible Galaxy before writing a role from scratch for something genuinely common — a well-maintained community role can save real time.
• If a role can’t be found, check your working directory and ansible.cfg’s roles_path before assuming something is wrong with the role itself.