[GR-57284] `JAVA_TOOL_OPTIONS` environment variable in native executables

[Mcdostone]

Feature request

Is your feature request related to a problem? Please describe.

This feature is about run time, not build time. When deploying a java app, we can configure the JVM with the JAVA_TOOL_OPTIONS environment variable or by passing arguments to the command.

In the graalVM world, it is also possible to declare system properties at run time by passing arguments to the native executable: ./my-native-executable -D hello=world. Unfortunately, I was not able to find any similar environment variable as JAVA_TOOL_OPTIONS for native executables.

Describe the solution you'd like.

It would be interesting to define an environment variable that is automatically read by the native executable. I have no inspiration for the name though: GRAALVM_TOOL_OPTIONS="-D hello=world" ./my-native-executable.

Describe who do you think will benefit the most.

This feature could benefit people shipping native executables in containers. Indeed, It is pretty common to configure applications with environment variables.

Describe alternatives you've considered.

So far, the only way to define system properties at run time is to declare them as arguments of the command line:

./my-native-executable \
    -D javax.net.ssl.trustStore=my-truststore.p12 \
    -D javax.net.ssl.trustStoreType=PKCS12 \
    -D javax.net.ssl.trustStorePassword=pass

Additional context.

This issue is related to #4650. The last message of this issue suggests that JAVA_TOOL_OPTIONS should be "compatible" with graalVM. I did some tests with different environment variables here and it's not the case. It might be a normal behavior or a bug, I don't know to be honest.

Why do I suggest this feature? I have a spring boot native executable running on kubernetes. this application needs a specific trust store to communicate with other applications. The trust store is automatically mounted to the pod by kubernetes at boot time, which means I need to configure my application to use it (-Djavax.net.ssl.trustStore).

Express whether you'd like to help contributing this feature

If I could, yes !

[fniephaus]

Hi @Mcdostone, thanks for the feature request!
I think it may even make sense to support JAVA_TOOL_OPTIONS in a native executable for compatibility. After all, the native executable should behave the same as the application running on HotSpot. A native executable even includes a JVM (called SubstrateVM).

Note that there already is a NATIVE_IMAGE_OPTIONS env var which you can use to inject arguments into the bin/native-image launcher, but that is for build time.

[gbaso]

Hi @fniephaus, what is the status of this issue?

[fniephaus]

Hi @gbaso, I'm afraid no one has worked on this yet. Maybe you could share more details about your use cases?

[gbaso]

We run Spring Boot applications on Kubernetes. The operations team that maintain the deployments wants images that are ready to run without additional JVM configurations, so we usually embed a JAVA_TOOL_OPTIONS into the image as described in the spring boot and paketo docs. This is necessary to tune the memory with e.g. MaxDirectMemorySize, and configure the JVM with e.g. jdk.virtualThreadScheduler.maxPoolSize.

The lack of support for JAVA_TOOL_OPTIONS or alternative mechanisms is currently preventing us to migrate to native images.

[fniephaus]

Thanks for sharing more details. I hope we can prioritize this soon!

[fniephaus]

In the meantime, there are some simple workarounds you may want to use, for example:

Using an array

JAVA_TOOL_OPTIONS=("--port" "8080" "-Xmx64m")
./yourimage "$JAVA_TOOL_OPTIONS[@]"

or

Using eval

JAVA_TOOL_OPTIONS="--port 8080 -Xmx64m"
eval ./yourimage $JAVA_TOOL_OPTIONS

Would this work for you?

[gbaso]

Unfortunately JAVA_TOOL_OPTIONS is computed dynamically on container startup by helper processes built by paketo buildpacks, see https://paketo.io/docs/reference/java-reference/#memory-calculator.

For example, setting BPE_APPEND_JAVA_TOOL_OPTIONS to -XX:MaxDirectMemorySize=30M -XX:ReservedCodeCacheSize=120M -Djdk.virtualThreadScheduler.maxPoolSize=16 and BPL_JVM_THREAD_COUNT to 64, and deploying the container with memory limits at 768 MB, will result in the following JAVA_TOOL_OPTIONS for a non-native application:

-Djava.security.properties=/layers/paketo-buildpacks_oracle/java-security-properties/java-security.properties
-XX:+ExitOnOutOfMemoryError
-XX:MaxDirectMemorySize=30M
-XX:ReservedCodeCacheSize=120M
-Djdk.virtualThreadScheduler.maxPoolSize=16
-Xmx407015K
-XX:MaxMetaspaceSize=160280K
-Xss1M
-XX:+UnlockDiagnosticVMOptions
-XX:NativeMemoryTracking=summary
-XX:+PrintNMTStatistics
-Dorg.springframework.cloud.bindings.boot.enable=true

As you can see there is a lot going on here, some depending on internal details of the build tools (the security properties location) some computed from the application (the metaspace) some configured by us (the max direct memory) some computed from runtime values (the -Xmx). This is subject to change not only due to our change in configuration, but also the natural develment of buildpacks may introduce, change or remove properties.

In non-native applications, this is not a concern. We only need to append to the JAVA_TOOL_OPTIONS at build time and the buildpack helpers will take care of it. Having to manually specify the options, or extracting them from the image, is a non-starter (although I do understand that most of those options are not applicable to native images).

[fniephaus]

JAVA_TOOL_OPTIONS is computed dynamically

Yes, that makes sense. I'm not an expert on buildpacks but is there no way you can control how your native image is launched? If you could replace ./mynativeimage with eval ./mynativeimage $JAVA_TOOL_OPTIONS the dynamically computed value should be picked up correctly.

[gbaso]

I'm not sure, I would need to investigate.