Ansible Galaxy & Collections: Pinning Versions to Avoid Production Surprises

It was 3 AM on a Sunday. Our CI pipeline had been green for weeks, but suddenly a deployment failed with ERROR! couldn't resolve module 'aws_s3'. The playbook had been using aws_s3 without a FQCN, and a new collection version had renamed the module. We had no version pinning, no requirements.yml—just ansible-galaxy collection install amazon.aws in a script. That night, I learned the hard way that Ansible Galaxy is not a 'set it and forget it' tool.

Ansible Galaxy has evolved significantly. Originally, it was just a repository for roles—shareable, reusable automation units. Then came Collections (introduced in Ansible 2.9), which bundle modules, plugins, roles, and playbooks under a namespace. This solved the 'module explosion' problem but introduced new complexity: namespace management, dependency hell, and version conflicts.

In this article, I'll cover exactly how to use ansible-galaxy for both roles and collections, write a bulletproof requirements.yml, understand namespace conventions, use FQCN in playbooks, connect to private Automation Hub, and pin versions for reproducible builds. Every example is production-tested, and I'll share the exact commands that fixed my 3 AM outage.

We'll also dive into a real production incident where a missing version pin caused a cascading failure across 200 servers, and how we recovered with a one-line fix.

ansible-galaxy Role Install vs Collection Install

The ansible-galaxy command has two subcommands: role and collection. They are not interchangeable. Roles install to ~/.ansible/roles/ (or a custom roles_path). Collections install to ~/.ansible/collections/ansible_collections/<namespace>/<name>/. This means you cannot use ansible-galaxy collection install to install a role, and vice versa.

Role install: ``bash ansible-galaxy role install geerlingguy.nginx,1.0.0 ` This downloads the role from Galaxy and places it in ~/.ansible/roles/geerlingguy.nginx/. You can also install from git: `bash ansible-galaxy role install git+https://github.com/geerlingguy/ansible-role-nginx.git,1.0.0 ``

Collection install: ``bash ansible-galaxy collection install community.general:6.0.0 ` This installs to ~/.ansible/collections/ansible_collections/community/general/. Note the colon :` between namespace.name and version.

Key gotcha: If you accidentally run ansible-galaxy install (without subcommand), it defaults to role install. Always specify role or collection.

Production pattern: Use requirements.yml to manage both. Example: ``yaml --- roles: - name: geerlingguy.nginx version: 1.0.0 collections: - name: community.general version: 6.0.0 ` Then run: `bash ansible-galaxy install -r requirements.yml `` This single command installs all roles and collections listed.

# Install a role from Ansible Galaxy
ansible-galaxy role install geerlingguy.nginx

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

# List installed roles and collections
ansible-galaxy role list
ansible-galaxy collection list

Writing a Bulletproof requirements.yml for Roles and Collections

A requirements.yml file is the cornerstone of reproducible Ansible environments. It should contain both roles and collections with explicit versions. Here's a production-tested template:

```yaml --- roles: - name: geerlingguy.nginx version: 1.0.0 source: https://galaxy.ansible.com - name: mycompany.custom_role version: 2.1.0 source: https://automationhub.mycompany.com

collections: - name: community.general version: 6.0.0 source: https://galaxy.ansible.com - name: mycompany.operations version: 1.2.3 source: https://automationhub.mycompany.com ```

Important fields: - name: For roles, it's the role name (e.g., geerlingguy.nginx). For collections, it's namespace.name. - version: Use exact version (e.g., 6.0.0) or version range (e.g., >=6.0.0,<7.0.0). For production, always use exact. - source: Optional. If omitted, it uses the default server from ansible.cfg. Specify for private hubs.

Gotcha: When using source, ensure it matches the server list in ansible.cfg. Otherwise, you may get authentication errors.

Install command: ``bash ansible-galaxy install -r requirements.yml -f ` The -f` flag forces reinstallation even if already present. Use in CI to ensure clean state.

Validating: ``bash ansible-galaxy collection list -r requirements.yml `` This shows what would be installed without actually installing.

---
roles:
  - name: geerlingguy.nginx
    version: 3.1.4
  - name: geerlingguy.postgresql
    version: 2.2.0

collections:
  - name: community.general
    version: ">=5.0.0,<6.0.0"
  - name: ansible.posix
    version: 1.5.4

Understanding Collections Namespace and Name Convention

Collections are identified by a fully qualified collection name (FQCN) in the format namespace.name. The namespace is a logical grouping (e.g., cisco, amazon, community), and the name is the specific collection (e.g., ios, aws, general). This convention prevents naming conflicts and allows multiple collections from the same vendor.

Examples: - cisco.ios — Cisco IOS modules and roles - amazon.aws — AWS modules - community.general — General-purpose modules (deprecated, use ansible.builtin where possible)

