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

Q: Where are Galaxy roles installed?

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

Q: How do I use a collection module in a playbook?

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

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.

• rendering files with Ansible template • event-driven tasks with Ansible handlers • the Ansible Windows reference • Docker Compose with Ansible • Ansible inventory file structure

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