Red Hat Certified Engineer (RHCE) #12 Collection: Galaxy, Automation Hub

In #11 Writing and Using Roles, we learned how to bundle tasks, variables, and handlers into a role for reuse. But Ansible has a unit one level above the role — the collection. In this post, we’ll sort out what a collection is, how to download collections and roles with ansible-galaxy, and the requirements.yml bulk-install flow that shows up often on the exam, all from a hands-on point of view.

What is a collection #

A collection is a distribution unit that bundles modules, roles, and plugins into one package. In the past, every module shipped inside Ansible itself, but now the core (ansible-core) and the content (collections) are separated. Modules related to firewalld or selinux no longer live in the core — they reside in separate collections, so when you need them you download the relevant collection and use it.

A single collection can contain the following content.

• module. The unit of work you call directly from a task. For example, the firewalld module of the ansible.posix collection
• role. A reusable unit bundling tasks, variables, and handlers. The very role we covered in #11
• plugin. Code that extends Ansible’s behavior, such as filter, lookup, and connection

A collection usually has a name in the namespace.collection form, like community.general, ansible.posix, or redhat.rhel_system_roles. The front part is the namespace (the maintaining body) and the back part is the collection name.

FQCN: namespace.collection.module #

The core rule of the collection era is the FQCN (Fully Qualified Collection Name). When you call a module, you use the full namespace.collection.module path rather than the short name.

# Short name (not recommended, ambiguous)
- name: Configure firewall
  firewalld:
    service: https
    state: enabled

# FQCN (recommended)
- name: Configure firewall
  ansible.posix.firewalld:
    service: https
    state: enabled

ansible.posix.firewalld means the firewalld module of the ansible.posix collection. Since a module with the same name can exist in several collections, using the FQCN designates exactly which collection’s module you mean, without ambiguity. We recommend building the habit of writing in FQCN on the exam, because the module you intended runs precisely regardless of the grading environment’s collection setup.

Modules included in the body by default (e.g. copy, template, service) actually belong to the ansible.builtin namespace. So ansible.builtin.copy, ansible.builtin.service are the accurate FQCNs. They also work by short name, but the FQCN is explicit.

Installing collections: ansible-galaxy collection install #

You install a collection with the ansible-galaxy collection install command.

# Install a single collection
ansible-galaxy collection install ansible.posix

# Specify a particular version
ansible-galaxy collection install ansible.posix:1.5.4

# List installed collections
ansible-galaxy collection list

Where an installed collection ends up matters on the exam. By default it installs into the user’s home at ~/.ansible/collections, but we recommend isolating it inside the project. The -p option lets you set the install path directly.

# Install into the collections path inside the project directory
ansible-galaxy collection install ansible.posix -p collections

When you install into a collections directory at the project root like this, Ansible automatically recognizes that path when you run a playbook from the same directory. If the working directory is fixed on the exam, this approach is safe.

Bulk install with requirements.yml #

When there are several collections, instead of typing commands one at a time, the standard approach is to write the dependencies into a requirements.yml file and install them all at once. This flow is a regular type on the RHCE exam. When a question instructs you to download and use a particular collection or role, you write it into requirements.yml, install in bulk, and then call it via FQCN.

# collections/requirements.yml
---
collections:
  - name: ansible.posix
  - name: community.general
    version: 6.0.0

You install the collections in bulk based on this file.

ansible-galaxy collection install -r collections/requirements.yml -p collections

-r is the option that reads in the requirements file, and -p collections fixes the install path inside the project. The exam environment may not have direct internet access and may be configured to point at an internal repository or Automation Hub, so if the install command fails, check the source settings first.

Installing roles with requirements too #

requirements.yml can install not only collections but also roles. You write roles and collections in one file, placing each under the roles and collections keys respectively.

# roles/requirements.yml
---
roles:
  - name: geerlingguy.nginx
  - src: https://github.com/example/my-role.git
    scm: git
    name: my_role

collections:
  - name: ansible.posix

You install roles with ansible-galaxy role install and collections with ansible-galaxy collection install, but a requirements file mixing both kinds of content can be handled all at once with ansible-galaxy install.

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

# Install roles and collections at once
ansible-galaxy install -r roles/requirements.yml

A role’s default install path is ~/.ansible/roles, and with -p roles you can isolate it into a roles directory inside the project.

Galaxy vs Automation Hub #

There are largely two sources for downloading collections.

Ansible Galaxy is the public repository where community collections gather. Collections like community.general are distributed here. Automation Hub, on the other hand, is the repository that provides certified content for which Red Hat guarantees quality and support. To use the stable, supported collections an enterprise relies on, you set Automation Hub as the source.

