Ansible Collection - redhat.jws

This repository contains the Ansible roles and playbooks to set up an automated installation of Red Hat JBoss Web Server (JWS).

Ansible version compatibility

Red Hat supports the most recent version of redhat.jws collection on Ansible Automation Platform 2.5 / ansible-core 2.16.

Content included in this collection

Roles

• The jws role contains the Ansible playbook and handles the following automated tasks:
  • Ensures that a Java Development Kit (JDK) is installed on your target hosts
  • Installs the basic packages that a JBoss Web Server installation requires
  • Creates a JBoss Web Server user account and group
  • Installs JBoss Web Server from product archive files or RPM packages
  • Assigns ownership of the JBoss Web Server directories to the appropriate user account and group
  • Deploys the server.xml, web.xml, and context.xml files
• The jws_validation role contains a set of utility playbooks and tasks to validate that the server was properly installed on the target and is functionnal.

Collection setup

For demonstration purposes, you can run the collection directly from this folder. However, the proper setup is to download and install the collection from the Red Hat Automation Hub.

Before you install the collection, you must ensure that your system complies with the following prerequisites: - You have installed the ansible-core package version 2.14 or later on a control node in your system by installing Red Hat Ansible Automation Platform 2.x. - You have updated the ansible.cfg file to use the Red Hat Automation Hub as your primary source of Ansible collections. You can install the collection on your Ansible control node by using the following command: $ ansible-galaxy collection install redhat.jws

Collection usage for installing JBoss Web Server

You can enable the collection to use any of the following installation methods when performing an automated installation of JBoss Web Server:

• Local archive files
• RPM packages
• Custom URL for downloading the archive files

Downloading from the Customer Portal

The redhat.jws.jws role supports downloading and installing from the Red Hat Customer Portal using credentials associated to a service account. After login in the customer portal and navigating to the hybrid cloud console, select the services account tab to create one, if needed. Client ID and Client secret associated to the service account needs to be provided with the following variables are defined:

rhn_username: '<client_id>'
rhn_password: '<client_secret>'

The downloaded product archive will be stored in the controller working directory, and then distributed to target nodes.

Using local archive files

To enable the collection to install JBoss Web Server from local archive files:

1. If copies of the archive files are not already on your system, download the appropriate archive files from the Red Hat Customer Portal:

   • Red Hat JBoss Web Server X.Y.0 Application Server (the application server)
   • Red Hat JBoss Web Server X.Y.0 Application Server for RHEL 8 x86_64 (the native components)

In the preceding file names, replace X.Y.0 with the JBoss Web Server version that you want to install (for example, 5.7.0 or 6.0.0).

1. Copy the archive files to your Ansible control node.

2. On your Ansible control node, set the following variables, as appropriate:

   vars:
     ...
     jws_install_method: zipfiles
     jws_version: 6.0.0
     jws_native: True
     zipfile_name: <application_server_filename>.zip
     native_zipfile: <native_filename>.zip
   

   Consider the following guidelines:

Note: If you did not change the archive file names, you do not need to set the zipfile_name and native_zipfile variables. The collection uses the JBoss Web Server version to determine the default file names automatically.

1. If you also want to install the latest cumulative patches for the appropriate JBoss Web Server version, copy the archive files for the latest patch updates to your Ansible control node. Then set the jws_apply_patches variable to True:

   vars:
     ...
     jws_apply_patches: True
   

Note: Even when local file are present on the controller, the role tries to contact the download server to verify is new cumulative patches are available. To completely turn off any remote access, set the parameter jws_offline_install: True

Using RPM packages

If you want the collection to install JBoss Web Server from RPM packages, you must first ensure that your system complies with the following prerequisites:

• Your system is compliant with Red Hat Enterprise Linux package requirements.

• You have attached subscriptions to Red Hat Enterprise Linux.

• You have a working internet connection that the collection can use to obtain the RPM packages from Red Hat.

Note: When you enable the RPM installation method, the collection always installs the latest available RPM packages for the latest JBoss Web Server version, including any patch updates.

