Ansible Collection for Red Hat Runtimes

Several of the key products of the Red Hat Runtimes portfolio (Red Hat JBoss Enterprise Application Platform (EAP), Red Hat JBoss Web Server, Red Hat AMQ including streams for Apache Kafka and AMQ Broker, Red Hat build of Keycloak, etc.) now offer an integration within Ansible. Following the open source model of Red Hat, those extensions for Ansible have both a community version and a productized version. To help users better understand the philosophy behind this approach, this article explains in detail the differences between each option and how they can be used.

Many, if not all, Red Hat products have origins in open source or free software communities and are developed by both contributors of the project and employees of the company. A few famous examples include Red Hat Enterprise Linux (RHEL), based on the Fedora Distribution, Red Hat JBoss Enterprise Application Platform (EAP), based on Wildfly, or Red Hat JBoss Web Server, based on Apache Tomcat. This is a foundational concept to understand when using either Red Hat products or their community derivative . Even if both are functionally identical (or almost identical), Red Hat customers can only benefit from the company’s support when using the products that it produces (so, for instance, RHEL or JBoss EAP) and not the community version (such as the Fedora Linux distribution or the Wildfly Java/JEE server).

When using Ansible to install Red Hat Runtimes, such as JBoss EAP, JBoss Web Server, Red Hat Single Sign-On/Red Hat build of Keycloak, streams for Apache Kafka, or AMQ Broker, the same distinction applies. Therefore, each community project has a dedicated extension for the automation engine (a collection, in Ansible parlance) and another one for the product supplied by Red Hat. In this article, we will explore in detail how the setup, configuration, and management of a Red Hat Runtimes product using Ansible differs from the community version.

Upstream and downstream

A bit of vocabulary first: the software originating from the open source project is often referred to as upstream, while the product, supported by Red Hat, is called downstream. As examples, RHEL is the downstream of the Fedora project, while Wildfly is the upstream of the JBoss EAP product.

This statement may immediately bring the following question to mind: What should I use? Downstream or upstream? The answer is simple: A Red Hat customer having a valid subscription for a product, let’s say JBoss Web Server, should deploy the downstream product provided and supported by the vendor. If the user is not a Red Hat customer (or does not have a valid subscription for the product utilized), then they can always decide to use the open source version, bearing in mind that this deployment will not be supported by Red Hat.

In any case, it is recommended that an automation tool be used to set up and manage the software. For the Runtimes solutions provided by Red Hat (JBoss EAP, JBoss Web Server, streams for Apache Kafka, AMQ Broker, Red Hat Single Sign-On/Red Hat build of Keycloak, and Red Hat Data Grid), Red Hat provides Ansible Content Collections to easily deploy and administer those products using Ansible. If the user decides, however, to use the upstream project, instead of the productized version (such as Wildfly, Apache Tomcat, Kafka, ActiveMQ Artemis, Keycloak, etc.), they can still benefit from the upstream variant of the associated Ansible Collection.

In short, the same logic Red Hat uses for products has been applied to the Ansible Collections provided for the Runtimes solutions. There is an upstream variant of the Ansible collection, dedicated to the upstream project, and there is a downstream version of the collection, intended for use with the downstream product (in this case, Red Hat provides both the product and the associated Ansible collection).

To make this difference even more concrete, let’s see an example.

You are starting a new project and the team has chosen to use two open source projects: Wildfly and ActiveMQ Artemis. Your company is keen to leverage these solutions as there is the possibility to get support from Red Hat later on by migrating to, respectively, JBoss EAP and AMQ Broker. At this stage however, the project the team is developing is still a proof of concept, so the decision was made to utilize the open source variants (upstream) for now.

You have been put in charge of the automation associated with the setup of those solutions using Ansible. As the upstream projects were selected, you can freely use the upstream of the Ansible collections dedicated to them. These collections can be obtained either from Ansible Galaxy and can be installed using the ansible-galaxy tool:

• See output of the installation the Ansible Collection for Wildfly.
• See output of installation of the Ansible Collection for AMQ.

Once the collections have been installed, you can use the playbook included within the collection to automate the deployment and management of both Wildfly and ActiveMQ Artemis:

$ ansible-playbook -i inventory middleware_automation.wildfly.playbook

$ ansible-playbook -i inventory middleware_automation.amq.activemq

Let’s jump forward a few months later. 

