Using JBoss EAP on OpenShift Container Platform

Procedure

1. Set up a Maven project using the mvn command. The command creates the directory structure for the project and the pom.xml configuration file.

   Syntax

   $ mvn archetype:generate \
   -DgroupId=${group-to-which-your-application-belongs} \
   -DartifactId=${name-of-your-application} \
   -DarchetypeGroupId=org.apache.maven.archetypes \
   -DarchetypeArtifactId=maven-archetype-webapp \
   -DinteractiveMode=false

   Example

   $ mvn archetype:generate \
   -DgroupId=com.example.app \
   -DartifactId=simple-webapp-example \
   -DarchetypeGroupId=org.apache.maven.archetypes \
   -DarchetypeArtifactId=maven-archetype-webapp \
   -DinteractiveMode=false

2. Navigate to the application root directory:

   Syntax

   $ cd <name-of-your-application>

   Example

   $ cd simple-webapp-example

3. Replace the content of the generated pom.xml file with the following text:

   <?xml version="1.0" encoding="UTF-8"?>
   
   <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
   
     <groupId>com.example.app</groupId>
     <artifactId>simple-webapp-example</artifactId>
     <version>1.0-SNAPSHOT</version>
     <packaging>war</packaging>
   
     <name>simple-webapp-example Maven Webapp</name>
     <!-- FIXME change it to the project's website -->
     <url>http://www.example.com</url>
   
     <properties>
       <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
       <version.maven.war.plugin>3.3.2</version.maven.war.plugin>
       <version.eap.plugin>1.0.0.Beta-redhat-00001</version.eap.plugin>
     </properties>
   
     <repositories>
       <repository>
           <id>jboss</id>
           <url>https://maven.repository.redhat.com/earlyaccess/all/</url>
           <snapshots>
               <enabled>false</enabled>
           </snapshots>
       </repository>
     </repositories>
     <pluginRepositories>
       <pluginRepository>
           <id>jboss</id>
           <url>https://maven.repository.redhat.com/earlyaccess/all/</url>
           <snapshots>
               <enabled>false</enabled>
           </snapshots>
       </pluginRepository>
     </pluginRepositories>
   
     <dependencies>
       <dependency>
         <groupId>jakarta.servlet</groupId>
         <artifactId>jakarta.servlet-api</artifactId>
         <version>6.0.0</version>
         <scope>provided</scope>
       </dependency>
       <dependency>
         <groupId>org.wildfly.security</groupId>
         <artifactId>wildfly-elytron-auth-server</artifactId>
         <version>1.19.0.Final</version>
       </dependency>
     </dependencies>
   
   <build>
       <finalName>${project.artifactId}</finalName>
       <plugins>
           <plugin>
               <groupId>org.apache.maven.plugins</groupId>
               <artifactId>maven-war-plugin</artifactId>
               <version>${version.maven.war.plugin}</version>
           </plugin>
           <plugin>
               <groupId>org.jboss.eap.plugins</groupId>
               <artifactId>eap-maven-plugin</artifactId>
               <version>${version.eap.plugin}</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>
                       <layer>elytron-oidc-client</layer>
                   </layers>
                   <galleon-options>
                           <jboss-fork-embedded>true</jboss-fork-embedded>
                   </galleon-options>
               </configuration>
               <executions>
                   <execution>
                       <goals>
                           <goal>package</goal>
                       </goals>
                   </execution>
               </executions>
           </plugin>
       </plugins>
   </build>
   </project>

4. Create a directory to store the Java files.

   Syntax

   $ mkdir -p src/main/java/<path_based_on_artifactID>

   Example

   $ mkdir -p src/main/java/com/example/app

5. Navigate to the new directory.

   Syntax

   $ cd src/main/java/<path_based_on_artifactID>

   Example

   $ cd src/main/java/com/example/app

