Chapter 3. Installing and Using Collections

3.1. Introduction to Ansible Collections

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 role is presented as rhel-system-roles.kernel_settings, using the Collection fully qualified collection name for the Kernel role would be presented as redhat.rhel_system_roles.kernel_settings.

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.

Additional resources

  • You can find the Red Hat Certified Collections by accessing the Automation Hub.

3.2. Collections Structure

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

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

  • Red Hat Ansible Engine version 2.9 and later is installed.
  • The python3-jmespath package is installed.
  • An inventory file that lists the managed nodes exists.

Procedure

  • Install the collection via RPM package:

    # yum install rhel-system-roles

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 that the Collections were successfully installed, you can apply the kernel_settings on your localhost:

  1. Copy one of the tests_default.yml to your working directory.

    $ cp /usr/share/ansible/collections/ansible_collections/redhat/rhel_system_roles/tests/kernel_settings/tests_default.yml .
  2. Edit the file, replacing "hosts: all" with "hosts: localhost" to make the playbook run only on the local system.
  3. Run the ansible-playbook in the check mode. This does not change any settings on your system.

    $ ansible-playbook --check tests_default.yml

The command returns the value failed=0.

Additional resources

  • The ansible-playbook man page.

3.4. Installing Collections from Automation Hub

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

Prerequisites

  • Red Hat Ansible Engine version 2.9 or later is installed.
  • The python3-jmespath package is installed.
  • An inventory file that lists the managed nodes exists.

Procedure

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

    # ansible-galaxy collection install redhat.rhel_system_roles
  2. 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 .

    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 that the Collections were successfully installed, you can apply the kernel_settings on your localhost:

  1. Copy one of the tests_default.yml to your working directory.

    $ cp /usr/share/ansible/collections/ansible_collections/redhat/rhel_system_roles/tests/kernel_settings/tests_default.yml .
  2. Edit the file, replacing "hosts: all" with "hosts: localhost" to make the playbook run only on the local system.
  3. Run the ansible-playbook on the check mode. This does not change any settings on your system.

    $ ansible-playbook --check tests_default.yml

    You can see the command returns with the value failed=0.

Additional resources

  • The ansible-playbook man page.

3.5. Applying a local logging System Role using Collections

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

Prerequisites

  • A Galaxy collection is installed.

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
    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]
  2. Execute the playbook on a specific inventory:

    # ansible-playbook -i inventory-file logging-playbook.yml

    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 /etc/rsyslog.conf file:

    # 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.
  2. Verify that the system sends messages to the log:

    1. Send a test message:

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

      # cat /var/log/messages
      Aug  5 13:48:31 hostname root[6778]: test

      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.