Chapter 8. Capability trimming in JBoss EAP for OpenShift Trimming the server can reduce the security exposure of the provisioned server, or reduce the memory footprint so it is more appropriate for a microservice container. When building an image that includes JBoss EAP, you can control the JBoss EAP features and subsystems to be included in the image. You can do this by using the JBoss EAP Maven plug-in when you create a new application during the Source-to-Image (S2I) build process. For more information, see Provisioning a JBoss EAP server using the Maven plug-in . Note During the S2I build process, you can use the following environment variables instead of the JBoss EAP Maven plug-in: GALLEON_PROVISION_FEATURE_PACKS GALLEON_PROVISION_LAYERS GALLEON_PROVISION_CHANNELS 8.1. Available JBoss EAP Layers You can use base layers and decorator layers to customize provisioning for JBoss EAP servers in OpenShift or bootable JARs. Base layers provide core functionality and decorator layers enhance the base layers with additional functionality. You can use decorator layers to build S2I images in JBoss EAP for OpenShift or to build a bootable JAR. If a layer does not support S2I images, the layer description will include a note. Note Only the listed layers are supported. Layers not listed here are not supported. The following Jakarta EE specifications are not supported in any provisioning layer: Jakarta Server Faces 2.3 Jakarta Enterprise Beans 3.2 Jakarta XML Web Services 2.3 8.1.1. Base layers Each base layer includes core functionality for a typical server user case. datasources-web-server This layer includes a servlet container and the ability to configure a datasource. The following are the JBoss EAP subsystems included by default in the datasources-web-server : core-management datasources deployment-scanner ee elytron io jca jmx logging naming request-controller security-manager transactions undertow The following Jakarta EE specifications are supported in this layer: Jakarta JSON Processing 1.1 Jakarta JSON Binding 1.0 Jakarta Servlet 4.0 Jakarta Expression Language 3.0 Jakarta Server Pages 2.3 Jakarta Standard Tag Library 1.2 Jakarta Concurrency 1.1 Jakarta Annotations 1.3 Jakarta XML Binding 2.3 Jakarta Debugging Support for Other Languages 1.0 Jakarta Transactions 1.3 Jakarta Connectors 1.7 jaxrs-server This layer enhances the datasources-web-server layer with the following JBoss EAP subsystems: jaxrs weld jpa This layer also adds an Infinispan-based second-level entity with local caching to the container. The following Jakarta EE specifications are supported in this layer in addition to those supported in the datasources-web-server layer: Jakarta Contexts and Dependency Injection 2.0 Jakarta Bean Validation 2.0 Jakarta Interceptors 1.2 Jakarta RESTful Web Services 2.1 Jakarta Persistence 2.2 cloud-server This layer enhances the jaxrs-server layer with the following JBoss EAP subsystems: resource-adapters messaging-activemq (remote broker messaging, not embedded messaging) This layer also adds the following observability features to the jaxrs-server layer: Native Health Native Metrics The following Jakarta EE specification is supported in this layer in addition to those supported in the jaxrs-server layer: Jakarta Security 1.0 cloud-default-config This layer provisions a server with server configuration based on standalone-ha.xml and includes the subsystem configuration messaging-activemq . On the contrary, the modcluster and core-management subsystems configuration are not included. This is configured to be used in the cloud. Additionally, all JBoss EAP server JBoss modules will be installed. ee-core-profile-server The ee-core-profile-server layer provisions a server with the Jakarta EE 10 Core Profile. The Core Profile provides a small, lightweight profile for users that provides both core JBoss EAP server functionality and Jakarta EE APIs. The ee-core-profile-server layer is best suited for smaller runtimes such as cloud-native applications and microservices. 8.1.2. Decorator layers Decorator layers are not used alone. You can configure one or more decorator layers with a base layer to deliver additional functionality. observability This decorator layer adds the following observability features to the provisioned server: Native Health Native Metrics Note This layer is built into the cloud-server layer. You do not need to add this layer to the cloud-server layer. web-clustering This layer adds embedded Infinispan-based web session clustering to the provisioned server. 8.2. Provisioning user-developed layers in JBoss EAP In addition to provisioning layers available from Red Hat, you can provision custom layers you develop. Procedure Build a custom layer using the Galleon Maven plugin. For more information, see Preparing the Maven project . Deploy the custom layer to an accessible Maven repository. You can use custom Galleon feature-pack environment variables to customize Galleon feature-packs and layers during the S2I image build process. For more information about customizing Galleon feature-packs and layers, see Using the custom Galleon feature-pack during S2I build . Optional : Create a custom provisioning file to reference the user-defined layer and supported JBoss EAP layers and store it in your application directory. For more information about creating a custom provisioning file, see The Galleon provisioning file . Run the S2I process to provision a JBoss EAP server in OpenShift. For more information, see Using the custom Galleon feature-pack during S2I build . 8.2.1. Building and using custom Galleon layers for JBoss EAP Custom Galleon layers are packaged inside a Galleon feature-pack that is designed to run with JBoss EAP 8.0. In Openshift, you can build and use a Galleon feature-pack that contains layers to provision, for example, a MariaDB driver and data source for the JBoss EAP 8.0 server. A layer contains the content that is installed in the server. A layer can update the server XML configuration file and add content to the server installation. This section documents how to build and use a Galleon feature-pack containing layers to provision a MariaDB driver and data source for the JBoss EAP 8.0 server in OpenShift. 8.2.1.1. Preparing the Maven project Galleon feature-packs are created using Maven. This procedure includes the steps to create a new Maven project. Procedure Create a new Maven project by runing the following command: Navigate to mariadb-galleon-pack directory and update the pom.xml file to include the Red Hat Maven repository: Update the pom.xml file to add dependencies on the JBoss EAP Galleon feature-pack and the MariaDB driver: <dependencies> <dependency> <groupId>org.jboss.eap</groupId> <artifactId>wildfly-ee-galleon-pack</artifactId> <version>8.0.0.GA-redhat-00010</version> <type>zip</type> </dependency> <dependency> <groupId>org.mariadb.jdbc</groupId> <artifactId>mariadb-java-client</artifactId> <version>2.7.2</version> </dependency> </dependencies> Note <version>A.B.C-redhat-XXXXX</version> Where A.B.C is the release number and XXXXX is build number of your JBoss EAP instance. See the Red Hat Maven repository for version details about JBoss EAP releases. The release and build numbers are available for all JBoss EAP releases. https://maven.repository.redhat.com/earlyaccess/all/org/jboss/eap/wildfly-ee-galleon-pack/ . Update the pom.xml file to include the Maven plugin that is used to build the Galleon feature-pack: 8.2.1.2. Adding the feature-pack content This procedure helps you add layers to a custom Galleon feature-pack, for example, the feature-pack including the MariaDB driver and datasource layers. Prerequisites You have created a Maven project. For more details, see Preparing the Maven project . Procedure Create the directory, src/main/resources , within a custom feature-pack Maven project, for example, see Preparing the Maven project . This directory is the root directory containing the feature-pack content. Create the directory src/main/resources/modules/org/mariadb/jdbc/main . In the main directory, create a file named module.xml with the following content: <?xml version="1.0" encoding="UTF-8"?> <module name="org.mariadb.jdbc" xmlns="urn:jboss:module:1.8"> <resources> <artifact name="USD{org.mariadb.jdbc:mariadb-java-client}"/> 1 </resources> <dependencies> 2 <module name="java.se"/> <module name="jakarta.transaction.api"/> <module name="jdk.net"/> </dependencies> </module> 1 The MariaDB driver groupId and artifactId . At provisioning time, the actual driver JAR file gets installed. The version of the driver is referenced from the pom.xml file. 2 The JBoss Modules modules dependencies for the MariaDB driver. Create the directory src/main/resources/layers/standalone/ . This is the root directory of all the layers that the Galleon feature-pack is defining. Create the directory src/main/resources/layers/standalone/mariadb-driver . In the mariadb-driver directory, create the layer-spec.xml file with the following content: <?xml version="1.0" ?> <layer-spec xmlns="urn:jboss:galleon:layer-spec:1.0" name="mariadb-driver"> <feature spec="subsystem.datasources"> 1 <feature spec="subsystem.datasources.jdbc-driver"> <param name="driver-name" value="mariadb"/> <param name="jdbc-driver" value="mariadb"/> <param name="driver-xa-datasource-class-name" value="org.mariadb.jdbc.MariaDbDataSource"/> <param name="driver-module-name" value="org.mariadb.jdbc"/> </feature> </feature> <packages> 2 <package name="org.mariadb.jdbc"/> </packages> </layer-spec> 1 Update the datasources subsystem configuration with a JDBC driver named MariaDB , implemented by the module org.mariadb.jdbc . 2 The JBoss Modules module containing the driver classes that are installed when the layer is provisioned. The mariadb-driver layer updates the datasources subsystem with the configuration of a JDBC driver, implemented by the JBoss Modules module. Create the directory src/main/resources/layers/standalone/mariadb-datasource . In the mariadb-datasource directory, create the layer-spec.xml file with the following content: <?xml version="1.0" ?> <layer-spec xmlns="urn:jboss:galleon:layer-spec:1.0" name="mariadb-datasource"> <dependencies> <layer name="mariadb-driver"/> 1 </dependencies> <feature spec="subsystem.datasources.data-source"> 2 <param name="data-source" value="MariaDBDS"/> <param name="jndi-name" value="java:jboss/datasources/USD{env.MARIADB_DATASOURCE:MariaDBDS}"/> <param name="connection-url" value="jdbc:mariadb://USD{env.MARIADB_HOST:localhost}:USD{env.MARIADB_PORT:3306}/USD{env.MARIADB_DATABASE}"/> 3 <param name="driver-name" value="mariadb"/> <param name="user-name" value="USD{env.MARIADB_USER}"/> 4 <param name="password" value="USD{env.MARIADB_PASSWORD}"/> </feature> </layer-spec> 1 This dependency enforces the provisioning of the MariaDB driver when the data source is provisioned. All the layers a layer depends on are automatically provisioned when that layer is provisioned. 2 Update the datasources subsystem configuration with a data source named MariaDBDS . 3 Datasource's name, host, port, and database values are resolved from the environment variables MARIADB_DATASOURCE , MARIADB_HOST , MARIADB_PORT , and MARIADB_DATABASE , which are set when the server is started. 4 User name and password values are resolved from the environment variables MARIADB_USER and MARIADB_PASSWORD . Build the Galleon feature-pack by running the following command: The file target/mariadb-galleon-pack-1.0-SNAPSHOT.zip is created. 8.2.1.3. Using the custom Galleon feature-pack during S2I build A custom feature-pack must be made available to the Maven build that occurs during OpenShift S2I build. This is usually achieved by deploying the custom feature-pack as an artifact, for example, org.jboss.eap.demo:mariadb-galleon-pack:1.0-SNAPSHOT to an accessible Maven repository. Note For more information about configuring the JBoss EAP S2I image for custom Galleon feature-pack usage, see Configure Galleon by using advanced environment variables . Prerequisites You have oc command-line installed You are logged in to an OpenShift cluster You have configured access to the Red Hat Container registry. For detailed information, see Red Hat Container Registry . You have created a custom Galleon feature-pack. For detailed information, see Preparing the Maven project . Procedure Start the MariaDB database by running the following command. This example uses the MariaDB image mariadb-105-rhel7 . You must use the latest supported version of MariaDB image. See Red Hat Ecosystem Catalog to get more information about MariaDB images . The OpenShift service mariadb-101-rhel7 is created and started. Create a secret from the feature-pack archive, generated by the custom feature-pack Maven build, by running the following command within the Maven project directory mariadb-galleon-pack : The secret mariadb-galleon-pack is created. When initiating the S2I build, this secret is used to mount the feature-pack .zip file in the pod, making the file available during the server provisioning phase. 8.2.1.4. Importing the JBoss EAP 8 image stream You can import the JBoss EAP 8.0 image stream by following the procedure below. Procedure Import the JBoss EAP 8.0 image stream: 8.2.1.4.1. Creating an S2I build using the JBoss EAP maven plugin The eap-maven-plugin has been configured with both a reference to the JBoss EAP galleon feature-pack , JBoss EAP cloud galleon feature-pack and the mariadb galleon feature-pack . See an extract of the pom.xml : <feature-packs> <feature-pack> <location>org.jboss.eap:wildfly-ee-galleon-pack</location> </feature-pack> <feature-pack> <location>org.jboss.eap.cloud:eap-cloud-galleon-pack</location> </feature-pack> <feature-pack> <location>org.jboss.eap.demo:mariadb-galleon-pack:1.0-SNAPSHOT</location> 1 </feature-pack> </feature-packs> <layers> <layer>jaxrs-server</layer> <layer>mariadb-datasource</layer> 2 </layers> 1 The mariadb feature-pack version is required. It is not resolved in the JBoss EAP 8 configured channel. 2 The mariadb-datasource layer. Procedure Create the S2I build by running the following command: 1 The mariadb-galleon-pack secret is mounted in the /tmp/demo-maven-repository/org/jboss/eap/demo/mariadb-galleon-pack/1.0-SNAPSHOT directory. Additional resources For more information see the JBoss EAP 8.0 demo example . 8.2.1.4.2. Creating an S2I build using the legacy S2I provisioning capabilities You can use the openshift-legacy profile to configure your S2I build so that you can provision your server. Procedure Create a new OpenShift build by running the following command: 1 This environment variable uses the JBoss EAP 8.0 channel during provisioning. 2 This environment variable references the JBoss EAP 8.0 feature-pack , cloud feature-pack and the mariadb feature-pack . 3 This environment variable references the set of Galleon layers you want to use to provision the server. jaxrs-server is a base server layer, mariadb-datasource is our custom layer that brings the mariadb driver and a new data source to the server installation. 4 This points to the location of your local maven repository where the mariadb feature-pack is contained. 5 This environment variable redefines the MAVEN_ARGS to enable the openshift-legacy profile. 6 The mariadb-galleon-pack secret is mounted in the /tmp/demo-maven-repository/org/jboss/eap/demo/mariadb-galleon-pack/1.0-SNAPSHOT directory. Note This directory path complies with Maven repository artifact coordinates to path mapping. 8.2.1.4.3. Starting the build You can create the mariadb-app-build image by creating a new build. Procedure Start a new build from the same OpenShift build that you created earlier and run the following command: After successful command execution, the image mariadb-app-build is created. 8.2.1.4.4. Creating a new deployment You can create a new deployment by providing the environment variables that are required to bind the data source to the running MariaDB database Procedure Create a new deployment by running the following command: 1 The demo expects the data source to be named Demo Note For more details about the custom Galleon feature-pack environment variables, see Custom Galleon feature pack environment variables . Expose the mariadb-app application, run the following command: To create a new task, run the following command: To access the list of tasks, run the following command: The added task is displayed in a browser. 8.2.2. Configure Galleon by using advanced environment variables You can use advanced custom Galleon feature pack environment variables to customize the location where you store your custom Galleon feature packs and layers during the S2I image build process. These advanced custom Galleon feature pack environment variables are as follows: GALLEON_DIR=<path> , which overrides the default <project_root_dir>/galleon directory path to <project_root_dir>/<GALLEON_DIR> . GALLEON_CUSTOM_FEATURE_PACKS_MAVEN_REPO=<path> , which overrides the <project root dir>/galleon/repository directory path with an absolute path to a Maven local repository cache directory. This repository contains custom Galleon feature packs. You must locate the Galleon feature pack archive files inside a sub-directory that is compliant with the Maven local-cache file system configuration. For example, locate the org.examples:my-feature-pack:1.0.0.Final feature pack inside the path-to-repository/org/examples/my-feature-pack/1.0.0.Final/my-feature-pack-1.0.0.Final.zip path. You can configure your Maven project settings by creating a settings.xml file in the <project_root>/<GALLEON_DIR> directory. The default value for GALLEON_DIR is <project_root_dir>/galleon . Maven uses the file to provision your custom Galleon feature packs for your application. If you do not create a settings.xml file, Maven uses a default settings.xml file that was created by the S2I image. Important Do not specify a local Maven repository location in a settings.xml file, because the S2I builder image specifies a location to your local Maven repository. The S2I builder image uses this location during the S2I build process. Additional resources Custom Galleon feature pack environment variables . 8.2.3. Custom Galleon feature pack environment variables You can use any of the following custom Galleon feature pack environment variables to customize how you use your JBoss EAP S2I image. Table 8.1. Descriptions of custom Galleon feature pack environment variables Environment variable Description GALLEON_DIR=<path> Where <path> is a directory relative to the root directory of your application project. Your <path> directory contains your optional Galleon custom content, such as the settings.xml file and local Maven repository cache. This cache contains the custom Galleon feature packs. Directory defaults to galleon . GALLEON_CUSTOM_FEATURE_PACKS_MAVEN_REPO=<path> <path> is the absolute path to a Maven local repository directory that contains custom feature packs. Directory defaults to galleon/repository . GALLEON_PROVISION_FEATURE_PACKS=<list_of_galleon_feature_packs> Where <list_of_galleon_feature_packs> is a comma-separated list of your custom Galleon feature packs identified by Maven coordinates. The listed feature packs must be compatible with the version of the JBoss EAP 8.0 server present in the builder image. You can use the GALLEON_PROVISION_LAYERS environment variable to set the Galleon layers, which were defined by your custom feature packs, for your server.