The prototype has been a success and the project is about to be promoted to production. Your company now wants to employ supported solutions so that Red Hat can provide assistance in the event questions arise, or as a result of an incident or security issue. The developers of the project will adapt their applications to be deployed on JBoss EAP, instead of Wildfly, and AMQ Broker in lieu of ActiveMQ Artemis. On the automation front, you also need to make changes to the Ansible collections to ensure that the downstream variant of the collections are used instead. Apart from that, the automation, like the application, will run the same.

Frequently asked questions

There are a few common questions you might have when deciding which Ansible Collection to use. The section below aims to address them.

Why can’t I keep employing the upstream collections?

For simplicity’s sake and to make the experience better, each variant (upstream and downstream) of the same collection has been tailored to the software it manages. As a result, the upstream variant of the collection for Wildfly is configured and geared toward the upstream version of the project, while the downstream collection for JBoss EAP comes preconfigured for the downstream product.

What are the differences with the downstream collection?

The distinction with regards to the upstream variant is primarily centered around how Ansible will retrieve the software binaries. In the upstream variant, the Ansible obtains the latest available archive of the software package from the upstream project website. For instance, as of the writing of this article, the Wildfly collection will, by default, fetch and install version 32 of the Wildfly server (note that this version can be configured to deploy an earlier release of the JEE server if desired).

In contrast, the downstream collection will, by default, connect to the Red Hat Customer Portal, include the provided authentication details associated with your organization's subscription, and download the software. 

What do I need to change?

There are two steps that differ when using the downstream collection with Ansible:

1. The collections themselves are obtained, by default, from Automation Hub on the Red Hat Hybrid Cloud Console.

2. Credentials associated with a Red Hat Customer Account are needed to connect to the Red Hat Customer Portal to download install the products when executing the automation.

Notes:

• RH customers using their own private Automation Hub can, of course, use it as a source when using the collections.
• Users can also provide the products archives files to Ansible by another mechanism and configure the collection to work without a direct connection to the Red Hat Customer portal.

First, you need to install the downstream collection the ansible-galaxy CLI. This time, however, the CLI will need to be configured to use Red Hat Automation Hub instead of Ansible Galaxy. Red Hat Automation Hub is a hosted solution supported by Red Hat that delivers the same functionality as Ansible Galaxy to host Ansible collections. The main distinction is that the content here is provided by Red Hat and its partners.

Note that each collection offers a specific level of support from Red Hat. For instance, as of the writing of this article, the Ansible collection for JBoss Web Server is fully supported, while the Ansible collection for JBoss EAP is still provided as a technical preview.

For ansible-galaxy to be able to fetch and install content from Red Hat Automation Hub, you will need to provide the required authentication information in the ansible.cfg file:

[galaxy]
server_list = automation_hub
[galaxy_server.automation_hub]
url=https://cloud.redhat.com/api/automation-hub/
auth_url=https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token
token=<insert-your-token-here>

The process for retrieving the token from Automation Hub is described here.

Once this step has been completed, you can use ansible-galaxy CLI to install the downstream versions of the collections associated to JBoss EAP and AMQ Broker:

$ ansible-galaxy collection install redhat.eap
$ ansible-galaxy collection install redhat.amq_broker

---
                - name: "Play for Wildfly and ActiveMQ"
                  hosts: all
                  collections:
                    - middleware_automation.wildfly
                    - middleware_automation.amq
                  vars:
                    wildfly_config_base: 'standalone-ha.xml'
                …

---
                - name: "Play forJBoss EAP and AMQ Broker"
                  hosts: all
                  collections:
                    - redhat.eap
                    - redhat.amq_broker
                …  
                  vars:
                    eap_config_base: 'standalone-full.xml'

With the playbook updated to now employ the downstream collections for both JBoss EAP and AMQ Broker, the final step that needs to be completed is to provide Ansible with the appropriate credentials so that Ansible can connect to the Red Hat Customers portal and download the product binaries. 

There are numerous ways to supply these properties to Ansible. However, the most straightforward approach is to use a file containing the variables that are needed to be referenced by Ansible:

---
rhn_username: <service_account_id> 
rhn_password: <service_account_token>

At this point, the modified playbook referencing the downstream collections can be used to provision the target system with both JBoss EAP and an instance of the AMQ Broker:

$ ansible-playbook -i inventory -e @service_account.yml <playbook>

Summary

To recap, depending if one uses the upstream variant of Red Hat Runtime or the products supported by the company, one should use the appropriate Ansible collection in order to benefits both from the sane defaults (defaults values matching the product used) and, in the case of downstream collection, of the support of Red Hat.

The table below summarizes which collection to use depending on the product being used.