Loading...

VONDS ©

Lab 103: Managing Roles with ansible-galaxy

Back to Lab Index

Use ansible-galaxy to discover and install roles, then generate a clean role skeleton inside a project-local roles/ directory. Validate the workflow by running a role-based playbook against an inventory target.

automation roles ansible

Scenario

You are standardizing how configuration is delivered across environments and want a repeatable way to reuse roles. Your goal is to search Galaxy for a proven Nginx role, install it, run it from a playbook, and then create a clean skeleton for an internal role that will live in your repo.

Operator context

Treat third-party roles like dependencies. Validate behavior, pin versions when possible, and keep your project structure consistent so roles are discoverable and maintainable over time.

Objective

  • Create a project directory with a local roles/ path.
  • Search Ansible Galaxy for a community role and install one.
  • Use the installed role from a simple site playbook.
  • Generate a new custom role skeleton with ansible-galaxy init.

Concepts

  • Role lifecycle: search, install, consume, then author.
  • Default Galaxy install paths versus project-local roles/.
  • Role execution via roles: and the default entry point (tasks/main.yml).
  • Role skeleton layout: tasks, handlers, defaults, vars, templates, and files.
  • Reproducibility basics: version pinning and consistent structure to reduce drift.

Walkthrough

Step 1 : Create a project directory and a local roles path.
Command 
mkdir -p galaxy_lab/roles && cd galaxy_lab

This establishes a simple project layout baseline. Playbooks live at the project root and roles live under ./roles (a common convention). 

# Confirm structure:
ls -la
ls -la roles
Step 2 : Search Galaxy for a role to install.
Command 
ansible-galaxy search nginx

Search is the fast discovery step. In production, you also review README content, supported platforms, defaults, and whether the role is actively maintained. 

Found roles matching 'nginx'
geerlingguy.nginx
nginxinc.nginx
...
Step 3 : Install the role.
Command 
ansible-galaxy install geerlingguy.nginx

By default, Galaxy installs into your user roles path (commonly ~/.ansible/roles ). You can keep roles project-local when you need repeatable builds. 

# Confirm the role exists (path may vary):
ls -la ~/.ansible/roles | grep geerlingguy.nginx
Step 4 : Create a playbook that consumes the role.
Command 
nano site.yml
# OR
vim site.yml
site.yml 
- hosts: all
  become: true
  roles:
    - geerlingguy.nginx

This is the simplest role consumption pattern: list the role under roles: and Ansible runs its default entry point ( tasks/main.yml ).

Step 5 : Run the role-based playbook.
Command 
ansible-playbook -i inventory.ini site.yml

This confirms the role installs packages, applies configuration, and manages the service. Use --syntax-check when you need fast parsing validation, and use --check when you need a dry-run view of changes. 

# Quick validation options:
ansible-playbook -i inventory.ini site.yml --syntax-check
ansible-playbook -i inventory.ini site.yml --check
Step 6 : Generate a new role skeleton in your project.
Command 
ansible-galaxy init roles/myrole

This is the baseline for internal roles: predictable structure, clear defaults, and a place for templates, files, and tests. Build logic under tasks/ and expose only necessary knobs through defaults/ . 

# Inspect the generated structure:
find roles/myrole -maxdepth 2 -type f -print

Common breakpoints

ansible-galaxy search returns no useful matches

Broaden the search term or search for the vendor namespace. For high-signal roles, validate the repo activity and supported platforms before installing.

Role installs but Ansible cannot find it at runtime

Confirm the role path Ansible is using. If you want project-local roles, install into ./roles and ensure your configuration points Ansible to that path.

Playbook fails due to missing privilege escalation

Many service roles require root-level changes. Use become: true and ensure the target user has sudo access.

Role applies changes but service does not start

Inventory and role execution may be correct, but the node may be missing dependencies or have conflicting configuration. Inspect service state and logs after the run.

Cleanup checklist

This lab creates local playbook content and a generated role skeleton. Remove the project directory if you do not need it for later labs.

Commands 
cd ..
rm -rf galaxy_lab
Success signal

Your working directory is clean and the project artifacts are removed without impacting your global Ansible install.

Reference

  • ansible-galaxy search <term> : Searches Ansible Galaxy for roles matching a keyword.
  • ansible-galaxy install <namespace.role> : Downloads and installs a role into the default roles path.
    • <namespace.role> : Galaxy role identifier (for example geerlingguy.nginx).
  • ansible-galaxy init <path> : Generates a standard role skeleton at the specified path.
  • ansible-playbook -i <inventory> <playbook> : Runs a playbook against the specified inventory.
    • -i <inventory> : Inventory source file (for example inventory.ini).
  • find <path> -maxdepth <n> -type f -print : Lists files under a path to quickly inspect generated role structure.
    • -maxdepth <n> : Limits recursion depth.
    • -type f : Restricts results to files.
  • rm -rf <path> : Removes a directory tree (use with caution).
    • -r : Recursively removes directories and contents.
    • -f : Forces removal and suppresses prompts/errors for missing files.