Language:
Format:

Chapter 7. Reference Information

Note

The content in this section is derived from the engineering documentation for this image. It is provided for reference as it can be useful for development purposes and for testing beyond the scope of the product documentation.

7.1. Persistent Templates

The JBoss EAP database templates, which deploy JBoss EAP and database pods, have both ephemeral and persistent variations.

Persistent templates include an environment variable to provision a persistent volume claim, which binds with an available persistent volume to be used as a storage volume for the JBoss EAP for OpenShift deployment. Information, such as timer schema, log handling, or data updates, is stored on the storage volume, rather than in ephemeral container memory. This information persists if the pod goes down for any reason, such as project upgrade, deployment rollback, or an unexpected error.

Without a persistent storage volume for the deployment, this information is stored in the container memory only, and is lost if the pod goes down for any reason.

For example, an EE timer backed by persistent storage continues to run if the pod is restarted. Any events triggered by the timer during the restart process are enacted when the application is running again.

Conversely, if the EE timer is running in the container memory, the timer status is lost if the pod is restarted, and starts from the beginning when the pod is running again.

7.2. Information Environment Variables

The following environment variables are designed to provide information to the image and should not be modified by the user:

Table 7.1. Information Environment Variables

Variable Name	Description and Value
JBOSS_IMAGE_NAME	The image names. Values: `jboss-eap-7/eap74-openjdk8-openshift-rhel7` (JDK 8 / RHEL 7) `jboss-eap-7/eap74-openjdk11-openshift-rhel8` (JDK 11 / RHEL 8)
JBOSS_IMAGE_VERSION	The image version. Value: This is the image version number. See the Red Hat Container Catalog for the latest values: JDK 8 / RHEL 7 JDK 11 / RHEL 8
JBOSS_MODULES_SYSTEM_PKGS	A comma-separated list of JBoss EAP system modules packages that are available to applications. Value: `jdk.nashorn.api`
STI_BUILDER	Provides OpenShift S2I support for `jee` project types. Value: `jee`

7.3. Configuration environment variables

You can configure the following environment variables to adjust the image without requiring a rebuild.

Note

See the JBoss EAP documentation for other environment variables that are not listed here.

Table 7.2. Configuration environment variables

