Appendix E. JVM Environment Variables

E.1. S2I Java Builder Image with OpenJDK 8

In this S2I builder image for Java builds, you can run results directly without using any other application server. It is suitable for microservices with a flat classpath (including fat jars).

You can configure Java options when using the Fuse on OpenShift images. All the options for the Fuse on OpenShift images are set by using environment variables as given below. For the JVM options, you can use the environment variable JAVA_OPTIONS. Also, provide JAVA_ARGS for the arguments which are given through to the application.

E.2. S2I Karaf Builder Image with OpenJDK 8

This image can be used with OpenShift’s Source To Image in order to build Karaf4 custom assembly based maven projects.

Following is the command to use S2I:

s2i build <git repo url> registry.redhat.io/fuse7/fuse-karaf-openshift:1.3 <target image name>
docker run <target image name>

E.2.1. Configuring the Karaf4 Assembly

The location of the Karaf4 assembly built by the maven project can be provided in multiple ways.

  • Default assembly file *.tar.gz in output directory
  • By using the -e flag in sti or oc command
  • By setting FUSE_ASSEMBLY property in .sti/environment under the project source

E.2.2. Customizing the Build

It is possible to customize the maven build. The MAVEN_ARGS environment variable can be set to change the behaviour.

By default, the MAVEN_ARGS is set as follows:

Karaf4: install karaf:assembly karaf:archive -DskipTests -e

E.3. Environment Variables

Following are the environment variables that are used to influence the behaviour of S2I Java and Karaf builder images:

E.3.1. Build Time

During the build time, you can use the following environment variables:

  • MAVEN_ARGS: Arguments to use when calling maven, replacing the default package.
  • MAVEN_ARGS_APPEND: Additional Maven arguments, useful for adding temporary arguments like -X or -am -pl.
  • ARTIFACT_DIR: Path to target/ where the jar files are created for multi-module builds. These are added to ${MAVEN_ARGS}.
  • ARTIFACT_COPY_ARGS: Arguments to use when copying artifacts from the output directory to the application directory. Useful to specify which artifacts will be part of the image.
  • MAVEN_CLEAR_REPO: If set, remove the Maven repository after you build the artifact. This is useful for keeping the application image small, however, It prevents the incremental builds. The default value is false.

E.3.2. Run Time

You can use the following environment variables to influence the run script:

  • JAVA_APP_DIR: the directory where the application resides. All paths in your application are relative to the directory.
  • JAVA_LIB_DIR: this directory contains the Java jar files as well an optional classpath file, which holds the classpath. Either as a single line classpath (colon separated) or with jar files listed line-by-line. However, If not set, then JAVA_LIB_DIR is the same as JAVA_APP_DIR directory.
  • JAVA_OPTIONS: options to add when calling java.
  • JAVA_MAX_MEM_RATIO: It is used when no -Xmx option is given in JAVA_OPTIONS. This is used to calculate a default maximal heap Memory based on a containers restriction. If used in a Docker container without any memory constraints for the container, then this option has no effect.
  • JAVA_MAX_CORE: It restricts manually the number of cores available, which is used for calculating certain defaults like the number of garbage collector threads. If set to 0, you cannot perform the base JVM tuning based on the number of cores.
  • JAVA_DIAGNOSTICS: Set this to fetch some diagnostics information, to standard out when things are happening.
  • JAVA_MAIN_CLASS: A main class to use as an argument for java. When you give this environment variable, all jar files in $JAVA_APP_DIR directory are added to the classpath and in the $JAVA_LIB_DIR directory.
  • JAVA_APP_JAR: A jar file with an appropriate manifest, so that you can start with java -jar. However, if it is not provided, then $JAVA_MAIN_CLASS is set. In all cases, this jar file is added to the classpath.
  • JAVA_APP_NAME: Name to use for the process.
  • JAVA_CLASSPATH: the classpath to use. If not given, the startup script checks for a file ${JAVA_APP_DIR}/classpath and use its content as classpath. If this file doesn’t exists, then all jars in the application directory are added under (classes:${JAVA_APP_DIR}/*).
  • JAVA_DEBUG: If set, remote debugging will be switched on.
  • JAVA_DEBUG_PORT: Port used for remote debugging. The default value is 5005.

E.3.3. Jolokia Configuration

You can use the following environment variables in Jolokia:

  • AB_JOLOKIA_OFF: If set, disables the activation of Jolokia (echos an empty value). By default, Jolokia is enabled.
  • AB_JOLOKIA_CONFIG: If set, uses the file (including path) as Jolokia JVM agent properties. However, If not set, the /opt/jolokia/etc/jolokia.properties will be created using the settings.
  • AB_JOLOKIA_HOST: Host address to bind (Default value is 0.0.0.0)
  • AB_JOLOKIA_PORT: Port to use (Default value is 8778)
  • AB_JOLOKIA_USER: User for basic authentication. By default, it is jolokia
  • AB_JOLOKIA_PASSWORD: Password for basic authentication. By default, authentication is switched off
  • AB_JOLOKIA_PASSWORD_RANDOM: Generates a value and is written in /opt/jolokia/etc/jolokia.pw file
  • 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
  • AB_JOLOKIA_ID: Agent ID to use
  • AB_JOLOKIA_DISCOVERY_ENABLED: Enables the Jolokia discovery. The default value is false.
  • AB_JOLOKIA_OPTS: Additional options to be appended to the agent configuration. Options are given in the format key=value

Here is an option for integration with various environments:

  • AB_JOLOKIA_AUTH_OPENSHIFT: Switch on client authentication for OpenShift TSL communication. Ensure that the value of this parameter must be present in a client certificate. If you enable this parameter, it will automatically switch Jolokia into HTTPS communication mode. The default CA cert is set to /var/run/secrets/kubernetes.io/serviceaccount/ca.crt

Application arguments can be provided by setting the variable JAVA_ARGS to the corresponding value.