Installation path: When you install community.general, it goes to: `` ~/.ansible/collections/ansible_collections/community/general/ `` Note the directory structure mirrors the namespace and name.

Listing installed collections: ``bash ansible-galaxy collection list | grep community.general ``

Importance of namespace: Namespaces are registered on Galaxy. You cannot publish a collection under a namespace you don't own. For private hubs, you can define custom namespaces.

Gotcha: Some collections have similar names (e.g., community.kubernetes vs kubernetes.core). Always verify the correct one from the official documentation.

---
# Collection namespace and name convention
# Namespace: community, Name: general -> community.general
# Namespace: ansible, Name: posix -> ansible.posix
# Namespace: mycompany, Name: network -> mycompany.network
collections:
  - name: community.general
  - name: ansible.posix
  - name: mycompany.network

Using Collection Modules in Playbooks with FQCN

To use a module from a collection in a playbook, you must use the Fully Qualified Collection Name (FQCN). The format is namespace.name.module_name. For example, to use the ios_config module from cisco.ios:

``yaml - name: Configure interface cisco.ios.ios_config: lines: - interface GigabitEthernet0/1 - ip address 192.0.2.1 255.255.255.0 ``

Why FQCN? Without FQCN, Ansible resolves module names by searching installed collections in order. If two collections provide a module with the same name, the first one found is used. This can lead to unexpected behavior. FQCN makes the source explicit.

Using filters and plugins: Filters from collections also require FQCN: ``yaml - name: Use ipaddr filter debug: msg: '{{ "192.0.2.1" | ansible.utils.ipaddr }}' ``

Legacy short names: Ansible still supports short names for some built-in modules (e.g., copy, file). But for collection modules, always use FQCN.

Verifying module availability: ``bash ansible-doc -t module cisco.ios.ios_config `` This shows documentation if the collection is installed.

Production pattern: Set the collections keyword in a playbook to avoid typing FQCN repeatedly: ``yaml --- - hosts: all collections: - cisco.ios tasks: - name: Configure interface ios_config: lines: - interface GigabitEthernet0/1 `` But be careful: this applies to all tasks in the play. Use with caution in large playbooks.

---
- name: Use collection modules with FQCN
  hosts: all
  tasks:
    - name: Ensure nginx is installed
      ansible.builtin.package:
        name: nginx
        state: present

    - name: Copy config file
      ansible.builtin.copy:
        src: nginx.conf
        dest: /etc/nginx/nginx.conf

    - name: Start nginx service
      ansible.builtin.service:
        name: nginx
        state: started
        enabled: yes

Connecting to Private Automation Hub

Many organizations run a private Automation Hub (part of Red Hat Ansible Automation Platform) to host internal collections and roles. To use it, configure ansible.cfg:

