Ansible Galaxy

What is Ansible Galaxy? Ansible Galaxy is a free community hub for discovering, downloading, and sharing Ansible roles and collections. It provides pre-packaged automation content to jumpstart your projects and accelerate development.

Understanding Ansible Galaxy

What is Galaxy?

Ansible Galaxy (galaxy.ansible.com) is the central repository for Ansible content created and maintained by the community. It offers:

Roles - Reusable automation units for specific tasks
Collections - Bundled content including modules, plugins, roles, and playbooks
Documentation - Integrated documentation for all published content
Ratings and Reviews - Community feedback on quality and usefulness
Version History - Track releases and updates over time

Why Use Galaxy?

Galaxy accelerates automation development by providing:

Tested, production-ready automation content
Best practices from the Ansible community
Reduced development time and effort
Consistent patterns across projects
Easy sharing and collaboration

Finding Content on Galaxy

Browsing Collections

Navigate to the Collections section in the left sidebar to explore available collections. You can filter by:

Keywords - Search terms related to your needs
Tags - Categorized labels (cloud, networking, database, etc.)
Namespaces - Organization or author (ansible, community, amazon, etc.)
Popularity - Download counts and community usage

Browsing Roles

Visit the Roles section to find standalone roles. Use filters to narrow your search:

# Search roles from command line
ansible-galaxy role search elasticsearch

# Search by author
ansible-galaxy role search elasticsearch --author geerlingguy

# Search by platform
ansible-galaxy role search nginx --platforms EL

Getting Detailed Information

# Get detailed role information
ansible-galaxy role info geerlingguy.apache

# Display information includes:
# - Description
# - Available versions
# - Dependencies
# - Supported platforms
# - Installation instructions

Quality Indicators: Look for roles and collections with high download counts, recent updates, good documentation, and positive community ratings. The Galaxy platform computes quality scores based on code quality, documentation, and testing.

Installing Content from Galaxy

Installing Roles

Install roles using the ansible-galaxy role install command:

# Install latest version
ansible-galaxy role install geerlingguy.apache

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

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

# Force reinstall (overwrite existing)
ansible-galaxy role install geerlingguy.mysql --force

Installing Collections

Install collections using the ansible-galaxy collection install command:

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

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

# Install version range
ansible-galaxy collection install 'community.general:>=5.0.0,<6.0.0'

# Install to specific path
ansible-galaxy collection install amazon.aws -p ./collections

Default Installation Paths

Content is installed to default locations unless overridden:

Roles: ~/.ansible/roles
Collections: ~/.ansible/collections

Customize installation paths using:

-p or --path command-line option
ANSIBLE_ROLES_PATH or ANSIBLE_COLLECTIONS_PATH environment variables
roles_path or collections_paths in ansible.cfg

Using Requirements Files

roles/requirements.yml

Manage role dependencies with a requirements file:

---
# Install from Galaxy
- name: geerlingguy.apache
  version: "3.2.0"

# Install from GitHub
- src: https://github.com/geerlingguy/ansible-role-nginx
  version: main
  name: nginx

# Install from Git with specific branch
- src: git+https://github.com/organization/ansible-role-app.git
  version: develop
  name: myapp

# Install from tarball URL
- src: https://example.com/roles/myrole.tar.gz
  name: myrole

collections/requirements.yml

Manage collection dependencies:

---
collections:
  # Install latest version
  - name: community.general

  # Install specific version
  - name: ansible.posix
    version: "1.4.0"

  # Install version range
  - name: amazon.aws
    version: ">=5.0.0,<6.0.0"

  # Install from custom Galaxy server
  - name: my_namespace.my_collection
    source: https://galaxy.example.com
    version: "1.0.0"

  # Install from Git repository
  - name: namespace.collection
    source: git+https://github.com/organization/repo.git
    type: git
    version: main

Combined Requirements File

Include both roles and collections in a single file:

---
roles:
  - name: geerlingguy.docker
    version: "6.0.0"

  - name: geerlingguy.nodejs
    version: "6.1.0"

collections:
  - name: community.general
    version: ">=6.0.0"

  - name: community.docker
    version: "3.4.0"

Installing from Requirements File

# Install roles
ansible-galaxy role install -r requirements.yml

# Install collections
ansible-galaxy collection install -r requirements.yml

# Install both (automatically detects type)
ansible-galaxy install -r requirements.yml

# Force reinstallation
ansible-galaxy install -r requirements.yml --force

Project Organization: Keep requirements files in version control and use project-local installation paths (./roles and ./collections) for reproducible deployments.

