Ansible Galaxy: Install, Create & Share Roles and Collections (Guide)

By Luca Berton · Published 2024-01-01 · Category: installation

Complete guide to Ansible Galaxy. Install roles and collections, create your own, publish to Galaxy, manage requirements.yml. Practical command-line examples.

Ansible Galaxy: Install, Create & Share Roles and Collections (Guide)

What Is Ansible Galaxy?

Ansible Galaxy is the community hub for finding, sharing, and downloading Ansible roles and collections. Think of it as the npm/PyPI for Ansible — a registry of reusable automation content.

Galaxy Website vs CLI

galaxy.ansible.com — Web interface to browse and search content
ansible-galaxy — CLI tool to install and manage content locally

Roles vs Collections

Feature	Roles	Collections
Contains	Tasks, handlers, vars, templates, files	Modules, roles, plugins, docs
Namespace	`author.role_name`	`namespace.collection`
Install	`ansible-galaxy role install`	`ansible-galaxy collection install`
Distribution	Galaxy, Git	Galaxy, Automation Hub
Standard since	Ansible 1.x	Ansible 2.9+

Collections are the modern distribution format. They bundle modules, roles, and plugins together.

Installing Content from Galaxy

Install a Role

# Install from Galaxy
ansible-galaxy role install geerlingguy.docker

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

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

# Install from Git
ansible-galaxy role install git+https://github.com/user/repo.git

Install a Collection

# Install from Galaxy
ansible-galaxy collection install community.general

# Install specific version
ansible-galaxy collection install community.general:9.0.0

# Install from Automation Hub
ansible-galaxy collection install ansible.netcommon \
  --server https://console.redhat.com/api/automation-hub/

# Install from tarball
ansible-galaxy collection install community-general-9.0.0.tar.gz

Requirements File

Create requirements.yml for reproducible installs:

---
roles:
  - name: geerlingguy.docker
    version: "6.1.0"
  - name: geerlingguy.nginx
  - src: https://github.com/user/custom-role.git
    version: main

collections:
  - name: community.general
    version: ">=9.0.0"
  - name: ansible.posix
  - name: community.docker

Install everything:

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

Most Popular Collections

Collection	Purpose	Modules
`community.general`	General-purpose modules	200+
`ansible.builtin`	Core modules (included)	70+
`ansible.posix`	POSIX system management	20+
`community.docker`	Docker management	15+
`amazon.aws`	AWS cloud modules	100+
`azure.azcollection`	Azure modules	80+
`community.vmware`	VMware management	150+
`community.windows`	Windows modules	50+
`ansible.netcommon`	Network automation base	20+
`community.kubernetes`	K8s management	10+

Most Popular Roles

Author	Role	Purpose
geerlingguy	docker	Install Docker
geerlingguy	nginx	Install/configure nginx
geerlingguy	java	Install Java
geerlingguy	postgresql	PostgreSQL server
geerlingguy	security	Linux security hardening
robertdebock	bootstrap	System bootstrapping

Creating Your Own Role

# Generate role skeleton
ansible-galaxy role init my_role

# Directory structure created:
my_role/
├── README.md
├── defaults/
│   └── main.yml      # Default variables (lowest priority)
├── files/             # Static files
├── handlers/
│   └── main.yml      # Handlers
├── meta/
│   └── main.yml      # Role metadata (dependencies, platforms)
├── tasks/
│   └── main.yml      # Main task list
├── templates/         # Jinja2 templates
├── tests/
│   ├── inventory
│   └── test.yml
└── vars/
    └── main.yml       # Role variables (high priority)

Using Your Role

---
- name: Apply my role
  hosts: webservers
  roles:
    - my_role
    - role: my_role
      vars:
        port: 8080

Creating a Collection

# Create collection skeleton
ansible-galaxy collection init my_namespace.my_collection

# Structure:
my_namespace/my_collection/
├── docs/
├── galaxy.yml          # Collection metadata
├── meta/runtime.yml
├── plugins/
│   ├── modules/        # Custom modules
│   ├── filter/         # Filter plugins
│   └── lookup/         # Lookup plugins
├── roles/              # Bundled roles
└── README.md

