JBoss EAP 7 thin image

Solution Verified - Updated

Environment

  • Red Hat JBoss Enterprise Application Platform (EAP)
    • 7.x
    • EAP 7 image
  • Red hat OpenShift Container Platform (OCP)
    • 4.x

Issue

  • Why does JBoss image comes without many essential jars for production?
  • JDBC Jars absent in JBoss EAP 7 image absent

Resolution

Runtime image: The absence of the jars in the default EAP 7 image runtime is expected. This means EAP 7 image is a thin server, the jars are retrieved by the JBoss Modules runtime at startup from a local maven cache.

Builder image: it already contains all the EAP 7 jars. The build will trim those subsystems already there, i.e. use the local cache to provision a trimmed server. The jars won't be downloaded again from maven, instead will be cached already on the builder image.

A complete overview - and comparison - of the deployment methods for EAP 7/8 in Openshift 4 can be found in Comparing JBoss EAP 7 deployment methods in Openshift 4.

Provisioning EAP with layers:

One should use Galleon to provision an image with the relevant application's source and subsystem layers.
Provisioning is more than copying the jar from the builder image, it consists of generating a server configuration, not only jars. With provisioning, one has control over the dependencies between modules, and the relationship between the server config and the JBoss Modules modules.
To provision a custom server with trimmed capabilities, there are a few options such as:

  • pass the GALLEON_PROVISION_LAYERS environment variable during the S2I build phase. And use GALLEON_PROVISION_FEATURE_PACKS to feat more packages inside of the base or decoration layers via environment variables, as described here.
  • Use a provisioning.xml file in the project's source, which contains feature packs and layers in the project, as described here.
  • For bootable jar, the layers are added below feature packs

Example Using Data source via GALLEON_PROVISION_LAYERS env variable :

Task: Deploy the project helloworld-html5 which is located in github's jboss-eap-quickstarts, with datasource, jaxrs, jpa, and sso subsystem.
Solution Using EAP Provisioning laywers, adding base layer (jaxrs-server) or decorator layers ,web-clustering, sso):

oc new-app --template=eap74-basic-s2i -p IMAGE_STREAM_NAMESPACE=eap-galleon -p EAP_IMAGE_NAME=jboss-eap74-openjdk11-openshift:7.4.0 \
 -p EAP_RUNTIME_IMAGE_NAME=jboss-eap74-openjdk11-runtime-openshift:7.4.0 \
 -p SOURCE_REPOSITORY_URL=https://github.com/jboss-developer/jboss-eap-quickstarts \
 -p SOURCE_REPOSITORY_REF=7.4.x \
 -p GALLEON_PROVISION_LAYERS=jaxrs-server,web-clustering,sso \ <-- base layer jaxrs-server and decorator layers: sso and web-clustering for infinispan
 -p CONTEXT_DIR=helloworld-html5

Even if the project has a provisioning.xml - it will be ignored since GALLEON_PROVISION_LAYERS is being used.

Galleon provisioning layers

For datasource jars (i.e. data source subsystems) one can use Galleon during S2I setting GALLEON_PROVISION_LAYERS=jaxrs-server, which will bring the jars to the new provisioned image for jaxrs (see what it brings on the table below):

LayersType of LayerImport subsystems
ejblayerEjb3 subsystem
jsflayerJSF subsystem
datasources-web-serverBase layercore-management datasources deployment-scanner ee elytron io jca jmx logging naming request-controller security-manager transactions undertow
jaxrs-serverBase layerdatasources-web-server + jaxrs, weld, jpa
cloud-serverBase layerjaxrs-server + resource-adapters, messaging-activemq
ssoDecorator layerRHSSO integration
observabilityDecorator layerMicroprofiles
web-clusteringDecorator layerInfinispan-based web session

Note: do not add space between the layers, the parser won't accept it and the build will fail.

Custom Modules

To create a custom module, see solution Creating a custom module in EAP 7's OCP image

EAP XP

JBoss EAP XP has its own specific image and can be used as bootable jar;

Deploying an application on the Image

The following options can be done to deploy an application in EAP image:

MethodUsage
S2I MethodUse Source to image via JBoss EAP templates
Binary BuildUse a binary build to embeed the image with a JAR/WAR/WAR artifact
DockerfileUse a dockerfile to add the application directly to deployments

Galleon usage Limitations

Galleon provides a series of features that can be used with EAP 7, however some of those features are not supported. For example setting parameters via Galleon feature syntax for the sso subsystem via provisioning.xml. See solution JBoss EAP 7 Galleon using provisioning.xml for more information. EAP 7 template images have the environment variable GALLEON_PROVISION_DEFAULT_FAT_SERVER true by default, which is used for the chain build, where the server is copied to the runtime image. See below:

  • FAT means that the jars are in the modules directory
  • NOT FAT means the jars are loaded from the Maven cache

EAP 7 can be FAT or not. EAP 8 is always FAT. So this option was removed in EAP 8. For more details on template deployment see How do I deploy jboss-eap-7/eap-74-openjdk8-openshift-rhel8 image on OpenShift? - not that the template is an argument on the S2I BuildConfig process and will result in a series of arguments being added, such as clustering, tx, and Java arguments.

Adding EJB subsystem