Managing Installed Content

Listing Installed Content

# List all installed roles
ansible-galaxy role list

# List roles in specific path
ansible-galaxy role list -p ./roles

# List all installed collections
ansible-galaxy collection list

# List collections in specific path
ansible-galaxy collection list -p ./collections

# Show specific collection details
ansible-galaxy collection list community.general

Removing Content

# Remove a role
ansible-galaxy role remove geerlingguy.apache

# Remove from specific path
ansible-galaxy role remove geerlingguy.nginx -p ./roles

# Note: Collections don't have a built-in remove command
# Manually delete from ~/.ansible/collections/ansible_collections/

Downloading for Offline Use

# Download collection without installing
ansible-galaxy collection download community.general

# Download specific version
ansible-galaxy collection download community.general:5.0.0

# Download with dependencies
ansible-galaxy collection download -r requirements.yml -p ./downloads

# Download roles (downloads to current directory as tar.gz)
ansible-galaxy role install geerlingguy.docker --roles-path=./downloads

Security and Verification

Collection Signatures

Verify signed collections to ensure authenticity and integrity:

# Install with signature verification
ansible-galaxy collection install community.general \
  --keyring ~/.ansible/pubring.kbx

# Verify installed collection
ansible-galaxy collection verify community.general

# Verify all installed collections
ansible-galaxy collection verify --collections-path ~/.ansible/collections

Configure in ansible.cfg

[galaxy]
gpg_keyring = ~/.ansible/pubring.kbx
required_valid_signature_count = 1
ignore_signature_status_codes = REVKEYSIG

Security Best Practice: Always verify collection signatures in production environments and avoid installing content from untrusted sources. Review code before using it in critical systems.

Publishing Content to Galaxy

Prerequisites for Publishing

GitHub account linked to Ansible Galaxy
Galaxy API token (available from galaxy.ansible.com)
Properly structured role or collection
Valid metadata files (galaxy.yml for collections, meta/main.yml for roles)

Publishing Roles

Roles are imported directly from GitHub repositories:

# Role structure requirements
my-role/
├── README.md
├── meta/
│   └── main.yml          # Role metadata
├── tasks/
│   └── main.yml
├── handlers/
├── templates/
├── files/
├── vars/
└── defaults/

Role metadata in meta/main.yml:

---
galaxy_info:
  author: Your Name
  description: Role description
  company: Your Company (optional)

  license: MIT

  min_ansible_version: 2.9

  platforms:
    - name: Ubuntu
      versions:
        - focal
        - jammy
    - name: EL
      versions:
        - 8
        - 9

  galaxy_tags:
    - web
    - apache
    - httpd

dependencies: []

To publish a role:

Push your role repository to GitHub
Log in to galaxy.ansible.com
Click "My Content" > "Add Content"
Select your GitHub repository
Galaxy automatically imports and publishes the role

Publishing Collections

Collections are built and uploaded as tarballs:

# Collection structure
my_namespace/
└── my_collection/
    ├── README.md
    ├── galaxy.yml              # Collection metadata
    ├── plugins/
    │   ├── modules/
    │   ├── inventory/
    │   ├── lookup/
    │   └── filter/
    ├── roles/
    ├── playbooks/
    ├── docs/
    └── tests/

Collection metadata in galaxy.yml:

---
namespace: my_namespace
name: my_collection
version: 1.0.0
readme: README.md

authors:
  - Your Name 

description: Comprehensive collection for application management

license:
  - GPL-3.0-or-later

tags:
  - automation
  - deployment
  - monitoring

dependencies: {}

repository: https://github.com/my_namespace/my_collection
documentation: https://docs.example.com/my_collection
homepage: https://example.com
issues: https://github.com/my_namespace/my_collection/issues

Building and Publishing Collections

# Navigate to collection directory
cd my_namespace/my_collection

# Build collection tarball
ansible-galaxy collection build

# This creates: my_namespace-my_collection-1.0.0.tar.gz

# Publish to Galaxy (requires API token)
ansible-galaxy collection publish my_namespace-my_collection-1.0.0.tar.gz \
  --api-key=your_galaxy_api_token

# Alternative: Configure token in ansible.cfg
[galaxy]
server_list = release_galaxy

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

Obtaining Galaxy API Token

Log in to galaxy.ansible.com
Click your username in the top-right corner
Select "API Key" from the dropdown
Copy the displayed token
Store securely (treat like a password)

Custom Galaxy Servers