Variable Name	Description
AB_JOLOKIA_AUTH_OPENSHIFT	Switch on client authentication for OpenShift TLS communication. The value of this parameter can be `true`, `false`, or a relative distinguished name, which must be contained in a presented client’s certificate. The default CA cert is set to `/var/run/secrets/kubernetes.io/serviceaccount/ca.crt`. Set to `false` to disable client authentication for OpenShift TLS communication. Set to `true` to enable client authentication for OpenShift TLS communication using the default CA certificate and client principal. Set to a relative distinguished name, for example `cn=someSystem`, to enable client authentication for OpenShift TLS communication but override the client principal. This distinguished name must be contained in a presented client’s certificate.
AB_JOLOKIA_CONFIG	If set, uses this fully qualified file path for the Jolokia JVM agent properties, which are described in the Jolokia reference documentation. If you set your own Jolokia properties config file, the rest of the Jolokia settings in this document are ignored. If not set, `/opt/jolokia/etc/jolokia.properties` is created using the settings as defined in the Jolokia reference documentation. Example value: `/opt/jolokia/custom.properties`
AB_JOLOKIA_DISCOVERY_ENABLED	Enable Jolokia discovery. Defaults to `false`.
AB_JOLOKIA_HOST	Host address to bind to. Defaults to `0.0.0.0`. Example value: `127.0.0.1`
AB_JOLOKIA_HTTPS	Switch on secure communication with HTTPS. By default self-signed server certificates are generated if no `serverCert` configuration is given in `AB_JOLOKIA_OPTS`. Example value: `true`
AB_JOLOKIA_ID	Agent ID to use. The default value is the `$HOSTNAME`, which is the container id. Example value: `openjdk-app-1-xqlsj`
AB_JOLOKIA_OFF	If set to `true`, disables activation of Jolokia, which echos an empty value. Jolokia is enabled by default.
AB_JOLOKIA_OPTS	Additional options to be appended to the agent configuration. They should be given in the format `key=value, key=value, …`. Example value: `backlog=20`
AB_JOLOKIA_PASSWORD	The password for basic authentication. By default, authentication is switched off. Example value: `mypassword`
AB_JOLOKIA_PASSWORD_RANDOM	Determines if a random `AB_JOLOKIA_PASSWORD` should be generated. Set to `true` to generate a random password. The generated value is saved in the `/opt/jolokia/etc/jolokia.pw` file.
AB_JOLOKIA_PORT	The port to listen to. Defaults to `8778`. Example value: `5432`
AB_JOLOKIA_USER	The name of the user to use for basic authentication. Defaults to `jolokia`. Example value: `myusername`
AB_PROMETHEUS_ENABLE	If set to `true`, this variable activates the `jmx-exporter` java agent that exposes Prometheus format metrics. Default is set to `false`. Note The MicroProfile Metrics subsystem is the preferred method to expose data in the Prometheus format. For more information about the MicroProfile Metrics susbsystem, see Eclipse MicroProfile in the Configuration Guide for JBoss EAP.
AB_PROMETHEUS_JMX_EXPORTER_CONFIG	The path within the container to a user-specified `configuration.yaml` for the `jmx-exporter` agent to use instead of the default `configuration.yaml` file. To find out more about the `S2I` mechanism to incorporate additional configuration files, see S2I Artifacts.
AB_PROMETHEUS_JMX_EXPORTER_PORT	The port on which the `jmx-exporter` agent listens for scrapes from the Prometheus server. Default is `9799`. The agent listens on `localhost`. Metrics can be made available outside of the container by configuring the `DeploymentConfig` API for the application to include the service exposing this endpoint.
CLI_GRACEFUL_SHUTDOWN	If set to any non-zero length value, the image will prevent shutdown with the `TERM` signal and will require execution of the `shutdown` command using the JBoss EAP management CLI. Example value: `true`
CONTAINER_HEAP_PERCENT	Set the maximum Java heap size, as a percentage of available container memory. Example value: `0.5`
CUSTOM_INSTALL_DIRECTORIES	A list of comma-separated directories used for installation and configuration of artifacts for the image during the S2I process. Example value: `custom,shared`
DEFAULT_JMS_CONNECTION_FACTORY	This value is used to specify the default JNDI binding for the Jakarta Messaging connection factory, for example `jms-connection-factory='java:jboss/DefaultJMSConnectionFactory'`. Example value: `java:jboss/DefaultJMSConnectionFactory`
DISABLE_EMBEDDED_JMS_BROKER	The use of an embedded messaging broker in OpenShift containers is deprecated. Support for an embedded broker will be removed in a future release. If the following conditions are true, a warning is logged. A container is configured to use an embedded messaging broker. A remote broker is not configured for the container. This variable is not set or is set with a value of `false`. If this variable is included with the value set to `true`, the embedded messaging broker is disabled, and no warning is logged. Include this variable set to `true` for any container that is not configured with remote messaging destinations.
ENABLE_ACCESS_LOG	Enable logging of access messages to the standard output channel. Logging of access messages is implemented using following methods: The JBoss EAP 6.4 OpenShift image uses a custom JBoss Web Access Log Valve. The JBoss EAP for OpenShift image uses the Undertow `AccessLogHandler`. Defaults to `false`.
INITIAL_HEAP_PERCENT	Set the initial Java heap size, as a percentage of the maximum heap size. Example value: `0.5`
JAVA_OPTS_APPEND	Server startup options. Example value: `-Dfoo=bar`
JBOSS_MODULES_SYSTEM_PKGS_APPEND	A comma-separated list of package names that will be appended to the `JBOSS_MODULES_SYSTEM_PKGS` environment variable. Example value: `org.jboss.byteman`
JGROUPS_CLUSTER_PASSWORD	Password used to authenticate the node so it is allowed to join the JGroups cluster. Required, when using `ASYM_ENCRYPT` JGroups cluster traffic encryption protocol. If not set, authentication is disabled, cluster communication is not encrypted and a warning is issued. Optional, when using `SYM_ENCRYPT` JGroups cluster traffic encryption protocol. Example value: `mypassword`
JGROUPS_ENCRYPT_KEYSTORE	Name of the keystore file within the secret specified via `JGROUPS_ENCRYPT_SECRET` variable, when using `SYM_ENCRYPT` JGroups cluster traffic encryption protocol. If not set, cluster communication is not encrypted and a warning is issued. Example value: `jgroups.jceks`
JGROUPS_ENCRYPT_KEYSTORE_DIR	Directory path of the keystore file within the secret specified via `JGROUPS_ENCRYPT_SECRET` variable, when using `SYM_ENCRYPT` JGroups cluster traffic encryption protocol. If not set, cluster communication is not encrypted and a warning is issued. Example value: `/etc/jgroups-encrypt-secret-volume`
JGROUPS_ENCRYPT_NAME	Name associated with the server’s certificate, when using `SYM_ENCRYPT` JGroups cluster traffic encryption protocol. If not set, cluster communication is not encrypted and a warning is issued. Example value: `jgroups`
JGROUPS_ENCRYPT_PASSWORD	Password used to access the keystore and the certificate, when using `SYM_ENCRYPT` JGroups cluster traffic encryption protocol. If not set, cluster communication is not encrypted and a warning is issued. Example value: `mypassword`
JGROUPS_ENCRYPT_PROTOCOL	JGroups protocol to use for encryption of cluster traffic. Can be either `SYM_ENCRYPT` or `ASYM_ENCRYPT`. Defaults to `SYM_ENCRYPT`. Example value: `ASYM_ENCRYPT`
JGROUPS_ENCRYPT_SECRET	Name of the secret that contains the `JGroups keystore` file used for securing the JGroups communications when using `SYM_ENCRYPT` JGroups cluster traffic encryption protocol. If not set, cluster communication is not encrypted and a warning is issued. Example value: `eap7-app-secret`
JGROUPS_PING_PROTOCOL	JGroups protocol to use for node discovery. Can be either `dns.DNS_PING` or `kubernetes.KUBE_PING`.
MQ_SIMPLE_DEFAULT_PHYSICAL_DESTINATION	For backwards compatibility, set to `true` to use `MyQueue` and `MyTopic` as physical destination name defaults instead of `queue/MyQueue` and `topic/MyTopic`.
OPENSHIFT_DNS_PING_SERVICE_NAME	Name of the service exposing the ping port on the servers for the DNS discovery mechanism. Example value: `eap-app-ping`
OPENSHIFT_DNS_PING_SERVICE_PORT	The port number of the ping port for the DNS discovery mechanism. If not specified, an attempt is made to discover the port number from the SRV records for the service, otherwise the default `8888` is used. Defaults to `8888`.
OPENSHIFT_KUBE_PING_LABELS	Clustering labels selector for the Kubernetes discovery mechanism. Example value: `app=eap-app`
OPENSHIFT_KUBE_PING_NAMESPACE	Clustering project namespace for the Kubernetes discovery mechanism. Example value: `myproject`
SCRIPT_DEBUG	If set to `true`, ensures that the Bash scripts are executed with the `-x` option, printing the commands and their arguments as they are executed.

7.4. Application Templates

Table 7.3. Application Templates

Variable Name Description

Variable Name	Description
AUTO_DEPLOY_EXPLODED	Controls whether exploded deployment content should be automatically deployed. Example value: `false`

AUTO_DEPLOY_EXPLODED

Controls whether exploded deployment content should be automatically deployed.

Example value: false

7.5. Exposed Ports

Table 7.4. Exposed Ports

Port Number	Description
8443	HTTPS
8778	Jolokia Monitoring

7.6. Datasources

Datasources are automatically created based on the value of some of the environment variables.

The most important environment variable is DB_SERVICE_PREFIX_MAPPING, as it defines JNDI mappings for the datasources. The allowed value for this variable is a comma-separated list of POOLNAME-DATABASETYPE=PREFIX triplets, where:

POOLNAME is used as the pool-name in the datasource.
DATABASETYPE is the database driver to use.
PREFIX is the prefix used in the names of environment variables that are used to configure the datasource.

7.6.1. JNDI Mappings for Datasources

For each POOLNAME-DATABASETYPE=PREFIX triplet defined in the DB_SERVICE_PREFIX_MAPPING environment variable, the launch script creates a separate datasource, which is executed when running the image.

Note

The first part (before the equal sign) of the DB_SERVICE_PREFIX_MAPPING should be lowercase.

The DATABASETYPE determines the driver for the datasource.

For more information about configuring a driver, see Modules, Drivers, and Generic Deployments. The JDK 8 image has drivers for postgresql and mysql configured by default.

Warning

Do not use any special characters for the POOLNAME parameter.

Database drivers

Support for using the Red Hat-provided internal datasource drivers with the JBoss EAP for OpenShift image is now deprecated. Red Hat recommends that you use JDBC drivers obtained from your database vendor for your JBoss EAP applications.

The following internal datasources are no longer provided with the JBoss EAP for OpenShift image:

MySQL
PostgreSQL

For more information about installing drivers, see Modules, Drivers, and Generic Deployments.

For more information on configuring JDBC drivers with JBoss EAP, see JDBC drivers in the JBoss EAP Configuration Guide.

Note that you can also create a custom layer to install these drivers and datasources if you want to add them to a provisioned server.

7.6.1.1. Datasource Configuration Environment Variables

To configure other datasource properties, use the following environment variables.

Important

Be sure to replace the values for POOLNAME, DATABASETYPE, and PREFIX in the following variable names with the appropriate values. These replaceable values are described in this section and in the Datasources section.

Variable Name	Description
POOLNAME_DATABASETYPE_SERVICE_HOST	Defines the database server’s host name or IP address to be used in the datasource’s `connection-url` property. Example value: `192.168.1.3`
POOLNAME_DATABASETYPE_SERVICE_PORT	Defines the database server’s port for the datasource. Example value: `5432`
PREFIX_BACKGROUND_VALIDATION	When set to `true` database connections are validated periodically in a background thread prior to use. Defaults to `false`, meaning the `validate-on-match` method is enabled by default instead.
PREFIX_BACKGROUND_VALIDATION_MILLIS	Specifies frequency of the validation, in milliseconds, when the `background-validation` database connection validation mechanism is enabled (`PREFIX_BACKGROUND_VALIDATION` variable is set to `true`). Defaults to `10000`.
PREFIX_CONNECTION_CHECKER	Specifies a connection checker class that is used to validate connections for the particular database in use. Example value: `org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker`
PREFIX_DATABASE	Defines the database name for the datasource. Example value: `myDatabase`
PREFIX_DRIVER	Defines Java database driver for the datasource. Example value: `postgresql`
PREFIX_EXCEPTION_SORTER	Specifies the exception sorter class that is used to properly detect and clean up after fatal database connection exceptions. Example value: `org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter`
PREFIX_JNDI	Defines the JNDI name for the datasource. Defaults to `java:jboss/datasources/POOLNAME_DATABASETYPE`, where `POOLNAME` and `DATABASETYPE` are taken from the triplet described above. This setting is useful if you want to override the default generated JNDI name. Example value: `java:jboss/datasources/test-postgresql`
PREFIX_JTA	Defines Jakarta Transactions option for the non-XA datasource. The XA datasources are already Jakarta Transactions capable by default. Defaults to `true`.
PREFIX_MAX_POOL_SIZE	Defines the maximum pool size option for the datasource. Example value: `20`
PREFIX_MIN_POOL_SIZE	Defines the minimum pool size option for the datasource. Example value: `1`
PREFIX_NONXA	Defines the datasource as a non-XA datasource. Defaults to `false`.
PREFIX_PASSWORD	Defines the password for the datasource. Example value: `password`
PREFIX_TX_ISOLATION	Defines the java.sql.Connection transaction isolation level for the datasource. Example value: `TRANSACTION_READ_UNCOMMITTED`
PREFIX_URL	Defines connection URL for the datasource. Example value: `jdbc:postgresql://localhost:5432/postgresdb`
PREFIX_USERNAME	Defines the username for the datasource. Example value: `admin`

When running this image in OpenShift, the POOLNAME_DATABASETYPE_SERVICE_HOST and POOLNAME_DATABASETYPE_SERVICE_PORT environment variables are set up automatically from the database service definition in the OpenShift application template, while the others are configured in the template directly as env entries in container definitions under each pod template.

7.6.1.2. Examples

These examples show how value of the DB_SERVICE_PREFIX_MAPPING environment variable influences datasource creation.

7.6.1.2.1. Single Mapping

Consider value test-postgresql=TEST.

This creates a datasource with java:jboss/datasources/test_postgresql name. Additionally, all the required settings like password and username are expected to be provided as environment variables with the TEST_ prefix, for example TEST_USERNAME and TEST_PASSWORD.

7.6.1.2.2. Multiple Mappings

You can specify multiple datasource mappings.

Note

Always separate multiple datasource mappings with a comma.

Consider the following value for the DB_SERVICE_PREFIX_MAPPING environment variable: cloud-postgresql=CLOUD,test-mysql=TEST_MYSQL.

This creates the following two datasources:

java:jboss/datasources/test_mysql
java:jboss/datasources/cloud_postgresql

Then you can use TEST_MYSQL prefix for configuring things like the username and password for the MySQL datasource, for example TEST_MYSQL_USERNAME. And for the PostgreSQL datasource, use the CLOUD_ prefix, for example CLOUD_USERNAME.

7.7. Clustering

7.7.1. Configuring a JGroups Discovery Mechanism

To enable JBoss EAP clustering on OpenShift, configure the JGroups protocol stack in your JBoss EAP configuration to use either the kubernetes.KUBE_PING or the dns.DNS_PING discovery mechanism.

Although you can use a custom standalone-openshift.xml configuration file, it is recommended that you use environment variables to configure JGroups in your image build.

The instructions below use environment variables to configure the discovery mechanism for the JBoss EAP for OpenShift image.

Important

If you use one of the available application templates to deploy an application on top of the JBoss EAP for OpenShift image, the default discovery mechanism is dns.DNS_PING.

The dns.DNS_PING and kubernetes.KUBE_PING discovery mechanisms are not compatible with each other. It is not possible to form a supercluster out of two independent child clusters, with one using the dns.DNS_PING mechanism for discovery and the other using the kubernetes.KUBE_PING mechanism. Similarly, when performing a rolling upgrade, the discovery mechanism needs to be identical for both the source and the target clusters.

7.7.1.1. Configuring KUBE_PING

To use the KUBE_PING JGroups discovery mechanism:

The JGroups protocol stack must be configured to use KUBE_PING as the discovery mechanism.
You can do this by setting the JGROUPS_PING_PROTOCOL environment variable to kubernetes.KUBE_PING:
```
JGROUPS_PING_PROTOCOL=kubernetes.KUBE_PING
```
The KUBERNETES_NAMESPACE environment variable must be set to your OpenShift project name. If not set, the server behaves as a single-node cluster (a "cluster of one"). For example:
```
KUBERNETES_NAMESPACE=PROJECT_NAME
```
The KUBERNETES_LABELS environment variable should be set. This should match the label set at the service level. If not set, pods outside of your application (albeit in your namespace) will try to join. For example:
```
KUBERNETES_LABELS=application=APP_NAME
```
Authorization must be granted to the service account the pod is running under to be allowed to access Kubernetes' REST API. This is done using the OpenShift CLI. The following example uses the default service account in the current project’s namespace:
```
oc policy add-role-to-user view system:serviceaccount:$(oc project -q):default -n $(oc project -q)
```
Using the eap-service-account in the project namespace:
```
oc policy add-role-to-user view system:serviceaccount:$(oc project -q):eap-service-account -n $(oc project -q)
```
Note
See Prepare OpenShift for Application Deployment for more information on adding policies to service accounts.

7.7.1.2. Configuring DNS_PING

To use the DNS_PING JGroups discovery mechanism:

The JGroups protocol stack must be configured to use DNS_PING as the discovery mechanism.
You can do this by setting the JGROUPS_PING_PROTOCOL environment variable to dns.DNS_PING:
```
JGROUPS_PING_PROTOCOL=dns.DNS_PING
```
The OPENSHIFT_DNS_PING_SERVICE_NAME environment variable must be set to the name of the ping service for the cluster.
```
OPENSHIFT_DNS_PING_SERVICE_NAME=PING_SERVICE_NAME
```
The OPENSHIFT_DNS_PING_SERVICE_PORT environment variable should be set to the port number on which the ping service is exposed. The DNS_PING protocol attempts to discern the port from the SRV records, otherwise it defaults to 8888.
```
OPENSHIFT_DNS_PING_SERVICE_PORT=PING_PORT
```
A ping service which exposes the ping port must be defined. This service should be headless (ClusterIP=None) and must have the following:
1. The port must be named.
2. The service must be annotated with the service.alpha.kubernetes.io/tolerate-unready-endpoints and the publishNotReadyAddresses properties, both set to true.
  Note
  Use both the service.alpha.kubernetes.io/tolerate-unready-endpoints and the publishNotReadyAddresses properties to ensure that the ping service works in both the older and newer OpenShift releases.
  Omitting these annotations result in each node forming its own "cluster of one" during startup. Each node then merges its cluster into the other nodes' clusters after startup, because the other nodes are not detected until after they have started.
```
kind: Service
apiVersion: v1
spec:
    publishNotReadyAddresses: true
    clusterIP: None
    ports:
    - name: ping
      port: 8888
    selector:
        deploymentConfig: eap-app
metadata:
    name: eap-app-ping
    annotations:
        service.alpha.kubernetes.io/tolerate-unready-endpoints: "true"
        description: "The JGroups ping port for clustering."
```

Note

DNS_PING does not require any modifications to the service account and works using the default permissions.

7.7.2. Configuring JGroups to Encrypt Cluster Traffic

To encrypt cluster traffic for JBoss EAP on OpenShift, you must configure the JGroups protocol stack in your JBoss EAP configuration to use either the SYM_ENCRYPT or ASYM_ENCRYPT protocol.

Although you can use a custom standalone-openshift.xml configuration file, it is recommended that you use environment variables to configure JGroups in your image build.

The instructions below use environment variables to configure the protocol for cluster traffic encryption for the JBoss EAP for OpenShift image.

Important

The SYM_ENCRYPT and ASYM_ENCRYPT protocols are not compatible with each other. It is not possible to form a supercluster out of two independent child clusters, with one using the SYM_ENCRYPT protocol for the encryption of cluster traffic and the other using the ASYM_ENCRYPT protocol. Similarly, when performing a rolling upgrade, the protocol needs to be identical for both the source and the target clusters.

7.7.2.1. Configuring SYM_ENCRYPT

To use the SYM_ENCRYPT protocol to encrypt JGroups cluster traffic:

The JGroups protocol stack must be configured to use SYM_ENCRYPT as the encryption protocol.
You can do this by setting the JGROUPS_ENCRYPT_PROTOCOL environment variable to SYM_ENCRYPT:
```
JGROUPS_ENCRYPT_PROTOCOL=SYM_ENCRYPT
```
The JGROUPS_ENCRYPT_SECRET environment variable must be set to the name of the secret containing the JGroups keystore file used for securing the JGroups communications. If not set, cluster communication is not encrypted and a warning is issued. For example:
```
JGROUPS_ENCRYPT_SECRET=eap7-app-secret
```
The JGROUPS_ENCRYPT_KEYSTORE_DIR environment variable must be set to the directory path of the keystore file within the secret specified via JGROUPS_ENCRYPT_SECRET variable. If not set, cluster communication is not encrypted and a warning is issued. For example:
```
JGROUPS_ENCRYPT_KEYSTORE_DIR=/etc/jgroups-encrypt-secret-volume
```
The JGROUPS_ENCRYPT_KEYSTORE environment variable must be set to the name of the keystore file within the secret specified via JGROUPS_ENCRYPT_SECRET variable. If not set, cluster communication is not encrypted and a warning is issued. For example:
```
JGROUPS_ENCRYPT_KEYSTORE=jgroups.jceks
```
The JGROUPS_ENCRYPT_NAME environment variable must be set to the name associated with the server’s certificate. If not set, cluster communication is not encrypted and a warning is issued. For example:
```
JGROUPS_ENCRYPT_NAME=jgroups
```
The JGROUPS_ENCRYPT_PASSWORD environment variable must be set to the password used to access the keystore and the certificate. If not set, cluster communication is not encrypted and a warning is issued. For example:
```
JGROUPS_ENCRYPT_PASSWORD=mypassword
```

7.7.2.2. Configuring ASYM_ENCRYPT

Note

JBoss EAP 7.4 includes a new version of the ASYM_ENCRYPT protocol. The previous version of the protocol is deprecated. If you specify the JGROUPS_CLUSTER_PASSWORD environment variable, the deprecated version of the protocol is used and a warning is printed in the pod log.

To use the ASYM_ENCRYPT protocol to encrypt JGroups cluster traffic, specify ASYM_ENCRYPT as the encryption protocol, and configure it to use a keystore configured in the elytron subsystem.

-e JGROUPS_ENCRYPT_PROTOCOL="ASYM_ENCRYPT" \
-e JGROUPS_ENCRYPT_SECRET="encrypt_secret" \
-e JGROUPS_ENCRYPT_NAME="encrypt_name" \
-e JGROUPS_ENCRYPT_PASSWORD="encrypt_password" \
-e JGROUPS_ENCRYPT_KEYSTORE="encrypt_keystore" \
-e JGROUPS_CLUSTER_PASSWORD="cluster_password"

7.7.3. Considerations for scaling up pods

Based on the discovery mechanism in JGroups, a starting node searches for an existing cluster coordinator node. If no coordinator node is found within a given timeout, the starting node assumes that it is the first member and takes up the coordinator status.

When multiple nodes start concurrently, they all make this assumption of being the first member, leading to the creation of a split cluster with multiple partitions. For example, scaling up from 0 to 2 pods using the DeploymentConfig API may lead to the creation of a split cluster. To avoid this situation, you need to start the first pod and then scale up to the required number of pods.

Note

By default, the EAP Operator uses the StatefulSet API, which starts pods in order, that is, one by one, preventing the creation of split clusters.

7.8. Health Checks

The JBoss EAP for OpenShift image utilizes the liveness and readiness probes included in OpenShift by default. In addition, this image includes Eclipse MicroProfile Health, as discussed in the Configuration Guide.

The following table demonstrates the values necessary for these health checks to pass. If the status is anything other than the values found below, then the check is failed and the image is restarted per the image’s restart policy.

Table 7.5. Liveness and Readiness Checks

Performed Test	Liveness	Readiness
Server Status	Any status	Running
Boot Errors	None	None
Deployment Status ^[a]	N/A or no `failed` entries	N/A or no `failed` entries
Eclipse MicroProfile Health ^[b]	N/A or `UP`	N/A or `UP`
^[a] N/A is only a valid state when no deployments are present. ^[b] N/A is only a valid state when the `microprofile-health-smallrye` subsystem has been disabled.

7.9. Messaging

7.9.1. Configuring External Red Hat AMQ Brokers

You can configure the JBoss EAP for OpenShift image with environment variables to connect to external Red Hat AMQ brokers.

Example OpenShift Application Definition

The following example uses a template to create a JBoss EAP application connected to an external Red Hat AMQ 7 broker.

Example: JDK 8

oc new-app eap74-amq-s2i \
-p EAP_IMAGE_NAME=jboss-eap74-openjdk8-openshift:7.4.0 \
-p EAP_RUNTIME_IMAGE_NAME=jboss-eap74-openjdk8-runtime-openshift:7.4.0 \
-p APPLICATION_NAME=eap74-mq \
-p MQ_USERNAME=MY_USERNAME \
-p MQ_PASSWORD=MY_PASSWORD

Important

The template used in this example provides valid default values for the required parameters. If you do not use a template and provide your own parameters, be aware that the MQ_SERVICE_PREFIX_MAPPING name must match the APPLICATION_NAME name, appended with "-amq7=MQ".

7.10. Security Domains

To configure a new Security Domain, the user must define the SECDOMAIN_NAME environment variable.

This results in the creation of a security domain named after the environment variable. The user may also define the following environment variables to customize the domain:

Table 7.6. Security Domains

Variable name	Description
SECDOMAIN_NAME	Defines an additional security domain. Example value: `myDomain`
SECDOMAIN_PASSWORD_STACKING	If defined, the `password-stacking` module option is enabled and set to the value `useFirstPass`. Example value: `true`
SECDOMAIN_LOGIN_MODULE	The login module to be used. Defaults to `UsersRoles`
SECDOMAIN_USERS_PROPERTIES	The name of the properties file containing user definitions. Defaults to `users.properties`
SECDOMAIN_ROLES_PROPERTIES	The name of the properties file containing role definitions. Defaults to `roles.properties`

7.11. HTTPS Environment Variables

Variable name Description

Variable name	Description
HTTPS_NAME	If defined along with `HTTPS_PASSWORD` and `HTTPS_KEYSTORE`, enables HTTPS and sets the SSL name. This should be the value specified as the alias name of your keystore if you created it with the `keytool -genkey` command. Example value: `example.com`
HTTPS_PASSWORD	If defined along with `HTTPS_NAME` and `HTTPS_KEYSTORE`, enables HTTPS and sets the SSL key password. Example value: `passw0rd`
HTTPS_KEYSTORE	If defined along with `HTTPS_PASSWORD` and `HTTPS_NAME`, enables HTTPS and sets the SSL certificate key file to a relative path under `EAP_HOME/standalone/configuration` Example value: `ssl.key`

HTTPS_NAME

If defined along with HTTPS_PASSWORD and HTTPS_KEYSTORE, enables HTTPS and sets the SSL name.

This should be the value specified as the alias name of your keystore if you created it with the keytool -genkey command.

Example value: example.com

HTTPS_PASSWORD

If defined along with HTTPS_NAME and HTTPS_KEYSTORE, enables HTTPS and sets the SSL key password.

Example value: passw0rd

HTTPS_KEYSTORE

If defined along with HTTPS_PASSWORD and HTTPS_NAME, enables HTTPS and sets the SSL certificate key file to a relative path under EAP_HOME/standalone/configuration

Example value: ssl.key

7.12. Administration Environment Variables

Table 7.7. Administration Environment Variables

Variable name Description

Variable name	Description
ADMIN_USERNAME	If both this and `ADMIN_PASSWORD` are defined, used for the JBoss EAP management user name. Example value: `eapadmin`
ADMIN_PASSWORD	The password for the specified `ADMIN_USERNAME`. Example value: `passw0rd`

ADMIN_USERNAME

If both this and ADMIN_PASSWORD are defined, used for the JBoss EAP management user name.

Example value: eapadmin

ADMIN_PASSWORD

The password for the specified ADMIN_USERNAME.

Example value: passw0rd

7.13. S2I

The image includes S2I scripts and Maven.

Maven is currently only supported as a build tool for applications that are supposed to be deployed on JBoss EAP-based containers (or related/descendant images) on OpenShift.

Only WAR deployments are supported at this time.

7.13.1. Custom Configuration

It is possible to add custom configuration files for the image. All files put into configuration/ directory will be copied into EAP_HOME/standalone/configuration/. For example to override the default configuration used in the image, just add a custom standalone-openshift.xml into the configuration/ directory. See example for such a deployment.

7.13.1.1. Custom Modules

It is possible to add custom modules. All files from the modules/ directory will be copied into EAP_HOME/modules/. See example for such a deployment.

7.13.2. Deployment Artifacts

By default, artifacts from the source target directory will be deployed. To deploy from different directories set the ARTIFACT_DIR environment variable in the BuildConfig definition. ARTIFACT_DIR is a comma-delimited list. For example: ARTIFACT_DIR=app1/target,app2/target,app3/target

7.13.3. Artifact Repository Mirrors

A repository in Maven holds build artifacts and dependencies of various types, for example, all of the project JARs, library JARs, plug-ins, or any other project specific artifacts. It also specifies locations from where to download artifacts while performing the S2I build. Besides using central repositories, it is a common practice for organizations to deploy a local custom mirror repository.

Benefits of using a mirror are:

Availability of a synchronized mirror, which is geographically closer and faster.
Ability to have greater control over the repository content.
Possibility to share artifacts across different teams (developers, CI), without the need to rely on public servers and repositories.
Improved build times.

Often, a repository manager can serve as local cache to a mirror. Assuming that the repository manager is already deployed and reachable externally at https://10.0.0.1:8443/repository/internal/, the S2I build can then use this manager by supplying the MAVEN_MIRROR_URL environment variable to the build configuration of the application as follows:

Identify the name of the build configuration to apply MAVEN_MIRROR_URL variable against.
```
oc get bc -o name
buildconfig/eap
```

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

Verify the setting.

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

Schedule new build of the application.

Note

During application build, you will notice that Maven dependencies are pulled from the repository manager, instead of the default public repositories. Also, after the build is finished, you will see that the mirror is filled with all the dependencies that were retrieved and used during the build.

7.13.3.1. Secure Artifact Repository Mirror URLs

To prevent "man-in-the-middle" attacks through the Maven repository, JBoss EAP requires the use of secure URLs for artifact repository mirror URLs.

The URL should specify a secure http ("https") and a secure port.

By default, if you specify an unsecure URL, an error will be returned. You can override this behavior using the the property -Dinsecure.repositories=WARN.

7.13.4. Scripts

run: This script uses the openshift-launch.sh script that configures and starts JBoss EAP with the standalone-openshift.xml configuration.
assemble: This script uses Maven to build the source, create a package (WAR), and move it to the EAP_HOME/standalone/deployments directory.

7.13.5. Custom Scripts

You can add custom scripts to run when starting a pod, before JBoss EAP is started.

You can add any script valid to run when starting a pod, including CLI scripts.

Two options are available for including scripts when starting JBoss EAP from an image:

Mount a configmap to be executed as postconfigure.sh
Add an install.sh script in the nominated installation directory

7.13.5.1. Mounting a configmap to execute custom scripts

Mount a configmap when you want to mount a custom script at runtime to an existing image (in other words, an image that has already been built).

To mount a configmap:

Create a configmap with content you want to include in the postconfigure.sh.
For example, create a directory called extensions in the project root directory to include the scripts postconfigure.sh and extensions.cli and run the following command:
```
$ oc create configmap jboss-cli --from-file=postconfigure.sh=extensions/postconfigure.sh --from-file=extensions.cli=extensions/extensions.cli
```

Mount the configmap into the pods via the deployment controller (dc).

$ oc set volume dc/eap-app --add --name=jboss-cli -m /opt/eap/extensions -t configmap --configmap-name=jboss-cli --default-mode='0755' --overwrite

Example postconfigure.sh

#!/usr/bin/env bash
set -x
echo "Executing postconfigure.sh"
$JBOSS_HOME/bin/jboss-cli.sh --file=$JBOSS_HOME/extensions/extensions.cli

Example extensions.cli

embed-server --std-out=echo  --server-config=standalone-openshift.xml
:whoami
quit

7.13.5.2. Using install.sh to execute custom scripts

Use install.sh when you want to include the script as part of the image when it is built.

To execute custom scripts using install.sh:

In the git repository of the project that will be used during s2i build, create a directory called .s2i.
Inside the s2i directory, add a file called environment, with the following content:
```
$ cat .s2i/environment
CUSTOM_INSTALL_DIRECTORIES=extensions
```
Create a directory called extensions.
In the extensions directory, create the file postconfigure.sh with contents similar to the following (replace placeholder code with appropriate code for your environment):
```
$ cat extensions/postconfigure.sh
#!/usr/bin/env bash
echo "Executing patch.cli"
$JBOSS_HOME/bin/jboss-cli.sh --file=$JBOSS_HOME/extensions/some-cli-example.cli
```

In the extensions directory, create the file install.sh with contents similar to the following (replace placeholder code with appropriate code for your environment):

$ cat extensions/install.sh
#!/usr/bin/env bash
set -x
echo "Running $PWD/install.sh"
injected_dir=$1
# copy any needed files into the target build.
cp -rf ${injected_dir} $JBOSS_HOME/extensions

7.13.6. Environment Variables

You can influence the way the build is executed by supplying environment variables to the s2i build command. The environment variables that can be supplied are:

Table 7.8. s2i Environment Variables

