docs

Author: csviri

caffein-bounded-cache-support/src/main/java/io/javaoperatorsdk/operator/processing/event/source/cache/CaffeinBoundedItemStores.java

@@ -8,20 +8,28 @@
 import com.github.benmanes.caffeine.cache.Cache;
 import com.github.benmanes.caffeine.cache.Caffeine;
 
+/**
+ * The idea about CaffeinBoundedItemStore-s is that, caffeine will cache the resources which were
+ * recently used, and will evict resource, which are not used for a while. This is ideal from the
+ * perspective that on startup controllers reconcile all resources (this is why a maxSize not ideal)
+ * but after a while it can happen (well depending on the controller and domain) that only some
+ * resources are actually active, thus related events happen. So in case large amount of custom
+ * resources only the active once will remain in the cache. Note that if a resource is reconciled
+ * all the secondary resources are usually reconciled too, in that case all those resources are
+ * fetched and populated to the cache, and will remain there for some time, for a subsequent
+ * reconciliations.
+ */
 public class CaffeinBoundedItemStores {
 
   private CaffeinBoundedItemStores() {}
 
-  public static <R extends HasMetadata> BoundedItemStore<R> boundedItemStore(
-      KubernetesClient client, Class<R> rClass,
-      Duration accessExpireDuration, long cacheMaxSize) {
-    Cache<String, R> cache = Caffeine.newBuilder()
-        .expireAfterAccess(accessExpireDuration)
-        .maximumSize(cacheMaxSize)
-        .build();
-    return boundedItemStore(client, rClass, cache);
-  }
-
+  /**
+   * @param client Kubernetes Client
+   * @param rClass resource class
+   * @param accessExpireDuration the duration after resources is evicted from cache if not accessed.
+   * @return the ItemStore implementation
+   * @param <R> resource type
+   */
   public static <R extends HasMetadata> BoundedItemStore<R> boundedItemStore(
       KubernetesClient client, Class<R> rClass,
       Duration accessExpireDuration) {

caffein-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/BoundedCacheTestBase.java

@@ -83,4 +83,6 @@ private void createTestResources() {
 
   abstract LocallyRunOperatorExtension extension();
 
+
+
 }

caffein-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/CaffeinBoundedCacheClusterScopeIT.java

@@ -11,14 +11,16 @@
 import io.javaoperatorsdk.operator.processing.event.source.cache.sample.clusterscope.BoundedCacheClusterScopeTestReconciler;
 import io.javaoperatorsdk.operator.processing.event.source.cache.sample.namespacescope.BoundedCacheTestSpec;
 
+import static io.javaoperatorsdk.operator.processing.event.source.cache.sample.AbstractTestReconciler.boundedItemStore;
+
 public class CaffeinBoundedCacheClusterScopeIT
     extends BoundedCacheTestBase<BoundedCacheClusterScopeTestCustomResource> {
 
   @RegisterExtension
   LocallyRunOperatorExtension extension =
       LocallyRunOperatorExtension.builder()
           .withReconciler(new BoundedCacheClusterScopeTestReconciler(), o -> {
-            o.withItemStore(CaffeinBoundedItemStores.boundedItemStore(
+            o.withItemStore(boundedItemStore(
                 new KubernetesClientBuilder().build(),
                 BoundedCacheClusterScopeTestCustomResource.class,
                 Duration.ofMinutes(1),

caffein-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/CaffeinBoundedCacheNamespacedIT.java

@@ -11,12 +11,14 @@
 import io.javaoperatorsdk.operator.processing.event.source.cache.sample.namespacescope.BoundedCacheTestReconciler;
 import io.javaoperatorsdk.operator.processing.event.source.cache.sample.namespacescope.BoundedCacheTestSpec;
 
+import static io.javaoperatorsdk.operator.processing.event.source.cache.sample.AbstractTestReconciler.boundedItemStore;
+
 class CaffeinBoundedCacheNamespacedIT extends BoundedCacheTestBase<BoundedCacheTestCustomResource> {
 
   @RegisterExtension
   LocallyRunOperatorExtension extension =
       LocallyRunOperatorExtension.builder().withReconciler(new BoundedCacheTestReconciler(), o -> {
-        o.withItemStore(CaffeinBoundedItemStores.boundedItemStore(
+        o.withItemStore(boundedItemStore(
             new KubernetesClientBuilder().build(), BoundedCacheTestCustomResource.class,
             Duration.ofMinutes(1),
             1));

caffein-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/sample/AbstractTestReconciler.java

@@ -15,13 +15,17 @@
 import io.javaoperatorsdk.operator.api.reconciler.Context;
 import io.javaoperatorsdk.operator.junit.KubernetesClientAware;
 import io.javaoperatorsdk.operator.processing.event.source.EventSource;
+import io.javaoperatorsdk.operator.processing.event.source.cache.BoundedItemStore;
 import io.javaoperatorsdk.operator.processing.event.source.cache.CaffeinBoundedItemStores;
 import io.javaoperatorsdk.operator.processing.event.source.cache.sample.clusterscope.BoundedCacheClusterScopeTestReconciler;
 import io.javaoperatorsdk.operator.processing.event.source.cache.sample.namespacescope.BoundedCacheTestSpec;
 import io.javaoperatorsdk.operator.processing.event.source.cache.sample.namespacescope.BoundedCacheTestStatus;
 import io.javaoperatorsdk.operator.processing.event.source.informer.InformerEventSource;
 import io.javaoperatorsdk.operator.processing.event.source.informer.Mappers;
 
+import com.github.benmanes.caffeine.cache.Cache;
+import com.github.benmanes.caffeine.cache.Caffeine;
+
 public abstract class AbstractTestReconciler<P extends CustomResource<BoundedCacheTestSpec, BoundedCacheTestStatus>>
     implements KubernetesClientAware, Reconciler<P>,
     EventSourceInitializer<P> {
@@ -82,9 +86,8 @@ public Map<String, EventSource> prepareEventSources(
       EventSourceContext<P> context) {
 
     var boundedItemStore =
-        CaffeinBoundedItemStores.boundedItemStore(new KubernetesClientBuilder().build(),
-            ConfigMap.class, Duration.ofMinutes(1),
-            1);
+        boundedItemStore(new KubernetesClientBuilder().build(),
+            ConfigMap.class, Duration.ofMinutes(1), 1); // setting max size for testing purposes
 
     var es = new InformerEventSource<>(InformerConfiguration.from(ConfigMap.class, context)
         .withItemStore(boundedItemStore)
@@ -101,4 +104,15 @@ private void ensureStatus(P resource) {
     }
   }
 
+  public static <R extends HasMetadata> BoundedItemStore<R> boundedItemStore(
+      KubernetesClient client, Class<R> rClass,
+      Duration accessExpireDuration,
+      // max size is only for testing purposes
+      long cacheMaxSize) {
+    Cache<String, R> cache = Caffeine.newBuilder()
+        .expireAfterAccess(accessExpireDuration)
+        .maximumSize(cacheMaxSize)
+        .build();
+    return CaffeinBoundedItemStores.boundedItemStore(client, rClass, cache);
+  }
 }

docs/documentation/features.md

@@ -739,3 +739,29 @@ with a `mycrs` plural form will result in 2 files:
 **NOTE:**
 > Quarkus users using the `quarkus-operator-sdk` extension do not need to add any extra dependency
 > to get their CRD generated as this is handled by the extension itself.
+
+## Optimizing Caches
+
+One of the ideas around operator pattern, is that all the relevant resources are cached, thus reconciliation is usually
+very fast (especially if it does not need to update resources) since it's mostly working with in memory state.
+However or large clusters, caching huge amount of primary and secondary resources might consume lots of memory.
+There are some semi-experimental (experimental in terms that it works, but we need feedback from real production usage) 
+features to optimize memory usage of controllers. 
+
+### Bounded Caches for Informers 
+
+Limiting caches for informers - thus for Kubernetes resources, both controllers primary resource - is supported for now.
+The idea with the implementation that is provided, is that resources are in the cache for a limited time. 
+So for use cases, when a resource is only frequently reconciled when it is created, and later no or 
+occasionally reconciled, will be evicted from the cache, since the resources are not accessed. 
+If a resource accessed in the future but not in the cache, the bounded cache implementation will fetch it from
+the service if needed. 
+Note that on start of a controller all the resources are reconciled, for this reason explicitly setting a maximal
+size of a cache might not be ideal. In other words it is desired to have all the resources in the cache at startup, 
+but not later if not accessed.
+
+See usage of the related implementation using Caffein cache in integration tests for [primary resource](https://github.com/java-operator-sdk/java-operator-sdk/blob/10e11e587447667ef0da1ddb29e0ba15fcd24ada/caffein-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/CaffeinBoundedCacheNamespacedIT.java#L19-L19) and for an [informer](https://github.com/java-operator-sdk/java-operator-sdk/blob/10e11e587447667ef0da1ddb29e0ba15fcd24ada/caffein-bounded-cache-support/src/test/java/io/javaoperatorsdk/operator/processing/event/source/cache/sample/AbstractTestReconciler.java#L84-L93).
+
+See also [CaffeinBoundedItemStores](https://github.com/java-operator-sdk/java-operator-sdk/blob/10e11e587447667ef0da1ddb29e0ba15fcd24ada/caffein-bounded-cache-support/src/main/java/io/javaoperatorsdk/operator/processing/event/source/cache/CaffeinBoundedItemStores.java#L22-L22)
+
+

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/cache/BoundedItemStore.java

@@ -114,7 +114,7 @@ public static <R extends HasMetadata> Function<R, String> namespaceKeyFunc() {
   }
 
   protected R refreshMissingStateFromServer(String key) {
-    log.debug("Fetching resource from server");
+    log.debug("Fetching resource from server for key: {}", key);
     var newRes = resourceFetcher.fetchResource(key);
     synchronized (this) {
       log.debug("Fetched resource: {}", newRes);