Ansible Galaxy: Complete Guide to Finding and Using Roles

What is Ansible Galaxy?

Ansible Galaxy is the official hub for sharing and discovering Ansible content. It's a free service where the community shares over 25,000 pre-built roles covering everything from basic system configuration to complex application deployments.

Why Use Ansible Galaxy?

• Save Time - Don't reinvent the wheel; use battle-tested roles
• Learn - Study how experienced automation engineers solve problems
• Contribute - Share your work with the community
• Standards - Follow community best practices
• Quality - Find well-documented, tested automation code

Installing ansible-galaxy CLI

The ansible-galaxy command comes bundled with Ansible:

# Verify installation
ansible-galaxy --version

# Get help
ansible-galaxy --help

Searching for Roles

Search on the Website

Visit galaxy.ansible.com and use the search bar to find roles by:

• Keyword (e.g., "docker", "nginx", "postgresql")
• Author (e.g., "geerlingguy")
• Tags (e.g., "security", "web", "database")
• Platform (e.g., "Ubuntu", "CentOS")

Search from Command Line

# Search for nginx roles
ansible-galaxy search nginx

# Search with specific author
ansible-galaxy search nginx --author geerlingguy

# Search by platform
ansible-galaxy search nginx --platforms Ubuntu

Evaluating Roles

Key Quality Indicators

Before using a role, check these metrics:

1. Download Count - Popular roles are often more reliable
2. Star Rating - Community feedback indicator
3. Recent Activity - Check last update date
4. GitHub Stars - Source repository popularity
5. Open Issues - Check for unresolved problems
6. Documentation - README quality and examples
7. Tests - Look for CI/CD integration
8. Platform Support - Ensure it supports your OS

Top Trusted Authors

Some well-known, trusted role authors:

• geerlingguy - 150+ high-quality roles
• robertdebock - 200+ comprehensive roles
• cloudalchemy - Monitoring and observability
• ansible-community - Official community roles

Installing Roles

Install Individual Roles

# Install latest version
ansible-galaxy install geerlingguy.nginx

# Install specific version
ansible-galaxy install geerlingguy.nginx,3.1.4

# Install to custom path
ansible-galaxy install geerlingguy.nginx -p ./custom-roles/

# Force reinstall (overwrite existing)
ansible-galaxy install geerlingguy.nginx --force

Install Multiple Roles with requirements.yml

Create a requirements.yml file:

---
# Install from Galaxy
- name: geerlingguy.nginx
  version: "3.1.4"

- name: geerlingguy.php
  version: "4.8.0"

- name: geerlingguy.mysql
  version: "4.3.1"

# Install from GitHub directly
- src: https://github.com/geerlingguy/ansible-role-docker
  name: docker
  version: main

# Install from Git with specific branch
- src: git+https://github.com/username/custom-role.git
  name: custom
  version: develop

# Install from URL (tarball)
- src: https://example.com/roles/myrole.tar.gz
  name: myrole

Install all requirements:

# Install from requirements.yml
ansible-galaxy install -r requirements.yml

# Install and force update
ansible-galaxy install -r requirements.yml --force

Managing Installed Roles

List Installed Roles

# List all installed roles
ansible-galaxy list

# List roles with version info
ansible-galaxy list -p ./roles/

Role Information

# Get role details
ansible-galaxy info geerlingguy.nginx

# View role README
ansible-galaxy info geerlingguy.nginx | less

Remove Roles

# Remove specific role
ansible-galaxy remove geerlingguy.nginx

# Remove role from custom path
ansible-galaxy remove geerlingguy.nginx -p ./roles/

Using Galaxy Roles in Playbooks

Basic Usage

---
- name: Setup web server
  hosts: webservers
  become: yes

  roles:
    - geerlingguy.nginx
    - geerlingguy.php
    - geerlingguy.mysql

With Custom Variables

---
- name: Setup LEMP stack
  hosts: webservers
  become: yes

  roles:
    - role: geerlingguy.nginx
      vars:
        nginx_vhosts:
          - listen: "80"
            server_name: "example.com"
            root: "/var/www/html"

    - role: geerlingguy.mysql
      vars:
        mysql_root_password: "{{ vault_mysql_root_password }}"
        mysql_databases:
          - name: wordpress
        mysql_users:
          - name: wpuser
            password: "{{ vault_wpuser_password }}"
            priv: "wordpress.*:ALL"

Popular Galaxy Roles by Category

Web Servers

• geerlingguy.nginx - Nginx web server
• geerlingguy.apache - Apache web server
• geerlingguy.haproxy - HAProxy load balancer

Databases

• geerlingguy.mysql - MySQL/MariaDB
• geerlingguy.postgresql - PostgreSQL
• geerlingguy.mongodb - MongoDB
• geerlingguy.redis - Redis cache

Programming Languages

• geerlingguy.php - PHP runtime
• geerlingguy.nodejs - Node.js
• geerlingguy.java - Java JDK
• geerlingguy.ruby - Ruby

Container & Orchestration

• geerlingguy.docker - Docker engine
• geerlingguy.kubernetes - Kubernetes cluster
• geerlingguy.helm - Helm package manager

Security & Monitoring

• geerlingguy.security - Security hardening
• geerlingguy.firewall - Firewall configuration
• cloudalchemy.prometheus - Prometheus monitoring
• cloudalchemy.grafana - Grafana dashboards

