Chapter 5. xPaaS Middleware Images
5.1. Overview
This topic group includes information on the different xPaaS middleware images available for OpenShift users.
5.2. Red Hat JBoss Enterprise Application Platform (JBoss EAP) xPaaS Image
5.2.1. Overview
Red Hat JBoss Enterprise Application Platform (JBoss EAP) is available as a containerized xPaaS image that is designed for use with OpenShift. Developers can quickly build, scale, and test applications deployed across hybrid environments.
There are significant differences in supported configurations and functionality in the JBoss EAP xPaaS image compared to the regular release of JBoss EAP.
This topic details the differences between the JBoss EAP xPaaS image and the regular release of JBoss EAP, and provides instructions specific to running and configuring the JBoss EAP xPaaS image. Documentation for other JBoss EAP functionality not specific to the JBoss EAP xPaaS image can be found in the JBoss EAP documentation on the Red Hat Customer Portal.
EAP_HOME in this documentation, as in the JBoss EAP documentation, is used refer to the JBoss EAP installation directory. The location of EAP_HOME inside a JBoss EAP xPaaS image is /opt/eap/, which the JBOSS_HOME environment variable is set to by default.
5.2.2. Comparing the JBoss EAP xPaaS Image to the Regular Release of JBoss EAP
5.2.2.1. Functionality Differences for OpenShift JBoss EAP xPaaS Images
There are several major functionality differences in the OpenShift JBoss EAP xPaaS image:
- The JBoss EAP Management Console is not available to manage OpenShift JBoss EAP xPaaS images.
- The JBoss EAP Management CLI is only bound locally. This means that you can only access the Management CLI of a container from within the pod.
- Domain mode is not supported. OpenShift controls the creation and distribution of applications in the containers.
- The default root page is disabled. You may want to deploy your own application to the root context (as ROOT.war).
- A-MQ is supported for inter-pod and remote messaging. HornetQ is only supported for intra-Pod messaging and only enabled in the absence of A-MQ.
5.2.2.2. Managing OpenShift JBoss EAP xPaaS Images
A major difference in managing an OpenShift JBoss EAP xPaaS image is that there is no Management Console exposed for the JBoss EAP installation inside the image. Because images are intended to be immutable, with modifications being written to a non-persistent file system, the Management Console is not exposed.
However, the JBoss EAP Management CLI (EAP_HOME/bin/jboss-cli.sh) is still accessible from within the container for troubleshooting purposes. First open a remote shell session to the running pod:
$ oc rsh <pod_name>
Then run the following from the remote shell session to launch the JBoss EAP Management CLI:
$ /opt/eap/bin/jboss-cli.sh
Any configuration changes made using the JBoss EAP Management CLI on a running container will be lost when the container restarts.
Making configuration changes to the JBoss EAP instance inside the JBoss EAP xPaaS image is different from the process you may be used to for a regular release of JBoss EAP.
5.2.2.3. Unsupported Configurations
The following is a list of unsupported configurations specific to the JBoss EAP xPaaS image:
- Using MySQL in a scaled environment with XA distributed transactions is not recommended. For applications that support both scaling and XA distributed transactions, PostgreSQL is recommended instead.
5.2.3. Installing the JBoss EAP xPaaS Image Streams and Application Templates
To use the Red Hat xPaaS middleware images in your OpenShift project, you must first install the image streams and Source-to-Image (S2I) application templates.
5.2.4. Running and Configuring the JBoss EAP xPaaS Image
You can make changes to the JBoss EAP configuration in the xPaaS image using either the S2I templates, or by using a modified JBoss EAP xPaaS image.
5.2.4.1. Using the JBoss EAP xPaaS Image Source-to-Image (S2I) Process
The recommended method to run and configure the OpenShift JBoss EAP xPaaS image is to use the OpenShift S2I process together with the application template parameters and environment variables.
The S2I process for the JBoss EAP xPaaS image works as follows:
If there is a pom.xml file in the source repository, a Maven build is triggered with the contents of
$MAVEN_ARGSenvironment variable.By default the
packagegoal is used with theopenshiftprofile, including the system properties for skipping tests (-DskipTests) and enabling the Red Hat GA repository (-Dcom.redhat.xpaas.repo.redhatga).The results of a successful Maven build are copied to EAP_HOME/standalone/deployments. This includes all JAR, WAR, and EAR files from the directory within the source repository specified by
$ARTIFACT_DIRenvironment variable. The default value of$ARTIFACT_DIRis the target directory.- Any JAR, WAR, and EAR in the deployments source repository directory are copied to the EAP_HOME/standalone/deployments directory.
All files in the configuration source repository directory are copied to EAP_HOME/standalone/configuration.
NoteIf you want to use a custom JBoss EAP configuration file, it should be named standalone-openshift.xml.
- All files in the modules source repository directory are copied to EAP_HOME/modules.
5.2.4.1.1. Using a Different JDK Version in the JBoss EAP xPaaS Image
The JBoss EAP xPaaS image may come with multiple versions of OpenJDK installed, but only one is the default. For example, the JBoss EAP 6.4 xPaaS image comes with OpenJDK 1.7 and 1.8 installed, but OpenJDK 1.8 is the default.
If you want the JBoss EAP xPaaS image to use a different JDK version than the default, you must:
- Ensure that your pom.xml specifies to build your code using the intended JDK version.
In the S2I application template, configure the image’s
JAVA_HOMEenvironment variable to point to the intended JDK version. For example:{ "name": "JAVA_HOME", "value": "/usr/lib/jvm/java-1.7.0" }
5.2.4.2. Using a Modified JBoss EAP xPaaS Image
An alternative method is to make changes to the image, and then use that modified image in OpenShift.
The JBoss EAP configuration file that OpenShift uses inside the JBoss EAP xPaaS image is EAP_HOME/standalone/configuration/standalone-openshift.xml, and the JBoss EAP startup script is EAP_HOME/bin/openshift-launch.sh.
You can run the JBoss EAP xPaaS image in Docker, make the required configuration changes using the JBoss EAP Management CLI (EAP_HOME/bin/jboss-cli.sh), and then commit the changed container as a new image. You can then use that modified image in OpenShift.
It is recommended that you do not replace the OpenShift placeholders in the JBoss EAP xPaaS configuration file, as they are used to automatically configure services (such as messaging, datastores, HTTPS) during a container’s deployment. These configuration values are intended to be set using environment variables.
Ensure that you follow the guidelines for creating images.
5.2.5. Troubleshooting
In addition to viewing the OpenShift logs, you can troubleshoot a running JBoss EAP container by viewing the JBoss EAP logs that are outputted to the container’s console:
$ oc logs -f <pod_name> <container_name>
By default, the OpenShift JBoss EAP xPaaS image does not have a file log handler configured. Logs are only sent to the console.
5.3. Red Hat JBoss A-MQ xPaaS Image
5.3.1. Overview
Red Hat JBoss A-MQ (JBoss A-MQ) is available as a containerized xPaaS image that is designed for use with OpenShift. It allows developers to quickly deploy an A-MQ message broker in a hybrid cloud environment.
There are significant differences in supported configurations and functionality in the JBoss A-MQ image compared to the regular release of JBoss A-MQ.
This topic details the differences between the JBoss A-MQ xPaaS image and the regular release of JBoss A-MQ, and provides instructions specific to running and configuring the JBoss A-MQ xPaaS image. Documentation for other JBoss A-MQ functionality not specific to the JBoss A-MQ xPaaS image can be found in the JBoss A-MQ documentation on the Red Hat Customer Portal.
5.3.2. Differences Between the JBoss A-MQ xPaaS Image and the Regular Release of JBoss A-MQ
There are several major functionality differences in the OpenShift JBoss A-MQ xPaaS image:
- The Karaf shell is not available.
- The Fuse Management Console (Hawtio) is not available.
Configuration of the broker can be performed:
- using parameters specified in the A-MQ application template, as described in Application Template Parameters.
- using the S2I (Source-to-image) tool, as described in Configuration Using S2I.
5.3.3. Installing the JBoss A-MQ xPaaS Image Streams and Application Templates
To use the Red Hat xPaaS middleware images in your OpenShift project, you must first install the image streams and Source-to-Image (S2I) application templates.
5.3.4. Configuring the JBoss A-MQ Image
5.3.4.1. Application Template Parameters
Basic configuration of the JBoss A-MQ xPaaS image is performed by specifying values of application template parameters. The following parameters can be configured:
AMQ_RELEASE- The JBoss A-MQ release version. This determines which JBoss A-MQ image will be used as a basis for the application. At the moment, only version 6.2 is available.
APPLICATION_NAME- The name of the application used internally in OpenShift. It is used in names of services, pods, and other objects within the application.
MQ_USERNAME- The user name used for authentication to the broker. In a standard non-containerized JBoss A-MQ, you would specify the user name in the AMQ_HOME/opt/user.properties file. If no value is specified, a random user name is generated.
MQ_PASSWORD- The password used for authentication to the broker. In a standard non-containerized JBoss A-MQ, you would specify the password in the AMQ_HOME/opt/user.properties file. If no value is specified, a random password is generated.
AMQ_ADMIN_USERNAME- The user name used as an admin authentication to the broker. If no value is specified, a random user name is generated.
AMQ_ADMIN_PASSWORD- The password used for authentication to the broker. If no value is specified, a random password is generated.
MQ_PROTOCOL- Comma-separated list of the messaging protocols used by the broker. Available options are amqp, mqtt, openwire, and stomp. If left empty, all available protocols will be available. Please note that for integration of the image with Red Hat JBoss Enterprise Application Platform, the openwire protocol must be specified, while other protocols can be optionally specified as well.
MQ_QUEUES- Comma-separated list of queues available by default on the broker on its startup.
MQ_TOPICS- Comma-separated list of topics available by default on the broker on its startup.
AMQ_SECRET- The name of a secret containing SSL related files. If no value is specified, a random password is generated.
AMQ_TRUSTSTORE- The SSL trust store filename. If no value is specified, a random password is generated.
AMQ_KEYSTORE- The SSL key store filename. If no value is specified, a random password is generated.
5.3.4.2. Configuration Using S2I
Configuration of the JBoss A-MQ image can also be modified using the Source-to-image feature, described in full detail at S2I Requirements.
Custom A-MQ broker configuration can be specified by creating an openshift-activemq.xml file inside the git directory of your application’s Git project root. On each commit, the file will be copied to the conf directory in the A-MQ root and its contents used to configure the broker.
5.3.5. Configuring the JBoss A-MQ Persistent Image
5.3.5.1. Application Template Parameters
Basic configuration of the JBoss A-MQ Persistent xPaaS image is performed by specifying values of application template parameters. The following parameters can be configured:
AMQ_RELEASE- The JBoss A-MQ release version. This determines which JBoss A-MQ image will be used as a basis for the application. At the moment, only version 6.2 is available.
APPLICATION_NAME- The name of the application used internally in OpenShift. It is used in names of services, pods, and other objects within the application.
MQ_PROTOCOL- Comma-separated list of the messaging protocols used by the broker. Available options are amqp, mqtt, openwire, and stomp. If left empty, all available protocols will be available. Please note that for integration of the image with Red Hat JBoss Enterprise Application Platform, the openwire protocol must be specified, while other protocols can be optionally specified as well.
MQ_QUEUES- Comma-separated list of queues available by default on the broker on its startup.
MQ_TOPICS- Comma-separated list of topics available by default on the broker on its startup.
VOLUME_CAPACITY- The size of the persistent storage for database volumes.
MQ_USERNAME- The user name used for authentication to the broker. In a standard non-containerized JBoss A-MQ, you would specify the user name in the AMQ_HOME/opt/user.properties file. If no value is specified, a random user name is generated.
MQ_PASSWORD- The password used for authentication to the broker. In a standard non-containerized JBoss A-MQ, you would specify the password in the AMQ_HOME/opt/user.properties file. If no value is specified, a random password is generated.
AMQ_ADMIN_USERNAME- The user name used as an admin authentication to the broker. If no value is specified, a random user name is generated.
AMQ_ADMIN_PASSWORD- The password used for authentication to the broker. If no value is specified, a random password is generated.
AMQ_SECRET- The name of a secret containing SSL related files. If no value is specified, a random password is generated.
AMQ_TRUSTSTORE- The SSL trust store filename. If no value is specified, a random password is generated.
AMQ_KEYSTORE- The SSL key store filename. If no value is specified, a random password is generated.
For more information, see Using Persistent Volumes.
5.3.6. Security
Only SSL connections can connect from outside of the OpenShift instance, regardless of the protocol specified in the MQ_PROTOCOL property of the A-MQ application templates. The non-SSL version of the protocols can only be used inside the OpenShift instance.
For security reasons, using the default KeyStore and TrustStore generated by the system is discouraged. It is recommended to generate your own KeyStore and TrustStore and supply them to the image using the OpenShift secrets mechanism or S2I.
5.3.7. High-Availability and Scalability
The JBoss xPaaS A-MQ image is supported in two modes:
- A single A-MQ pod mapped to a Persistent Volume for message persistence. This mode provides message High Availability and guaranteed messaging but does not provide scalability.
- Multiple A-MQ pods using local message persistence (i.e. no mapped Persistent Volume). This mode provides scalability but does not provide message High Availability or guaranteed messaging.
5.3.8. Logging
In addition to viewing the OpenShift logs, you can troubleshoot a running JBoss A-MQ image by viewing the JBoss A-MQ logs that are outputted to the container’s console:
$ oc logs -f <pod_name> <container_name>
By default, the OpenShift JBoss A-MQ xPaaS image does not have a file log handler configured. Logs are only sent to the console.
5.4. Red Hat JBoss Web Server xPaaS Images
5.4.1. Overview
The Apache Tomcat 7 and Apache Tomcat 8 components of Red Hat JBoss Web Server 3 are available as containerized xPaaS images that are designed for use with OpenShift. Developers can use these images to quickly build, scale, and test Java web applications deployed across hybrid environments.
There are significant differences in the functionality between the JBoss Web Server xPaaS images and the regular release of JBoss Web Server.
This topic details the differences between the JBoss Web Server xPaaS images and the regular release of JBoss Web Server, and provides instructions specific to running and configuring the JBoss Web Server xPaaS images. Documentation for other JBoss Web Server functionality not specific to the JBoss Web Server xPaaS images can be found in the JBoss Web Server documentation on the Red Hat Customer Portal.
The location of JWS_HOME/tomcat<version>/ inside a JBoss Web Server xPaaS image is: /opt/webserver/.
5.4.2. Functionality Differences in the OpenShift JBoss Web Server xPaaS Images
A major functionality difference compared to the regular release of JBoss Web Server is that there is no Apache HTTP Server in the OpenShift JBoss Web Server xPaaS images. All load balancing in OpenShift is handled by the OpenShift router, so there is no need for a load-balancing Apache HTTP Server with mod_cluster or mod_jk connectors.
5.4.3. Installing the JBoss Web Server xPaaS Image Streams and Application Templates
To use the Red Hat xPaaS middleware images in your OpenShift project, you must first install the image streams and Source-to-Image (S2I) application templates.
The JBoss Web Server xPaaS application templates are distributed as two sets: one set for Tomcat 7, and another for Tomcat 8.
5.4.4. Using the JBoss Web Server xPaaS Image Source-to-Image (S2I) Process
To run and configure the OpenShift JBoss Web Server xPaaS images, use the OpenShift S2I process with the application template parameters and environment variables.
The S2I process for the JBoss Web Server xPaaS images works as follows:
If there is a pom.xml file in the source repository, a Maven build is triggered with the contents of
$MAVEN_ARGSenvironment variable.By default the
packagegoal is used with theopenshiftprofile, including the system properties for skipping tests (-DskipTests) and enabling the Red Hat GA repository (-Dcom.redhat.xpaas.repo.redhatga).The results of a successful Maven build are copied to /opt/webserver/webapps. This includes all WAR files from the source repository directory specified by the
$ARTIFACT_DIRenvironment variable. The default value of$ARTIFACT_DIRis the target directory.- All WAR files from the deployment source repository directory are copied to /opt/webserver/webapps.
All files in the configuration source repository directory are copied to /opt/webserver/conf.
NoteIf you want to use custom Tomcat configuration files, the file names should be the same as for a normal Tomcat installation. For example, context.xml and server.xml.
5.4.5. Troubleshooting
In addition to viewing the OpenShift logs, you can troubleshoot a running JBoss Web Server container by viewing the logs that are outputted to the container’s console:
$ oc logs -f <pod_name> <container_name>
Additionally, access logs are written to /opt/webserver/logs/.
