Add concepts page on JVM argument overrides (#697)

* Add concepts page on JVM argument overrides * Apply suggestions from code review Co-authored-by: Andrew Kenworthy <[email protected]> Co-authored-by: Malte Sander <[email protected]> * Reword merge mechanism * Update modules/concepts/pages/overrides.adoc --------- Co-authored-by: Andrew Kenworthy <[email protected]> Co-authored-by: Malte Sander <[email protected]>
stackabletech · Jan 27, 2025 · 26ccbda · 26ccbda
1 parent c318eb9
commit 26ccbda
Showing 1 changed file with 69 additions and 0 deletions.
diff --git a/modules/concepts/pages/overrides.adoc b/modules/concepts/pages/overrides.adoc
@@ -150,3 +150,72 @@ The `podOverrides` will be merged onto the following resources the operators dep
 They will *not* be applied to:
 
 * Jobs, that are used to setup systems the product depends on e.g. create a database schema for Superset or Airflow.
+
+[#jvm-argument-overrides]
+== JVM argument overrides
+
+You can configure the JVM arguments used by JVM based tools.
+This is often needed to e.g. configure a HTTP proxy or other network settings.
+
+As with other overrides, the operator generates a set of JVM arguments that are needed to run the tool. You can specify additional arguments which are merged on top of the ones the operator generated.
+As some JVM arguments are mutually exclusive (think of `-Xmx123m` and `-Xmx456m`), you also have the option to remove JVM arguments - either by specifying the exact argument or a regex.
+
+The merging mechanism is applied <operator generated> <- <role user specified> <- <rolegroup user specified> and works as follows:
+
+1. All arguments listed in user specified `remove` are removed from operator generated
+2. All arguments matching any regex from user removeRegex are removed from operator generated.
+   The regex needs to match the entire argument, not only a substring
+3. All arguments from user specified `add` are added to operator
+
+You can check the resulting effective JVM arguments by looking at the ConfigMap containing the config for the roleGroup (although some tools read the JVM arguments from environmental variables).
+
+=== Simple example
+
+One simple usage of this functionality is to add some JVM arguments, in this case needed for a special network setup:
+
+[source,yaml]
+----
+kind: NifiCluster
+spec:
+  # ...
+  nodes:
+    jvmArgumentOverrides:
+      add: # Add some networking arguments
+        - -Dhttps.proxyHost=proxy.my.corp
+        - -Dhttps.proxyPort=8080
+        - -Djava.net.preferIPv4Stack=true
+----
+
+=== Advanced example
+
+The following more advanced setups shows how the garbage collector can be changed, the JVM memory configs can be changed and how roleGroups can override roles.
+
+[source,yaml]
+----
+kind: NifiCluster
+spec:
+  # ...
+  nodes:
+    config:
+      resources:
+        memory:
+          limit: 42Gi # We define some memory config, so that we can override it further down
+    jvmArgumentOverrides:
+      remove:
+        - -XX:+UseG1GC # Remove argument generated by operator
+      add: # Add some networking arguments
+        - -Dhttps.proxyHost=proxy.my.corp
+        - -Dhttps.proxyPort=8080
+        - -Djava.net.preferIPv4Stack=true
+    roleGroups:
+      default:
+        replicas: 1
+        jvmArgumentOverrides:
+          # We need more memory!
+          removeRegex: # They need to match the entire string, not only a part!
+            - -Xmx.* # So this will match "-Xmx123m", but not "-foo-Xmx123m"
+            - -Dhttps.proxyPort=.* # Remove arguments from the role, so that we can override it
+          add: # After we removed some arguments we can add the correct ones
+            - -Xmx40000m
+            - -Dhttps.proxyPort=1234 # Override arguments from the role
+----