OpenShift docs are moving and will soon only be available at docs.redhat.com, the home of all Red Hat product documentation. Explore the new docs experience today.
  1. Documentation
    2. history
×

Red Hat JBoss Enterprise Application Platform (JBoss EAP) xPaaS Image

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.

Comparing the JBoss EAP xPaaS Image to the Regular Release of JBoss EAP

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.

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.

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.

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.

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.

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:

  1. If there is a pom.xml file in the source repository, a Maven build is triggered with the contents of $MAVEN_ARGS environment variable.

    By default the package goal is used with the openshift profile, 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_DIR environment variable. The default value of $ARTIFACT_DIR is the target directory.

  2. Any JAR, WAR, and EAR in the deployments source repository directory are copied to the EAP_HOME/standalone/deployments directory.

  3. All files in the configuration source repository directory are copied to EAP_HOME/standalone/configuration.

    If you want to use a custom JBoss EAP configuration file, it should be named standalone-openshift.xml.

  4. All files in the modules source repository directory are copied to EAP_HOME/modules.

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_HOME environment variable to point to the intended JDK version. For example:

    {
  "name": "JAVA_HOME",
  "value": "/usr/lib/jvm/java-1.7.0"
}

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.

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.