Using Private Galaxy Server

Organizations can host private Galaxy servers for internal content:

# Install from custom server
ansible-galaxy collection install my_namespace.my_collection \
  --server https://galaxy.example.com

# Configure multiple servers in ansible.cfg
[galaxy]
server_list = my_galaxy, public_galaxy

[galaxy_server.my_galaxy]
url=https://galaxy.example.com
token=my_private_token

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

Server Priority

When multiple servers are configured, Ansible searches in the order listed. First match wins.

# requirements.yml with specific source
---
collections:
  - name: internal.collection
    source: https://galaxy.internal.example.com

  - name: community.general
    source: https://galaxy.ansible.com

Alternative Installation Sources

Install from Git Repository

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

# Install specific branch or tag
ansible-galaxy role install git+https://github.com/org/role.git,main
ansible-galaxy role install git+https://github.com/org/role.git,v1.0.0

# Install collection from Git
ansible-galaxy collection install git+https://github.com/org/collection.git

# Install specific branch
ansible-galaxy collection install git+https://github.com/org/collection.git,develop

Install from Local Files

# Install collection from tarball
ansible-galaxy collection install /path/to/my_namespace-my_collection-1.0.0.tar.gz

# Install collection from directory
ansible-galaxy collection install /path/to/my_namespace/my_collection/

# Install role from local path
ansible-galaxy role install /path/to/role -p ./roles

Install from Web URL

# Install from direct download link
ansible-galaxy role install https://example.com/downloads/myrole.tar.gz

Best Practices

Galaxy Best Practices:

Pin Versions: Always specify exact versions in requirements.yml for reproducibility
Review Before Use: Examine role/collection code before using in production
Local Installation: Install to project directories for isolation and portability
Documentation: Read role/collection documentation thoroughly
Test First: Test Galaxy content in dev environments before production
Keep Updated: Regularly update dependencies but test changes
Contribute Back: Report issues and contribute improvements to community content
Verify Signatures: Use signature verification for security-critical environments

Creating Quality Content for Galaxy

Documentation Standards

High-quality Galaxy content includes:

Comprehensive README with examples
Clear variable documentation with defaults
Supported platform requirements
Dependency information
License information
Changelog tracking versions

Testing and Quality

Ensure your content is tested and validated:

Use ansible-lint for code quality
Implement Molecule tests for roles
Test on multiple platforms
Validate with multiple Ansible versions
Use CI/CD for automated testing

Semantic Versioning

Follow semantic versioning (MAJOR.MINOR.PATCH):

MAJOR: Incompatible API changes
MINOR: Backwards-compatible functionality additions
PATCH: Backwards-compatible bug fixes

Common Issues and Solutions

Content Not Found

If Galaxy content isn't found:

Verify correct namespace and name
Check network connectivity to Galaxy server
Ensure content is published and not private
Try explicit server URL with --server

Version Conflicts

When dependencies conflict:

Use --force to override existing installations
Pin exact versions in requirements.yml
Use separate collection paths for different projects
Review dependency trees with list command

Authentication Failures

If publishing fails:

Verify API token is valid and not expired
Check GitHub account is linked to Galaxy
Ensure proper permissions on Galaxy namespace
Verify ansible.cfg configuration

Build Errors

If collection build fails:

Validate galaxy.yml syntax
Check for required files (README.md)
Ensure proper directory structure
Verify version follows semantic versioning
Check for invalid characters in names

Content	Type	Description	Namespace
`community.general`	Collection	General community modules and plugins	community
`ansible.posix`	Collection	POSIX system modules	ansible
`amazon.aws`	Collection	AWS cloud management	amazon
`geerlingguy.docker`	Role	Install and configure Docker	geerlingguy
`geerlingguy.nginx`	Role	Install and configure Nginx	geerlingguy
`geerlingguy.postgresql`	Role	PostgreSQL database setup	geerlingguy
`kubernetes.core`	Collection	Kubernetes resource management	kubernetes
`community.docker`	Collection	Docker container management	community
`azure.azcollection`	Collection	Microsoft Azure management	azure
`google.cloud`	Collection	Google Cloud Platform	google

Next Steps

Ansible Collections - Deep dive into collection usage
Roles - Learn about creating and using roles
Custom Modules - Build your own modules for collections
Testing with Molecule - Test roles before publishing
Try the Playground - Practice using Galaxy content

Try in Playground Practice in Labs

Getting Started

Content Distribution

Core Concepts

Platforms

Development

Infrastructure

Operations

Security

Enterprise