To enable the collection to install JBoss Web Server from RPM packages, set the jws_install_method variable to rpm on your Ansible control node:

vars:
  ...
  jws_install_method: rpm

Note: By default, the collection installs JBoss Web Server in the /opt/rh/jws6/root/usr/share/tomcat/ directory. If you want to use a different installation directory, you can manually create a symbolic link to /opt/rh/jws6/root/usr/share/tomcat/.

Using a custom URL to download the archive files

To enable the collection to download and install the JBoss Web Server archive files from a custom URL, set the following variables on your Ansible control node:

vars:
   ...
   jws_install_method: zipfiles
   zipfile_name: <archive_file_name>.zip
   zipfile_name_url: <URL_path/archive_file_name>.zip

In the preceding example, ensure that the zipfile_name and zipfile_name_url variables specify the correct archive file name and URL path, respectively.

Running the playbook

To run the playbook:

1. Set the jws_install_method variable to the appropriate installation method, as described in the preceding sections.

2. Update the inventory for your target hosts. For example:

[jws]
192.168.0.1      # Remote host to act on

1. If you want the collection to install a supported OpenJDK version on your target hosts, set the jws_java_version variable to the appropriate value (for example, 1.8.0, 11, or 17). The collection is not configured to install a JDK by default.

2. Set the jws_listen_http_port and jws_listen_https_port variables to specify which HTTP and HTTPS ports you want JBoss Web Server to listen on. The default HTTP port is 8080. The default HTTPS port is 8443.

3. Run the playbook. For more information, see Running the Playbook.

Note: If you are using a remote user account that is not the root user, set the username and enable sudo privileges:

become: True
become_method: sudo

Using the collection to configure the mod_cluster listener

The mod_cluster listener enables communication between JBoss Web Server and the mod_proxy_cluster module on the Apache HTTP Server. The mod_proxy_cluster module enables use of the Apache HTTP Server as an intelligent load-balancing solution for sending requests to JBoss Web Server. For information about configuring mod_proxy_cluster and alternative load balancers such as mod_jk and mod_proxy, see the Apache HTTP Server Connectors and Load Balancing Guide.

To enable the collection to configure the mod_cluster listener, set the following variables on your Ansible control node:

vars:
  ...
  jws_modcluster_enabled: True
  jws_modcluster_ip: <ip_address>
  jws_modcluster_port: <port>

Consider the following guidelines:

The following Molecule scenario supports the validation and testing of this feature.

Using the collection to configure the password vault for JBoss Web Server

You can use the password vault for JBoss Web Server, which is named tomcat-vault, to mask passwords and other sensitive strings, and to store sensitive information in an encrypted Java keystore. When you use the password vault, you can stop storing clear-text passwords in your JBoss Web Server configuration files. JBoss Web Server can use the password vault to search for passwords and other sensitive strings from a keystore.

Note: If you want to use the password vault feature, you must first create the required vault.keystore, VAULT.dat, and vault.properties files as a prerequisite. For more information about creating these files, see the Red Hat JBoss Web Server Installation Guide: Using a password vault with Red Hat JBoss Web Server.

To enable the collection to configure the password vault, set the following variables on your Ansible control node:

vars:
  ...
  jws_vault_name: ./vault_files/vault.keystore
  jws_vault_data: ./vault_files/VAULT.dat
  jws_vault_properties: ./vault_files/vault.properties
  jws_tomcat_vault_enabled: True
  jws_tomcat_vault_alias: <keystore_alias>
  jws_tomcat_vault_storepass: <keystore_password>
  jws_tomcat_vault_iteration: <iteration_count>
  jws_tomcat_vault_salt: <salt>

Consider the following guidelines:

Using the collection to enable HTTPS support

The collection provides a default template for the server.xml file that already includes the required configuration to use HTTPS. To enable HTTPS support, you only need to set the appropriate variables. However, the collection does not build or provide the required Java Keystore. In this situation, you must ensure that a Java keystore already exists on each target host.

