build: deprecate Java 17. Upgrade to Java 21 in containers. (kroxylicious#3147)

piotrpdev · k-wall · web-flow · commit 195f44c5c3a4 · 2026-01-27T17:05:50.000Z
* build: upgrade to jdk 21 in Dockerfiles Signed-off-by: Piotr Płaczek <piotrpdev@gmail.com> * docs: upgrade to jdk 21 Signed-off-by: Piotr Płaczek <piotrpdev@gmail.com> * build: upgrade to jdk 21 in pom.xml files Signed-off-by: Piotr Płaczek <piotrpdev@gmail.com> * build: remove explicit java version in IT tests pom.xml Signed-off-by: Piotr Płaczek <piotrpdev@gmail.com> * fix: remove `@SuppressWarnings("resource")` using JDK 21 Signed-off-by: Piotr Płaczek <piotrpdev@gmail.com> * docs: update code comments referencing JDK 17 Signed-off-by: Piotr Płaczek <piotrpdev@gmail.com> * docs: add CHANGELOG.md entry Signed-off-by: Piotr Płaczek <piotrpdev@gmail.com> * docs: upgrade to Maven 3.8.8 Signed-off-by: Piotr Płaczek <piotrpdev@gmail.com> * Revert "build: upgrade to jdk 21 in pom.xml files" This reverts commit 372b351. Signed-off-by: Piotr Płaczek <piotrpdev@gmail.com> * Revert "build: remove explicit java version in IT tests pom.xml" This reverts commit 236d400. Signed-off-by: Piotr Płaczek <piotrpdev@gmail.com> * Revert "fix: remove `@SuppressWarnings("resource")` using JDK 21" This reverts commit b3f292f. Signed-off-by: Piotr Płaczek <piotrpdev@gmail.com> * Revert "docs: update code comments referencing JDK 17" This reverts commit f86a169. Signed-off-by: Piotr Płaczek <piotrpdev@gmail.com> * Revert "docs: upgrade to jdk 21" This reverts commit 1ef5e70 Signed-off-by: Piotr Płaczek <piotrpdev@gmail.com> * docs: JDK 17 deprecation Signed-off-by: Piotr Płaczek <piotrpdev@gmail.com> * docs: update CHANGELOG.md Signed-off-by: Piotr Płaczek <piotrpdev@gmail.com> * build: add Java 17 deprecation warning Signed-off-by: Piotr Płaczek <piotrpdev@gmail.com> * docs: adjust deprecation notice wording Signed-off-by: Piotr Płaczek <piotrpdev@gmail.com> * docs: log warning for Java <17 Signed-off-by: Piotr Płaczek <piotrpdev@gmail.com> * Revert "docs: log warning for Java <17" This reverts commit 570e00d. Signed-off-by: Piotr Płaczek <piotrpdev@gmail.com> * docs: log warning for deprecated and unsupported JREs Signed-off-by: Piotr Płaczek <piotrpdev@gmail.com> * change wording in changelog Signed-off-by: Piotr Płaczek <piotrpdev@gmail.com> * change startup warning wording Signed-off-by: Piotr Płaczek <piotrpdev@gmail.com> * filter author persona targeted wording Signed-off-by: Piotr Płaczek <piotrpdev@gmail.com> * remove un-needed changelog entry Signed-off-by: Piotr Płaczek <piotrpdev@gmail.com> * adjust pom.xml maven message Signed-off-by: Piotr Płaczek <piotrpdev@gmail.com> * fix version if statement Signed-off-by: Piotr Płaczek <piotrpdev@gmail.com> --------- Signed-off-by: Piotr Płaczek <piotrpdev@gmail.com> Signed-off-by: Keith Wall <kwall@apache.org> Co-authored-by: Keith Wall <kwall@apache.org>
diff --git a/.github/workflows/docker.yaml b/.github/workflows/docker.yaml
@@ -40,7 +40,7 @@ jobs:
         uses: actions/setup-java@v5
         with:
           distribution: 'temurin'
-          java-version: '17'
+          java-version: '21'
 
       - name: Determine Build Configuration
         id: build_configuration
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,7 @@ Format `<github issue/pr number>: <short description>`.
 
 ## SNAPSHOT
 
+* [#3147](https://github.com/kroxylicious/kroxylicious/pull/3129): Deprecate Java 17. Upgrade to Java 21 in containers.
 * [#3127](https://github.com/kroxylicious/kroxylicious/pull/3127): build(deps): bump kubernetes-client.version from 7.4.0 to 7.5.0
 * [#3112](https://github.com/kroxylicious/kroxylicious/pull/3112): cache topic name lookups per VirtualCluster
 * [#3129](https://github.com/kroxylicious/kroxylicious/pull/3129): build(deps): bump netty.version from 4.2.7.Final to 4.2.9.Final
@@ -15,6 +16,8 @@ Format `<github issue/pr number>: <short description>`.
 
 ### Changes, deprecations and removals
 
+* Running Kroxylicious on Java 17 is deprecated. The minimum required Java version will be raised to 21 in a future release.
+* Containers have been upgraded to use Java 21.
 * The four argument forms of `RequestFilter#onRequest` and `ResponseFilter#onResponse` are deprecated and will be removed in a future release.
   Implement the five argument form, which includes the `apiVersion` instead.
 
diff --git a/DEV_GUIDE.md b/DEV_GUIDE.md
@@ -49,8 +49,8 @@ This document gives a detailed breakdown of the various build processes and opti
 
 ## Build Prerequisites
 
-- [JDK](https://openjdk.org/projects/jdk/17/) (version 21 and above) - JDK
-- [`mvn`](https://maven.apache.org/index.html) (version 3.6.3 and above) - [Apache Maven®](https://maven.apache.org)
+- [JDK](https://openjdk.org/projects/jdk/21/) (version 21 and above) - JDK
+- [`mvn`](https://maven.apache.org/index.html) (version 3.8.8 and above) - [Apache Maven®](https://maven.apache.org)
 - [`docker`](https://docs.docker.com/install/) or [`podman`](https://podman.io/docs/installation) - Docker or Podman
 
 > :warning: **If you are using Podman please see [these notes](#running-integration-tests-on-podman) below**
@@ -62,7 +62,7 @@ This document gives a detailed breakdown of the various build processes and opti
 JDK version 21 or newer, and [Apache Maven®](https://maven.apache.org) are required for building this project.
 
 Kroxylicious targets language level 17, except for the `integrationtests` module
-which targets 21 to access some new language features.
+which targets 21 to access some new language features. At production runtime, Java 17 remains supported but is deprecated. Use Java 21 or later.
 
 Build the project like this:
 
@@ -299,15 +299,15 @@ While Kroxylicious is a java application we've had reports of issues running the
       Expect output similar to: 
       ```shell
       > java --version
-   openjdk 19.0.2 2023-01-17
-   OpenJDK Runtime Environment Temurin-19.0.2+7 (build 19.0.2+7)
-   OpenJDK 64-Bit Server VM Temurin-19.0.2+7 (build 19.0.2+7, mixed mode, sharing)
+   openjdk 21.0.8 2025-07-15 LTS
+   OpenJDK Runtime Environment Temurin-21.0.8+9 (build 21.0.8+9-LTS)
+   OpenJDK 64-Bit Server VM Temurin-21.0.8+9 (build 21.0.8+9-LTS, mixed mode, sharing
    ```
     2. Update if needed: sample update command like:
     ```shell
     sudo apt update
     sudo apt upgrade
-    sudo apt install openjdk-18-jre-headless
+    sudo apt install openjdk-21-jre-headless
     ```
 4. Ensure GIT is available
    1. ```shell
diff --git a/Dockerfile b/Dockerfile
@@ -4,7 +4,7 @@
 # Licensed under the Apache Software License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 #
 
-FROM registry.access.redhat.com/ubi9/openjdk-17:1.24-2.1767878246 AS builder
+FROM registry.access.redhat.com/ubi9/openjdk-21:1.24-2.1767878250 AS builder
 
 ARG TARGETOS
 ARG TARGETARCH
@@ -42,7 +42,7 @@ RUN mvn -q -B clean package -Pdist -Dquick -DskipContainerImageBuild=true -Dskip
 
 FROM registry.access.redhat.com/ubi9/ubi-minimal:9.7-1768783948
 
-ARG JAVA_VERSION=17
+ARG JAVA_VERSION=21
 ARG KROXYLICIOUS_VERSION
 ARG CONTAINER_USER=kroxylicious
 ARG CONTAINER_USER_UID=185
@@ -58,7 +58,7 @@ RUN microdnf -y update \
     && microdnf remove -y shadow-utils \
     && microdnf clean all
 
-ENV JAVA_HOME=/usr/lib/jvm/jre-17
+ENV JAVA_HOME=/usr/lib/jvm/jre-21
 
 COPY --from=builder /opt/tini/bin/tini /usr/bin/tini
 COPY --from=builder /opt/kroxylicious/kroxylicious-app/target/kroxylicious-app-${KROXYLICIOUS_VERSION}-bin/kroxylicious-app-${KROXYLICIOUS_VERSION}/ /opt/kroxylicious/
diff --git a/Dockerfile.operator b/Dockerfile.operator
@@ -4,7 +4,7 @@
 # Licensed under the Apache Software License version 2.0, available at http://www.apache.org/licenses/LICENSE-2.0
 #
 
-FROM registry.access.redhat.com/ubi9/openjdk-17:1.24-2.1767878246 AS builder
+FROM registry.access.redhat.com/ubi9/openjdk-21:1.24-2.1767878250 AS builder
 
 ARG TARGETOS=linux
 ARG TARGETARCH
@@ -43,7 +43,7 @@ RUN mvn -q -B clean package -Pdist -Dquick -DskipContainerImageBuild=true -Dskip
 
 FROM registry.access.redhat.com/ubi9/ubi-minimal:9.7-1768783948
 
-ARG JAVA_VERSION=17
+ARG JAVA_VERSION=21
 ARG KROXYLICIOUS_VERSION
 ARG CONTAINER_USER=kroxylicious
 ARG CONTAINER_USER_UID=185
@@ -59,7 +59,7 @@ RUN microdnf -y update \
     && microdnf remove -y shadow-utils \
     && microdnf clean all
 
-ENV JAVA_HOME=/usr/lib/jvm/jre-17
+ENV JAVA_HOME=/usr/lib/jvm/jre-21
 
 COPY --from=builder /opt/tini/bin/tini /usr/bin/tini
 COPY --from=builder /opt/kroxylicious/kroxylicious-operator/target/kroxylicious-operator-${KROXYLICIOUS_VERSION}-app/kroxylicious-operator-${KROXYLICIOUS_VERSION} /opt/kroxylicious-operator
diff --git a/PERFORMANCE.md b/PERFORMANCE.md
@@ -22,10 +22,11 @@ The tested scenarios are:
 * Kroxylicious + Kafka - envelope encryption with encrypted topic
 * Kroxylicious + Kafka - envelope encryption without encrypted topic
 
-## Prerequisites 
+## Prerequisites
 
-- [JDK](https://openjdk.org/projects/jdk/17/) (version 17 and above) - JDK
-- [`mvn`](https://maven.apache.org/index.html) (version 3.5 and above) - Maven CLI
+- [JDK](https://openjdk.org/projects/jdk/21/) (version 21 and above) - JDK
+  - At production runtime, Java 17 remains supported but is deprecated. Use Java 21 or later. 
+- [`mvn`](https://maven.apache.org/index.html) (version 3.8.8 and above) - Maven CLI
 - [`docker`](https://docs.docker.com/install/) or [`podman`](https://podman.io/docs/installation) - Docker or Podman
 - [`jq`](https://jqlang.github.io/) 1.7 or higher
 
diff --git a/kroxylicious-app/src/main/docker/proxy.dockerfile b/kroxylicious-app/src/main/docker/proxy.dockerfile
@@ -8,7 +8,7 @@ FROM registry.access.redhat.com/ubi9/ubi-minimal:9.7-1768783948
 
 ARG TARGETOS
 ARG TARGETARCH
-ARG JAVA_VERSION=17
+ARG JAVA_VERSION=21
 ARG KROXYLICIOUS_VERSION
 ARG CONTAINER_USER=kroxylicious
 ARG CONTAINER_USER_UID=185
diff --git a/kroxylicious-docs/docs/_modules/con-custom-filters.adoc b/kroxylicious-docs/docs/_modules/con-custom-filters.adoc
@@ -9,7 +9,7 @@
 
 [role="_abstract"]
 Custom filters can be written in the Java programming language.
-Kroxylicious supports Java 17.
+Kroxylicious supports Java 21.
 Knowledge of the {kafka-protocol}[Kafka protocol^] is generally required to write a protocol filter.
 
 There is currently one class of Custom Filters users can implement:
diff --git a/kroxylicious-docs/docs/proxy-quick-start/index.adoc b/kroxylicious-docs/docs/proxy-quick-start/index.adoc
@@ -13,9 +13,9 @@ Get Kroxylicious, the snappy open source proxy for Apache Kafka®, up and runnin
 
 Before you begin, ensure you have the following installed and configured.
 
-* **Java 17+**
+* **Java 21+**
 +
-Kroxylicious requires a Java Runtime Environment (JRE) version 17 or higher. To check your version, run:
+Kroxylicious requires a Java Runtime Environment (JRE) version 21 or higher (JRE 17 remains supported for now but is deprecated). To check your version, run:
 +
 [source,bash]
 ----
diff --git a/kroxylicious-operator/src/main/docker/operator.dockerfile b/kroxylicious-operator/src/main/docker/operator.dockerfile
@@ -8,7 +8,7 @@ FROM registry.access.redhat.com/ubi9/ubi-minimal:9.7-1768783948
 
 ARG TARGETOS=linux
 ARG TARGETARCH
-ARG JAVA_VERSION=17
+ARG JAVA_VERSION=21
 ARG KROXYLICIOUS_VERSION
 ARG CONTAINER_USER=kroxylicious
 ARG CONTAINER_USER_UID=185
diff --git a/kroxylicious-runtime/src/main/java/io/kroxylicious/proxy/KafkaProxy.java b/kroxylicious-runtime/src/main/java/io/kroxylicious/proxy/KafkaProxy.java
@@ -9,6 +9,8 @@
 import java.util.List;
 import java.util.Map;
 import java.util.Optional;
+import java.util.Set;
+import java.util.TreeSet;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.ForkJoinPool;
 import java.util.concurrent.TimeUnit;
@@ -73,6 +75,9 @@ public final class KafkaProxy implements AutoCloseable {
     private static final Logger LOGGER = LoggerFactory.getLogger(KafkaProxy.class);
     private static final Logger STARTUP_SHUTDOWN_LOGGER = LoggerFactory.getLogger("io.kroxylicious.proxy.StartupShutdownLogger");
 
+    private static final int JRE_FEATURE_VERSION = Runtime.version().feature();
+    private static final TreeSet<Integer> TESTED_JRE_VERSIONS = new TreeSet<>(Set.of(21, 25));
+
     @VisibleForTesting
     record EventGroupConfig(String name, EventLoopGroup bossGroup, EventLoopGroup workerGroup, Class<? extends ServerChannel> clazz) {
 
@@ -179,6 +184,20 @@ public KafkaProxy startup() {
             throw new IllegalStateException("This proxy is already running");
         }
         try {
+            if (!TESTED_JRE_VERSIONS.contains(JRE_FEATURE_VERSION)) {
+                String versionStatus = "untested";
+                String deprecatedMessage = "";
+
+                if (JRE_FEATURE_VERSION < TESTED_JRE_VERSIONS.first()) {
+                    versionStatus = "deprecated";
+                    deprecatedMessage = " The ability to run Kroxylicious on JRE %s will be removed in a future release.".formatted(JRE_FEATURE_VERSION);
+                }
+
+                STARTUP_SHUTDOWN_LOGGER.warn(
+                        "Detected {} JRE version: {}.{} Running Kroxylicious is only tested on LTS releases >={}. If you find any issues, please try to re-create them on one of the tested JREs.",
+                        versionStatus, JRE_FEATURE_VERSION, deprecatedMessage, TESTED_JRE_VERSIONS.first());
+            }
+
             STARTUP_SHUTDOWN_LOGGER.info("Kroxylicious is starting");
             meterRegistries = new MeterRegistries(pfr, micrometerConfig);
             initVersionInfoMetric();
diff --git a/pom.xml b/pom.xml
@@ -19,7 +19,9 @@
     <properties>
         <!--suppress XmlUnresolvedReference --> <!-- git.commit.time is generated by the git-commit-id-maven-plugin-->
         <project.build.outputTimestamp>2025-11-28T12:25:47Z</project.build.outputTimestamp>
+        <!-- Warning: Running Kroxylicious on Java 17 is deprecated. The minimum required Java version will be raised to 21 in a future release. -->
         <java.version>17</java.version>
+        <java.recommended.version>21</java.recommended.version>
         <java.test.version>17</java.test.version>
         <maven.exec.version>3.1.0</maven.exec.version>
         <maven.compiler.version>3.10.1</maven.compiler.version>
@@ -1015,6 +1017,23 @@
                             </rules>
                         </configuration>
                     </execution>
+                    <execution>
+                        <id>enforce-recommended-java</id>
+                        <goals>
+                            <goal>enforce</goal>
+                        </goals>
+                        <configuration>
+                            <rules>
+                                <requireJavaVersion>
+                                    <version>[${java.recommended.version},)</version>
+                                    <message>
+                                        Use of JDK ${java.version} has been deprecated and will be removed in a future release. Please upgrade to JDK ${java.recommended.version} or later.
+                                    </message>
+                                </requireJavaVersion>
+                            </rules>
+                            <fail>false</fail>
+                        </configuration>
+                    </execution>
                     <execution>
                         <id>ban-build-time-dependencies-from-runtime</id>
                         <goals>

Original file line number	Diff line number	Diff line change
`@@ -13,9 +13,9 @@ Get Kroxylicious, the snappy open source proxy for Apache Kafka®, up and runnin`
`13`	`13`
`14`	`14`	`Before you begin, ensure you have the following installed and configured.`
`15`	`15`
`16`		`-* Java 17+`
	`16`	`+* Java 21+`
`17`	`17`	`+`
`18`		`-Kroxylicious requires a Java Runtime Environment (JRE) version 17 or higher. To check your version, run:`
	`18`	`+Kroxylicious requires a Java Runtime Environment (JRE) version 21 or higher (JRE 17 remains supported for now but is deprecated). To check your version, run:`
`19`	`19`	`+`
`20`	`20`	`[source,bash]`
`21`	`21`	`----`