ZOOKEEPER-4391: Allow custom JVM heap sizing

bin/zkEnv.sh

@@ -136,8 +136,14 @@ export CLASSPATH
 
 # default heap for zookeeper server
 ZK_SERVER_HEAP="${ZK_SERVER_HEAP:-1000}"
-export SERVER_JVMFLAGS="-Xmx${ZK_SERVER_HEAP}m $SERVER_JVMFLAGS"
+if [[ $ZK_SERVER_HEAP != omit ]]; then
+  SERVER_JVMFLAGS="-Xmx${ZK_SERVER_HEAP}m $SERVER_JVMFLAGS"
+fi
+export SERVER_JVMFLAGS
 
 # default heap for zookeeper client
 ZK_CLIENT_HEAP="${ZK_CLIENT_HEAP:-256}"
-export CLIENT_JVMFLAGS="-Xmx${ZK_CLIENT_HEAP}m $CLIENT_JVMFLAGS"
+if [[ $ZK_CLIENT_HEAP != omit ]]; then
+  CLIENT_JVMFLAGS="-Xmx${ZK_CLIENT_HEAP}m $CLIENT_JVMFLAGS"
+fi
+export CLIENT_JVMFLAGS

conf/java.env

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+# ZooKeeper defaults to a 1000 MiB server heap and a 256 MiB client heap.
+# Set either heap to a positive integer to choose a different size in MiB.
+# ZK_SERVER_HEAP=1000
+# ZK_CLIENT_HEAP=256
+
+# Set a heap to "omit" to skip ZooKeeper's generated -Xmx option. The matching
+# JVMFLAGS variable can still provide -Xmx or any other heap-related JVM options.
+# ZK_SERVER_HEAP=omit
+# SERVER_JVMFLAGS="-XX:InitialRAMPercentage=25 -XX:MaxRAMPercentage=75"
+# ZK_CLIENT_HEAP=omit
+# CLIENT_JVMFLAGS="-XX:MaxRAMPercentage=25"

zookeeper-website/app/pages/_docs/docs/_mdx/admin-ops/tools.mdx

@@ -56,9 +56,48 @@ See [ZooKeeper CLI](/admin-ops/cli).
 
 ### zkEnv.sh
 
-Sets environment variables for the ZooKeeper server. Key variables:
+Sets environment variables for ZooKeeper scripts. Values can be provided in
+the environment or in `conf/java.env`, whose values take precedence. Key
+variables:
 
 - `ZOO_LOG_DIR` — the directory where logs are stored.
+- `ZK_SERVER_HEAP` — configures the server maximum heap in MiB.
+- `SERVER_JVMFLAGS` — additional JVM options for the server.
+- `ZK_CLIENT_HEAP` — configures the client maximum heap in MiB.
+- `CLIENT_JVMFLAGS` — additional JVM options for clients.
+
+Heap settings produce the following JVM options:
+
+| Heap setting     | Server result                    | Client result                    |
+| ---------------- | -------------------------------- | -------------------------------- |
+| Unset            | `-Xmx1000m`                      | `-Xmx256m`                       |
+| Positive integer | `-Xmx<number>m`                  | `-Xmx<number>m`                  |
+| `omit`           | No `-Xmx` generated by ZooKeeper | No `-Xmx` generated by ZooKeeper |
+
+Unless the heap setting is `omit`, ZooKeeper prepends the generated `-Xmx`
+option to any options provided in the corresponding `*_JVMFLAGS` variable.
+
+The server and client settings are independent. Setting either heap variable to
+`omit` skips only the `-Xmx` option ZooKeeper would otherwise generate from the
+corresponding heap setting. It does not remove or override options in the corresponding
+`*_JVMFLAGS` variable, including an explicitly supplied `-Xmx` option.
+
+Use `omit` when heap-related JVM options should be configured manually. For
+example, a containerized server can use a percentage of the available memory:
+
+```bash
+ZK_SERVER_HEAP=omit \
+SERVER_JVMFLAGS="-XX:InitialRAMPercentage=25 -XX:MaxRAMPercentage=75" \
+./zkServer.sh start
+```
+
+It can also be used to provide an `-Xmx` value directly:
+
+```bash
+ZK_SERVER_HEAP=omit \
+SERVER_JVMFLAGS="-Xmx2g" \
+./zkServer.sh start
+```
 
 ### zkCleanup.sh