Configure a JBoss EAP 8 application for OpenShift

Red Hat JBoss Enterprise Application Platform (JBoss EAP) 8 introduces significant enhancements to developer tools that streamline building and deploying JBoss EAP applications on Red Hat OpenShift, such as the JBoss EAP Maven plug-in. This lesson introduces these tools and demonstrates how to use them to migrate a traditional JBoss EAP application to Red Hat OpenShift.

In order to get full benefit from taking this lesson, you need to:

• Create a Red Hat Developer program account.

In this lesson, you will:

• Learn the fundamentals of the JBoss EAP 8 Source-to-Image process.
• Use the JBoss EAP Maven plug-in to configure and tune JBoss EAP 8 on OpenShift.
• Understand the benefits of capability trimming in JBoss EAP 8 on OpenShift.

What's different with JBoss EAP 8?

JBoss EAP 8 introduces changes to the provisioning and configuration of JBoss EAP application images on Red Hat OpenShift. The process now incorporates the JBoss EAP Maven plug-in, which provides significant improvements that make configuring JBoss EAP on OpenShift easier and more flexible.

When building a JBoss EAP 7.x image for OpenShift, the OpenShift builder image used Maven to build the deployment artifact and then directly provisioned the JBoss EAP server instance. The server provisioning configuration was provided by a combination of runtime variables, configuration snippets, and JBoss CLI scripts.

With JBoss EAP 8, the JBoss EAP Maven plug-in provisions the server and deploys the packaged application during the Maven execution. All the configuration for this build process is maintained in the Maven pom.xml file. This lets developers and operations teams control and test their JBoss EAP deployments in their local environments, which provides significant benefits.

JBoss EAP 8 Source-to-Image (S2I) process fundamentals

The JBoss EAP Source-to-Image (S2I) process consists of two builds:  

• Artifact image build
• Runtime image build

First build: Artifact image build

The artifact image build process is shown in Figure 1 and described below.

Looking at the numbered areas, we can see the following:

• The JBoss EAP 8 application Git source repository; this contains the source code for the JBoss EAP 8 application. The code in this repository should contain the configuration necessary for the S2I process to provision an instance of JBoss EAP 8.
• Within the Git repository, the pom.xml contains the JBoss EAP Maven plug-in configuration to provision the JBoss EAP server and deploy an application.
• An optional modules directory holds JBoss Modules artifacts.
• An optional configuration directory contains content to copy to the server configurations directory. 

Once the S2I process has built the application and provisioned the server, it is then copied to the artifact image as shown in Step 5 of Figure 1.

Second build: Runtime image build

The output from this first build is an artifact image that is pushed to an OpenShift image stream. Once this image is pushed, the second build (runtime build) is started. The runtime image build process is shown in Figure 2.

Looking at the numbered areas of this second build, we can see the following:

• The server installed in the artifact image built in the previous step is installed into the JBoss EAP runtime image in the $JBOSS_HOME directory (/opt/server directory).
• The final application image is pushed to the OpenShift image registry used to deploy the JBoss EAP application. The base image for this final image is the JBoss EAP OpenShift runtime image, a minimal image with the required libraries and JVM to run an instance of JBoss EAP. No build tools (e.g., Maven) are included in this image, thereby reducing the image size and potential attack surface.

How to use the JBoss EAP Maven plug-in to configure and tune JBoss EAP 8 on OpenShift

The JBoss EAP Maven plug-in uses Galleon layers to provision a JBoss EAP server configured with the minimum set of features to support the deployed application. Galleon is a provisioning tool for working with Maven repositories. Galleon automatically retrieves released JBoss EAP Maven artifacts to compose a software distribution of a JBoss EAP-based application server according to a user's configuration.

To build and deploy this application on OpenShift, the only change we need to make is to the Maven pom.xml file. This involves adding the eap-maven-plugin, which takes care of all the provisioning and configuration required to build an instance of JBoss EAP 8 to run our application.

You can use the Developer Sandbox and Red Hat OpenShift Dev Spaces to check the code and understand the changes required to deploy the application to OpenShift.

1. Navigate to the Developer Sandbox. If you do not already have a Red Hat account, follow the Register for a Red Hat account link to create one. Otherwise, log in with your existing Red Hat account.

2. Once you've logged in, you should see the console interface (Figure 3). 

   

3. Click the Get Started button to launch the Developer Sandbox.

4. Once the Developer Sandbox has started, you will see a selection of services (Figure 4). 

   

5. To launch OpenShift Dev Spaces, click Launch in the OpenShift Dev Spaces box. This prompts you to log in using OpenShift, then guides you through using your Developer Sandbox account to log into OpenShift Dev Spaces.
6. Once you've logged into OpenShift Dev Spaces from the Create Workspace tab, enter the following GitHub URL in the Git Repo URL field: https://github.com/RedHat-Middleware-Workshops/eap8-rhd-learning-path.git

7. Click Create & Open (Figure 5). 

   

8. Your OpenShift Dev Spaces workspace will start and you will see a familiar development IDE interface with the source code cloned and ready to edit (Figure 6). 

   

