Collections and Galaxy

Ansible · Advanced · 8 min

Most modules (cloud, network, databases, Kubernetes) ship in collections, not in ansible-core.

Since Ansible 2.10, content is packaged in collections: a namespace and name (community.general, amazon.aws, kubernetes.core, ansible.posix) bundling modules, plugins, roles and playbooks. ansible-core includes only ansible.builtin; the ansible community package bundles a curated set of collections on top.

That's why fully qualified names matter: community.postgresql.postgresql_db tells readers and Ansible exactly where a module comes from.

Install from Ansible Galaxy (galaxy.ansible.com), Automation Hub, a private Galaxy server, or git:

  • ansible-galaxy collection install community.general
  • for projects, list everything in requirements.yml with version constraints and install with ansible-galaxy install -r requirements.yml (handles both roles and collections).

Collections install to ~/.ansible/collections by default; set collections_path (or install with -p ./collections) to keep a project's dependencies inside the project, making CI reproducible.

ansible-galaxy collection list shows what is installed and where. Watch for duplicates: the same collection installed in two paths, with the first one found winning.

Some collections need Python libraries on the control node or target (boto3 for amazon.aws, kubernetes for kubernetes.core). For fully reproducible environments, Red Hat's execution environments package ansible-core, collections and Python dependencies into a container image, built with ansible-builder.

Example

# requirements.yml
collections:
  - name: community.general
    version: ">=10.0.0,<11.0.0"
  - name: ansible.posix
    version: ">=2.0.0"
  - name: kubernetes.core
    version: "6.1.0"
roles:
  - name: geerlingguy.docker
    version: "7.4.1"
# ansible-galaxy install -r requirements.yml -p ./collections   (roles: use roles_path)
# ansible-galaxy collection list | grep -E 'community.general|kubernetes.core'
# usage in a task:
#   - community.general.timezone: {name: Europe/Berlin}

Remember

  • ansible-core has only ansible.builtin; everything else is in collections
  • Pin collections and roles in requirements.yml
  • Install into the project for reproducible CI; execution environments for full isolation

Watch out for

  • Relying on whatever collection versions happen to be on a laptop instead of a pinned requirements.yml.

Check yourself

  1. A playbook using community.general.ufw fails with 'couldn't resolve module' on a fresh ansible-core install. Why?

Sign in to answer, see the explanations, and get this lesson back as a quick review later.

Official docs: docs.ansible.com/ansible/latest/collections_guide/index.html