```ini [galaxy] server_list = automation_hub, galaxy

[galaxy_server.automation_hub] url=https://automationhub.example.com/api/galaxy/ auth_url=https://automationhub.example.com/auth/realms/automation-hub/protocol/openid-connect/token token=your_token_here

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

Getting a token: From Automation Hub UI, generate an API token. Or use ansible-galaxy: ``bash ansible-galaxy auth login --server https://automationhub.example.com ``

Installing from private hub: ``bash ansible-galaxy collection install mycompany.operations --server automation_hub ` Or specify in requirements.yml: `yaml collections: - name: mycompany.operations version: 1.0.0 source: https://automationhub.example.com/api/galaxy/ ``

Troubleshooting: If you get 404 or 401, check: - Token validity (regenerate if expired) - URL path (must end with /api/galaxy/ for Automation Hub) - User permissions for the namespace

Production pattern: Store token in a vault or environment variable, not in ansible.cfg. Use ANSIBLE_GALAXY_SERVER_TOKEN or ansible-vault.

[galaxy]
server_list = automation_hub

[galaxy_server.automation_hub]
url=https://automation-hub.example.com/api/galaxy/
auth_url=https://sso.example.com/auth/realms/myrealm/protocol/openid-connect/token
token=my_long_token_here

Pinning Versions for Reproducible Builds

Reproducibility is the holy grail of infrastructure as code. Without version pinning, ansible-galaxy install gives you whatever is latest at that moment. This is a disaster for CI/CD.

How to pin: In requirements.yml: ``yaml collections: - name: community.general version: 6.0.0 ``

Version formats: - Exact: 6.0.0 - Range: >=6.0.0,<7.0.0 - Latest: * (avoid)

Lock file approach: Use ansible-galaxy collection install -r requirements.yml --lock (Ansible 2.10+) to generate a lock file requirements.yml.lock with exact versions of all dependencies. Then commit the lock file and use it for installs: ``bash ansible-galaxy collection install -r requirements.yml.lock ``

Verifying pinned versions: ``bash ansible-galaxy collection list | grep community.general ` Should show exactly 6.0.0`.

CI/CD integration: In your pipeline: ``bash ansible-galaxy collection install -r requirements.yml -f ansible-galaxy collection list > installed_versions.txt `` Then diff against expected versions.

Gotcha: Pinning roles is similar: version: 1.0.0 in requirements.yml. But roles from git must use git+ syntax and pin to a commit or tag.

# Pin collection version during installation
ansible-galaxy collection install community.general:==5.8.0

# Pin role version
ansible-galaxy role install geerlingguy.nginx,v3.1.4

# Install from requirements.yml with pinned versions
ansible-galaxy install -r requirements.yml

Managing Dependencies Between Collections

Collections can depend on other collections. For example, community.kubernetes depends on kubernetes.core. When you install a collection, ansible-galaxy automatically installs its dependencies. This can lead to unexpected version conflicts.

How dependencies work: Each collection has a galaxy.yml file that lists dependencies. When you install community.kubernetes, it might install kubernetes.core>=1.0.0.

Problem: If your requirements.yml pins kubernetes.core to 2.0.0, but community.kubernetes requires <2.0.0, you get a conflict. ansible-galaxy will fail with a message like: `` ERROR! Cannot satisfy requirements for 'kubernetes.core' as it conflicts with version '2.0.0' required by 'community.kubernetes' ``

Solution: - Use a lock file to resolve all transitive dependencies. - Manually specify compatible versions in requirements.yml. - Use --force with caution; it may install conflicting versions.

Best practice: Always run ansible-galaxy collection install -r requirements.yml --lock to generate a consistent set of versions. Then commit the lock file.

Checking dependencies: ``bash ansible-galaxy collection install community.kubernetes --dry-run `` This shows what will be installed without actually doing it.

---
collections:
  - name: mycompany.network
    version: 2.0.0
    # This collection depends on community.general >=5.0.0
    # and ansible.utils >=2.0.0
  - name: community.general
    version: ">=5.0.0,<6.0.0"
  - name: ansible.utils
    version: ">=2.0.0,<3.0.0"

Using ansible-galaxy with Git Repositories and Tarballs

Not all collections and roles are on Galaxy. You can install from git repositories or local tarballs. This is common for internal tools.

Installing a collection from git: ``bash ansible-galaxy collection install git+https://github.com/mycompany/mycollection.git,main ` This clones the repo and installs from the main branch. You can also pin to a tag or commit: `bash ansible-galaxy collection install git+https://github.com/mycompany/mycollection.git,v1.0.0 ``

Installing from a tarball: ``bash ansible-galaxy collection install ./mycollection-1.0.0.tar.gz ``

In requirements.yml: ``yaml collections: - name: https://github.com/mycompany/mycollection.git version: v1.0.0 type: git ` Or for tarball: `yaml collections: - name: ./mycollection-1.0.0.tar.gz type: file ``

Roles from git: ``bash ansible-galaxy role install git+https://github.com/geerlingguy/ansible-role-nginx.git,1.0.0 ``

Production pattern: For internal collections, host them on a private git server or tarball repository. Use version tags to pin.

Gotcha: Git installs can be slow and require network access. Consider packaging as tarballs for faster CI.

# Install collection from a Git repository
ansible-galaxy collection install git+https://github.com/myorg/mycollection.git,master

# Install collection from a tarball
ansible-galaxy collection install ./mycollection-1.0.0.tar.gz

# Install role from a Git repository
ansible-galaxy role install git+https://github.com/geerlingguy/ansible-role-nginx.git,master

Troubleshooting Collection Installation Failures

Collection installation can fail for many reasons. Here's a systematic approach:

1. Check connectivity: ``bash ansible-galaxy collection install community.general --server https://galaxy.ansible.com -vvv ` The -vvv` flag shows detailed HTTP requests. Look for 200 OK or error codes.

2. Authentication issues: For private hubs, ensure token is valid. Test with: ``bash curl -H "Authorization: Bearer YOUR_TOKEN" https://automationhub.example.com/api/galaxy/content/ ``

3. Version conflicts: If you get dependency conflict errors, use --dry-run to see the dependency tree: ``bash ansible-galaxy collection install community.kubernetes --dry-run ``

4. Corrupted cache: Clear the galaxy cache: ``bash rm -rf ~/.ansible/galaxy_cache/ ``

5. Wrong server list: Verify ansible.cfg: ``bash ansible-config dump | grep GALAXY_SERVER ``

6. Permission issues: Ensure the install directory is writable. For system-wide installs, use sudo or set collections_path in ansible.cfg.

7. YAML syntax errors in requirements.yml: Validate with: ``bash python -c "import yaml; yaml.safe_load(open('requirements.yml'))" ``

# Troubleshooting: increase verbosity
ansible-galaxy collection install community.general -vvv

# Check if collection is installed
ansible-galaxy collection list | grep community.general

# Force reinstall
ansible-galaxy collection install community.general --force

# Validate requirements.yml
ansible-galaxy collection install -r requirements.yml --dry-run

Best Practices for ansible-galaxy in CI/CD Pipelines

In CI/CD, every build must be deterministic. Here's how to integrate ansible-galaxy:

1. Use a lock file: Generate it once and commit: ``bash ansible-galaxy collection install -r requirements.yml --lock ` Then in CI: `bash ansible-galaxy collection install -r requirements.yml.lock -f ``

2. Cache collections: In CI, cache the ~/.ansible/collections/ directory to speed up builds. But invalidate cache when lock file changes.

3. Validate requirements.yml: Add a step to check YAML syntax and that all versions are pinned (no *).

4. Test with multiple Ansible versions: Different Ansible versions may have different collection compatibility. Test with the version you use in production.

5. Use a dedicated CI user: Create a service account on Automation Hub with minimal permissions.

6. Monitor for deprecations: Regularly run: ``bash ansible-galaxy collection list --format json | jq '.[].version' `` And compare with latest available versions.

Example CI script: ```bash #!/bin/bash set -euo pipefail