6. Create a file SecuredServlet.java with the following content:

   package com.example.app;
   
   import java.io.IOException;
   import java.io.PrintWriter;
   import java.security.Principal;
   import java.util.ArrayList;
   import java.util.Collection;
   import java.util.Iterator;
   import java.util.List;
   import java.util.Set;
   
   import jakarta.servlet.ServletException;
   import jakarta.servlet.annotation.WebServlet;
   import jakarta.servlet.http.HttpServlet;
   import jakarta.servlet.http.HttpServletRequest;
   import jakarta.servlet.http.HttpServletResponse;
   import org.wildfly.security.auth.server.SecurityDomain;
   import org.wildfly.security.auth.server.SecurityIdentity;
   import org.wildfly.security.authz.Attributes;
   import org.wildfly.security.authz.Attributes.Entry;
   /**
    * A simple secured HTTP servlet. It returns the user name and
    * attributes obtained from the logged-in user's Principal. If
    * there is no logged-in user, it returns the text
    * "NO AUTHENTICATED USER".
    */
   
   @WebServlet("/secured")
   public class SecuredServlet extends HttpServlet {
   
       @Override
       protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
           try (PrintWriter writer = resp.getWriter()) {
   
           	Principal user = req.getUserPrincipal();
           	SecurityIdentity identity = SecurityDomain.getCurrent().getCurrentSecurityIdentity();
           	Attributes identityAttributes = identity.getAttributes();
           	Set <String> keys = identityAttributes.keySet();
           	String attributes = "<ul>";
   
           	for (String attr : keys) {
           		attributes += "<li> " +  attr + " : " + identityAttributes.get(attr).toString() + "</li>";
           	}
   
           	attributes+="</ul>";
           	writer.println("<html>");
           	writer.println("  <head><title>Secured Servlet</title></head>");
           	writer.println("  <body>");
           	writer.println("    <h1>Secured Servlet</h1>");
           	writer.println("    <p>");
           	writer.print(" Current Principal '");
           	writer.print(user != null ? user.getName() : "NO AUTHENTICATED USER");
           	writer.print("'");
           	writer.print(user != null ? "\n" + attributes : "");
           	writer.println("    </p>");
           	writer.println("  </body>");
           	writer.println("</html>");
           }
       }
   
   }

7. Configure the application’s web.xml to protect the application resources.

   Example

   <?xml version="1.0" encoding="UTF-8"?>
   
   <web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
       metadata-complete="false">
   
       <security-constraint>
           <web-resource-collection>
               <web-resource-name>secured</web-resource-name>
               <url-pattern>/secured</url-pattern>
           </web-resource-collection>
   
           <auth-constraint>
               <role-name>Users</role-name>
           </auth-constraint>
       </security-constraint>
   
       <login-config>
           <auth-method>OIDC</auth-method>
       </login-config>
   
       <security-role>
           <role-name>*</role-name>
       </security-role>
   </web-app>

   In this example, only the users with the role Users can access the application.

Procedure

1. Deploy your application code to Git Repository.

2. Create a secret containing the OIDC configuration.

   1. Create a file named oidc-secret.yaml using the following content:

      apiVersion: v1
      kind: Secret
      metadata:
        name: oidc-secret
      type: Opaque
      stringData:
        OIDC_PROVIDER_NAME: rh-sso
        OIDC_USER_NAME: demo
        OIDC_USER_PASSWORD: demo
        OIDC_SECURE_DEPLOYMENT_SECRET: mysecret

   2. Use the following command to create a secret:

      $ oc apply -f oidc-secret.yaml

3. Create a file named helm.yaml using the following content:

   build:
     uri: [URL TO YOUR GIT REPOSITORY]
   deploy:
     envFrom:
   	- secretRef:
       	  name: oidc-secret

4. Deploy the example application using JBoss EAP Helm charts:

   $ helm install eap-oidc-test-app -f helm.yaml jboss-eap/eap8

5. Add the environment variables to the oidc-secret.yaml file to configure the OIDC provider URL and application hostname.

   yaml
   stringData:
     ...
     OIDC_HOSTNAME_HTTPS: <host of the application>
     OIDC_PROVIDER_URL: https://<host of the SSO provider>/auths/realms/JBossEAP

   The value for OIDC_HOSTNAME_HTTPS corresponds to the following output:

   echo $(oc get route eap-oidc-test-app --template='{{ .spec.host }}')

   The value for OIDC_PROVIDER_URL corresponds to the following output:

   echo https://$(oc get route sso --template='{{ .spec.host }}')/auth/realms/JBossEAP

   A route discovery attempt is made if OIDC_HOSTNAME_HTTP(S) is not set. To enable route discovery, the OpenShift user must be able to list the route resources. For example, to create and associate the routeview role with the view user, use the following oc command:

   $ oc create role <role-name> --verb=list --resource=route
   
   $ oc adm policy add-role-to-user <role-name> <user-name> --role-namespace=<your namespace>

6. Update the secret with oc apply -f oidc-secret.yaml.

7. Deploy the application again to ensure OpenShift uses the new environment variables:

   $ oc rollout restart deploy eap-oidc-test-app

Verification

1. In your browser, navigate to https://<eap-oidc-test-app route>/.

   You will be redirected to Red Hat Single Sign-On login page.

2. Access the secured servlet.

3. Log in with the following credentials:

   username: demo
   password: demo

   A page appears that contains the Principal ID.

Procedure

1. Set up the Maven project.

   $ mvn archetype:generate \
   -DgroupId=GROUP_ID \
   -DartifactId=ARTIFACT_ID \
   -DarchetypeGroupId=org.apache.maven.archetypes \
   -DarchetypeArtifactId=maven-archetype-webapp \
   -DinteractiveMode=false

   Where GROUP_ID is the groupId of your project and ARTIFACT_ID is the artifactId of your project.

2. To configure the Maven to automatically manage versions for the Jakarta EE artifacts in the jboss-eap-ee BOM, add the BOM to the <dependencyManagement> section of the project pom.xml file. For example:

   <dependencyManagement>
     <dependencies>
       <dependency>
           <groupId>org.jboss.bom</groupId>
           <artifactId>jboss-eap-ee</artifactId>
           <version>8.0.0.Beta</version>
           <type>pom</type>
           <scope>import</scope>
       </dependency>
     </dependencies>
   </dependencyManagement>

3. Add the servlet API artifact, which is managed by the BOM, to the <dependencies> section of the project pom.xml file, as shown in the following example:

   <dependency>
       <groupId>jakarta.servlet</groupId>
       <artifactId>jakarta.servlet-api</artifactId>
   </dependency>

4. Create a Java file TestServlet.java with the following content and save the file in the APPLICATION_ROOT/src/main/java/com/example/simple/ directory.

   package com.example.simple;
   import jakarta.servlet.annotation.WebServlet;
   import jakarta.servlet.http.HttpServlet;
   import jakarta.servlet.http.HttpServletRequest;
   import jakarta.servlet.http.HttpServletResponse;
   import java.io.IOException;
   import java.io.PrintWriter;
   @WebServlet(urlPatterns = "/hello")
   public class TestServlet extends HttpServlet {
       @Override
       protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
           PrintWriter writer = resp.getWriter();
           writer.println("Hello World!");
           writer.close();
       }
   }

Procedure

1. Configure Maven to retrieve the JBoss EAP BOM and JBoss EAP Maven plug-in from a remote repository by adding the following content to the pom.xml file:

   <repositories>
       <repository>
           <id>jboss</id>
           <url>https://maven.repository.redhat.com/earlyaccess/all/</url>
           <snapshots>
               <enabled>false</enabled>
           </snapshots>
       </repository>
   </repositories>
   <pluginRepositories>
       <pluginRepository>
           <id>jboss</id>
           <url>https://maven.repository.redhat.com/earlyaccess/all/</url>
           <snapshots>
               <enabled>false</enabled>
           </snapshots>
       </pluginRepository>
   </pluginRepositories>

