How to modify JVM options (JAVA_OPTS) for JBoss EAP in Openshift

Solution Verified - Updated 3 Dec 2025

Environment

Red Hat Openshift Container Platform
- 4.x
- 3.x
Red Hat xPaaS JBoss Enterprise Application Platform
- 8.x
- 7.x
- 6.4

Issue

Where to define JBoss EAP template with the xms/xmx value ?
How to modify heap size in Openshift v3.
How and where to define xms/xmx values on a JBoss in Openshift?
How about Tomcat (JWS) image?

Resolution

The explanation below assumes direct deployment (deployment yaml is used) not Operator. For Operator use the respective Operator's Custom Resource.

The recommended approach for setting JVM memory options is outlined in this article How to change JVM memory options using Red Hat JBoss EAP image for Openshift, via resource constraint.

JBoss EAP is possible to add the environment variable JAVA_OPTS/JAVA_OPTS_APPEND (or CATALINA_OPTS_APPEND for JWS, see JVM options to JWS for OpenShift) to a pod or Deployment or DeploymentConfig and customize JVM options. The environment variable JAVA_OPTS_APPEND can be used to append or override JVM options.
The JAVA_OPTS_APPEND environment variable can be applied via template (Option A) or DeploymentConfig (Option B) or via oc env command (Option C).

Option A: Update template

$ oc edit template <TEMPLATE_NAME> -n <NAME_SPACE e.g. openshift>

      spec:
        containers:
        - env:
          - name: JAVA_OPTS_APPEND
            value: -Dmy.custom.property=123

Option B. Update DeploymentConfig

$ oc edit dc <DC_NAME>

      spec:
        containers:
        - env:
          - name: JAVA_OPTS_APPEND
            value: -Dmy.custom.property=123

Option C. Use oc env to modify DeploymentConfig

$ oc set env dc/<DC_NAME> JAVA_OPTS_APPEND=-Dmy.custom.property=123

Full Example and verification:

Verify the environment variable exists and contains the correct value:

### get dc
$ oc get dc
NAME      REVISION   DESIRED   CURRENT   TRIGGERED BY
$dcname   8          1         1         config,image(eap-app:latest)
###
### set variable:
$ oc set env dc/$dcname JAVA_OPTS_APPEND="-XX:-UseParallelOldGC -XX:+UseG1GC"
### verify variable set:
$ oc set env dc/eap-app --list | grep JAVA_OPTS_APPEND
JAVA_OPTS_APPEND=-XX:-UseParallelOldGC -XX:+UseG1GC
###
### Verify application the pod logs:
$ oc logs $podname | grep UseG1GC
JAVA_OPTS: -javaagent:"/opt/eap/jboss-modules.jar"  -server -verbose:gc -Xloggc:"/opt/eap/standalone/log/gc.log" -XX:+PrintGCDetails -XX:+PrintGCDateStamps -XX:+UseGCLogFileRotation -XX:NumberOfGCLogFiles=5 -XX:GCLogFileSize=3M -XX:-TraceClassUnloading -Xms128m -Xmx512m -XX:MetaspaceSize=96m -Djava.net.preferIPv4Stack=true -Djboss.modules.system.pkgs=jdk.nashorn.api,com.sun.crypto.provider -Djava.awt.headless=true -XX:+UseParallelOldGC -XX:MinHeapFreeRatio=10 -XX:MaxHeapFreeRatio=20 -XX:GCTimeRatio=4 -XX:AdaptiveSizePolicyWeight=90 -XX:+ExitOnOutOfMemoryError -Djava.security.egd=file:/dev/./urandom -XX:-UseParallelOldGC -XX:+UseG1GC  <-----

JBoss Web Server uses `CATALINA_OPTS_APPEND`:

For JWS, see JVM options to JWS for OpenShift - summarized version below:

The This content is not included.Red Hat JBoss Web Server (JWS) image provides Apache Tomcat. This image uses the CATALINA_OPTS_APPEND environment variable instead ofJAVA_OPTS_APPEND.

 oc set env deployment/jws-wsch-app CATALINA_OPTS_APPEND="-XX:MaxGCPauseMillis=153"
deployment.apps/jws-wsch-app updated
[jws]$ oc get pod
NAME                            READY   STATUS      RESTARTS   AGE
jws-wsch-app-1-build            0/1     Completed   0          44m
jws-wsch-app-5b9dcfd486-b55p7   1/1     Running     0          37s
[jws]$ oc set env deployment/jws-wsch-app --list
# deployments/jws-wsch-app, container jws-wsch-app
CATALINA_OPTS_APPEND=-XX:MaxGCPauseMillis=153
[jws]$ oc logs jws-wsch-app-5b9dcfd486-b55p7 | grep MaxGCPauseMillis
01-Feb-2023 02:14:58.210 INFO [main] org.apache.catalina.startup.VersionLoggerListener.log Command line argument: -XX:MaxGCPauseMillis=153

Root Cause

The approach to set the JAVA_OPTS_APPEND will depend on how the deployment was made. That's because if you deploy directly EAP via deployment resource, it will be there the place to set the environment variables.
However, if the EAP Operator is used so then the JAVA_OPTS_APPEND must be set on the WildflyServer Custom resource - see the solution Setting Env variables in JWS and JBoss EAP Operator in Openshift 4. Finally, if EAP Helm charts is to be set, so then the environment is set on the statefulset(sts).

The following table summarizes deployment vs approach:

Deployment	How to set the variable:
EAP 7 deployed directly (deployment/deploymentconfig)	`JAVA_OPTS_APPEND` set on the deploymentconfig or deployment yaml
EAP 7 or EAP 8 deployed via JBoss EAP Operator	set `JAVA_OPTS_APPEND` in the spec.env for WildflyServer Custom resource
EAP 8 deployed via Helm charts	set `JAVA_OPTS_APPEND` in the env in the respective statefulset
JWS deployed directly	GC_CONTAINER_OPTIONS (for GC Option switch), `CATALINA_OPTS`/`CATALINA_OPTS_APPEND` (gc logs and other flags) on the deployment

Diagnostic Steps

To list all en variables on a deployment file: oc set env deployment/$deploymentname --list ( or oc set env dc/$deploymentconfig --list
To set env: oc set env dc/eap-app JAVA_OPTS_APPEND="-XX:-UseParallelOldGC -XX:+UseG1GC"
To unset: $ oc set env dc/eap-app JAVA_OPTS_APPEND-
Avoid deprecated flags, like using JDK 17 with UseParallelOldGC, it will return: Unrecognized VM option 'UseParallelOldGC' and the pod won't start.
For JWS, see JVM options to JWS for OpenShift

SBR

Product(s)

Components

jbossas

Category

JBoss EAP for OpenShift

Tags

This solution is part of Red Hat’s fast-track publication program, providing a huge library of solutions that Red Hat engineers have created while supporting our customers. To give you the knowledge you need the instant it becomes available, these articles may be presented in a raw and unedited form.