Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 3. Installing and Using Collections

3.1. Introduction to Ansible Collections
Copy link

Ansible Collections are the new way of distributing, maintaining, and consuming automation. By combining multiple types of Ansible content such as playbooks, roles, modules, and plugins, you can benefit from improvements in flexibility and scalability.

The Ansible Collections are an option to the traditional RHEL System Roles format. Using the RHEL System Roles in the Ansible Collection format is almost the same as using it in the traditional RHEL System Roles format. The difference is that Ansible Collections use the concept of a fully qualified collection name (FQCN), which consists of a namespace and the collection name. The namespace we use is redhat and the collection name is rhel_system_roles. So, while the traditional RHEL System Roles format for the kernel_settings role is presented as rhel-system-roles.kernel_settings (with dashes), using the Collection fully qualified collection name for the kernel_settings role would be presented as redhat.rhel_system_roles.kernel_settings (with underscores).

The combination of a namespace and a collection name guarantees that the objects are unique. It also ensures that objects are shared across the Ansible Collections and namespaces without any conflicts.

3.2. Collections structure
Copy link

Collections are a package format for Ansible content. The data structure is as below:

  • docs/: local documentation for the collection, with examples, if the role provides the documentation
  • galaxy.yml: source data for the MANIFEST.json that will be part of the Ansible Collection package

  • playbooks/: playbooks are available here

    • tasks/: this holds 'task list files' for include_tasks/import_tasks usage

  • plugins/: all Ansible plugins and modules are available here, each in its subdirectory

    • modules/: Ansible modules
    • modules_utils/: common code for developing modules
    • lookup/: search for a plugin
    • filter/: Jinja2 filter plugin
    • connection/: connection plugins required if not using the default
  • roles/: directory for Ansible roles
  • tests/: tests for the collection’s content

3.3. Installing Collections by using the CLI
Copy link

Collections are a distribution format for Ansible content that can include playbooks, roles, modules, and plugins.

You can install Collections through Ansible Galaxy, through the browser, or by using the command line.

Prerequisites

  • Access and permissions to one or more managed nodes.

  • Access and permissions to a control node, which is a system from which Red Hat Ansible Core configures other systems.

    On the control node:

    • The ansible-core and rhel-system-roles packages are installed.
    • An inventory file which lists the managed nodes.

Procedure

  • Install the collection via RPM package: 

    # yum install rhel-system-roles
    Copy to Clipboard Toggle word wrap

After the installation is finished, the roles are available as redhat.rhel_system_roles.<role_name>. Additionally, you can find the documentation for each role at /usr/share/ansible/collections/ansible_collections/redhat/rhel_system_roles/roles/<role_name>/README.md.

Verification steps

To verify the installation, run the kernel_settings role with check mode on your localhost. You must also use the --become parameter because it is necessary for the Ansible package module. However, the parameter will not change your system:

  1. Run the following command: 

    $ ansible-playbook -c local -i localhost, --check --become /usr/share/ansible/collections/ansible_collections/redhat/rhel_system_roles/tests/kernel_settings/tests_default.yml
    Copy to Clipboard Toggle word wrap

The last line of the command output should contain the value failed=0.

Note

The comma after localhost is mandatory. You must add it even if there is only one host on the list. Without it, ansible-playbook would identify localhost as a file or a directory.

3.4. Installing Collections from Automation Hub
Copy link

If you are using the Automation Hub, you can install the RHEL System Roles Collection hosted on the Automation Hub.

Prerequisites

  • Access and permissions to one or more managed nodes.

  • Access and permissions to a control node, which is a system from which Red Hat Ansible Core configures other systems.

    On the control node:

    • The ansible-core and rhel-system-roles packages are installed.
    • An inventory file which lists the managed nodes.

Procedure

  1. Define Red Hat Automation Hub as the default source for content in the ansible.cfg configuration file. See Configuring Red Hat Automation Hub as the primary source for content .

  2. Install the redhat.rhel_system_roles collection from the Automation Hub: 

    # ansible-galaxy collection install redhat.rhel_system_roles
    Copy to Clipboard Toggle word wrap

    After the installation is finished, the roles are available as redhat.rhel_system_roles.<role_name>. Additionally, you can find the documentation for each role at /usr/share/ansible/collections/ansible_collections/redhat/rhel_system_roles/roles/<role_name>/README.md.

Verification steps

To verify the install, run the kernel_settings role with check mode on your localhost. You must also use the --become parameter because it is necessary for the Ansible package module. However, the parameter will not change your system:

  1. Run the following command: 

    $ ansible-playbook -c local -i localhost, --check --become /usr/share/ansible/collections/ansible_collections/redhat/rhel_system_roles/tests/kernel_settings/tests_default.yml
    Copy to Clipboard Toggle word wrap

The last line of the command output should contain the value failed=0.

Note

The comma after localhost is mandatory. You must add it even if there is only one host on the list. Without it, ansible-playbook would identify localhost as a file or a directory.

Following is an example using Collections to prepare and apply an Ansible playbook to configure a logging solution on a set of separate machines.

Prerequisites

  • A Collection format of rhel-system-roles is installed either from an rpm package or from the Automation Hub.

Procedure

  1. Create a playbook that defines the required role:

    1. Create a new YAML file and open it in a text editor, for example: 

      # vi logging-playbook.yml
      Copy to Clipboard Toggle word wrap

    2. Insert the following content into the YAML file: 

      ---
- name: Deploying basics input and implicit files output
  hosts: all
  roles:
    - redhat.rhel_system_roles.logging
  vars:
    logging_inputs:
      - name: system_input
        type: basics
    logging_outputs:
      - name: files_output
        type: files
    logging_flows:
      - name: flow1
        inputs: [system_input]
        outputs: [files_output]
      Copy to Clipboard Toggle word wrap

  2. Execute the playbook on a specific inventory: 

    # ansible-playbook -i inventory-file logging-playbook.yml
    Copy to Clipboard Toggle word wrap

    Where:

    • inventory-file is the name of your inventory file.
    • logging-playbook.yml is the playbook you use.

Verification steps

  1. Test the syntax of the configuration files /etc/rsyslog.conf and /etc/rsyslog.d: 

    # rsyslogd -N 1
rsyslogd: version 8.1911.0-6.el8, config validation run (level 1), master config /etc/rsyslog.conf
rsyslogd: End of config validation run. Bye.
    Copy to Clipboard Toggle word wrap

  2. Verify that the system sends messages to the log:

    1. Send a test message: 

      # logger test
      Copy to Clipboard Toggle word wrap

    2. View the /var/log/messages log, for example: 

      # cat /var/log/messages
Aug  5 13:48:31 hostname root[6778]: test
      Copy to Clipboard Toggle word wrap

      The hostname is the hostname of the client system. The log displays the user name of the user that entered the logger command, in this case, root.

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat