docs

Author: csviri

docs/documentation/features.md

@@ -324,7 +324,30 @@ intersections:
    will still happen, but won't reset the retry, will be still marked as the last attempt in the retry info. The point
    (1) still holds, but in case of an error, no retry will happen.
 
-## Rate Limiting Reconciliation
+## Rate Limiting
+
+It is possible to rate limit reconciliation for a resource. Thus rate limiting is per resource, 
+and it takes precedence over retry and re-schedule configurations. So for example event a retry is scheduled in
+1 seconds but this does not meet the rate limit, the next reconciliation will be postponed according rate limiting rules;
+however never cancelled, just executed as early as possible according rate limit configuration.
+
+Rate limiting is by default turned off, since correct configuration depends on the reconciler implementation, and 
+how long an execution takes. 
+(The parallelism of reconciliation itself can be limited  [`ConfigurationService`](https://github.com/java-operator-sdk/java-operator-sdk/blob/ce4d996ee073ebef5715737995fc3d33f4751275/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ConfigurationService.java#L120-L120)
+by setting appropriate ExecutorService.)
+
+A default implementation of rate limiter is provided, see: [`PeriodRateLimiter`](https://github.com/java-operator-sdk/java-operator-sdk/blob/ce4d996ee073ebef5715737995fc3d33f4751275/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/rate/PeriodRateLimiter.java#L14-L14). 
+Users can override it with a custom implementation of 
+[`RateLimiter`](https://github.com/java-operator-sdk/java-operator-sdk/blob/ce4d996ee073ebef5715737995fc3d33f4751275/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/rate/RateLimiter.java)
+interface.
+
+To configure the default rate limiter use `@ControllerConfiguration` annotation. The following configuration limits
+the reconciliation to 2 in 3 seconds: 
+
+`@ControllerConfiguration(rateLimit = @RateLimit(limitForPeriod = 2,refreshPeriod = 3,refreshPeriodTimeUnit = TimeUnit.SECONDS))`.
+
+That means if the reconciler executed twice in one second, it will wait at least additional two seconds before it is
+reconciled again.
 
 
 ## Handling Related Events with Event Sources

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

@@ -148,10 +148,10 @@ public Optional<Duration> reconciliationMaxInterval() {
 
   @Override
   public RateLimiter getRateLimiter() {
-    if (annotation.rateLimiter() != null) {
-      return new PeriodRateLimiter(Duration.of(annotation.rateLimiter().refreshPeriod(),
-          annotation.rateLimiter().refreshPeriodTimeUnit().toChronoUnit()),
-          annotation.rateLimiter().limitForPeriod());
+    if (annotation.rateLimit() != null) {
+      return new PeriodRateLimiter(Duration.of(annotation.rateLimit().refreshPeriod(),
+          annotation.rateLimit().refreshPeriodTimeUnit().toChronoUnit()),
+          annotation.rateLimit().limitForPeriod());
     } else {
       return io.javaoperatorsdk.operator.api.config.ControllerConfiguration.super.getRateLimiter();
     }

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

@@ -70,7 +70,7 @@ ReconciliationMaxInterval reconciliationMaxInterval() default @ReconciliationMax
       interval = 10);
 
 
-  RateLimiter rateLimiter() default @RateLimiter;
+  RateLimit rateLimit() default @RateLimit;
 
   /**
    * Optional list of {@link Dependent} configurations which associate a resource type to a

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/RateLimiter.java renamed to operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/RateLimit.java

@@ -10,7 +10,7 @@
 
 @Retention(RetentionPolicy.RUNTIME)
 @Target({ElementType.TYPE})
-public @interface RateLimiter {
+public @interface RateLimit {
 
   int limitForPeriod() default PeriodRateLimiter.NO_LIMIT_PERIOD;
 

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/rate/RateLimiter.java

@@ -14,6 +14,9 @@ public interface RateLimiter {
    */
   Optional<Duration> acquirePermission(ResourceID resourceID);
 
+  /**
+   * Cleanup state. Called when resource is deleted.
+   */
   void clear(ResourceID resourceID);
 
 }

operator-framework/src/test/java/io/javaoperatorsdk/operator/sample/ratelimit/RateLimitReconciler.java

@@ -5,7 +5,7 @@
 
 import io.javaoperatorsdk.operator.api.reconciler.*;
 
-@ControllerConfiguration(rateLimiter = @RateLimiter(limitForPeriod = 1,
+@ControllerConfiguration(rateLimit = @RateLimit(limitForPeriod = 1,
     refreshPeriod = RateLimitReconciler.REFRESH_PERIOD,
     refreshPeriodTimeUnit = TimeUnit.MILLISECONDS))
 public class RateLimitReconciler

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

@@ -3,6 +3,7 @@
 import java.util.HashMap;
 import java.util.Map;
 import java.util.Objects;
+import java.util.concurrent.TimeUnit;
 
 import org.apache.commons.lang3.StringUtils;
 import org.slf4j.Logger;
@@ -18,22 +19,16 @@
 import io.fabric8.kubernetes.client.KubernetesClient;
 import io.javaoperatorsdk.operator.ReconcilerUtils;
 import io.javaoperatorsdk.operator.api.config.informer.InformerConfiguration;
-import io.javaoperatorsdk.operator.api.reconciler.Context;
-import io.javaoperatorsdk.operator.api.reconciler.ControllerConfiguration;
-import io.javaoperatorsdk.operator.api.reconciler.ErrorStatusHandler;
-import io.javaoperatorsdk.operator.api.reconciler.ErrorStatusUpdateControl;
-import io.javaoperatorsdk.operator.api.reconciler.EventSourceContext;
-import io.javaoperatorsdk.operator.api.reconciler.EventSourceInitializer;
-import io.javaoperatorsdk.operator.api.reconciler.Reconciler;
-import io.javaoperatorsdk.operator.api.reconciler.UpdateControl;
+import io.javaoperatorsdk.operator.api.reconciler.*;
 import io.javaoperatorsdk.operator.processing.event.source.EventSource;
 import io.javaoperatorsdk.operator.processing.event.source.informer.InformerEventSource;
 
 import static io.javaoperatorsdk.operator.sample.Utils.*;
 import static io.javaoperatorsdk.operator.sample.WebPageManagedDependentsReconciler.SELECTOR;
 
 /** Shows how to implement reconciler using the low level api directly. */
-@ControllerConfiguration
+@ControllerConfiguration(rateLimit = @RateLimit(limitForPeriod = 2, refreshPeriod = 3,
+    refreshPeriodTimeUnit = TimeUnit.SECONDS))
 public class WebPageReconciler
     implements Reconciler<WebPage>, ErrorStatusHandler<WebPage>, EventSourceInitializer<WebPage> {