2. Add the following content to the <build> element of the pom.xml file. You must specify the latest version of the JBoss EAP Maven plug-in. For example:

   <plugins>
       <plugin>
           <groupId>org.jboss.eap.plugins</groupId>
           <artifactId>eap-maven-plugin</artifactId>
           <version>1.0.0.Beta-redhat-00001</version>
           <configuration>
               <channels>
                	<channel>
                       <groupId>org.jboss.eap.channels</groupid> 1
                       <artifactId>eap-8.0-beta</artifactId>
                   </channel>
               </channels>
               <feature-packs>
                   <feature-pack>
                       <location>org.jboss.eap:wildfly-ee-galleon-pack</location> 2
                   </feature-pack>
                   <feature-pack>
                       <location>org.jboss.eap.cloud:eap-cloud-galleon-pack</location> 3
                   </feature-pack>
               </feature-packs>
               <layers>
                   <layer>cloud-server</layer> 4
               </layers>
               <runtime-name>ROOT.war</runtime-name> 5
           </configuration>
           <executions>
               <execution>
                   <goals>
                       <goal>package</goal> 6
                   </goals>
               </execution>
           </executions>
       </plugin>
   </plugins>

   1

   This specifies the JBoss EAP 8.0 Beta channel in which the JBoss EAP server artifacts are defined.

   2

   You can retrieve the version of this feature pack from the JBoss EAP channel. The Galleon feature-pack includes Galleon layers such as cloud-server for provisioning trimmed JBoss EAP servers.

   3

   This feature pack adjusts the server Galleon layers for the cloud. It is necessary to use this feature pack to build applications for OpenShift.

   4

   This Galleon layer provisions a server with features that are necessary when running JBoss EAP applications in the cloud.

   5

   With this configuration option, you can register your deployment in the HTTP root context.

   6

   With this plug-in goal, you can provision the server, deploy your application, apply custom configured CLI scripts, and copy custom content into the server installation.

3. Package the application.

   $ mvn package

   The directory target/server contains a server and application that are ready for use for debugging or development purposes. In the JBoss EAP S2I build context, the server provisioned by the JBoss EAP maven-plugin is installed in the JBoss EAP image at the /opt/server location. For more information see Building Applications Images using Source-to-Image (S2I) in OpenShift.

Procedure

1. In the OpenShift Container Platform web console, navigate to Operators→ OperatorHub.
2. Scroll down or type EAP into the Filter by keyword box to find the EAP operator.
3. Select JBoss EAP operator and click Install.

4. On the Create Operator Subscription page:

   1. Select one of the following:

      • All namespaces on the cluster (default) installs the operator in the default openshift-operators namespace to watch and be made available to all namespaces in the cluster. This option is not always available.
      • A specific namespace on the cluster installs the operator in a specific, single namespace that you choose. The operator is made available for use only in this single namespace.
   2. Select an Update Channel.
   3. Select Automatic or Manual approval strategy, as described earlier.

5. Click Subscribe to make the EAP operator available to the selected namespaces on this OpenShift Container Platform cluster.

   1. If you selected a manual approval strategy, the subscription’s upgrade status remains Upgrading until you review and approve its install plan. After you approve the install plan on the Install Plan page, the subscription upgrade status moves to Up to date.
   2. If you selected an automatic approval strategy, the upgrade status moves to Up to date without intervention.

6. After the subscription’s upgrade status is Up to date, select Operators → Installed Operators to verify that the EAP ClusterServiceVersion (CSV) shows up and its Status changes to InstallSucceeded in the relevant namespace.

   Note

   For the All namespaces…​ installation mode, the status displayed is InstallSucceeded in the openshift-operators namespace. In other namespaces the status displayed is Copied. . If the Status field does not change to InstallSucceeded, check the logs in any pod in the openshift-operators project (or other relevant namespace if A specific namespace…​ installation mode was selected) on the Workloads → Pods page that are reporting issues to troubleshoot further.

Procedure

