From 14483ea5a01bc8c67e2347b6ec1d58d7e011f5f1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Attila=20M=C3=A9sz=C3=A1ros?= Date: Mon, 13 Apr 2026 10:11:55 +0200 Subject: [PATCH 1/5] docs: dedicated section for rate limiting MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Attila Mészáros --- docs/content/en/docs/documentation/_index.md | 1 + .../content/en/docs/documentation/eventing.md | 47 +----------------- .../en/docs/documentation/rate-limiting.md | 49 +++++++++++++++++++ .../documentation/working-with-es-caches.md | 2 +- 4 files changed, 52 insertions(+), 47 deletions(-) create mode 100644 docs/content/en/docs/documentation/rate-limiting.md diff --git a/docs/content/en/docs/documentation/_index.md b/docs/content/en/docs/documentation/_index.md index 1352d70ca5..57e7fef122 100644 --- a/docs/content/en/docs/documentation/_index.md +++ b/docs/content/en/docs/documentation/_index.md @@ -14,6 +14,7 @@ This section contains detailed documentation for all Java Operator SDK features - **[Dependent Resources & Workflows](dependent-resource-and-workflows/)** - Managing resource relationships - **[Configuration](configuration/)** - Customizing operator behavior - **[Error Handling & Retries](error-handling-retries/)** - Managing failures gracefully +- **[Rate Limiting](rate-limiting/)** - Controlling reconciliation frequency per resource ## Advanced Features diff --git a/docs/content/en/docs/documentation/eventing.md b/docs/content/en/docs/documentation/eventing.md index 77daeb6fa3..d16031fa58 100644 --- a/docs/content/en/docs/documentation/eventing.md +++ b/docs/content/en/docs/documentation/eventing.md @@ -1,6 +1,6 @@ --- title: Event sources and related topics -weight: 47 +weight: 48 --- ## Handling Related Events with Event Sources @@ -251,51 +251,6 @@ or any non-positive number. The automatic retries are not affected by this feature so a reconciliation will be re-triggered on error, according to the specified retry policy, regardless of this maximum interval setting. -## Rate Limiting - -It is possible to rate limit reconciliation on a per-resource basis. The rate limit also takes -precedence over retry/re-schedule configurations: for example, even if a retry was scheduled for -the next second but this request would make the resource go over its rate limit, the next -reconciliation will be postponed according to the rate limiting rules. Note that the -reconciliation is never cancelled, it will just be executed as early as possible based on rate -limitations. - -Rate limiting is by default turned **off**, since correct configuration depends on the reconciler -implementation, in particular, on how long a typical reconciliation 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 configuring the `ExecutorService` appropriately.) - -A default rate limiter implementation 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 by implementing their own -[`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) -and specifying this custom implementation using the `rateLimiter` field of the -`@ControllerConfiguration` annotation. Similarly to the `Retry` implementations, -`RateLimiter` implementations must provide an accessible, no-arg constructor for instantiation -purposes and can further be automatically configured from your own, provided annotation provided -your `RateLimiter` implementation also implements the `AnnotationConfigurable` interface, -parameterized by your custom annotation type. - -To configure the default rate limiter use the `@RateLimited` annotation on your -`Reconciler` class. The following configuration limits each resource to reconcile at most twice -within a 3 second interval: - -```java - -@RateLimited(maxReconciliations = 2, within = 3, unit = TimeUnit.SECONDS) -@ControllerConfiguration -public class MyReconciler implements Reconciler { - -} -``` - -Thus, if a given resource was reconciled twice in one second, no further reconciliation for this -resource will happen before two seconds have elapsed. Note that, since rate is limited on a -per-resource basis, other resources can still be reconciled at the same time, as long, of course, -that they stay within their own rate limits. - ## Optimizing Caches One of the ideas around the operator pattern is that all the relevant resources are cached, thus reconciliation is diff --git a/docs/content/en/docs/documentation/rate-limiting.md b/docs/content/en/docs/documentation/rate-limiting.md new file mode 100644 index 0000000000..f621a5cd84 --- /dev/null +++ b/docs/content/en/docs/documentation/rate-limiting.md @@ -0,0 +1,49 @@ +--- +title: Rate limiting +weight: 47 +--- + +It is possible to rate limit reconciliation on a per-resource basis. The rate limit also takes +precedence over retry/re-schedule configurations: for example, even if retry would re-schedule a reconciliation +but this request would make the resource go over its rate limit, the next +reconciliation will be postponed according to the rate limiting rules. Note that the +reconciliation is never canceled, it will just be executed as early as possible based on rate +limitations. + +Rate limiting is by default turned **off**, since correct configuration depends on the reconciler +implementation, in particular, on how long a typical reconciliation takes. +(The parallelism of reconciliation itself can be limited via +[`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 configuring the `ExecutorService` appropriately.) + +We provide a generic rate limiter implementation: +[`PeriodRateLimiter`](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/rate/PeriodRateLimiter.java) +. +You can provide your own rate limiter by implementing the [`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. + +You can set this custom implementation using explicit [configuration](./operations/configuration.md) or using the `rateLimiter` +field of the `@ControllerConfiguration` annotation. +For the annotation approach, similarly to `Retry` implementations, +`RateLimiter` implementations must provide an accessible, no-arg constructor for instantiation +purposes and can further be automatically configured from your own annotation, provided that +your `RateLimiter` implementation also implements the `AnnotationConfigurable` interface, +parameterized by your custom annotation type. + +To configure the default rate limiter, use the `@RateLimited` annotation on your +`Reconciler` class. The following configuration limits each resource to reconcile at most twice +within a 3 second interval: + +```java + +@RateLimited(maxReconciliations = 2, within = 3, unit = TimeUnit.SECONDS) +@ControllerConfiguration +public class MyReconciler implements Reconciler { + +} +``` + +Thus, if a given resource was reconciled twice in one second, no further reconciliation for this +resource will happen before two seconds have elapsed. Note that, since rate is limited on a +per-resource basis, other resources can still be reconciled at the same time, as long, of course, +that they stay within their own rate limits. diff --git a/docs/content/en/docs/documentation/working-with-es-caches.md b/docs/content/en/docs/documentation/working-with-es-caches.md index a190d2a6cb..07c8a02f1b 100644 --- a/docs/content/en/docs/documentation/working-with-es-caches.md +++ b/docs/content/en/docs/documentation/working-with-es-caches.md @@ -1,6 +1,6 @@ --- title: Working with EventSource caches -weight: 48 +weight: 49 --- As described in [Event sources and related topics](eventing.md), event sources serve as the backbone From 6f3f7318ccaee318c43d4d29445fd8420d0e4763 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Attila=20M=C3=A9sz=C3=A1ros?= Date: Mon, 13 Apr 2026 10:19:46 +0200 Subject: [PATCH 2/5] fix links MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Attila Mészáros --- docs/content/en/docs/documentation/rate-limiting.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/en/docs/documentation/rate-limiting.md b/docs/content/en/docs/documentation/rate-limiting.md index f621a5cd84..a3a12109b1 100644 --- a/docs/content/en/docs/documentation/rate-limiting.md +++ b/docs/content/en/docs/documentation/rate-limiting.md @@ -17,12 +17,12 @@ implementation, in particular, on how long a typical reconciliation takes. by configuring the `ExecutorService` appropriately.) We provide a generic rate limiter implementation: -[`PeriodRateLimiter`](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/rate/PeriodRateLimiter.java) +[`LinearRateLimiter`](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/rate/LinearRateLimiter.java) . You can provide your own rate limiter by implementing the [`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. -You can set this custom implementation using explicit [configuration](./operations/configuration.md) or using the `rateLimiter` +You can set this custom implementation using explicit [configuration](operations/configuration.md) or using the `rateLimiter` field of the `@ControllerConfiguration` annotation. For the annotation approach, similarly to `Retry` implementations, `RateLimiter` implementations must provide an accessible, no-arg constructor for instantiation From 0bfe814a65059121954893c4f6697e25347d452c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Attila=20M=C3=A9sz=C3=A1ros?= Date: Mon, 13 Apr 2026 10:25:15 +0200 Subject: [PATCH 3/5] wip MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Attila Mészáros --- .../en/docs/documentation/rate-limiting.md | 44 ++++++++++--------- 1 file changed, 24 insertions(+), 20 deletions(-) diff --git a/docs/content/en/docs/documentation/rate-limiting.md b/docs/content/en/docs/documentation/rate-limiting.md index a3a12109b1..8d2df2a116 100644 --- a/docs/content/en/docs/documentation/rate-limiting.md +++ b/docs/content/en/docs/documentation/rate-limiting.md @@ -3,7 +3,7 @@ title: Rate limiting weight: 47 --- -It is possible to rate limit reconciliation on a per-resource basis. The rate limit also takes +It is possible to rate limit reconciliation on a per-resource basis. The rate limit takes precedence over retry/re-schedule configurations: for example, even if retry would re-schedule a reconciliation but this request would make the resource go over its rate limit, the next reconciliation will be postponed according to the rate limiting rules. Note that the @@ -16,26 +16,15 @@ implementation, in particular, on how long a typical reconciliation takes. [`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 configuring the `ExecutorService` appropriately.) -We provide a generic rate limiter implementation: -[`LinearRateLimiter`](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/rate/LinearRateLimiter.java) -. -You can provide your own rate limiter by implementing the [`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. +## Default Rate Limiter -You can set this custom implementation using explicit [configuration](operations/configuration.md) or using the `rateLimiter` -field of the `@ControllerConfiguration` annotation. -For the annotation approach, similarly to `Retry` implementations, -`RateLimiter` implementations must provide an accessible, no-arg constructor for instantiation -purposes and can further be automatically configured from your own annotation, provided that -your `RateLimiter` implementation also implements the `AnnotationConfigurable` interface, -parameterized by your custom annotation type. +We provide a generic rate limiter implementation: +[`LinearRateLimiter`](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/rate/LinearRateLimiter.java). -To configure the default rate limiter, use the `@RateLimited` annotation on your -`Reconciler` class. The following configuration limits each resource to reconcile at most twice -within a 3 second interval: +To configure it, use the `@RateLimited` annotation on your `Reconciler` class. The following +configuration limits each resource to reconcile at most twice within a 3 second interval: ```java - @RateLimited(maxReconciliations = 2, within = 3, unit = TimeUnit.SECONDS) @ControllerConfiguration public class MyReconciler implements Reconciler { @@ -44,6 +33,21 @@ public class MyReconciler implements Reconciler { ``` Thus, if a given resource was reconciled twice in one second, no further reconciliation for this -resource will happen before two seconds have elapsed. Note that, since rate is limited on a -per-resource basis, other resources can still be reconciled at the same time, as long, of course, -that they stay within their own rate limits. +resource will happen before two seconds have elapsed. Note that, since rate limiting is on a +per-resource basis, other resources can still be reconciled at the same time, as long as +they stay within their own rate limits. + +## Custom Rate Limiter + +You can provide your own rate limiter by implementing the +[`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 and setting it either through: + +- explicit [configuration](operations/configuration.md), or +- the `rateLimiter` field of the `@ControllerConfiguration` annotation. + +For the annotation approach, similarly to `Retry` implementations, +`RateLimiter` implementations must provide an accessible, no-arg constructor for instantiation +purposes and can further be automatically configured from your own annotation, provided that +your `RateLimiter` implementation also implements the `AnnotationConfigurable` interface, +parameterized by your custom annotation type. From a5596e27a08e4a54a6904747979f95b54a0bfa4d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Attila=20M=C3=A9sz=C3=A1ros?= Date: Mon, 13 Apr 2026 10:31:24 +0200 Subject: [PATCH 4/5] wip MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Attila Mészáros --- docs/content/en/docs/documentation/rate-limiting.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/content/en/docs/documentation/rate-limiting.md b/docs/content/en/docs/documentation/rate-limiting.md index 8d2df2a116..8fa8ee7b0f 100644 --- a/docs/content/en/docs/documentation/rate-limiting.md +++ b/docs/content/en/docs/documentation/rate-limiting.md @@ -12,11 +12,10 @@ limitations. Rate limiting is by default turned **off**, since correct configuration depends on the reconciler implementation, in particular, on how long a typical reconciliation takes. -(The parallelism of reconciliation itself can be limited via -[`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 configuring the `ExecutorService` appropriately.) -## Default Rate Limiter +Rate limiting is configured per controller, see [ControllerConfiguration](https://github.com/operator-framework/java-operator-sdk/blob/e976fb80d62f6bd0f714d78cec0a7a38d9b4a928/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ControllerConfiguration.java#L81). + +## The default LinearRateLimiter We provide a generic rate limiter implementation: [`LinearRateLimiter`](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/rate/LinearRateLimiter.java). @@ -40,7 +39,7 @@ they stay within their own rate limits. ## Custom Rate Limiter You can provide your own rate limiter by implementing the -[`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) +[`RateLimiter`](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/rate/RateLimiter.java) interface and setting it either through: - explicit [configuration](operations/configuration.md), or From 0b0062c7e40951cf9039af742a3a092b9e6c4c86 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Attila=20M=C3=A9sz=C3=A1ros?= Date: Mon, 13 Apr 2026 10:47:55 +0200 Subject: [PATCH 5/5] Update docs/content/en/docs/documentation/rate-limiting.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Attila Mészáros --- docs/content/en/docs/documentation/rate-limiting.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/en/docs/documentation/rate-limiting.md b/docs/content/en/docs/documentation/rate-limiting.md index 8fa8ee7b0f..c1d0147807 100644 --- a/docs/content/en/docs/documentation/rate-limiting.md +++ b/docs/content/en/docs/documentation/rate-limiting.md @@ -4,10 +4,10 @@ weight: 47 --- It is possible to rate limit reconciliation on a per-resource basis. The rate limit takes -precedence over retry/re-schedule configurations: for example, even if retry would re-schedule a reconciliation +precedence over retry/reschedule configurations: for example, even if a retry would reschedule a reconciliation but this request would make the resource go over its rate limit, the next reconciliation will be postponed according to the rate limiting rules. Note that the -reconciliation is never canceled, it will just be executed as early as possible based on rate +reconciliation is never cancelled, it will just be executed as early as possible based on rate limitations. Rate limiting is by default turned **off**, since correct configuration depends on the reconciler