Variable name	Description
ARTIFACT_DIR	The `.war`, `.ear`, and `.jar` files from this directory will be copied into the `deployments/` directory. Example value: `target`
ENABLE_GENERATE_DEFAULT_DATASOURCE	Optional. When included with the value `true`, the server is provisioned with the default datasource. Otherwise, the default datasource is not included.
GALLEON_PROVISION_DEFAULT_FAT_SERVER	Optional. When included with the value `true`, and no galleon layers have been set, a default JBoss EAP server is provisioned.
GALLEON_PROVISION_LAYERS	Optional. Instructs the S2I process to provision the specified layers. The value is a comma-separated list of layers to provision, including one base layer and any number of decorator layers. Example value: `jaxrs, sso`
HTTP_PROXY_HOST	Host name or IP address of a HTTP proxy for Maven to use. Example value: `192.168.1.1`
HTTP_PROXY_PORT	TCP Port of a HTTP proxy for Maven to use. Example value: `8080`
HTTP_PROXY_USERNAME	If supplied with `HTTP_PROXY_PASSWORD`, use credentials for HTTP proxy. Example value: `myusername`
HTTP_PROXY_PASSWORD	If supplied with `HTTP_PROXY_USERNAME`, use credentials for HTTP proxy. Example value: `mypassword`
HTTP_PROXY_NONPROXYHOSTS	If supplied, a configured HTTP proxy will ignore these hosts. Example value: `some.example.org\|*.example.net`
MAVEN_ARGS	Overrides the arguments supplied to Maven during build. Example value: `-e -Popenshift -DskipTests -Dcom.redhat.xpaas.repo.redhatga package`
MAVEN_ARGS_APPEND	Appends user arguments supplied to Maven during build. Example value: `-Dfoo=bar`
MAVEN_MIRROR_URL	URL of a Maven Mirror/repository manager to configure. Example value: `https://10.0.0.1:8443/repository/internal/` Note that the specified URL should be secure. For details see Section 7.13.3.1, “Secure Artifact Repository Mirror URLs”.
MAVEN_CLEAR_REPO	Optionally clear the local Maven repository after the build. If the server present in the image is strongly coupled to the local cache, the cache is not deleted and a warning is printed. Example value: `true`
APP_DATADIR	If defined, directory in the source from where data files are copied. Example value: `mydata`
DATA_DIR	Directory in the image where data from `$APP_DATADIR` will be copied. Example value: `EAP_HOME/data`

Note

For more information, see Build and Run a Java Application on the JBoss EAP for OpenShift Image, which uses Maven and the S2I scripts included in the JBoss EAP for OpenShift image.

7.14. Single Sign-On image

This image includes the Red Hat Single Sign-On-enabled applications.

For more information on deploying the Red Hat Single Sign-On for OpenShift image with the JBoss EAP for OpenShift image, see Deploy the Red Hat Single Sign-On-enabled JBoss EAP Image on the Red Hat Single Sign-On for OpenShift guide.

Table 7.9. Single Sign-On environment variables

Variable name	Description
SSO_URL	URL of the Single Sign-On server.
SSO_REALM	Single Sign-On realm for the deployed applications.
SSO_PUBLIC_KEY	Public key of the Single Sign-On realm. This field is optional but if omitted can leave the applications vulnerable to man-in-middle attacks.
SSO_USERNAME	Single Sign-On user required to access the Single Sign-On REST API. Example value: `mySsoUser`
SSO_PASSWORD	Password for the Single Sign-On user defined by the `SSO_USERNAME` variable. Example value: `6fedmL3P`
SSO_SAML_KEYSTORE	Keystore location for SAML. Defaults to `/etc/sso-saml-secret-volume/keystore.jks`.
SSO_SAML_KEYSTORE_PASSWORD	Keystore password for SAML. Defaults to `mykeystorepass`.
SSO_SAML_CERTIFICATE_NAME	Alias for keys/certificate to use for SAML. Defaults to `jboss`.
SSO_BEARER_ONLY	Single Sign-On client access type. (Optional) Example value: `true`
SSO_CLIENT	Path for Single Sign-On redirects back to the application. Defaults to match `module-name`.
SSO_ENABLE_CORS	If `true`, enable CORS for Single Sign-On applications. (Optional)
SSO_SECRET	The Single Sign-On client secret for confidential access. Example value: `KZ1QyIq4`
SSO_DISABLE_SSL_CERTIFICATE_VALIDATION	If `true` the SSL/TLS communication between JBoss EAP and the RH Single Sign-On server is unsecure, for example, the certificate validation is disabled with `curl`. Not set by default. Example value: `true`

7.15. Unsupported Transaction Recovery Scenarios

JTS transactions are not supported in OpenShift.
XTS transactions are not supported in OpenShift.
The XATerminator interface that some third parties use for transaction completion and crash recovery flows is not supported in OpenShift.
Transactions propagated over JBoss Remoting is unsupported with OpenShift 3.

Note

Transactions propagated over JBoss Remoting is supported with OpenShift 4 and the EAP operator.

7.16. Included JBoss Modules

The table below lists included JBoss Modules in the JBoss EAP for OpenShift image.

Table 7.10. Included JBoss Modules

JBoss Module
org.jboss.as.clustering.common
org.jboss.as.clustering.jgroups
org.jboss.as.ee
org.jgroups
org.openshift.ping
net.oauth.core

7.17. EAP Operator: API Information

The EAP operator introduces the following APIs:

7.17.1. WildFlyServer

WildFlyServer defines a custom JBoss EAP resource.

Table 7.11. WildFlyServer

Field	Description	Scheme	Required
`metadata`	Standard object’s metadata	ObjectMeta v1 meta	false
`spec`	Specification of the desired behaviour of the JBoss EAP deployment.	`WildFlyServerSpec`	true
`status`	Most recent observed status of the JBoss EAP deployment. Read-only.	WildFlyServerStatus	false

7.17.2. WildFlyServerList

WildFlyServerList defines a list of JBoss EAP deployments.

Table 7.12. Table

Field	Description	Scheme	Required
`metadata`	Standard list’s metadata	metav1.ListMeta	false
`items`	List of `WildFlyServer`	`WildFlyServer`	true

7.17.3. WildFlyServerSpec

WildFlyServerSpec is a specification of the desired behavior of the JBoss EAP resource.

It uses a StatefulSet with a pod spec that mounts the volume specified by storage on /opt/jboss/wildfly/standalone/data.

Table 7.13. WildFlyServerSpec

Field	Description	Scheme	Required
`applicationImage`	Name of the application image to be deployed	string	false
`replicas`	the desired number of replicas for the application	int32]	true
`standaloneConfigMap`	Spec to specify how a standalone configuration can be read from a `ConfigMap`.	`StandaloneConfigMapSpec`	false
`resources`	`Resources` spec to specify the request or limits of the Stateful Set. If omitted, the namespace defaults are used.	`Resources`	false
`storage`	Storage spec to specify how storage should be used. If omitted, an `EmptyDir` is used (that does not persist data across pod restart)	`StorageSpec`	false
`serviceAccountName`	Name of the ServiceAccount to use to run the JBoss EAP pods	string	false
`envFrom`	List of environment variables present in the containers from `configMap` or secret	`corev1.EnvFromSource`	false
`env`	List of environment variable present in the containers	corev1.EnvVar	false
`secrets`	List of secret names to mount as volumes in the containers. Each secret is mounted as a read-only volume at `/etc/secrets/<secret name>`	string	false
`configMaps`	List of `ConfigMap` names to mount as volumes in the containers. Each `ConfigMap` is mounted as a read-only volume under `/etc/configmaps/<config map name>`	string	false
`disableHTTPRoute`	Disable the creation a route to the HTTP port of the application service (false if omitted)	boolean	false
`sessionAffinity`	If connections from the same client IP are passed to the same JBoss EAP instance/pod each time (false if omitted)	boolean	false

7.17.4. Resources

Resources defines the configured resources for a WildflyServer resource. If the Resources field is not defined or Request or Limits is empty, this resource is removed from the StatefulSet. The description of this resource is a standard Container resource and uses the scheme for corev1.ResourceRequirements.

7.17.5. StorageSpec

StorageSpec defines the configured storage for a WildFlyServer resource. If neither an EmptyDir nor a volumeClaimTemplate is defined, a default EmptyDir is used.

The EAP Operator configures the StatefulSet using information from this StorageSpec to mount a volume dedicated to the standalone/data directory used by JBoss EAP to persist its own data. For example, transaction log). If an EmptyDir is used, the data does not survive a pod restart. If the application deployed on JBoss EAP relies on transaction, specify a volumeClaimTemplate, so that the same persistent volume can be reused upon pod restarts.

Table 7.14. Table

Field	Description	Scheme	Required
`emptyDir`	`EmptyDirVolumeSource` to be used by the JBoss EAP `StatefulSet`	corev1.EmptyDirVolumeSource	false
`volumeClaimTemplate`	A PersistentVolumeClaim spec to configure `Resources` requirements to store JBoss EAP standalone data directory. The name of the template is derived from the `WildFlyServer` name. The corresponding volume is mounted in `ReadWriteOnce` access mode.	corev1.PersistentVolumeClaim	false

7.17.6. StandaloneConfigMapSpec

StandaloneConfigMapSpec defines how JBoss EAP standalone configuration can be read from a ConfigMap. If omitted, JBoss EAP uses its standalone.xml configuration from its image.

Table 7.15. StandaloneConfigMapSpec

Field	Description	Scheme	Required
`name`	Name of the `ConfigMap` containing the standalone configuration XML file.	string	true
key	Key of the `ConfigMap` whose value is the standalone configuration XML file. If omitted, the spec finds the `standalone.xml` key.	string	false

7.17.7. WildFlyServerStatus

WildFlyServerStatus is the most recent observed status of the JBoss EAP deployment. Read-only.

Table 7.16. WildFlyServerStatus

Field	Description	Scheme	Required
`replicas`	The actual number of replicas for the application	int32	true
`selector`	selector for pods, used by HorizontalPodAutoscaler	string	true
`hosts`	Hosts that route to the application HTTP service	string	true
`pods`	Status of the pods	PodStatus	true
`scalingdownPods`	Number of pods that are under scale down cleaning process	int32	true

7.17.8. PodStatus

PodStatus is the most recent observed status of a pod running the JBoss EAP application.

Table 7.17. PodStatus

Field	Description	Scheme	Required
`name`	Name of the pod	string	true
`podIP`	IP address allocated to the pod	string	true
`state`	State of the pod in the scale down process. The state is ACTIVE by default, which means it serves requests.	string	false

Revised on 2022-06-27 13:29:56 UTC

Language and Page Formatting Options

Chapter 7. Reference Information

7.1. Persistent Templates

7.2. Information Environment Variables

7.3. Configuration environment variables

7.4. Application Templates

7.5. Exposed Ports

7.6. Datasources

7.6.1. JNDI Mappings for Datasources

7.6.1.1. Datasource Configuration Environment Variables

7.6.1.2. Examples

7.6.1.2.1. Single Mapping

7.6.1.2.2. Multiple Mappings

7.7. Clustering

7.7.1. Configuring a JGroups Discovery Mechanism

7.7.1.1. Configuring KUBE_PING

7.7.1.2. Configuring DNS_PING

7.7.2. Configuring JGroups to Encrypt Cluster Traffic

7.7.2.1. Configuring SYM_ENCRYPT

7.7.2.2. Configuring ASYM_ENCRYPT

7.7.3. Considerations for scaling up pods

7.8. Health Checks

7.9. Messaging

7.9.1. Configuring External Red Hat AMQ Brokers

Example OpenShift Application Definition

7.10. Security Domains

7.11. HTTPS Environment Variables

7.12. Administration Environment Variables

7.13. S2I

7.13.1. Custom Configuration

7.13.1.1. Custom Modules

7.13.2. Deployment Artifacts

7.13.3. Artifact Repository Mirrors

7.13.3.1. Secure Artifact Repository Mirror URLs

7.13.4. Scripts

7.13.5. Custom Scripts

7.13.5.1. Mounting a configmap to execute custom scripts

7.13.5.2. Using install.sh to execute custom scripts

7.13.6. Environment Variables

7.14. Single Sign-On image

7.15. Unsupported Transaction Recovery Scenarios

7.16. Included JBoss Modules

7.17. EAP Operator: API Information

7.17.1. WildFlyServer

7.17.2. WildFlyServerList

7.17.3. WildFlyServerSpec

7.17.4. Resources

7.17.5. StorageSpec

7.17.6. StandaloneConfigMapSpec

7.17.7. WildFlyServerStatus

7.17.8. PodStatus