Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 29 ยท Structuring Automation

Collections, Galaxy and Reusable Content

Understand Ansible collections and fully qualified names (FQCN), install content with ansible-galaxy and requirements.yml, pin versions, and package a minimal role for sharing.

Ansible's built-in modules cover files, packages and services, but the world is bigger: firewalls, Docker, cloud providers, databases, network gear. That content ships in collections, versioned packages that bundle modules, plugins, roles and documentation under one name, such as community.general or community.docker. A collection is to Ansible what a library is to a programming language.

This lesson explains collections and fully qualified collection names (FQCN), how to install and pin them with ansible-galaxy and a requirements.yml file, and how to package a small role of your own for reuse. It builds on Roles and Project Layout.

Installing collections needs network access and a real Ansible installation, so the commands and YAML here are read-only. The runnable examples are JavaScript stand-ins for two ideas: how a module name is resolved to a collection, and how a version requirement is checked. They are simplified models, not Ansible's resolver.

What a collection is

A collection has a namespace and a name, joined by a dot: community.general has the namespace community and the name general. Inside, it can contain:

  • modules (community.general.ufw, a firewall front end)
  • plugins (filters, lookups, inventory plugins, connection plugins)
  • roles
  • documentation and sample playbooks

Two things matter from day one. ansible.builtin holds the core modules (copy, template, apt, service, debug, command) and comes with ansible-core itself. The ansible package (the "batteries included" install) adds a large, curated set of community collections, whereas plain ansible-core installs only ansible.builtin and you add the rest yourself (see Installing Ansible and Your First Ping).

Fully qualified collection names

Early Ansible let you write copy: or apt: and found the module by magic. With thousands of modules from many authors, short names could clash. The fix is the FQCN: namespace.collection.module.

YAML
- name: Copy a file
  ansible.builtin.copy:
    src: motd
    dest: /etc/motd

- name: Open a firewall port
  community.general.ufw:
    rule: allow
    port: "443"
    proto: tcp

Using FQCNs everywhere is today's recommended style. It makes a playbook explicit about where each module comes from, avoids clashes with a same-named module in another collection, and lets tools like ansible-lint check it. Short names still work for builtin modules in many setups, but they are a legacy habit. There is also an older play keyword, collections:, that adds a search list of collections so short names resolve; avoid it in new code because it hides which collection a task uses.

Inspect a module's documentation locally with ansible-doc community.general.ufw, or list what is installed:

Terminal
ansible-galaxy collection list
ansible-doc -l community.general | head

Stand-in: resolving module names

This model keeps a table of installed collections and resolves names the way a reader would expect: a three-part name must match an installed collection and a module in it, and a short name falls back to ansible.builtin.

JS Resolve module names to collections

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Notice that ufw alone fails while community.general.ufw works, and that a missing collection produces a different error from a missing module. Add "amazon.aws" to installed, with the module listed, and the cloud name starts resolving.

Installing with ansible-galaxy

ansible-galaxy is the package manager for roles and collections. It talks to Ansible Galaxy, the public hub, or to your own server (Automation Hub or a Git URL).

Terminal
ansible-galaxy collection install community.general
ansible-galaxy collection install community.docker:==3.12.0
ansible-galaxy collection install -r requirements.yml
ansible-galaxy collection list

By default, collections install into ~/.ansible/collections. For a project, install them next to your playbooks with -p ./collections and set collections_path = ./collections in ansible.cfg, so everyone on the team and the CI server use the same set.

requirements.yml and pinning versions

Typing install commands by hand does not scale, and "whatever version was newest" is not reproducible. A requirements.yml file records what the project needs:

YAML
---
collections:
  - name: community.general
    version: ">=9.0.0,<10.0.0"
  - name: community.docker
    version: "3.12.0"
  - name: ansible.posix

roles:
  - name: example.webserver
    src: https://git.example.com/automation/ansible-role-webserver.git
    scm: git
    version: v1.4.0

Version strings accept a range (>=9.0.0,<10.0.0), an exact version, or * for any. A role from a Git URL can be pinned to a tag or commit. Commit this file to your repository and install from it in CI, so a build next month uses the same code as today.

Pinning matters because collections change: modules gain parameters, and deprecated ones disappear in major releases (collections follow semantic versioning, so a major version bump is where breaking changes can appear). A range such as >=9.0.0,<10.0.0 accepts bug-fix and feature releases but blocks the next major version.

Stand-in: checking versions against requirements

The model compares installed versions with the specification and reports ok, WRONG VERSION or MISSING. Real ansible-galaxy does this when installing, and also resolves collection dependencies.

JS Do installed versions satisfy requirements?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Change the community.docker requirement to >=3.10.0 and the status flips to ok.

Writing a minimal role for sharing

To share a role, first make it self-contained: sensible defaults, a clear README.md, no hidden dependencies on your own inventory, and variable names prefixed with the role name (webserver_port, not port) so they do not clash with other roles. The metadata goes in meta/main.yml:

YAML
# roles/webserver/meta/main.yml
galaxy_info:
  author: Your Name
  description: Installs and configures a simple web server
  license: MIT
  min_ansible_version: "2.14"
  platforms:
    - name: Ubuntu
      versions: [jammy, noble]
dependencies: []
YAML
# roles/webserver/defaults/main.yml
webserver_port: 80
webserver_packages:
  - nginx

Then push the role's folder to its own Git repository. Others can reference it from a requirements.yml with src and version as above, or you can package it inside a collection (a collection has a galaxy.yml file, a roles/ folder and a plugins/ folder, and is built with ansible-galaxy collection build). The prefixing rule and tested defaults matter more than the packaging method: a role that quietly depends on a variable from your inventory is not reusable.

flowchart LR
  R["requirements.yml<br/>(names + versions)"] --> G["ansible-galaxy install"]
  G --> S["Galaxy, Automation Hub<br/>or a Git repository"]
  S --> L["collections/ and roles/<br/>on the control node"]
  L --> P["playbook uses<br/>ansible.builtin.copy,<br/>community.general.ufw"]

Requirements are fetched from a source into local folders, then playbooks refer to the content by FQCN.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the FQCN of the ufw module in the general collection of the community namespace?

    An FQCN is namespace.collection.module, so community.general.ufw. ansible.builtin only holds the core modules.
  2. 2. Why pin collection versions in requirements.yml?

    Without pins you get whatever is newest, so a build next month could differ from today. A range such as >=9.0.0,<10.0.0 blocks the next major version, where breaking changes can appear.
  3. 3. Which command installs everything listed in a requirements file?

    ansible-galaxy with -r reads the file and installs the collections it lists; roles use the matching ansible-galaxy role install -r form.
  4. 4. Why should variables in a shareable role be prefixed with the role name?

    Variables share one namespace per host, so webserver_port is much safer than port when several roles are combined.

Summary

  • A collection is a versioned package of modules, plugins and roles named namespace.collection; ansible.builtin ships with ansible-core.
  • Use fully qualified names (ansible.builtin.copy, community.general.ufw) so a task states exactly where its module comes from.
  • ansible-galaxy installs collections and roles; requirements.yml records them, and version pins or ranges keep builds reproducible.
  • A shareable role has documented defaults, prefixed variable names, meta/main.yml metadata and its own repository.

Next: Files, Users and Packages.