Red Hat Summit Red Hat SummitSupportConsoleDéveloppeursCommencer un essaiContact

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

Chapter 11. Reference information for OpenShift Container Platform

The content in this section is derived from the engineering documentation for this application image. The content is provided as a reference for development purposes and for testing beyond the scope of the product documentation.

11.1. Information environment variables
Copier lien

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

Expand
Table 11.1. Information Environment Variables
Variable NameDescription and Value

JBOSS_IMAGE_NAME

The image names.

Values:

  • jboss-eap-8/eap8-openjdk17-builder-openshift-rhel8 (JDK 17 / 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:

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

11.2. Configuration environment variables
Copier lien

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.

Expand
Table 11.2. Configuration environment variables
Variable NameDescription

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

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 in the JBoss EAP 7.4 Development Guide.

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 created secret specified 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 in which the secret containing the keystore is mounted.

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

11.3. Exposed ports
Copier lien

Expand
Table 11.3. Exposed Ports
Port NumberDescription

8443

HTTPS

11.4. Datasources
Copier lien

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.

11.4.1. JNDI mappings for datasources
Copier lien

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.

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.

11.4.1.1. Datasource Configuration Environment Variables
Copier lien

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.

Expand
Variable NameDescription

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

11.4.1.2. Examples
Copier lien

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

11.4.1.2.1. Single Mapping
Copier lien

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.

11.4.1.2.2. Multiple Mappings
Copier lien

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:

  1. java:jboss/datasources/test_mysql
  2. 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.

11.5. Clustering
Copier lien

11.5.1. Configuring a JGroups Discovery Mechanism
Copier lien

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.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 Helm chart 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.

11.5.1.1. Configuring KUBE_PING
Copier lien

To use the KUBE_PING JGroups discovery mechanism:

  1. 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
    Copy to Clipboard Toggle word wrap

  2. The KUBERNETES_NAMESPACE environment variable must be set to your OpenShift project name. For example: 

    KUBERNETES_NAMESPACE=PROJECT_NAME
    Copy to Clipboard Toggle word wrap

  3. 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
    Copy to Clipboard Toggle word wrap

  4. 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)
    Copy to Clipboard Toggle word wrap

    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)
    Copy to Clipboard Toggle word wrap
    Note

    See Preparing OpenShift to deploy an application for more information on adding policies to service accounts.

11.5.1.2. Configuring DNS_PING
Copier lien

To use the DNS_PING JGroups discovery mechanism:

  1. 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
    Copy to Clipboard Toggle word wrap

  2. 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
    Copy to Clipboard Toggle word wrap

  3. 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
    Copy to Clipboard Toggle word wrap

  4. 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."
      Copy to Clipboard Toggle word wrap
Note

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

11.5.2. Configuring JGroups to Encrypt Cluster Traffic
Copier lien

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

11.5.2.1. Configuring SYM_ENCRYPT
Copier lien

To use the SYM_ENCRYPT protocol to encrypt JGroups cluster traffic:

  1. 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
    Copy to Clipboard Toggle word wrap

  2. The JGROUPS_ENCRYPT_KEYSTORE_DIR environment variable must be set to the directory path in which the secret containing the keystore is mounted. For example: 

    JGROUPS_ENCRYPT_KEYSTORE_DIR=/etc/jgroups-encrypt-secret-volume
    Copy to Clipboard Toggle word wrap

  3. The JGROUPS_ENCRYPT_KEYSTORE environment variable must be set to the name of the keystore file within the created secret specified. If not set, cluster communication is not encrypted and a warning is issued. For example: 

    JGROUPS_ENCRYPT_KEYSTORE=jgroups.jceks
    Copy to Clipboard Toggle word wrap

  4. 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
    Copy to Clipboard Toggle word wrap

  5. 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
    Copy to Clipboard Toggle word wrap

11.5.2.2. Configuring ASYM_ENCRYPT
Copier lien

Note

JBoss EAP 8.0 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_NAME="encrypt_name" \
-e JGROUPS_ENCRYPT_PASSWORD="encrypt_password" \
-e JGROUPS_ENCRYPT_KEYSTORE="encrypt_keystore" \
-e JGROUPS_CLUSTER_PASSWORD="cluster_password"
Copy to Clipboard Toggle word wrap

11.5.3. Considerations for scaling up pods
Copier lien

Based on the discovery mechanism in JGroups, a starting node searches for an existing cluster coordinator node. If a coordinator node is not 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 make an assumption of being the first member that leads 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 JBoss EAP Operator uses the StatefulSet API, which starts the creation of pods in order, that is, one by one, preventing the creation of split clusters.

11.6. Native Health checks
Copier lien

The JBoss EAP for OpenShift image implements Liveness and readiness probes that are included in OpenShift by default. For more information, see liveness and readiness probes in the OpenShift Container Platform Developer 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.

Expand
Table 11.4. Liveness and Readiness Checks
Performed TestLivenessReadiness

Server Status

Any status

Running

Boot Errors

None

None

Deployment Status [a]

N/A or no failed entries

N/A or no failed entries

Native Health Checks

UP

UP

[a] N/A is only a valid state when no deployments are present.

11.7. Messaging
Copier lien

11.7.1. Configuring External Red Hat AMQ Brokers
Copier lien

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

11.8. Security domains
Copier lien

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:

Expand
Table 11.5. Security Domains
Variable nameDescription

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

11.9. HTTPS environment variables
Copier lien

Expand
Variable nameDescription

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

11.10. Administration environment variables
Copier lien

Expand
Table 11.6. Administration Environment Variables
Variable nameDescription

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

11.11. S2I
Copier lien

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.

11.11.1. Custom Configuration
Copier lien

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.xml into the configuration/ directory. See example for such a deployment.

11.11.1.1. Custom Modules
Copier lien

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.

11.11.2. Deployment Artifacts
Copier lien

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

11.11.3. Artifact repository mirrors
Copier lien

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:

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

    oc get bc -o name
buildconfig/eap
    Copy to Clipboard Toggle word wrap

  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
    Copy to Clipboard Toggle word wrap

  3. Verify the setting. 

    oc env bc/eap --list
# buildconfigs eap
MAVEN_MIRROR_URL=https://10.0.0.1:8443/repository/internal/
    Copy to Clipboard Toggle word wrap
  4. 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.

11.11.3.1. Secure artifact repository mirror URLs
Copier lien

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.

11.11.4. Scripts
Copier lien

run
This script uses the openshift-launch.sh script that configures and starts JBoss EAP with the standalone.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.

11.11.5. Custom Scripts
Copier lien

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

11.11.5.1. Mounting a configmap to execute custom scripts
Copier lien

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:

  1. 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
    Copy to Clipboard Toggle word wrap

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

    $ oc set volume dc/eap-app --add --name=jboss-cli -m /opt/server/extensions -t configmap --configmap-name=jboss-cli --default-mode='0755' --overwrite
    Copy to Clipboard Toggle word wrap

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
Copy to Clipboard Toggle word wrap

Example extensions.cli

embed-server --std-out=echo  --server-config=standalone.xml
:whoami
quit
Copy to Clipboard Toggle word wrap

11.11.5.2. Using install.sh to execute custom scripts
Copier lien

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:

  1. In the git repository of the project that will be used during s2i build, create a directory called .s2i.

  2. Inside the s2i directory, add a file called environment, with the following content: 

    $ cat .s2i/environment
CUSTOM_INSTALL_DIRECTORIES=extensions
    Copy to Clipboard Toggle word wrap
  3. Create a directory called extensions.

  4. 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
    Copy to Clipboard Toggle word wrap

  5. 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
    Copy to Clipboard Toggle word wrap

11.11.6. Environment variables
Copier lien

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:

Expand
Table 11.7. s2i Environment Variables
Variable nameDescription

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_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

GALLEON_PROVISION_CHANNELS

This is a comma separated list of JBoss EAP channels manifest. The JBoss EAP channel manifest is identified by groupid:artifactId:[version].

Note

The version is optional, which means that the latest channel manifest will be retrieved. For JBoss EAP 8.0, use this channel org.jboss.eap.channels:eap-8.0.

GALLEON_PROVISION_FEATURE_PACKS

Builds environment variable to specify a custom Galleon feature pack for your S2I image. For example: org.jboss.eap:wildfly-ee-galleon-pack:[version],org.jboss.eap.cloud:eap-cloud-galleon-pack:[version].

Note

When you set up the GALLEON_PROVISION_CHANNELS=org.jboss.eap.channels:eap-8.0, the feature-packs versions are not required.

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 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 Building and running JBoss EAP applications on OpenShift Container Platform, which uses Maven and the S2I scripts included in the JBoss EAP for OpenShift image.

11.12. Unsupported Transaction Recovery Scenarios
Copier lien

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

Transactions propagated over JBoss Remoting is supported using EAP operator.

11.13. Included JBoss modules
Copier lien

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

Expand
Table 11.8. 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

11.14. EAP Operator: API Information
Copier lien

The EAP operator introduces the following APIs:

11.14.1. WildFlyServer
Copier lien

WildFlyServer defines a custom JBoss EAP resource.

Expand
Table 11.9. WildFlyServer
FieldDescriptionSchemeRequired

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

11.14.2. WildFlyServerList
Copier lien

WildFlyServerList defines a list of JBoss EAP deployments.

Expand
Table 11.10. Table
FieldDescriptionSchemeRequired

metadata

Standard list’s metadata

metav1.ListMeta

false

items

List of WildFlyServer

WildFlyServer

true

11.14.3. WildFlyServerSpec
Copier lien

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.

Expand
Table 11.11. WildFlyServerSpec
FieldDescriptionSchemeRequired

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

SecurityContext

SecurityContext spec to define privilege and access control settings for the pod containers created by the Stateful Set. If omitted, default privileges are used. For additional information see securityContext

*corev1.SecurityContext

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

11.14.4. Resources
Copier lien

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.

11.14.5. StorageSpec
Copier lien

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.

Expand
Table 11.12. Table
FieldDescriptionSchemeRequired

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

11.14.6. StandaloneConfigMapSpec
Copier lien

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.

Expand
Table 11.13. StandaloneConfigMapSpec
FieldDescriptionSchemeRequired

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

11.14.7. WildFlyServerStatus
Copier lien

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

Expand
Table 11.14. WildFlyServerStatus
FieldDescriptionSchemeRequired

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

11.14.8. PodStatus
Copier lien

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

Expand
Table 11.15. PodStatus
FieldDescriptionSchemeRequired

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 2025-02-21 14:11:18 UTC

Retour au début
Red Hat logoGithubredditYoutubeTwitter

Apprendre

Essayez, achetez et vendez

Communautés

À propos de la documentation Red Hat

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

Rendre l’open source plus inclusif

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

À propos de Red Hat

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

Theme

© 2025 Red Hat