wip

Signed-off-by: Attila Mészáros <a_meszaros@apple.com>

Author: csviri

docs/content/en/docs/documentation/operations/configuration.md

@@ -45,7 +45,11 @@ reasonable with platform threads.
 
 Two things to keep in mind:
 
-- Virtual threads require Java 21 or later at runtime. When the flag is set on an older JVM, a
+- Virtual threads are officially supported on **Java 25 or later**. They exist from Java 21 on and
+  the flag does enable them there, but before Java 25 a virtual thread pins its carrier thread
+  while it is inside a `synchronized` block, which can starve the carrier pool. [JEP
+  491](https://openjdk.org/jeps/491), delivered in Java 25, removed that pinning, so this is the
+  baseline the framework supports. On a JVM without virtual threads at all (below Java 21) a
   warning is logged and platform threads are used instead, so the same configuration works on any
   supported Java version.
 - A custom `ExecutorService` provided through `withExecutorService(...)` or
@@ -293,7 +297,7 @@ All operator-level keys are prefixed with `josdk.`.
 |---|---|---|
 | `josdk.check-crd` | `Boolean` | Validate CRDs against local model on startup |
 | `josdk.close-client-on-stop` | `Boolean` | Close the Kubernetes client when the operator stops |
-| `josdk.use-virtual-threads` | `Boolean` | Run the framework's concurrent work on virtual threads (requires Java 21+ at runtime) |
+| `josdk.use-virtual-threads` | `Boolean` | Run the framework's concurrent work on virtual threads (officially supported on Java 25+ at runtime) |
 | `josdk.use-ssa-to-patch-primary-resource` | `Boolean` | Use Server-Side Apply to patch the primary resource |
 | `josdk.clone-secondary-resources-when-getting-from-cache` | `Boolean` | Clone secondary resources on cache reads |
 

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ConfigurationService.java

@@ -251,9 +251,11 @@ default Metrics getMetrics() {
    * pool of platform threads anymore. Since virtual threads are cheap, those limits can be set
    * considerably higher than what would be reasonable for platform threads.
    *
-   * <p>Requires Java 21 or later at runtime. When enabled on an older JVM, a warning is logged and
-   * platform threads are used, so that the same configuration works regardless of the Java version
-   * the operator runs on.
+   * <p>Officially supported on Java 25 or later. Virtual threads exist as of Java 21 and are used
+   * there as well, but before Java 25 a virtual thread pins its carrier thread while inside a
+   * {@code synchronized} block, which <a href="https://openjdk.org/jeps/491">JEP 491</a> removed in
+   * Java 25. On a JVM without virtual threads at all, a warning is logged and platform threads are
+   * used, so that the same configuration works regardless of the Java version the operator runs on.
    *
    * <p>Note that this only affects the executors created by the framework: a custom {@link
    * ExecutorService} provided through {@link #getExecutorService()} or {@link

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ConfigurationServiceOverrider.java

@@ -122,7 +122,7 @@ public ConfigurationServiceOverrider withWorkflowExecutorService(
 
   /**
    * Makes the framework run the tasks it executes concurrently on virtual threads instead of
-   * platform threads. Requires Java 21 or later at runtime, see {@link
+   * platform threads. Officially supported on Java 25 or later, see {@link
    * ConfigurationService#useVirtualThreads()} for the details.
    *
    * @param useVirtualThreads {@code true} to use virtual threads

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/VirtualThreads.java

@@ -89,7 +89,8 @@ static boolean shouldUse(boolean requested) {
     if (UNSUPPORTED_WARNING_LOGGED.compareAndSet(false, true)) {
       log.warn(
           "Virtual threads were requested but are not supported by the JVM in use (Java {}, Java 21"
-              + " or later is required). Falling back to platform threads.",
+              + " or later is required, Java 25 or later is officially supported). Falling back to"
+              + " platform threads.",
           Runtime.version().feature());
     }
     return false;
@@ -99,7 +100,8 @@ static boolean shouldUse(boolean requested) {
   static ExecutorService newVirtualThreadPerTaskExecutor() {
     if (!isSupported()) {
       throw new OperatorException(
-          "Virtual threads are not supported by the JVM in use, Java 21 or later is required");
+          "Virtual threads are not supported by the JVM in use, Java 21 or later is required"
+              + " (Java 25 or later is officially supported)");
     }
     try {
       return (ExecutorService) NEW_VIRTUAL_THREAD_PER_TASK_EXECUTOR.invokeExact();

sample-operators/webpage/src/main/java/io/javaoperatorsdk/operator/sample/WebPageOperator.java

@@ -40,7 +40,9 @@ public class WebPageOperator {
   public static void main(String[] args) throws IOException {
     log.info("WebServer Operator starting!");
 
-    Operator operator = new Operator(o -> o.withStopOnInformerErrorDuringStartup(false));
+    Operator operator =
+        new Operator(
+            o -> o.withStopOnInformerErrorDuringStartup(false).withUseVirtualThreads(true));
     String reconcilerEnvVar = System.getenv(WEBPAGE_RECONCILER_ENV);
     if (WEBPAGE_CLASSIC_RECONCILER_ENV_VALUE.equals(reconcilerEnvVar)) {
       operator.register(new WebPageReconciler());