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 Images

Overview

Red Hat offers a containerized xPaaS image for the Red Hat JBoss Enterprise Application Platform (JBoss EAP) that is designed for use with OpenShift. Using this image, developers can quickly and easily build, scale, and test applications deployed across hybrid environments.

Comparing the Product and Image

The xPaas JBoss EAP images differ from the JBoss EAP product in several ways:

  1. The image does not include the JBoss EAP Management Console used to manage xPaaS JBoss EAP images.

  2. The JBoss EAP Management CLI is included in the xPaaS JBoss EAP image, but can only access the Management CLI of a container from within the pod.

  3. Domain mode is not supported in the xPaaS JBoss EAP image. Instead, OpenShift manages the creation and distribution of applications in the containers.

  4. The image’s default root page is disabled. Deploy your own application to the root context as ROOT.war.

  5. The EAP 6.4 image supports A-MQ for inter-pod and remote messaging. HornetQ is only supported for intra-pod messaging and only enabled when A-MQ is absent. The EAP 7 Beta image includes Artemis as a replacement for HornetQ.

For further information about JBoss EAP functionality and features independent from the JBoss EAP image, see the JBoss EAP documentation on the Red Hat Customer Portal.

Comparing the xPaaS JBoss EAP 6.4 and 7.0 Beta Images

Red Hat offers two xPaaS EAP images for use with OpenShift. The first is based on JBoss EAP 6.4 and the second is based on JBoss EAP 7 Beta. There are several differences between the two images:

JBoss Web is replaced by Undertow

  • The xPaaS JBoss EAP 6.4 image uses JBoss Web.

  • The xPaas JBoss EAP 7 Beta image uses Undertow instead of JBoss Web. This change only affects users implementing custom JBoss Web Valves in their applications. Affected users must refer to the Red Hat JBoss EAP 7 Beta documentation for details about migrating JBoss EAP Web Valve handlers.

HornetQ is replaced by Artemis

  • The EAP 6.4 image only uses HornetQ for intra-pod messaging when A-MQ is absent.

  • The EAP 7 Beta image uses Artemis instead of HornetQ. This change resulted in renaming the HORNETQ_QUEUES and HORNETQ_TOPICS environment variables to MQ_QUEUES and MQ_TOPICS respectively. For complete instructions to deal with migrating applications from JBoss EAP 6.4 to 7 Beta, see the JBoss EAP 7 Beta Migration Guide.

Compatibility with xPaaS JBoss EAP

See the xPaaS section of the OpenShift and Atomic Platform Tested Integrations page for details about OpenShift EAP image version compatibility.

Setting Up the xPaaS JBoss EAP Image

The following is a list of prerequisites for using the xPaaS JBoss EAP images:

  1. Acquire Red Hat Subscriptions - Ensure that you have the relevant subscriptions for OpenShift as well as a subscription for xPaaS Middleware.

  2. Install OpenShift - Before using the xPaaS JBoss EAP images, you must have an OpenShift environment installed and configured:

    1. The Quick Installation method allows you to install OpenShift using an interactive CLI utility.

    2. The Advanced Installation method allows you to install OpenShift using a reference configuration. This method is best suited for production environments.

  3. Install and Deploy Docker Registry - Install the Docker Registry and then ensure that the Docker Registry is deployed to locally manage images as follows:

    $ oadm registry --config=/etc/origin/master/admin.kubeconfig --credentials=/etc/origin/master/openshift-registry.kubeconfig

    For further information, see Deploying a Docker Registry

  4. Deploy a Router - Use the instructions at the Deploying a Router page for this step.

  5. Privileges - Ensure that you can run the oc create command with cluster-admin privileges.

  6. Create Image Streams - Image streams are configured during the Quick or Advanced OpenShift Installation. If required, manually create the image streams for both versions of the xPaaS JBoss EAP image as follows:

    $ oc create -f /usr/share/ansible/openshift-ansible/roles/openshift_examples/files/examples/v1.1/xpaas-streams/jboss-image-streams.json -n openshift

    For further information about creating image streams, see Loading the Default Image Streams and Templates

  7. Create Instant App Templates - Instant App templates define a full set of objects for running applications and are configured during the Quick or Advanced OpenShift Installation. If required, create Instant App templates as follows:

    1. Create the core Instant App templates:

      $ oc create -f \ openshift-ansible/roles/openshift_examples/files/examples/quickstart-templates -n openshift

    2. Register Instant App templates for xPaaS Middleware products:

      $ oc create -f \ openshift-ansible/roles/openshift_examples/files/examples/xPaaS-templates -n openshift