Which source to use is specified as a server list in the [galaxy] section of ansible.cfg.

# ansible.cfg
[galaxy]
server_list = automation_hub, galaxy

[galaxy_server.automation_hub]
url = https://console.redhat.com/api/automation-hub/content/published/
auth_url = https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
token = <your-token>

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

It searches sources in the order listed in server_list. On the exam the source is often configured in advance, so rather than building it anew, reading and using the given settings as-is is faster.

collections_path and ansible.cfg #

Where Ansible looks for an installed collection is decided by the collections_path setting in ansible.cfg (the old name is collections_paths, and both are recognized).

# ansible.cfg
[defaults]
inventory = inventory
collections_path = ./collections:~/.ansible/collections

Multiple paths are separated with a colon (:), and it searches from the front path first. The setting above looks at the project’s collections first and, if absent, the user’s home. There’s one convenience: if there’s a collections directory directly under the project directory, Ansible recognizes it automatically even without specifying collections_path. That’s why the convention of downloading with -p collections is a safe choice on the exam.

A role’s search path is handled separately by roles_path.

[defaults]
roles_path = ./roles:~/.ansible/roles

Example: install with requirements, then use via FQCN #

Let’s look at the whole flow of downloading a collection and calling it via FQCN in one pass. First, the project structure.

project/
├── ansible.cfg
├── inventory
├── collections/
│   └── requirements.yml
└── site.yml

We tidy up the working directory in ansible.cfg.

# ansible.cfg
[defaults]
inventory = inventory
collections_path = ./collections
remote_user = devops

[privilege_escalation]
become = true

Write the collections to install into requirements.yml, install in bulk, and then check the result.

# collections/requirements.yml
---
collections:
  - name: ansible.posix

ansible-galaxy collection install -r collections/requirements.yml -p collections
ansible-galaxy collection list | grep ansible.posix

Now we call the module by FQCN in the playbook.

# site.yml
---
- name: Configure web server firewall
  hosts: webservers
  tasks:
    - name: Install httpd
      ansible.builtin.dnf:
        name: httpd
        state: present

    - name: Enable httpd service
      ansible.builtin.service:
        name: httpd
        state: started
        enabled: true

    - name: Allow https service through the firewall
      ansible.posix.firewalld:
        service: https
        permanent: true
        immediate: true
        state: enabled

Run the playbook.

ansible-navigator run site.yml -m stdout
# or
ansible-playbook site.yml

Since ansible.posix.firewalld is a module from a separate collection, if you don’t install the collection beforehand, you’ll get an error that the module can’t be found. So the order of install first, use later decides points in grading.

Exam points #

• Write in FQCN. Call modules in the namespace.collection.module form. For example, write ansible.posix.firewalld, ansible.builtin.copy. Short names are ambiguous, so on the exam we recommend FQCN.
• Install in bulk with requirements.yml. If you need several collections or roles, write them into collections/requirements.yml and download them all at once with ansible-galaxy collection install -r ... -p collections. This flow is an exam staple.
• Fix the install path inside the project. When you download with -p collections, it’s recognized automatically when you run a playbook from the same directory. Isolate roles with -p roles.
• Check collections_path. Confirm which paths the collections_path and roles_path in ansible.cfg look at, and match them to the install path.
• Install first, use later. If you call an FQCN before downloading the collection, the module can’t be found. Complete the install before running the playbook.
• Use the source settings as-is. When Galaxy and Automation Hub sources are configured in advance, reading and using the existing [galaxy] settings in ansible.cfg is faster than building them from scratch.

Wrap-up #

What this post locked in:

• A collection is a distribution unit bundling modules, roles, and plugins, and the core (ansible-core) and the content are separated.
• Calling a module by FQCN (namespace.collection.module) leaves no ambiguity. On the exam we recommend FQCN.
• You install with ansible-galaxy collection install, install in bulk with -r requirements.yml, and fix the path with -p collections.
• requirements.yml can list collections and roles together, and ansible-galaxy install can handle them at once.
• Galaxy is the community public repository, and Automation Hub is the Red Hat certified content repository.
• The search paths are decided by collections_path and roles_path in ansible.cfg.

Next — system roles #

We’ve learned how to bring in external content with collections. Now we move into rhel-system-roles, the bundle of certified roles that Red Hat provides directly for RHEL system management.

In #13 system roles (rhel-system-roles), we’ll write our way through installing the redhat.rhel_system_roles collection, the variable structure of representative roles like timesync, firewall, and selinux, and the “apply this setting with a system role” type that shows up often on the exam.