Ansible Galaxy Complete Guide: Roles, Collections, and Best Practices

Ansible Galaxy is the official community hub for finding, sharing, and reusing Ansible roles and collections. It is the primary way Ansible users distribute reusable automation content, with thousands of roles and collections covering everything from package management to cloud provisioning.

What Is Ansible Galaxy?

Ansible Galaxy serves two purposes:

1. A website (galaxy.ansible.com) where you browse, search, and download community-contributed automation content
2. A CLI tool (ansible-galaxy) that installs, creates, and manages roles and collections from the command line

Roles vs Collections

Collections are the modern standard. Red Hat and the Ansible community have shifted from standalone roles to collections, which bundle modules, plugins, and roles together.

Installing Content from Galaxy

Install a Role

# Install a single role
ansible-galaxy role install geerlingguy.docker

# Install a specific version
ansible-galaxy role install geerlingguy.docker,6.1.0

# Install to a custom path
ansible-galaxy role install geerlingguy.docker -p ./roles/

Install a Collection

# Install a collection
ansible-galaxy collection install community.general

# Install a specific version
ansible-galaxy collection install community.general:==8.0.0

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

Requirements Files

For reproducible environments, use a requirements.yml file:

---
roles:
  - name: geerlingguy.docker
    version: "6.1.0"
  - name: geerlingguy.mysql
    version: "4.0.0"

collections:
  - name: community.general
    version: ">=8.0.0"
  - name: ansible.posix
    version: ">=1.5.0"
  - name: amazon.aws
    version: ">=7.0.0"

Install everything at once:

ansible-galaxy install -r requirements.yml
ansible-galaxy collection install -r requirements.yml

Searching for Content

Command Line Search

# Search for roles related to nginx
ansible-galaxy role search nginx

# Search with platform filter
ansible-galaxy role search nginx --platforms Ubuntu

# Search for collections
ansible-galaxy collection list  # List installed collections

Web Interface

Browse galaxy.ansible.com to:

• Search by keyword, platform, or tag
• View download counts and community ratings
• Read documentation and README files
• Check version history and changelogs

Popular Collections

Creating Your Own Role

Initialize a Role

ansible-galaxy role init my_nginx_role

This creates the standard role directory structure:

my_nginx_role/
├── README.md
├── defaults/
│   └── main.yml       # Default variables (lowest priority)
├── files/             # Static files to copy
├── handlers/
│   └── main.yml       # Handlers (triggered by notify)
├── meta/
│   └── main.yml       # Role metadata and dependencies
├── tasks/
│   └── main.yml       # Main task list
├── templates/         # Jinja2 templates
├── tests/
│   ├── inventory
│   └── test.yml
└── vars/
    └── main.yml       # Role variables (high priority)

Role Metadata

Edit meta/main.yml for Galaxy publishing:

galaxy_info:
  author: your_name
  description: Install and configure Nginx web server
  license: MIT
  min_ansible_version: "2.14"
  platforms:
    - name: Ubuntu
      versions: [jammy, noble]
    - name: EL
      versions: [8, 9]
  galaxy_tags:
    - nginx
    - webserver
    - proxy

dependencies:
  - role: geerlingguy.certbot
    when: nginx_ssl_enabled | default(false)

Creating Your Own Collection

Initialize a Collection

ansible-galaxy collection init my_namespace.my_collection

Structure:

my_namespace/my_collection/
├── galaxy.yml          # Collection metadata
├── plugins/
│   ├── modules/        # Custom modules
│   ├── inventory/      # Inventory plugins
│   ├── filter/         # Filter plugins
│   └── lookup/         # Lookup plugins
├── roles/              # Roles within the collection
├── playbooks/          # Reusable playbooks
├── docs/
└── tests/

Build and Publish

# Build the collection tarball
ansible-galaxy collection build

# Publish to Galaxy
ansible-galaxy collection publish my_namespace-my_collection-1.0.0.tar.gz --api-key YOUR_API_KEY

Get your API key from your Galaxy profile page.

Galaxy NG: The New Platform

In September 2023, Ansible Galaxy migrated from the legacy platform to Galaxy NG, built on the same codebase as Red Hat Automation Hub. Key improvements:

• Faster search and better UI
• Namespaces for better content organization
• Improved API (v3) for programmatic access
• Content signing for verified collections
• Better dependency resolution

Migration Steps

If you published content on the old Galaxy:

1. Visit galaxy.ansible.com
2. Regenerate your API token
3. Update your CI/CD to use the new token
4. Verify your content appears correctly

The ansible-galaxy CLI works seamlessly with the new platform — no changes needed for consumers.

Best Practices

For Consuming Galaxy Content

1. Pin versions in requirements.yml — avoid unexpected breaking changes
2. Use a virtual environment to isolate collection versions per project
3. Vendor critical roles — copy important roles into your repo for reliability
4. Review before using — check the role's GitHub repo, issues, and last update date
5. Prefer collections over standalone roles — collections are actively maintained

For Publishing to Galaxy

1. Write comprehensive README — include examples, variables table, and platform support
2. Follow semantic versioning — breaking changes = major version bump
3. Add CI testing — use Molecule and GitHub Actions for automated testing
4. Include a changelog — users need to know what changed between versions
5. Tag releases in Git — Galaxy imports content based on Git tags

Security Considerations

• Review role code before running — especially tasks with become: true
• Check for hardcoded credentials in downloaded roles
• Use ansible-galaxy collection verify to check collection integrity
• Prefer Red Hat Certified collections for production environments

Troubleshooting

Collection Not Found

# Check configured Galaxy servers
ansible-config dump | grep GALAXY

# Verify the collection exists
ansible-galaxy collection list community.general

# Force reinstall
ansible-galaxy collection install community.general --force

Version Conflicts

# List all installed collections with versions
ansible-galaxy collection list

# Install a specific compatible version
ansible-galaxy collection install community.general:==7.5.0 --force

Network/Proxy Issues

# Use a proxy
export HTTPS_PROXY=http://proxy:8080
ansible-galaxy collection install community.general

# Specify a custom Galaxy server
ansible-galaxy collection install community.general -s https://galaxy.ansible.com

Links

• Ansible Galaxy
• Galaxy NG GitHub
• Galaxy Documentation
• Ansible Galaxy CLI

Related Articles

• Understanding Ansible Roles
• Ansible Fully Qualified Collection Name (FQCN)
• How to Install Ansible Step-by-Step
• Ansible Best Practices for Production Environments
• Ansible Lightspeed Complete Guide
• Ansible Tutorial for Beginners
• Ansible Collections Path Configuration

Conclusion

Ansible Galaxy is essential infrastructure for the Ansible ecosystem. Whether you are installing a community role to save development time or publishing your own collection to share with others, understanding the ansible-galaxy CLI, requirements files, and Galaxy platform is fundamental to productive Ansible development.

The shift from standalone roles to collections reflects the maturity of the Ansible ecosystem — and Galaxy NG provides the modern platform to support it. Start with consuming existing content, then consider contributing your own as your automation expertise grows.