Modifying the JDK Used by the xPaaS JBoss EAP Image

The xPaaS JBoss EAP 6.4 image includes OpenJDK 1.7 and 1.8, with OpenJDK 1.8 as the default. The xPaaS JBoss EAP 7 Beta image only includes and supports OpenJDK 1.8.

To change the JDK version used by the xPaaS JBoss EAP 6.4 image:

  1. Ensure that the pom.xml file specifies that the code must be built using the intended JDK version.

  2. In the S2I application template, configure the image’s JAVA_HOME environment variable to point to the intended JDK version. For example:

    Example 1. Setting the JDK version

    Change the defined value to point to the required version of the JDK.

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

Getting Started Using xPaaS JBoss EAP Images

Configuring the xPaaS JBoss EAP Images

You can change the configuration for the xPaaS JBoss EAP images by either using the S2I (Source to Image) templates, or by using a modified xPaaS JBoss EAP image. Red Hat recommends using the S2I method to configure the xPaaS JBoss EAP image.

Configuring the xPaaS JBoss EAP Image using the S2I Templates

The recommended method to run and configure the xPaaS JBoss EAP image is to use the OpenShift S2I process together with the application template parameters and environment variables.

The variable EAP_HOME is used to denote the path to the JBoss EAP installation. Replace this variable with the actual path to your JBoss EAP installation.

The S2I process for the xPaaS JBoss EAP image works as follows:

  1. If a pom.xml file is present in the source repository, a Maven build using the contents of the $MAVEN_ARGS environment variable is triggered. By default, the OpenShift profile uses the Maven package goal which includes 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 source repository specified by the $ARTIFACT_DIR environment variable. The default value of $ARTIFACT_DIR is the target directory.

  2. Any JAR, WAR, and EAR in the deployment’s 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 Modified xPaaS JBoss EAP Image

You can make changes to an image or create a custom image to use in OpenShift.

The JBoss EAP configuration file used by OpenShift in the xPaaS JBoss EAP image is EAP_HOME/standalone/configuration/standalone-openshift.xml. The script to start JBoss EAP is EAP_HOME/bin/openshift-launch.sh.

Ensure that you have read the guidelines for creating images and follow them when creating a modified image.

To use a modified image in OpenShift:

This procedure results in losing configuration placeholders for various settings such as datasources, messaging, HTTPS, KeyCloak, etc. A workaround for this issue is to create a duplicate copy of the standalone.xml file to edit. The original and edited versions can be compared after all edits are complete and placeholder values can be copied to the edited version from the original version to retain these values.

  1. Run the xPaaS JBoss EAP image using Docker.

  2. Make the required changes using the JBoss EAP Management CLI by running the script at EAP_HOME/bin/jboss-cli.sh.

  3. Commit the changed container as a new image and then use the modified image in OpenShift.

Troubleshooting

If an application is not starting, use the following command to view details to locate and troubleshoot the problem:

$ oc describe po <pod_name>

To troubleshoot running xPaaS JBoss EAP containers, you can either view the OpenShift logs, or view the JBoss EAP logs displayed to the container’s console. Use the following command to view the JBoss EAP logs:

$ oc logs -f <pod_name> <container_name>

By default, the xPaaS JBoss EAP image does not have a file log handler configured. Logs are therefore only sent to the console.