Menu Close
Chapter 4. Installing and Using Collections
4.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 Settings role is presented as rhel-system-roles.kernel_settings
, using the Collection fully qualified collection name
for the Kernel Settings 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
- To use the Red Hat Certified Collections by accessing the Automation Hub, you must have an Ansible Automation Platform (AAP subscription).
4.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
4.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
- 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
andrhel-system-roles
packages are installed. - An inventory file which lists the managed nodes.
-
The
Procedure
Install the collection via RPM package:
# dnf 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:
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 .
- Edit the file, replacing "hosts: all" with "hosts: localhost" to make the playbook run only on the local system.
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.
4.4. Installing Collections from Automation Hub
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
andrhel-system-roles
packages are installed. - An inventory file which lists the managed nodes.
-
The
Procedure
-
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 . Install the
redhat.rhel_system_roles
collection from the Automation Hub:# ansible-galaxy collection install redhat.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:
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 .
- Edit the file, replacing "hosts: all" with "hosts: localhost" to make the playbook run only on the local system.
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.
4.5. Deploying the Terminal Session Recording RHEL System Role using Collections
Following is an example using Collections to prepare and apply a playbook to deploy a logging solution on a set of separate machines.
Prerequisites
- A Galaxy collection is installed.
Procedure
Create a new
playbook.yml
file with the following content:--- - name: Deploy session recording hosts: all vars: tlog_scope_sssd: some tlog_users_sssd: - recordeduser roles: - redhat.rhel-system-roles.tlog
Where,
tlog_scope_sssd
:-
some
specifies you want to record only certain users and groups, notall
ornone
.
-
tlog_users_sssd
:-
recordeduser
specifies the user you want to record a session from. Note that this does not add the user for you. You must set the user by yourself.
-
Optionally, verify the playbook syntax.
# ansible-playbook --syntax-check playbook.yml
Run the playbook on your inventory file:
# ansible-playbook -i IP_Address /path/to/file/playbook.yml -v
As a result, the playbook installs the Terminal Session Recording role on the system you specified. It also creates an SSSD configuration drop file that can be used by the users and groups that you define. SSSD parses and reads these users and groups to overlay tlog
session as the shell user. Additionally, if the cockpit
package is installed on the system, the playbook also installs the cockpit-session-recording
package, which is a Cockpit
module that allows you to view and play recordings in the web console interface.
Verification steps
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.
- Verify that the system sends messages to the log:
To verify that the SSSD configuration drop file is created in the system, perform the following steps:
Navigate to the folder where the SSSD configuration drop file is created:
# cd /etc/sssd/conf.d
Check the file content:
# cat sssd-session-recording.conf
You can see that the file contains the parameters you set in the playbook.