1. View the list of operators available to the cluster from the OperatorHub:

   $ oc get packagemanifests -n openshift-marketplace | grep eap
   NAME        CATALOG               AGE
   ...
   eap         Red Hat Operators     43d
   ...

2. Create a Subscription object YAML file (for example, eap-operator-sub.yaml) to subscribe a namespace to your EAP operator. The following is an example Subscription object YAML file:

   apiVersion: operators.coreos.com/v1alpha1
   kind: Subscription
   metadata:
     name: eap
     namespace: openshift-operators
   spec:
     channel: stable
     installPlanApproval: Automatic
     name: eap 1
     source:  redhat-operators 2
     sourceNamespace: openshift-marketplace

   1

   Name of the operator to subscribe to.

   2

   The EAP operator is provided by the redhat-operators CatalogSource.

   For information about channels and approval strategy, see the web console version of this procedure.

3. Create the Subscription object from the YAML file:

   $ oc apply -f eap-operator-sub.yaml
   $ oc get csv -n openshift-operators
   NAME                  DISPLAY     VERSION   REPLACES   PHASE
   eap-operator.v1.0.0   JBoss EAP   1.0.0                Succeeded

   The EAP operator is successfully installed. At this point, the OLM is aware of the EAP operator. A ClusterServiceVersion (CSV) for the operator appears in the target namespace, and APIs provided by the EAP operator is available for creation.

Procedure

1. Open your web browser and log on to OperatorHub.
2. Select the Project or namespace you want to use for your Java application.
3. Navigate to Installed Operator and select JBoss EAP operator.
4. On the Overview tab, click the Create Instance link.

5. Specify the application image details.

   The application image specifies the Docker image that contains the Java application. The image must be built using the JBoss EAP for OpenShift Source-to-Image (S2I) build image. If the applicationImage field corresponds to an imagestreamtag, any change to the image triggers an automatic upgrade of the application.

   You can provide any of the following references of the JBoss EAP for OpenShift application image:

   • The name of the image: mycomp/myapp
   • A tag: mycomp/myapp:1.0
   • A digest: mycomp/myapp:@sha256:0af38bc38be93116b6a1d86a9c78bd14cd527121970899d719baf78e5dc7bfd2
   • An imagestreamtag: my-app:latest

6. Specify the size of the application. For example:

   spec:
     replicas:2

7. Configure the application environment using the env spec. The Environment variables can come directly from values, such as POSTGRESQL_SERVICE_HOST or from Secret objects, such as POSTGRESQL_USER. For example:

   spec:
     env:
     - name: POSTGRESQL_SERVICE_HOST
       value: postgresql
     - name: POSTGRESQL_SERVICE_PORT
       value: '5432'
     - name: POSTGRESQL_DATABASE
       valueFrom:
         secretKeyRef:
           key: database-name
           name: postgresql
     - name: POSTGRESQL_USER
       valueFrom:
         secretKeyRef:
           key: database-user
           name: postgresql
     - name: POSTGRESQL_PASSWORD
       valueFrom:
         secretKeyRef:
           key: database-password
           name: postgresql