# Build the collection
ansible-galaxy collection build

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

Managing Installed Content

# List installed roles
ansible-galaxy role list

# List installed collections
ansible-galaxy collection list

# Remove a role
rm -rf ~/.ansible/roles/geerlingguy.docker

# Verify collection
ansible-galaxy collection verify community.general

Best Practices

Pin versions in requirements.yml for reproducibility
Use collections over standalone roles for new projects
Check Galaxy ratings and downloads before installing
Vendor dependencies for air-gapped environments
Use Automation Hub for certified, supported content (AAP)
Keep requirements.yml in version control
Test roles with Molecule before publishing

FAQ

Is Ansible Galaxy free?

Yes. The Galaxy website and CLI are free to use. Automation Hub (certified content) requires an AAP subscription.

What is the difference between Galaxy and Automation Hub?

Galaxy is community-maintained (anyone can publish). Automation Hub provides Red Hat-certified and supported content for enterprise customers.

Where are Galaxy roles installed?

Default: ~/.ansible/roles/. Override with -p flag or roles_path in ansible.cfg.

How do I use a collection module in a playbook?

Use the FQCN: community.general.timezone instead of just timezone.

Conclusion

Ansible Galaxy is essential for productive Ansible automation. Don't reinvent the wheel — leverage the thousands of community roles and collections available.

For more tutorials, visit AnsiblePilot.

Install a Role

ansible-galaxy role install geerlingguy.docker
ansible-galaxy role install geerlingguy.nginx --roles-path ./roles

Install a Collection

ansible-galaxy collection install community.general
ansible-galaxy collection install amazon.aws
ansible-galaxy collection install community.docker --force

Requirements File

# requirements.yml
---
roles:
  - name: geerlingguy.docker
    version: "7.4.0"
  - name: geerlingguy.nginx

collections:
  - name: community.general
    version: ">=9.0.0"
  - name: amazon.aws
  - name: community.docker

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

Search Galaxy

ansible-galaxy role search nginx
ansible-galaxy role info geerlingguy.nginx
ansible-galaxy collection list  # Show installed

Use Roles in Playbooks

- hosts: webservers
  become: true
  roles:
    - geerlingguy.docker
    - role: geerlingguy.nginx
      vars:
        nginx_vhosts:
          - listen: "80"
            server_name: "example.com"

Use Collections

- hosts: all
  tasks:
    # FQCN (recommended)
    - community.general.timezone:
        name: UTC

    # Or with collections keyword
    - ansible.builtin.debug:
        msg: "Using builtin"

Create Your Own Role

ansible-galaxy role init my_role

my_role/
├── README.md
├── defaults/main.yml    # Default variables
├── files/               # Static files
├── handlers/main.yml    # Handlers
├── meta/main.yml        # Role metadata
├── tasks/main.yml       # Main tasks
├── templates/           # Jinja2 templates
├── tests/
└── vars/main.yml        # Role variables

Create a Collection

ansible-galaxy collection init myorg.mytools

myorg/mytools/
├── galaxy.yml          # Collection metadata
├── plugins/
│   ├── modules/        # Custom modules
│   ├── filters/        # Custom filters
│   └── lookup/         # Lookup plugins
├── roles/              # Bundled roles
├── playbooks/          # Playbooks
└── docs/

Publish to Galaxy

# Build collection
ansible-galaxy collection build

# Publish
ansible-galaxy collection publish myorg-mytools-1.0.0.tar.gz --api-key YOUR_KEY

Private Repositories

# ansible.cfg
[galaxy]
server_list = private_hub, galaxy

[galaxy_server.private_hub]
url = https://hub.internal.com/api/galaxy/
token = your-token

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

Popular Collections

Collection	Purpose
`community.general`	General utilities
`amazon.aws`	AWS management
`community.docker`	Docker automation
`ansible.posix`	POSIX systems
`ansible.windows`	Windows management
`community.mysql`	MySQL/MariaDB
`community.postgresql`	PostgreSQL
`ansible.netcommon`	Network common

FAQ

Roles vs Collections?