To add ejb subsystem:

oc new-app --template=eap74-basic-s2i -p IMAGE_STREAM_NAMESPACE=eap-galleon -p EAP_IMAGE_NAME=jboss-eap74-openjdk11-openshift:7.4.0 \
...
 -p GALLEON_PROVISION_LAYERS=ejb \ <-- ejb subsystem
...

Output:

$ cat /opt/eap/standalone/configuration/standalone-openshift.xml  | grep ejb
        <extension module="org.jboss.as.ejb3"/>
        <subsystem xmlns="urn:jboss:domain:ejb3:9.0">
                <resource-adapter-ref resource-adapter-name="${ejb.resource-adapter-name:activemq-ra.rar}"/>
                <passivation-store name="infinispan" cache-container="ejb" max-size="10000"/>
...

Java arguments

The arguments JAVA_TOOL_OPTIONS are discouraged, especially for java agents, and instead JAVA_OPTS and JAVA_OPTS_APPEND should be used instead. This will avoid overwriting of parameters on startup that guarantee the execution of custom scripts for instance. See EAP for Openshift - 3.2. CONFIGURING JBOSS EAP FOR OPENSHIFT USING ENVIRONMENT VARIABLES 3.2.1.4. JVM Environment Variables
Finally, JAVA_DIAGNOSTICS can be an option for enabling some diagnostics options, as described on Getting Started with JBoss EAP for OpenShift Container Platform - 4.2. Configuring JBoss EAP for OpenShift Using Environment Variables:

ImageJDK
EAP based on OpenJDK 8-XX:NativeMemoryTracking=summary -XX:+PrintGC -XX:+PrintGCDateStamps -XX:+PrintGCTimeStamps -XX:+UnlockDiagnosticVMOptions
EAP based on OpenJDK 11-Xlog:gc:utctime -XX:NativeMemoryTracking=summary

Root Cause

Verify brief summary:

  • EAP 7 builder image contains a server
  • EAP 7 runtime image does not contain any EAP 7 server

The absence of the jars in the default EAP 7 image is expected because EAP 7 is a thin client image.
To find which subsystems are included on each galleon layer, see EAP 7.4 OCP deployment.
Template deployment is an argument on the S2I deployment that adds arguments for the buildconfig and runtime result image, and for options see: JBoss EAP S2I build template options.

Jars from M2 repository

The installed server is a thin server, no jar are installed under the modules dir, they are loaded from the m2 repository.
JBoss Modules does a resolution of artifacts n the m2 repository and load the jars
This means the jar will be used from the m2 local repository on the image: $GALLEON_LOCAL_MAVEN_REPO (usually
/opt/jboss/container/wildfly/s2i/galleon/galleon-m2-repository).
This matters for jar replacements on EAP 7 images, see solution Replacement of of EAP 7 image jars.

Deployment methods

A complete overview - and comparison - of the deployment methods for EAP 7/8 in Openshift 4 can be found in Comparing JBoss EAP 7 deployment methods in Openshift 4.

Clustering capabilities

Also clustering capabilities is set by default - meaning the pods will naturally form a cluster when deployed on the same namespace.
About EAP Source to Image: EAP 7.4 OCP - deploy EAP S2I.

This content is not included.Dockerfile for EAP 7.4.4:

ROM registry.redhat.io/ubi8/ubi:latest
USER root
# Add scripts used to configure the image
COPY modules /tmp/scripts/
...
# Environment variables
ENV \
    GALLEON_LOCAL_MAVEN_REPO="/opt/jboss/container/wildfly/s2i/galleon/galleon-m2-repository" \
    GALLEON_MAVEN_BUILD_IMG_SETTINGS_XML="/opt/jboss/container/wildfly/s2i/galleon/build-image-settings.xml" \
    GALLEON_MAVEN_SETTINGS_XML="/opt/jboss/container/wildfly/s2i/galleon/settings.xml" \

Diagnostic Steps

IssueSolution
Deploy applications with EAP 7 OperatorHow to deploy an application in JBoss EAP 7 in OCP 4
Custom module in EAP 7Creating a custom module in EAP 7's OCP image
Custom configuration in EAP 7What are the options to use a custom runtime EAP configurations
EAP 7 trimming using GalleonAfter installing EAP openshift trimmed with Galleon cannot find openshift-launch.sh
EAP 7 Operator service creationJBoss EAP 7 Operator creates LoadBalancer service
Template (S2I options)JBoss EAP S2I build template options
Usage of provisioning.xmlJBoss EAP 7 Galleon using provisioning.xml
CONFIG_IS_FINAL Flag settingEAP 7/8 CONFIG_IS_FINAL on Galleon Build for image building
PROVISIONING_MAVEN_PLUGIN_VERSION for EAP 8How to set Maven Plugin Version in Galleon build EAP 8
Discusses MAVEN_OPTS, MAVEN_ARGS amd MAVEN_ARGS_APPEND flagsUsing Maven parameters on Buildconfig in OCP 4
SBR
Product(s)
Components
Category
Tags

This solution is part of Red Hat’s fast-track publication program, providing a huge library of solutions that Red Hat engineers have created while supporting our customers. To give you the knowledge you need the instant it becomes available, these articles may be presented in a raw and unedited form.