8. Complete the following optional configurations that are relevant to your application deployment:

   • Specify the storage requirements for the server data directory. For more information, see Configuring Persistent Storage for Applications.

   • Specify the name of the Secret you created in WildFlyServerSpec to mount it as a volume in the pods running the application. For example:

     spec:
       secrets:
         - my-secret

     The Secret is mounted at /etc/secrets/<secret name> and each key/value is stored as a file. The name of the file is the key and the content is the value. The Secret is mounted as a volume inside the pod. The following example demonstrates commands that you can use to find key values:

     $ ls /etc/secrets/my-secret/
     my-key  my-password
     $ cat /etc/secrets/my-secret/my-key
     devuser
     $ cat /etc/secrets/my-secret/my-password
     my-very-secure-pasword

     Note

     Modifying a Secret object might lead to project inconsistencies. Instead of modifying an existing Secret object, Red Hat recommends creating a new object with the same content as that of the old one. You can then update the content as required and change the reference in operator custom resource (CR) from old to new. This is considered a new CR update and the pods are reloaded.

   • Specify the name of the ConfigMap you created in WildFlyServerSpec to mount it as a volume in the pods running the application. For example:

     spec:
       configMaps:
       - my-config

     The ConfigMap is mounted at /etc/configmaps/<configmap name> and each key/value is stored as a file. The name of the file is the key and the content is the value. The ConfigMap is mounted as a volume inside the pod. To find the key values:

     $ ls /etc/configmaps/my-config/
     key1 key2
     $ cat /etc/configmaps/my-config/key1
     value1
     $ cat /etc/configmaps/my-config/key2
     value2

     Note

     Modifying a ConfigMap might lead to project inconsistencies. Instead of modifying an existing ConfigMap, Red Hat recommends creating a new ConfigMap with the same content as that of the old one. You can then update the content as required and change the reference in operator custom resource (CR) from old to new. This is considered a new CR update and the pods are reloaded.

   • If you choose to have your own standalone ConfigMap, provide the name of the ConfigMap as well as the key for the standalone.xml file:

       standaloneConfigMap:
         name: clusterbench-config-map
         key: standalone.xml

     Note

     Creating a ConfigMap from the standalone.xml file is not supported in JBoss EAP 8-beta.

   • If you want to disable the default HTTP route creation in OpenShift, set disableHTTPRoute to true:

     spec:
       disableHTTPRoute: true

Procedure

1. In the OpenShift Container Platform web console, navigate to Monitoring→ Metrics.
2. On the Metrics screen, type the name of your application in the text box to select your application. The metrics for your application appear on the screen.

Procedure

1. From the Operators→ Installed Operators page, select JBoss EAP.
2. On the right-hand side of the Operator Details page, select Uninstall Operator from the Actions drop-down menu.
3. When prompted by the Remove Operator Subscription window, optionally select the Also completely remove the Operator from the selected namespace check box if you want all components related to the installation to be removed. This removes the CSV, which in turn removes the pods, deployments, custom resource definitions (CRDs), and custom resources (CRs) associated with the operator.
4. Click Remove. The EAP operator stops running and no longer receives updates.

Procedure

1. Check the current version of the EAP operator subscription in the currentCSV field:

   $ oc get subscription eap-operator -n openshift-operators -o yaml | grep currentCSV
     currentCSV: eap-operator.v1.0.0

2. Delete the EAP operator’s subscription:

   $ oc delete subscription eap-operator -n openshift-operators
   subscription.operators.coreos.com "eap-operator" deleted

3. Delete the CSV for the EAP operator in the target namespace using the currentCSV value from the previous step:

   $ oc delete clusterserviceversion eap-operator.v1.0.0 -n openshift-operators
   clusterserviceversion.operators.coreos.com "eap-operator.v1.0.0" deleted

Procedure

1. Configure the resources:

   apiVersion: wildfly.org/v1alpha1
   kind: WildFlyServer
   metadata:
     name: eap-helloworld
   spec:
     applicationImage: 'eap-helloworld:latest'
     replicas: 1
     resources:
       limits:
         cpu: 500m
         memory: 2Gi
       requests:
         cpu: 100m
         memory: 1Gi

   Important

   You must specify the resource limits and requests for containers in a pod for autoscaling to work as expected.

2. Create the Horizontal pod autoscaler:

   oc autoscale wildflyserver/eap-helloworld --cpu-percent=50 --min=1 --max=10

1. Identify the name of the build configuration to apply MAVEN_MIRROR_URL variable against.

   oc get bc -o name
   buildconfig/eap

2. Update build configuration of eap with a MAVEN_MIRROR_URL environment variable.

   oc env bc/eap MAVEN_MIRROR_URL="https://10.0.0.1:8443/repository/internal/"
   buildconfig "eap" updated

3. Verify the setting.

   oc env bc/eap --list
   # buildconfigs eap
   MAVEN_MIRROR_URL=https://10.0.0.1:8443/repository/internal/

4. Schedule new build of the application.