Ansible Galaxy

Ansible Galaxy is the community hub for sharing and reusing Ansible roles and collections. With over twenty thousand published roles, there is an excellent chance that someone has already written, tested, and maintained the automation you need. Using Galaxy effectively means spending less time writing automation and more time delivering value — a direct application of the 80/20 principle.

What Is Ansible Galaxy

Ansible Galaxy (galaxy.ansible.com) is a free, publicly accessible repository where the community publishes roles and collections. Think of it as the npm registry or PyPI for Ansible automation. Roles on Galaxy range from simple utilities to comprehensive enterprise configurations maintained by vendors including Red Hat, Elastic, and HashiCorp.

Galaxy hosts two types of content:

  • Roles: The traditional sharing format — a role directory structure published under a namespace. Example: geerlingguy.nginx
  • Collections: The modern format — a package containing roles, modules, plugins, and playbooks together. Example: community.general, amazon.aws

Searching for Roles

Search from the command line:

ansible-galaxy role search nginx --author geerlingguy
ansible-galaxy role search postgresql --platforms Ubuntu

Or browse galaxy.ansible.com directly. When evaluating a role, check: the number of downloads (popularity), when it was last updated (maintenance), its GitHub star count, whether it has automated test runs, and the quality score shown on the Galaxy page.

Jeff Geerling's roles (the geerlingguy namespace) are widely considered the gold standard for Galaxy role quality — well-tested, cross-platform, actively maintained, and thoroughly documented. They are excellent models to study when writing your own roles.

Installing Roles

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

# Install a specific version
ansible-galaxy role install geerlingguy.nginx,3.2.0

# Install to a specific path
ansible-galaxy role install geerlingguy.nginx --roles-path ./roles

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

By default, roles are installed to ~/.ansible/roles/. For project-specific installations, use --roles-path ./roles to install alongside your playbooks.

The requirements.yml File

Rather than installing dependencies manually, define them in a requirements.yml file at the project root. This file documents exactly what your project depends on and at what versions — essential for reproducible builds in CI/CD pipelines:

---
roles:
  - name: geerlingguy.nginx
    version: "3.2.0"
  - name: geerlingguy.postgresql
    version: "3.4.2"
  - src: https://github.com/my-org/my-private-role
    name: myorg.myrole
    scm: git
    version: main

collections:
  - name: amazon.aws
    version: ">=6.0.0"
  - name: community.general
  - name: ansible.posix

Install all requirements with a single command:

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

In CI/CD pipelines, this command runs before your playbooks, ensuring all dependencies are available in a clean environment.

Using an Installed Galaxy Role

---
- name: Configure web servers using Galaxy roles
  hosts: webservers
  become: true
  roles:
    - role: geerlingguy.nginx
      vars:
        nginx_remove_default_vhost: true
        nginx_vhosts:
          - listen: "80"
            server_name: "myapp.example.com"
            root: "/var/www/myapp"
            index: "index.html"

Galaxy roles follow the same structure as roles you write yourself. Override defaults by passing vars in the role application. Read the role's README for the complete list of variables it supports.

Evaluating Galaxy Role Quality

Not all Galaxy roles are production-quality. Use this checklist before trusting a role with production infrastructure:

  • Does it have a clear, comprehensive README with documented variables?
  • Is it tested with Molecule or Travis CI (visible in the repository)?
  • Does it support multiple OS families (Ubuntu, CentOS, etc.) if you need cross-platform support?
  • When was it last updated? Roles not updated in over a year may have compatibility issues with recent Ansible versions.
  • Are there open issues mentioning security vulnerabilities or critical bugs?
  • Does the Galaxy quality score exceed 4.0?

Publishing Your Own Role to Galaxy

When your role is ready to share:

  1. Ensure meta/main.yml is complete with author, description, platforms, and tags
  2. Push the role to a public GitHub repository named exactly ansible-role-rolename
  3. Log into galaxy.ansible.com with your GitHub account
  4. Import the repository through the Galaxy web interface or CLI: ansible-galaxy role import github_username repo_name

Galaxy pulls the role from GitHub and makes it available as your_namespace.rolename. Future updates to your GitHub repository can be re-imported to update the Galaxy listing.

Collections: The Modern Standard

Collections are the future of Ansible content distribution. Unlike roles, collections bundle multiple types of content together and support proper semantic versioning. Key collections every Ansible practitioner should know:

  • ansible.builtin — Core modules included with Ansible
  • community.general — Hundreds of community modules for various tools
  • amazon.aws — AWS automation modules
  • azure.azcollection — Azure automation
  • google.cloud — GCP automation
  • ansible.posix — POSIX-focused modules (firewalld, selinux, etc.)
  • community.docker — Docker and container management

Try This: Use a Galaxy Role in Your Lab

Install geerlingguy.nginx and use it to configure your web servers. Compare the output with your hand-written Nginx role from Topic 22. Note which features the Galaxy role supports that yours does not. Then create a requirements.yml that pins the role to a specific version. Delete the installed role and reinstall from the requirements file to confirm the versioned install works.

Summary

Ansible Galaxy provides thousands of community-maintained roles and collections that eliminate the need to write automation for common tasks from scratch. The requirements.yml file documents and reproducibly installs all project dependencies. Evaluating Galaxy role quality requires checking documentation completeness, test coverage, platform support, and maintenance activity. Collections are the modern distribution format and bundle roles, modules, and plugins together. Publishing your own roles to Galaxy contributes to the community and demonstrates professional credibility.

Previous lessons
Back to courses
Next lessons

Leave a Comment