Note: To automate the creation of Java keystore files, you can use other collections and modules, such as the Ansible OpenSSH Keypair collection, the Ansible Collection Community Crypto and the Java Keystore module. For more information about automating the creation of a Java keystore, refer to the available documentation for these collections or modules.

To enable the collection to configure HTTPS support, set the following variables on your Ansible control node, as appropriate:

vars:
  ...
  jws_listen_https_enabled: True
  jws_listen_https_port: <port>
  jws_listen_https_bind_address: <ip_address>
  jws_listen_https_keystore_file: <keystore_path>
  jws_listen_https_keystore_password: <keystore_password>

Consider the following guidelines:

Refer to the Apache Tomcat documentation for more information about setting up and configuring HTTPS support.

The following Molecule scenario supports the validation and testing of this feature.

Using the collection to override the default template for server.xml

The collection provides a default server.xml.j2 template that covers the most basic server configuration only. To ensure a more fine-tuned configuration that suits your requirements, you can override the default template with your own customized template.

To override the default template, set the following variable on your Ansible control node:

vars:
  ...
  jws_conf_templates_server: <path_to_custom_template>.j2

The following Molecule scenario supports the validation and testing of this feature.

Using the collection to deploy web applications

Ansible provides various modules and features to facilitate the deployment of web applications on your target hosts.

For example:

• To deploy an application by downloading the .war file from a repository, use the get_url: module:

  - name: Download App
    get_url:
      url: https://repo1.maven.org/maven2/org/jolokia/jolokia-war/1.7.1/jolokia-war-1.7.1.war
      dest: "{{ jws_home }}/tomcat/webapps/"
  

• To deploy an application by copying the .war file from your control node to the target host, use the copy: module:

  - ansible.builtin.copy:
     src: files/jolokia-war-1.7.1.war
     dest: "{{ jws_home }}/tomcat/webapps/"
  

• To deploy an application when the .war file already exists on the target host, use the copy: module with the remote_src parameter:

  - ansible.builtin.copy:
     src: files/jolokia-war-1.7.1.war
     dest: "{{ jws_home }}/tomcat/webapps/"
     remote_src: True
  

• To deploy an application by using a symbolic link or hard link to the .war file, which avoids duplicating the file, use the file: module:

  - ansible.builtin.file:
      src: /apps/jolokia-war-1.7.1.war
      dest: "{{ jws_home }}/tomcat/webapps/jolokia-war-1.7.1.war"
      state: link
  

Running the playbook

After you define the appropriate variables and settings, you can run the playbook on your Ansible control node to begin the automated installation process. Ansible supports various ways to run the playbook.

For example:

• To run the playbook as the root user with a secure shell (SSH) key:

  $ ansible-playbook -i hosts playbooks/playbook.yml

• To run the playbook as the root user with a password:

  $ ansible-playbook -i hosts playbooks/playbook.yml --ask-pass

• To run the playbook as a user with sudo privileges and a password:

  $ ansible-playbook -i hosts playbooks/playbook.yml --ask-pass --ask-become-pass

• To run the playbook as a user with sudo privileges, an SSH key, and a sudo password:

  $ ansible-playbook -i hosts playbooks/playbook.yml --ask-become-pass

• To run the playbook as a user with sudo privileges and an SSH key but without a sudo password:

  $ ansible-playbook -i hosts playbooks/playbook.yml --ask-become-pass

Ensure that the playbook runs successfully without any errors.

Support

The redhat.jws collection v2.1.1 is released as the Red Hat Ansible certified content collection for JBoss Web Server with Production Support. If you have any issues or questions related to this collection, please contact support at Red Hat Customer Experience & Engagement. Alternatively contact the community by opening an issue at https://github.com/ansible-middleware/jws/issues.

For more information about using this collection, see Installing JBoss Web Server by using the Red Hat Ansible Certified Content Collection.

License

Apache License v2.0 or later

See LICENSE to view the full text.