ansible-galaxy collection install -r requirements.yml.lock -f ansible-galaxy collection list > /tmp/installed.txt diff <(sort /tmp/installed.txt) <(sort expected_versions.txt) || { echo "Version mismatch"; exit 1; } ```

stages:
  - test

before_script:
  - ansible-galaxy collection install -r requirements.yml --force

ansible-lint:
  stage: test
  script:
    - ansible-lint playbook.yml

molecule-test:
  stage: test
  script:
    - molecule test

Migrating from Roles to Collections: A Practical Guide

If you have a legacy Ansible codebase using roles exclusively, you might want to migrate to collections for better organization. Here's how to do it safely.

1. Create a collection scaffold: ``bash ansible-galaxy collection init mycompany.infrastructure `` This creates the directory structure.

2. Move roles into the collection: Place roles in mycompany/infrastructure/roles/. Then in playbooks, reference them as mycompany.infrastructure.rolename.

3. Create a requirements.yml for the collection: ``yaml collections: - name: mycompany.infrastructure version: 1.0.0 source: ./mycompany-infrastructure-1.0.0.tar.gz ``

4. Update playbooks: Replace role references with FQCN. For example: ``yaml - hosts: all roles: - mycompany.infrastructure.nginx ``

5. Test incrementally: Start with one collection and migrate roles one by one.

6. Use ansible-lint to enforce FQCN: Add rule fqcn-builtins to catch non-FQCN module usage.

Production pattern: Keep roles and collections side by side during migration. Use a requirements.yml that includes both.

Gotcha: Roles inside collections cannot use import_role with short name. Always use FQCN.

---
# Before: using roles
# - role: geerlingguy.nginx

# After: using collection
- name: Use collection instead of role
  hosts: all
  tasks:
    - name: Include role from collection
      ansible.builtin.include_role:
        name: geerlingguy.nginx
    # Or use module directly
    - name: Ensure nginx is installed
      community.general.nginx_config:
        state: present

Security Considerations for Ansible Galaxy Usage

Using public Galaxy content introduces security risks. Here's how to mitigate:

1. Use private Automation Hub: Host a curated set of approved collections. This prevents developers from accidentally using malicious content.

2. Pin versions: Always pin to exact versions. A new version of a collection could contain malware.

3. Verify checksums: For critical collections, download the tarball and verify its SHA256 checksum: ``bash wget https://galaxy.ansible.com/download/community-general-6.0.0.tar.gz sha256sum community-general-6.0.0.tar.gz `` Compare with the checksum published on Galaxy.

4. Audit installed collections: Regularly run: ``bash ansible-galaxy collection list --format json | jq '.[].name' `` And compare with an approved list.

5. Use signed collections: Ansible supports GPG signing of collections. Verify signatures before installation: ``bash ansible-galaxy collection verify community.general:6.0.0 ``

6. Limit network access: In CI, only allow connections to approved Galaxy servers.

7. Scan for vulnerabilities: Use tools like safety or trivy to scan collection dependencies.

Production pattern: Maintain an allowlist of namespaces and versions. Block all others at the network level.

[galaxy]
# Disable Galaxy by default
server_list = 

# Only use private Automation Hub
[galaxy_server.my_hub]
url=https://private-hub.example.com/api/galaxy/
token=my_secure_token

# Verify SSL certificates
galaxy_ignore_certs = false