Creating Your Own Galaxy Role

1. Initialize Role Structure

# Create role skeleton
ansible-galaxy init my-awesome-role

cd my-awesome-role
tree

2. Develop Your Role

Follow best practices (see our Complete Roles Guide):

• Write comprehensive tasks
• Add proper defaults and variables
• Create templates and files
• Include handlers
• Write tests

3. Document Your Role

Create a detailed README.md:

# My Awesome Role

A brief description of what this role does.

## Requirements

- Ansible 2.9+
- Ubuntu 20.04+ / CentOS 8+

## Role Variables

```yaml
my_var: default_value  # Description
another_var: 123       # Another description
```

## Dependencies

None

## Example Playbook

```yaml
- hosts: servers
  roles:
    - my-awesome-role
```

## License

MIT

## Author Information

Created by Your Name (your.email@example.com)

4. Update meta/main.yml

---
galaxy_info:
  role_name: my_awesome_role
  author: Your Name
  description: Brief description
  company: Your Company (optional)
  license: MIT
  min_ansible_version: 2.9

  platforms:
    - name: Ubuntu
      versions:
        - focal
        - jammy
    - name: EL
      versions:
        - 8
        - 9

  galaxy_tags:
    - system
    - web
    - security

dependencies: []

5. Test Thoroughly

# Syntax check
ansible-playbook tests/test.yml --syntax-check

# Run with molecule
molecule test

# Manual test
ansible-playbook tests/test.yml --check

Publishing to Ansible Galaxy

Prerequisites

1. GitHub account
2. Ansible Galaxy account (login with GitHub)
3. Git repository with your role

Step-by-Step Publishing

1. Create GitHub Repository

# Initialize git in role directory
cd my-awesome-role
git init

# Create repository on GitHub
# Repository name must start with 'ansible-role-'
# Example: ansible-role-my-awesome-role

# Add remote and push
git remote add origin git@github.com:username/ansible-role-my-awesome-role.git
git add .
git commit -m "Initial role commit"
git push -u origin main

2. Import to Galaxy

# Login to Galaxy
ansible-galaxy login

# Import your role
ansible-galaxy role import username ansible-role-my-awesome-role

Alternatively, use the web interface at galaxy.ansible.com

3. Setup Automated Imports

Configure GitHub webhook to auto-import on push:

1. Go to your role on Galaxy
2. Click "Settings" → "Integrations"
3. Enable GitHub integration
4. Role will auto-update on git push

Advanced Galaxy Features

Collections vs Roles

Ansible Collections are the new packaging format:

# Install collection
ansible-galaxy collection install community.general

# List collections
ansible-galaxy collection list

# Install from requirements
ansible-galaxy collection install -r requirements.yml

Collection requirements.yml:

---
collections:
  - name: community.general
    version: ">=3.0.0"

  - name: ansible.posix
    version: "1.4.0"

  - name: community.docker
    source: https://galaxy.ansible.com

Using Private Galaxy Servers

# Install from private Galaxy
ansible-galaxy install myrole \
  --server https://private-galaxy.company.com

# Configure in ansible.cfg
[galaxy]
server_list = company_galaxy, release_galaxy

[galaxy_server.company_galaxy]
url=https://private-galaxy.company.com
token=abc123xyz

[galaxy_server.release_galaxy]
url=https://galaxy.ansible.com

Best Practices

1. Pin Role Versions

# Good - specific version
- name: geerlingguy.nginx
  version: "3.1.4"

# Avoid - may break unexpectedly
- name: geerlingguy.nginx

2. Use requirements.yml

Always define dependencies in version control:

# Track in git
git add requirements.yml
git commit -m "Add role dependencies"

3. Review Role Code

Never blindly trust external code:

# Download and inspect before using
ansible-galaxy install geerlingguy.nginx -p ./temp-roles/
cat ./temp-roles/geerlingguy.nginx/tasks/main.yml

4. Keep Roles Updated

# Update all roles
ansible-galaxy install -r requirements.yml --force

# Review changelog before updating
# Test in staging before production

5. Namespace Your Roles

# Use fully qualified names
roles:
  - role: geerlingguy.nginx  # Clear origin
    # Not: nginx             # Ambiguous

Troubleshooting Common Issues

Installation Failures

# Clear cache
rm -rf ~/.ansible/tmp/

# Verbose installation
ansible-galaxy install geerlingguy.nginx -vvv

# Check connectivity
curl https://galaxy.ansible.com

Version Conflicts

# Force specific version
ansible-galaxy install geerlingguy.nginx,3.1.4 --force

# List installed versions
ansible-galaxy list

Role Not Found

# Check roles path
ansible-config dump | grep ROLES_PATH

# Specify custom path in ansible.cfg
[defaults]
roles_path = ./roles:~/.ansible/roles:/usr/share/ansible/roles

Conclusion

Ansible Galaxy is an invaluable resource that can dramatically accelerate your automation projects. By leveraging community expertise, you can:

• Implement complex solutions in minutes, not days
• Learn from thousands of working examples
• Contribute back to help others
• Stay current with automation best practices

Start by exploring popular roles, understand how they work, then adapt them to your needs. As you gain experience, consider giving back by publishing your own roles to help the community grow.