Roles bundle tasks/templates for a single purpose. Collections bundle roles, modules, plugins, and playbooks as a distribution package.

How do I pin versions?

In requirements.yml: version: "==2.0.0" for exact, version: ">=2.0.0,<3.0.0" for range.

Offline installation?

# Download
ansible-galaxy collection download community.general -p ./offline/
# Install from local
ansible-galaxy collection install ./offline/community-general-9.0.0.tar.gz

Install a Role

ansible-galaxy role install geerlingguy.docker
ansible-galaxy role install geerlingguy.nginx

Install a Collection

ansible-galaxy collection install community.docker
ansible-galaxy collection install amazon.aws
ansible-galaxy collection install community.general

Requirements File

# requirements.yml
---
roles:
  - name: geerlingguy.docker
    version: "7.4.0"
  - name: geerlingguy.nginx

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

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

List Installed

ansible-galaxy role list
ansible-galaxy collection list

Use in Playbook

# Use a role
- hosts: all
  roles:
    - geerlingguy.docker

# Use a collection module
- hosts: all
  tasks:
    - community.docker.docker_container:
        name: nginx
        image: nginx:latest

Create Your Own Role

ansible-galaxy role init my_role
# Creates:
# my_role/
# ├── defaults/main.yml
# ├── handlers/main.yml
# ├── meta/main.yml
# ├── tasks/main.yml
# ├── templates/
# ├── files/
# └── vars/main.yml

Create Your Own Collection

ansible-galaxy collection init myorg.mycollection
# Creates:
# myorg/mycollection/
# ├── galaxy.yml
# ├── plugins/
# ├── roles/
# └── docs/

Publish to Galaxy

# Build collection
ansible-galaxy collection build

# Publish
ansible-galaxy collection publish myorg-mycollection-1.0.0.tar.gz --api-key $GALAXY_API_KEY

Private Galaxy (Automation Hub)

# ansible.cfg
[galaxy]
server_list = automation_hub, galaxy

[galaxy_server.automation_hub]
url = https://hub.example.com/api/galaxy/content/published/
token = my-token

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

Install from Git

# requirements.yml
roles:
  - src: https://github.com/myorg/my-role.git
    version: main
    name: my-role

collections:
  - name: https://github.com/myorg/my-collection.git
    type: git
    version: main

FAQ

roles vs collections?

Roles are bundles of tasks/templates/handlers. Collections are broader packages that include roles, modules, plugins, and playbooks. Collections are the modern standard.

Where are they installed?

Roles: ~/.ansible/roles/. Collections: ~/.ansible/collections/. Override with ANSIBLE_ROLES_PATH / COLLECTIONS_PATHS.

How to pin versions?

Always pin in requirements.yml for reproducible builds. Use version: ">=4.0.0,<5.0.0" for flexible pinning.

Category: installation

Browse all Ansible tutorials · AnsiblePilot Home

AnsiblePilot — Master Ansible Automation

Popular Topics

About Luca Berton

Ansible Galaxy: Install, Create & Share Roles and Collections (Guide)

What Is Ansible Galaxy?

Galaxy Website vs CLI

Roles vs Collections

Installing Content from Galaxy

Install a Role

Install a Collection

Requirements File

Most Popular Collections

Most Popular Roles

Creating Your Own Role

Using Your Role

Creating a Collection

Managing Installed Content

Best Practices

FAQ

Is Ansible Galaxy free?

What is the difference between Galaxy and Automation Hub?

Where are Galaxy roles installed?

How do I use a collection module in a playbook?

Conclusion

Install a Role

Install a Collection

Requirements File

Search Galaxy

Use Roles in Playbooks

Use Collections

Create Your Own Role

Create a Collection

Publish to Galaxy

Private Repositories

Popular Collections

FAQ

Roles vs Collections?

How do I pin versions?

Offline installation?

Install a Role

Install a Collection

Requirements File

List Installed

Use in Playbook

Create Your Own Role

Create Your Own Collection

Publish to Galaxy

Private Galaxy (Automation Hub)

Install from Git

FAQ

roles vs collections?

Where are they installed?

How to pin versions?

Related Articles