9. The first step is to add the Red Hat plug-in repositories. Go to your OpenShift Dev Spaces workspace. Then, open the pom.xml file in the project root directory. Find the region of code with the following declaration:

   <!-- Paste pluginrepositories here -->       
   
   Paste the following XML where it says <!-- Paste pluginrepositories here -->:
   
      <pluginRepositories>
   
           <!-- keep this repository the first -->
   
           <pluginRepository>
   
               <id>jboss-public-maven-repository</id>
   
               <name>JBoss Public Maven Repository</name>
   
               <url>https://repository.jboss.org/nexus/content/groups/public/</url>
   
               <releases>
   
                   <enabled>true</enabled>
   
               </releases>
   
               <snapshots>
   
                   <enabled>true</enabled>
   
               </snapshots>
   
           </pluginRepository>
   
           <pluginRepository>
   
               <id>redhat-ga-maven-repository</id>
   
               <name>Red Hat GA Maven Repository</name>
   
               <url>https://maven.repository.redhat.com/ga/</url>
   
               <releases>
   
                   <enabled>true</enabled>
   
               </releases>
   
               <snapshots>
   
                   <enabled>true</enabled>
   
               </snapshots>
   
           </pluginRepository>
   
       </pluginRepositories>

10. Next, in the same pom.xml file, find the region of code with the following declaration:

    <!-- Paste OpenShift profile here -->     
    
    Replace <!-- Paste OpenShift profile here --> with the following XML:
    
    
    
            <profile>
    
                <id>openshift</id>
    
                <build>
    
                    <plugins>
    
                        <plugin>
    
                            <groupId>org.jboss.eap.plugins</groupId>
    
                            <artifactId>eap-maven-plugin</artifactId>
    
                            <version>1.0.0.Final-redhat-00014</version>
    
                            <configuration>
    
                                <channels>
    
                                    <channel>
    
                                        <manifest>
    
                                            <groupId>org.jboss.eap.channels</groupId>
    
                                            <artifactId>eap-8.0</artifactId>
    
                                        </manifest>
    
                                    </channel>
    
                                </channels>
    
                                <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:eap-datasources-galleon-pack</location>
    
                                    </feature-pack>
    
                                </feature-packs>
    
                                <layers>
    
                                    <layer>postgresql-datasource</layer>
    
                                    <layer>jaxrs-server</layer>
    
                                </layers>
    
                                <filename>ROOT.war</filename>
    
                            </configuration>
    
                            <executions>
    
                                <execution>
    
                                    <goals>
    
                                        <goal>package</goal>
    
                                    </goals>
    
                                </execution>
    
                            </executions>
    
                        </plugin>
    
                    </plugins>
    
                </build>
    
            </profile>

If we examine the pom.xml snippet, we can see the inclusion of the eap-maven-plugin and within the plug-in configuration, three feature packs are listed:

1. wildfly-ee-galleon-pack: This pack contains the features required to build an instance of JBoss EAP. This feature pack contains several layers (e.g., jaxrs-server and cloud-server).
2. eap-cloud-galleon-pack: This pack provisions a set of additional features that let you configure a JBoss EAP server to run on the cloud. The main features are as follows:
   • Server startup scripts: When starting a JBoss EAP server that was provisioned by the cloud feature pack, a set of Bash scripts are executed to adjust the server configuration. These scripts configure a range of server functions such as clustering, security, logging, messaging, tracing, and config management. Read more about server startup scripts.
   • Adjustment of WildFly Galleon layers to tune for deployment on OpenShift, for example, by disabling the management console. Read more about WildFly Galleon layers adjusted by the cloud feature-pack.
   • Automatic provisioning of the health subsystem allows for server state monitoring and provides liveness and readiness probes.
   • Automatic routing of server logs to the console to ensure they are visible in the pod logs in the OpenShift console.
3. eap-datasources-galleon-pack: This feature pack for JBoss EAP and JBoss EAP Expansion Pack provides JDBC drivers and data sources for the following databases:
   • Microsoft SQL Server
   • Oracle
   • PostgreSQL

Capability trimming in JBoss EAP 8 on OpenShift

JBoss EAP 8 makes it much easier to use capability trimming when building images for deployment on 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 so that they are included in the image. We're demonstrating this capability using the EAP Maven plug-in. The "layers" element of the plug-in configuration specifies which layers to use when deploying the server—in this case, the jaxrs-server and the postgresql-datasource:

• jaxrs-server provides support for JAX-RS, CDI, and JPA. The jaxrs-server layer also extends the datasources-web-server which provides support for data sources.
• The postgresql-datasource is provided by the eap-datasources-galleon-pack and enables the provisioning of the postgres driver and module.

The addition of the datasources feature pack and the postgresql-datasource layer will instruct eap-maven-plugin to install and configure a data source to connect to a PostgreSQL database. If we look at the documentation for the PostgreSQL layer, we can see the need for a POSTGRESQL_DRIVER_VERSION build time environment variable. This build time environment variable is mandatory and tells the eap-maven-plugin which version of the PostgreSQL driver to install.

Conclusion

JBoss EAP 8 introduces tools that make configuring JBoss EAP application images for OpenShift much easier, giving developers control of configuration options from within their development environment. These tools allow developers to ensure their applications images are optimal in terms of included libraries and subsystem configurations.