Commands:
mvn archetype:generate -DarchetypeGroupId=org.codehaus.mojo.archetypes -DarchetypeArtifactId=pom-root -DgroupId=org.jboss.eap.demo -DartifactId=mariadb-galleon-pack -DinteractiveMode=false
<repositories> <repository> <id>redhat-ga</id> <name>Redhat GA</name> <url>https://maven.repository.redhat.com/ga/</url> </repository> </repositories>
<dependencies> <dependency> <groupId>org.jboss.eap</groupId> <artifactId>wildfly-ee-galleon-pack</artifactId> <version>8.0.0.GA-redhat-00010</version> <type>zip</type> </dependency> <dependency> <groupId>org.mariadb.jdbc</groupId> <artifactId>mariadb-java-client</artifactId> <version>2.7.2</version> </dependency> </dependencies>
<build> <plugins> <plugin> <groupId>org.wildfly.galleon-plugins</groupId> <artifactId>wildfly-galleon-maven-plugin</artifactId> <version>6.4.8.Final-redhat-00001</version> <executions> <execution> <id>mariadb-galleon-pack-build</id> <goals> <goal>build-user-feature-pack</goal> </goals> <phase>compile</phase> </execution> </executions> </plugin> </plugins> </build>
<?xml version="1.0" encoding="UTF-8"?> <module name="org.mariadb.jdbc" xmlns="urn:jboss:module:1.8"> <resources> <artifact name="USD{org.mariadb.jdbc:mariadb-java-client}"/> 1 </resources> <dependencies> 2 <module name="java.se"/> <module name="jakarta.transaction.api"/> <module name="jdk.net"/> </dependencies> </module>
<?xml version="1.0" ?> <layer-spec xmlns="urn:jboss:galleon:layer-spec:1.0" name="mariadb-driver"> <feature spec="subsystem.datasources"> 1 <feature spec="subsystem.datasources.jdbc-driver"> <param name="driver-name" value="mariadb"/> <param name="jdbc-driver" value="mariadb"/> <param name="driver-xa-datasource-class-name" value="org.mariadb.jdbc.MariaDbDataSource"/> <param name="driver-module-name" value="org.mariadb.jdbc"/> </feature> </feature> <packages> 2 <package name="org.mariadb.jdbc"/> </packages> </layer-spec>
<?xml version="1.0" ?> <layer-spec xmlns="urn:jboss:galleon:layer-spec:1.0" name="mariadb-datasource"> <dependencies> <layer name="mariadb-driver"/> 1 </dependencies> <feature spec="subsystem.datasources.data-source"> 2 <param name="data-source" value="MariaDBDS"/> <param name="jndi-name" value="java:jboss/datasources/USD{env.MARIADB_DATASOURCE:MariaDBDS}"/> <param name="connection-url" value="jdbc:mariadb://USD{env.MARIADB_HOST:localhost}:USD{env.MARIADB_PORT:3306}/USD{env.MARIADB_DATABASE}"/> 3 <param name="driver-name" value="mariadb"/> <param name="user-name" value="USD{env.MARIADB_USER}"/> 4 <param name="password" value="USD{env.MARIADB_PASSWORD}"/> </feature> </layer-spec>
mvn clean install
new-app -e MYSQL_USER=admin -e MYSQL_PASSWORD=admin -e MYSQL_DATABASE=mariadb registry.redhat.io/rhscl/mariadb-105-rhel7
create secret generic mariadb-galleon-pack --from-file=target/mariadb-galleon-pack-1.0-SNAPSHOT.zip
import-image jboss-eap-8/eap8-openjdk17-builder-openshift-rhel8:latest --from=registry.redhat.io/jboss-eap-8/eap8-openjdk17-builder-openshift-rhel8:latest --confirm
<feature-packs> <feature-pack> <location>org.jboss.eap:wildfly-ee-galleon-pack</location> </feature-pack> <feature-pack> <location>org.jboss.eap.cloud:eap-cloud-galleon-pack</location> </feature-pack> <feature-pack> <location>org.jboss.eap.demo:mariadb-galleon-pack:1.0-SNAPSHOT</location> 1 </feature-pack> </feature-packs> <layers> <layer>jaxrs-server</layer> <layer>mariadb-datasource</layer> 2 </layers>
new-build eap8-openjdk17-builder-openshift-rhel8:latest~https://github.com/jboss-container-images/jboss-eap-8-openshift-image#EAP_8.0.0 --context-dir=examples/eap/custom-layers/application --build-secret=mariadb-galleon-pack:/tmp/demo-maven-repository/org/jboss/eap/demo/mariadb-galleon-pack/1.0-SNAPSHOT \ 1 --name=mariadb-app-build
new-build eap8-openjdk17-builder-openshift-rhel8:latest~https://github.com/jboss-container-images/jboss-eap-8-openshift-image#EAP_8.0.0 --context-dir=examples/eap/custom-layers/application --env=GALLEON_PROVISION_CHANNELS="org.jboss.eap.channels:eap-8.0" \ 1 --env=GALLEON_PROVISION_FEATURE_PACKS="org.jboss.eap:wildfly-ee-galleon-pack,org.jboss.eap.cloud:eap-cloud-galleon-pack,org.jboss.eap.demo:mariadb-galleon-pack:1.0-SNAPSHOT" \ 2 --env=GALLEON_PROVISION_LAYERS="jaxrs-server,mariadb-datasource" \ 3 --env=GALLEON_CUSTOM_FEATURE_PACKS_MAVEN_REPO="/tmp/demo-maven-repository" \ 4 --env=MAVEN_ARGS="-Popenshift-legacy" \ 5 --build-secret=mariadb-galleon-pack:/tmp/demo-maven-repository/org/jboss/eap/demo/mariadb-galleon-pack/1.0-SNAPSHOT \ 6 --name=mariadb-app-build
start-build mariadb-app-build
new-app --name=mariadb-app mariadb-app-build --env=MARIADB_PORT=3306 --env=MARIADB_USER=admin --env=MARIADB_PASSWORD=admin --env=MARIADB_HOST=mariadb-105-rhel7 --env=MARIADB_DATABASE=mariadb --env=MARIADB_DATASOURCE=Demo 1
expose svc/mariadb-app
curl -X POST http://USD(oc get route mariadb-app --template='{{ .spec.host }}')/tasks/title/foo
curl http://USD(oc get route mariadb-app --template='{{ .spec.host }}')