Rechercher

Ce contenu n'est pas disponible dans la langue sélectionnée.

Chapter 5. Capability Trimming in JBoss EAP for OpenShift

download PDF

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, and jpa 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
Note

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

  1. Build a custom layer using the Galleon Maven plugin.

    For more information, see Preparing the Maven project.

  2. Deploy the custom layer to an accessible Maven repository.
  3. 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.

  4. 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.

  5. 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

  1. 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
  2. In the directory mariadb-galleon-pack, update the pom.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>
  3. 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>
  4. 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

Procedure

  1. 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.
  2. Create the directory src/main/resources/modules/org/mariadb/jdbc/main.
  3. 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="${org.mariadb.jdbc:mariadb-java-client}"/> 1
       </resources>
       <dependencies> 2
           <module name="javax.api"/>
           <module name="javax.transaction.api"/>
       </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.
  4. Create the directory src/main/resources/layers/standalone/. This is the root directory of all the layers that the Galleon feature-pack is defining.
  5. Create the directory src/main/resources/layers/standalone/mariadb-driver.
  6. 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 subsytem 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.

  7. Create the directory src/main/resources/layers/standalone/mariadb-datasource.
  8. 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/${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, 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.
  9. 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.

Note

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

  1. 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.

  2. 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.

  3. 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 and mariadb-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.
  4. 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.

  5. 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
    Note

    For more details about the custom Galleon feature-pack environment variables, see Custom Galleon feature-pack environment variables

  6. To expose the todos-app application, run the following command:

    oc expose svc/todos-app
  7. 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"}'
  8. 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.

Important

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 the mariadb-datasource custom layer from the org.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

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.

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

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.

Table 5.1. Descriptions of custom Galleon feature pack environment variables
Environment variableDescription

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 7.4 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.

Red Hat logoGithubRedditYoutubeTwitter

Apprendre

Essayez, achetez et vendez

Communautés

À propos de la documentation Red Hat

Nous aidons les utilisateurs de Red Hat à innover et à atteindre leurs objectifs grâce à nos produits et services avec un contenu auquel ils peuvent faire confiance.

Rendre l’open source plus inclusif

Red Hat s'engage à remplacer le langage problématique dans notre code, notre documentation et nos propriétés Web. Pour plus de détails, consultez leBlog Red Hat.

À propos de Red Hat

Nous proposons des solutions renforcées qui facilitent le travail des entreprises sur plusieurs plates-formes et environnements, du centre de données central à la périphérie du réseau.

© 2024 Red Hat, Inc.