Ansible Galaxy

What is Ansible Galaxy?

When you realize you need to install Docker, configure Kubernetes, or harden an SSH server, your first thought is likely: "I should write a Role for that."

Stop! Someone has probably already written it.

Ansible Galaxy is the official public registry for Ansible Roles and Collections, maintained by Red Hat. It is to Ansible what the NPM Registry is to Node.js, or Docker Hub is to container images.

You can browse the website to find thousands of pre-written, highly-tested automation packages for nearly any tool, database, or cloud provider in existence.

Installing Roles from Galaxy

Ansible provides the ansible-galaxy CLI tool specifically for interacting with the registry.

To download an existing community role, you use the install command. For example, to install the astronomically popular geerlingguy.docker role:

ansible-galaxy install geerlingguy.docker

Ansible downloads the code and places it chronologically into your system's global roles directory (usually ~/.ansible/roles or /etc/ansible/roles).

Using Downloaded Roles

Once downloaded to your system, you reference it in your playbook just like you would a local role:

---
- name: Setup Docker Environment
  hosts: all
  become: yes
  
  roles:
    # Use the exact namespace.name format as downloaded from Galaxy
    - role: geerlingguy.docker

Using `requirements.yml`

If you are working on a team, you cannot just manually run ansible-galaxy install on your laptop and call it a day. If a coworker pulls your playbook repository from Git, they won't possess the geerlingguy.docker role on their local machine, and the playbook will fail.

The solution is the requirements.yml file. This operates exactly like a package.json in Node or a requirements.txt in Python.

You define the external dependencies your playbook needs:

# requirements.yml
---
roles:
  # Install a role from standard Ansible Galaxy
  - name: geerlingguy.docker
    version: "7.1.0"           # Strongly recommended to pin versions!
 
  # Install a generic Git-based role (doesn't have to be on Galaxy site)
  - name: corporate_secure_base
    src: https://github.com/my-corporation/ansible-secure-base.git
    scm: git
    version: v1.3.0

When a new developer clones your Git repository, the very first command they run must be:

# This reads the requirements file and downloads everything needed!
ansible-galaxy install -r requirements.yml

When running automated CI/CD pipelines (like GitHub Actions), you will always execute ansible-galaxy install -r requirements.yml as the pipeline setup step prior to executing ansible-playbook.

Roles vs. Collections

Historically, Ansible Galaxy was only used for sharing Roles. However, in modern Ansible architectures, Galaxy is primarily used for distributing Collections.

The Problem Collections Solve

Originally, Ansible shipped with everything included ("Batteries Included"). When you installed Ansible, you got the AWS modules, VM-ware modules, Cisco router modules, Windows modules, etc. The Ansible source code became bloated, gigabytes in size, and impossible to maintain.

Red Hat changed the architecture. Now, Ansible installs as a minuscule ansible-core package. All cloud modules and vendor-specific plugins are stripped out and bundled into Collections.

A Collection is a massive bundle of automation content. Rather than just containing a single Role, a Collection can contain:

Multiple Roles
Custom Python Modules (e.g., amazon.aws.ec2_instance)
Plugins (Inventory plugins, filter plugins)

Managing Collections via Galaxy

To install a collection (for example, the official AWS modules):

ansible-galaxy collection install amazon.aws

In your requirements.yml, Collections get their own separate section:

# requirements.yml
---
collections:
  # Required to execute tasks targeting AWS infrastructure
  - name: amazon.aws
    version: "6.0.0"
 
  # Required to target Kubernetes clusters
  - name: kubernetes.core
    version: "2.4.0"
 
roles:
  - name: geerlingguy.nginx

You install the requirements file the exact same way you do for roles:

ansible-galaxy install -r requirements.yml

By leveraging Galaxy appropriately, you can reuse world-class automation logic instead of reinventing the wheel, saving hundreds of hours of development time.