The recent release of Red Hat JBoss Enterprise Application Platform (EAP) 8 Beta introduced changes to the provisioning and configuration of JBoss EAP application images on Red Hat OpenShift. The process adopted the JBoss EAP Maven plugin, which provides significant improvements that make configuring JBoss EAP on OpenShift easier and more flexible.
This article demonstrates the steps required to add the JBoss EAP Maven plugin to an existing JBoss EAP 8 Beta application. We will also test our plugin locally and then build and deploy our application to OpenShift using Helm via the OpenShift UI and the Helm CLI.
The benefits of the JBoss EAP Maven plugin
The JBoss EAP Maven plugin provides the following functionalities:
- Uses the wildfly-ee-galleon-pack and eap-cloud-galleon-pack Galleon feature-packs and selection of layers for customizing the server configuration file.
- Applies CLI script commands to the server. These CLI scripts can be easily added to the application source code repository.
- Supports the addition of extra files into the server installation, such as a keystore file.
Refer to the documentation for more information. Refer to the quickstarts for JBoss EAP 8 Beta, where you will find working examples for your project.
When building a JBoss EAP 7.x image for OpenShift, the OpenShift builder image provisioned the JBoss EAP server instance. The configuration was provided by a combination of runtime variables, configuration snippets, and JBoss CLI scripts.
With JBoss EAP 8 Beta, the JBoss EAP Maven plugin 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 allows developers and operations teams to control and test their EAP deployments in their local environments, which provides significant benefits.
The JBoss EAP Maven plugin uses Galleon 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.
Prerequisites
- Helm CLI. Version 3.5+ (only required if you want to use Helm CLI instead of OpenShift Dev Console)
- OpenShift cluster. Version 4.11+
- Maven. Version 3.8.5+
Project setup
We're going to start with a simple "hello world" JBoss EAP 8 Beta application. You can check out the source from the GitHub page. We can create the deployment artifact from this project by running the following command from the folder you cloned your code into.
mvn clean package
Our application artifact should now be available at: ./target/helloworld.war. If you want to test this application in JBoss EAP 8 Beta, you can do so by following these instructions:
- Download the JBoss EAP 8 Beta distribution here.
- Extract the distribution into a local folder (e.g., ~/jboss-eap-8).
- Set the EAP_HOME environment variable as follows:
export EAP_HOME=~/jboss-eap-8
- Start JBoss EAP 8 Beta with the following command:
$EAP_HOME/bin/standalone.sh
- Connect to EAP using the CLI from the folder you cloned your code into by running the following command:
$EAP_HOME/bin/jboss-cli.sh --connect
- Deploy our application artifact as follows:
[standalone@localhost:9990 /] deploy ./target/helloworld.war
- You should now be able to access the sample application at http://localhost:8080/helloworld/HelloWorld.
- Shut down the JBoss EAP 8 Beta server.
Adding OpenShift support
To add OpenShift support, we're going to add the JBoss EAP Maven plugin to our project and create an OpenShift profile. To do this, add the following to the pom.xml file in the <profiles> section:
<profile>
<id>openshift</id>
<build>
<plugins>
<plugin>
<groupId>org.jboss.eap.plugins</groupId>
<artifactId>eap-maven-plugin</artifactId>
<version>1.0.0.Beta6-redhat-00001</version>
<configuration>
<channels>
<channel>
<groupId>org.jboss.eap.channels</groupId>
<artifactId>eap-8.0-beta</artifactId>
</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-packs>
<layers>
<layer>cloud-server</layer>
</layers>
<filename>ROOT.war</filename>
</configuration>
<executions>
<execution>
<goals>
<goal>package</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
Introducing this profile to our maven configuration makes the following updates:
- Creates an "openshift" profile with a "package" goal.
- Adds the eap-maven-plugin.
- Configures the eap-maven-plugin with feature packs. Feature packs are ZIP archives that are normally deployed to artifact repositories (such as Maven), where they can be used by Galleon tools. These features are then defined in predefined configuration layers that can be used to create installation configurations. The use of layers from feature packs enables the deployment of an EAP instance, providing minimal features to support the deployed application. For this project, we're adding two feature packs:
- org.jboss.eap:wildfly-ee-galleon-pack
- The wildfly-ee-galleon-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).
- org.jboss.eap.cloud:eap-cloud-galleon-pack
- The org.jboss.eap.cloud:eap-cloud-galleon-pack Galleon feature-pack provisions a set of additional features allowing you to configure a JBoss EAP server to run on the cloud.
- org.jboss.eap:wildfly-ee-galleon-pack
- Inclusion of the cloud-server layer. The cloud-server layer is the minimum layer required for applications deployed on OpenShift. This layer provides subsystems such as health and metrics.
- Setting the filename to ROOT.war ensures the application is deployed in the root context.
Testing the JBoss EAP Maven plugin
Now that we've added the OpenShift profile and eap-maven-plugin, we can test the provisioning of a JBoss EAP 8 Beta instance. To do this, we run the following command:
mvn package -Popenshift
This command will perform these tasks:
- Create a /target/server folder and deploy an instance of JBoss EAP. The JBoss EAP instance will only contain the functionality defined by the <layers> section of the pom.xml file, in this case, the cloud-server layer.
- Package the project code and name the resulting artifact ROOT.war.
- Start the JBoss EAP instance from the /target/server folder and deploy the ROOT.war artifact.
The output of the command should be as follows:
[INFO] Deploying ROOT.war
[disconnected /] embed-server --server-config=standalone.xml
[standalone@embedded /] deploy ROOT.war --name=ROOT.war --runtime-name=ROOT.war
[standalone@embedded /] stop-embedded-server
We can test the instance of JBoss EAP provisioned by the JBoss EAP Maven plugin by running the following command:
./target/server/bin/standalone.sh
This command will start JBoss EAP 8 Beta. Looking at the logs, you should see a couple of things of note:
INFO [org.jboss.as.server] (Controller Boot Thread) WFLYSRV0010: Deployed "ROOT.war" (runtime-name : "ROOT.war")
The packaged application has been deployed as ROOT.war. This will ensure the application is deployed to the root context.
INFO [org.jboss.as] (Controller Boot Thread) WFLYSRV0054: Admin console is not enabled
The admin console is not enabled for this instance of JBoss EAP. This is the recommended approach for JBoss EAP applications deployed on OpenShift.
Navigate to http://localhost:8080 (Figure 1).
Now that we are confident the eap-maven-plugin is configured correctly, we can move on to deploy the application to OpenShift.
Deploying to OpenShift
To deploy our application to OpenShift, we will utilize Helm charts using the OpenShift UI and the Helm CLI tool.
First, we need to create a Helm configuration by following these steps:
- Create a folder called "charts" in the folder you cloned the eap8-on-ocp code into.
- In this folder, create a file called
helm.yamlwith the following contents:
build:
uri: https://github.com/deewhyweb/eap8-on-ocp.git
ref: 8.0.x
deploy:
replicas: 1
- In this example, we're using a pre-prepared branch containing source code updated to include the eap-maven-plugin configuration. You can also use your repository by replacing the information in this yaml file.
- You will need to push the changes to pom.xml described above for the build to execute correctly.
- We're now ready to deploy our application to OpenShift.
Deploying the Helm chart using the OpenShift UI
Follow these steps to deploy the Helm chart in the OpenShift UI:
- Log in to OpenShift.
- Open the Developer UI.
- Click on Helm in the left-hand menu.
- Click on Install a Helm Chart from the developer catalog. This will bring you to the Helm Charts catalog page (Figure 2).
- In the Filter by keyword field, enter: "eap"
- From the list of Helm charts, select eap8
- Click on Install Helm Chart.
- Switch to the YAML view
- Paste the configuration we created in charts/helm.yaml, as shown in Figure 3.
- Click on Install to deploy the Helm chart.
Deploying the Helm chart using the Helm CLI
Now we need to deploy the Helm chart. We will use the Helm CLI. Follow these steps:
- Use the jboss-eap/eap8 Helm chart with our configuration:
helm install helloworld -f charts/helm.yaml --repo https://jbossas.github.io/eap-charts/ eap8
- When this command completes, you should see something like this:
NAME: helloworld
LAST DEPLOYED: Fri Dec 16 12:52:27 2022
NAMESPACE: eap8-helm
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
- Your EAP 8 application is building! To follow the build, run this command:
oc get build -w
(Note: Your deployment will report ErrImagePull and ImagePullBackOff until the build is complete. Once the build is complete, your image will be automatically rolled out.)
- To follow the deployment of your application, run the following command:
oc get deployment helloworld -w
Testing the application deployment
In the OpenShift UI, you should see two builds run and complete, then a pod will be deployed containing your JBoss EAP instance and application deployed (Figure 4).
To test your application, click on the route icon. Alternatively, to find the route with the OpenShift CLI, enter this command:
oc get routes
You should see something like this output:
NAME HOST/PORT PATH SERVICES PORT TERMINATION WILDCARD
helloworld helloworld-eap8-helm.apps.cluster-xxx.xxx.hostname.com helloworld <all> edge/Redirect None
Navigate to this route with http:// + host in your browser.
You should see Hello World! as with the local host instance we deployed earlier. Our application has now been successfully built and deployed to OpenShift.
Recap
JBoss EAP 8 Beta uses the eap-maven-plugin to provision and configure EAP for OpenShift images. In this article, we demonstrated how to add the eap-maven-plugin to an existing JBoss EAP 8 Beta application and the associated benefits. We then use this plugin to test the provisioning of a JBoss EAP 8 Beta server locally, and then deploy this application to OpenShift using the EAP 8 Helm chart.
Last updated: September 19, 2023