Ce contenu n'est pas disponible dans la langue sélectionnée.
Chapter 5. Capability Trimming in JBoss EAP for OpenShift
When building an image that includes JBoss EAP, you can control the JBoss EAP features and subsystems to include in the image.
The default JBoss EAP server included in S2I images includes the complete server and all features. You might want to trim the capabilities included in the provisioned server. For example, you might want to reduce the security exposure of the provisioned server, or you might want to reduce the memory footprint so it is more appropriate for a microservice container.
5.1. Provision a custom JBoss EAP server
To provision a custom server with trimmed capabilities, pass the GALLEON_PROVISION_LAYERS
environment variable during the S2I build phase.
The value of the environment variable is a comma-separated list of the layers to provision to build the server.
For example, if you specify the environment variable as GALLEON_PROVISION_LAYERS=jaxrs-server,sso
, a JBoss EAP server is provisioned with the following capabilities:
- A servlet container
- The ability to configure a datasource
-
The
jaxrs
,weld
, andjpa
subsystems - Red Hat SSO integration
5.2. Available JBoss EAP Layers
Red Hat makes available six layers to customize provisioning of the JBoss EAP server in OpenShift.
Three layers are base layers that provide core functionality. Three are decorator layers that enhance the base layers.
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
5.2.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 Infinispan-based second-level entity caching locally in 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:
- Health subsystem
- Metrics subsystem
The following Jakarta EE specification is supported in this layer in addition to those supported in the jaxrs-server
layer:
- Jakarta Security 1.0
5.2.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.
sso
This decorator layer adds Red Hat Single Sign-On integration to the provisioned server.
observability
This decorator layer adds the following observability features to the provisioned server:
- Health subsystem
- Metrics subsystem
This layer is built in to 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.
5.3. 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 Custom provisioning files for JBoss EAP.
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.
5.3.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 7.4.
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 7.4 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 in OpenShift a Galleon feature-pack containing layers to provision a MariaDB driver and data source for the JBoss EAP 7.4 server.
5.3.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
To create a new Maven project, run the following command:
mvn archetype:generate -DarchetypeGroupId=org.codehaus.mojo.archetypes -DarchetypeArtifactId=pom-root -DgroupId=org.example.mariadb -DartifactId=mariadb-galleon-pack -DinteractiveMode=false
In the directory
mariadb-galleon-pack
, update thepom.xml
file to include the Red Hat Maven repository:<repositories> <repository> <id>redhat-ga</id> <name>Redhat GA</name> <url>https://maven.repository.redhat.com/ga/</url> </repository> </repositories>
Update the
pom.xml
file to add dependencies on the EAP Galleon feature-pack and the MariaDB driver:<dependencies> <dependency> <groupId>org.jboss.eap</groupId> <artifactId>wildfly-ee-galleon-pack</artifactId> <version>7.4.4.GA-redhat-00011</version> <type>zip</type> </dependency> <dependency> <groupId>org.mariadb.jdbc</groupId> <artifactId>mariadb-java-client</artifactId> <version>3.0.5</version> </dependency> </dependencies>
Update the
pom.xml
file to include the Maven plugin that is used to build the Galleon feature-pack:<build> <plugins> <plugin> <groupId>org.wildfly.galleon-plugins</groupId> <artifactId>wildfly-galleon-maven-plugin</artifactId> <version>5.2.11.Final</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>
5.3.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 namedmodule.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="${org.mariadb.jdbc:mariadb-java-client}"/> 1 </resources> <dependencies> 2 <module name="javax.api"/> <module name="javax.transaction.api"/> </dependencies> </module>
-
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 thelayer-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>
The
mariadb-driver
layer updates the datasources subsystem with the configuration of a JDBC driver, implemented by theJBoss Modules
module.-
Create the directory
src/main/resources/layers/standalone/mariadb-datasource
. In the
mariadb-datasource
directory, create thelayer-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/${env.MARIADB_DATASOURCE:MariaDBDS}"/> <param name="connection-url" value="jdbc:mariadb://${env.MARIADB_HOST:localhost}:${env.MARIADB_PORT:3306}/${env.MARIADB_DATABASE}"/> 3 <param name="driver-name" value="mariadb"/> <param name="user-name" value="${env.MARIADB_USER}"/>4 <param name="password" value="${env.MARIADB_PASSWORD}"/> </feature> </layer-spec>
- 1
- This dependency enforces the provisioning of the MariaDB driver when the datasource 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 datasource named MariaDBDS.
- 3
- Datasource’s name, host, port, and database values are resolved from the environment variables
MARIADB_DATASOURCE
,MARIADB_HOST
,MARIADB_PORT
, andMARIADB_DATABASE
, which are set when the server is started. - 4
- User name and password values are resolved from the environment variables
MARIADB_USER
andMARIADB_PASSWORD
.
Build the Galleon feature-pack by running the following command:
mvn clean install
The file
target/mariadb-galleon-pack-1.0-SNAPSHOT.zip
is created.
5.3.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.example.mariadb:mariadb-galleon-pack:1.0-SNAPSHOT
to an accessible Maven repository.
In order to test the feature-pack before deployment, you can use the EAP S2I builder image capability that allows you to make use of a locally built Galleon feature-pack. Use the following procedure example to customize the todo-backend
EAP quickstart with the use of MariaDB driver instead of PostgreSQL driver.
-
For more information about the
todo-backend
EAP quickstart, see EAP quickstart. - 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 OpenShift command-line installed
- You are logged in to an OpenShift cluster
- You have installed the JBoss EAP OpenShift images in your 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:
oc new-app -e MYSQL_USER=admin -e MYSQL_PASSWORD=admin -e MYSQL_DATABASE=mariadb registry.redhat.io/rhscl/mariadb-101-rhel7
The OpenShift service
mariadb-101-rhel7
is created and started.Create a secret from the feature-pack ZIP archive, generated by the custom feature-pack Maven build, by running the following command within the Maven project directory
mariadb-galleon-pack
:oc create secret generic mariadb-galleon-pack --from-file=target/mariadb-galleon-pack-1.0-SNAPSHOT.zip
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.To create a new OpenShift build to build an application image containing the
todo-backend
quickstart deployment running inside a server trimmed with Galleon, run the following command:oc new-build jboss-eap74-openjdk11-openshift:latest~https://github.com/jboss-developer/jboss-eap-quickstarts#EAP_7.4.0.GA \ --context-dir=todo-backend \ --env=GALLEON_PROVISION_FEATURE_PACKS="org.example.mariadb:mariadb-galleon-pack:1.0-SNAPSHOT" \ 1 --env=GALLEON_PROVISION_LAYERS="jaxrs-server,mariadb-datasource" \ 2 --env=GALLEON_CUSTOM_FEATURE_PACKS_MAVEN_REPO="/tmp/repo" \ 3 --env=MAVEN_ARGS_APPEND="-Dcom.redhat.xpaas.repo.jbossorg" \ --build-secret=mariadb-galleon-pack:/tmp/repo/org/example/mariadb/mariadb-galleon-pack/1.0-SNAPSHOT \ 4 --name=todos-app-build
- 1
- The custom feature-pack environment variable that contains a comma separated list of feature-pack Maven coordinates, such as
groupId:artifactId:version
. - 2
- The set of Galleon layers that are used to provision the server.
jaxrs-server
is a base server layer andmariadb-datasource
is the custom layer that brings the MariaDB driver and a new datasource to the server installation. - 3
- The location of the local Maven repository within the image that contains the MariaDB feature-pack. This repository is populated when mounting the secret inside the image.
- 4
- The
mariadb-galleon-pack
secret is mounted in the/tmp/repo/org/example/mariadb/mariadb-galleon-pack/1.0-SNAPSHOT
directory.
To start a new build from the created OpenShift build, run the following command:
oc start-build todos-app-build
After successful command execution, the image
todos-app-build
is created.To create a new deployment, provide the environment variables that are required to bind the datasource to the running MariaDB database by executing the following command:
oc new-app --name=todos-app todos-app-build \ --env=MARIADB_PORT=3306 \ --env=MARIADB_USER=admin \ --env=MARIADB_PASSWORD=admin \ --env=MARIADB_HOST=mariadb-101-rhel7 \ --env=MARIADB_DATABASE=mariadb \ --env=MARIADB_DATASOURCE=ToDos 1
- 1
- The quickstart expects the datasource to be named
ToDos
NoteFor more details about the custom Galleon feature-pack environment variables, see Custom Galleon feature-pack environment variables
To expose the
todos-app
application, run the following command:oc expose svc/todos-app
To create a new task, run the following command:
curl -X POST http://$(oc get route todos-app --template='{{ .spec.host }}') \ -H 'Content-Type: application/json' \ -d '{"title":"todo1"}'
To access the list of tasks, run the following command:
curl http://$(oc get route todos-app --template='{{ .spec.host }}')
The added task is displayed in a browser.
5.3.1.4. Custom Provisioning Files for JBoss EAP
Custom provisioning files are XML files with the file name provisioning.xml
that are stored in the galleon
subdirectory.
Using the provisioning.xml
file is an alternative to the usage of GALLEON_PROVISION_FEATURE_PACKS
and GALLEON_PROVISION_LAYERS
environment variables. During S2I build, the provisioning.xml
file is used to provision the custom EAP server.
Do not create a custom provisioning file when using the GALLEON_PROVISION_LAYERS
environment variable, because this environment variable configures the S2I build process to ignore the file.
The following code illustrates a custom provisioning file.
<?xml version="1.0" ?> <installation xmlns="urn:jboss:galleon:provisioning:3.0"> <feature-pack location="eap-s2i@maven(org.jboss.universe:s2i-universe)">1 <default-configs inherit="false"/>2 <packages inherit="false"/>3 </feature-pack> <feature-pack location="org.example.mariadb:mariadb-galleon-pack:1.0-SNAPSHOT">4 <default-configs inherit="false"/> <packages inherit="false"/> </feature-pack> <config model="standalone" name="standalone.xml">5 <layers> <include name="jaxrs-server"/> <include name="mariadb-datasource"/> </layers> </config> <options>6 <option name="optional-packages" value="passive+"/> </options> </installation>
- 1
- This element instructs the provisioning process to provision the current eap-s2i feature-pack. Note that a builder image includes only one feature pack.
- 2
- This element instructs the provisioning process to exclude default configurations.
- 3
- This element instructs the provisioning process to exclude default packages.
- 4
- This element instructs the provisioning process to provision the
org.example.mariadb:mariadb-galleon-pack:1.0-SNAPSHOT
feature pack. The child elements instruct the process to exclude default configurations and default packages. - 5
- This element instructs the provisioning process to create a custom standalone configuration. The configuration includes the
jaxrs-server
base layer and themariadb-datasource
custom layer from theorg.example.mariadb:mariadb-galleon-pack:1.0-SNAPSHOT
feature pack. - 6
- This element instructs the provisioning process to optimize provisioning of JBoss EAP modules.
Additional resources
-
For more information about using the
GALLEON_PROVISION_LAYERS
environment variable, see Provision a Custom JBoss EAP server.
5.3.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.
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
- For more information about custom Galleon feature pack environment variables, see custom Galleon feature pack environment variables.
5.3.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.
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
Directory defaults to |
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_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 7.4 server present in the builder image.
You can use the |