feat: ReconcileUtils for strongly consistent updates (#3106)

- Adds utility that provides methods to update resources using comparable resource versions
- Integrates this utility to the core of the framework (thus simplifying `ReconciliationDispatcher`)
  -  note that this introduces a change in the behavior for the `UpdateControl.patchStatus` (and others), since it won't trigger the reconiliation for the event in that update.
-  Renames former `ReconcilerUtils` to `ReconcilerUtilsInternal`, this is breaking but that utils was never advertised for non-internal usage 
- Includes also fixes for ControllerEventSource event filtering
- Improves TemporaryResourceCache event filtering algorithm

Signed-off-by: Attila Mészáros <a_meszaros@apple.com>
Signed-off-by: Steve Hawkins <shawkins@redhat.com>
Co-authored-by: Steve Hawkins <shawkins@redhat.com>

Author: csviri

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/Operator.java

@@ -263,7 +263,7 @@ public <P extends HasMetadata> RegisteredController<P> register(
           "Cannot register reconciler with name "
               + reconciler.getClass().getCanonicalName()
               + " reconciler named "
-              + ReconcilerUtils.getNameFor(reconciler)
+              + ReconcilerUtilsInternal.getNameFor(reconciler)
               + " because its configuration cannot be found.\n"
               + " Known reconcilers are: "
               + configurationService.getKnownReconcilerNames());

…peratorsdk/operator/ReconcilerUtils.java …dk/operator/ReconcilerUtilsInternal.javaoperator-framework-core/src/main/java/io/javaoperatorsdk/operator/ReconcilerUtils.java renamed to operator-framework-core/src/main/java/io/javaoperatorsdk/operator/ReconcilerUtilsInternal.java operator-framework-core/src/main/java/io/javaoperatorsdk/operator/ReconcilerUtils.java renamed to operator-framework-core/src/main/java/io/javaoperatorsdk/operator/ReconcilerUtilsInternal.java

@@ -34,7 +34,7 @@
 import io.javaoperatorsdk.operator.api.reconciler.Reconciler;
 
 @SuppressWarnings("rawtypes")
-public class ReconcilerUtils {
+public class ReconcilerUtilsInternal {
 
   private static final String FINALIZER_NAME_SUFFIX = "/finalizer";
   protected static final String MISSING_GROUP_SUFFIX = ".javaoperatorsdk.io";
@@ -46,7 +46,7 @@ public class ReconcilerUtils {
       Pattern.compile(".*http(s?)://[^/]*/api(s?)/(\\S*).*"); // NOSONAR: input is controlled
 
   // prevent instantiation of util class
-  private ReconcilerUtils() {}
+  private ReconcilerUtilsInternal() {}
 
   public static boolean isFinalizerValid(String finalizer) {
     return HasMetadata.validateFinalizer(finalizer);

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

@@ -22,7 +22,7 @@
 
 import io.fabric8.kubernetes.api.model.HasMetadata;
 import io.fabric8.kubernetes.client.KubernetesClient;
-import io.javaoperatorsdk.operator.ReconcilerUtils;
+import io.javaoperatorsdk.operator.ReconcilerUtilsInternal;
 import io.javaoperatorsdk.operator.api.reconciler.Reconciler;
 
 /**
@@ -145,7 +145,7 @@ private String getReconcilersNameMessage() {
   }
 
   protected <R extends HasMetadata> String keyFor(Reconciler<R> reconciler) {
-    return ReconcilerUtils.getNameFor(reconciler);
+    return ReconcilerUtilsInternal.getNameFor(reconciler);
   }
 
   @SuppressWarnings("unused")

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

@@ -28,7 +28,7 @@
 
 import io.fabric8.kubernetes.api.model.HasMetadata;
 import io.fabric8.kubernetes.client.KubernetesClient;
-import io.javaoperatorsdk.operator.ReconcilerUtils;
+import io.javaoperatorsdk.operator.ReconcilerUtilsInternal;
 import io.javaoperatorsdk.operator.api.config.Utils.Configurator;
 import io.javaoperatorsdk.operator.api.config.dependent.DependentResourceConfigurationResolver;
 import io.javaoperatorsdk.operator.api.config.dependent.DependentResourceSpec;
@@ -265,7 +265,7 @@ private <P extends HasMetadata> ResolvedControllerConfiguration<P> controllerCon
       io.javaoperatorsdk.operator.api.reconciler.ControllerConfiguration annotation) {
     final var resourceClass = getResourceClassResolver().getPrimaryResourceClass(reconcilerClass);
 
-    final var name = ReconcilerUtils.getNameFor(reconcilerClass);
+    final var name = ReconcilerUtilsInternal.getNameFor(reconcilerClass);
     final var generationAware =
         valueOrDefaultFromAnnotation(
             annotation,

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

@@ -20,7 +20,7 @@
 import java.util.Set;
 
 import io.fabric8.kubernetes.api.model.HasMetadata;
-import io.javaoperatorsdk.operator.ReconcilerUtils;
+import io.javaoperatorsdk.operator.ReconcilerUtilsInternal;
 import io.javaoperatorsdk.operator.api.config.dependent.DependentResourceSpec;
 import io.javaoperatorsdk.operator.api.config.workflow.WorkflowSpec;
 import io.javaoperatorsdk.operator.api.reconciler.MaxReconciliationInterval;
@@ -42,16 +42,18 @@ default String getName() {
   }
 
   default String getFinalizerName() {
-    return ReconcilerUtils.getDefaultFinalizerName(getResourceClass());
+    return ReconcilerUtilsInternal.getDefaultFinalizerName(getResourceClass());
   }
 
   static String ensureValidName(String name, String reconcilerClassName) {
-    return name != null ? name : ReconcilerUtils.getDefaultReconcilerName(reconcilerClassName);
+    return name != null
+        ? name
+        : ReconcilerUtilsInternal.getDefaultReconcilerName(reconcilerClassName);
   }
 
   static String ensureValidFinalizerName(String finalizer, String resourceTypeName) {
     if (finalizer != null && !finalizer.isBlank()) {
-      if (ReconcilerUtils.isFinalizerValid(finalizer)) {
+      if (ReconcilerUtilsInternal.isFinalizerValid(finalizer)) {
         return finalizer;
       } else {
         throw new IllegalArgumentException(
@@ -61,7 +63,7 @@ static String ensureValidFinalizerName(String finalizer, String resourceTypeName
                 + " for details");
       }
     } else {
-      return ReconcilerUtils.getDefaultFinalizerName(resourceTypeName);
+      return ReconcilerUtilsInternal.getDefaultFinalizerName(resourceTypeName);
     }
   }
 

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

@@ -25,7 +25,7 @@
 import io.fabric8.kubernetes.api.model.HasMetadata;
 import io.fabric8.kubernetes.client.informers.cache.ItemStore;
 import io.javaoperatorsdk.operator.OperatorException;
-import io.javaoperatorsdk.operator.ReconcilerUtils;
+import io.javaoperatorsdk.operator.ReconcilerUtilsInternal;
 import io.javaoperatorsdk.operator.api.config.ControllerConfiguration;
 import io.javaoperatorsdk.operator.api.config.Utils;
 import io.javaoperatorsdk.operator.api.reconciler.Constants;
@@ -92,7 +92,7 @@ private InformerConfiguration(Class<R> resourceClass) {
             // controller
             // where GenericKubernetesResource now does not apply
             ? GenericKubernetesResource.class.getSimpleName()
-            : ReconcilerUtils.getResourceTypeName(resourceClass);
+            : ReconcilerUtilsInternal.getResourceTypeName(resourceClass);
   }
 
   @SuppressWarnings({"rawtypes", "unchecked"})

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/BaseControl.java

@@ -21,22 +21,53 @@
 
 public abstract class BaseControl<T extends BaseControl<T>> {
 
+  public static final Long INSTANT_RESCHEDULE = 0L;
+
   private Long scheduleDelay = null;
 
+  /**
+   * Schedules a reconciliation to occur after the specified delay in milliseconds.
+   *
+   * @param delay the delay in milliseconds after which to reschedule
+   * @return this control instance for fluent chaining
+   */
   public T rescheduleAfter(long delay) {
     rescheduleAfter(Duration.ofMillis(delay));
     return (T) this;
   }
 
+  /**
+   * Schedules a reconciliation to occur after the specified delay.
+   *
+   * @param delay the {@link Duration} after which to reschedule
+   * @return this control instance for fluent chaining
+   */
   public T rescheduleAfter(Duration delay) {
     this.scheduleDelay = delay.toMillis();
     return (T) this;
   }
 
+  /**
+   * Schedules a reconciliation to occur after the specified delay using the given time unit.
+   *
+   * @param delay the delay value
+   * @param timeUnit the time unit of the delay
+   * @return this control instance for fluent chaining
+   */
   public T rescheduleAfter(long delay, TimeUnit timeUnit) {
     return rescheduleAfter(timeUnit.toMillis(delay));
   }
 
+  /**
+   * Schedules an instant reconciliation. The reconciliation will be triggered as soon as possible.
+   *
+   * @return this control instance for fluent chaining
+   */
+  public T reschedule() {
+    this.scheduleDelay = INSTANT_RESCHEDULE;
+    return (T) this;
+  }
+
   public Optional<Long> getScheduleDelay() {
     return Optional.ofNullable(scheduleDelay);
   }

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/PrimaryUpdateAndCacheUtils.java

@@ -45,7 +45,11 @@
  * caches the updated resource from the response in an overlay cache on top of the Informer cache.
  * If the update fails, it reads the primary resource from the cluster, applies the modifications
  * again and retries the update.
+ *
+ * @deprecated Use {@link ReconcileUtils} that contains the more efficient up-to-date versions of
+ *     the target utils.
  */
+@Deprecated(forRemoval = true)
 public class PrimaryUpdateAndCacheUtils {
 
   public static final int DEFAULT_MAX_RETRY = 10;