improve

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

Author: csviri

docs/content/en/docs/documentation/access-resources.md

@@ -1,75 +1,71 @@
 ---
-title: Working with EventSource caches
+title: Accessing resources in caches
 weight: 48
 ---
 
 As described in [Event sources and related topics](eventing.md) event sources are the backbone
-for caching resources and triggering reconciliation of primary resources related
-to these secondary resources.
+for caching resources and triggering the reconciliation for primary resources thar are related 
+to cached resources.
 
-In Kubernetes parlance, `Informers` handle that responsibility. Without going into
-the details (there are plenty of good documents online regarding this topics), informers
-watch resources, cache them, and emit an event whenever watched resources change.
+In Kubernetes world, the component that does this is called Informer. Without going into
+the details (there are plenty of good documents online regarding informers), its responsibility
+is to watch resources, cache them, and emit an event if the resource changed.
 
-`EventSource` generalizes this concept to also cover non-Kubernetes resources. Thus,
-allowing caching of external resources, and triggering reconciliation when those change.
+EventSource is a generalized concept of Informer to non-Kubernetes resources. Thus,
+to cache external resources, and trigger reconciliation if those change.
 
 ## The InformerEventSource
 
-The underlying informer implementation comes from the Fabric8 client,
-called [DefaultSharedIndexInformer](https://github.com/fabric8io/kubernetes-client/blob/main/kubernetes-client/src/main/java/io/fabric8/kubernetes/client/informers/impl/DefaultSharedIndexInformer.java).
-[InformerEventSource](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/informer/InformerEventSource.java)
-in Java Operator SDK wraps informers from Fabric8 client, thus presenting a unified front to deal with Kubernetes and
-non-Kubernetes resources with the `EventSource` architecture.
+The underlying informer implementation comes from the fabric8 client, called [DefaultSharedIndexInformer](https://github.com/fabric8io/kubernetes-client/blob/main/kubernetes-client/src/main/java/io/fabric8/kubernetes/client/informers/impl/DefaultSharedIndexInformer.java).
+[InformerEventSource](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/informer/InformerEventSource.java) 
+in Java Operator SDK wraps informers from fabric8 client.
+The purpose of such wrapping is to add additional capabilities required for controllers.
+(In general, Informers are not used only for implementing controllers).
 
-However, `InformerEventSource` also provide additional capabilities such as:
-
-- recording the relations between primary and secondary resources so that the event source knows which primary resource
-  to trigger a reconciler with whenever one of the cached secondary resources cached by the informer changes,
-- setting up multiple informers for the same type if needed, for example to transparently watch multiple namespaces,
-  without you having to worry about it,
-- dynamically adding/removing watched namespaces, if needed
-- and more, outside of the scope of this document.
+Such capabilities are:
+- maintaining and index to which primary are the secondary resources in informer cache are related to.
+- setting up multiple informers for the same type if needed. You need informer per namespace if the informer 
+  is not watching the whole cluster.
+- Dynamically adding/removing watched namespaces.
+- Some others, what is out of the scope of this document.
 
 ### Associating Secondary Resources to Primary Resource
 
-Event sources need to trigger the appropriate reconciler, providing the correct primary resource, whenever one of their
-handled secondary resources changes. It is thus core to an event source's role to identify which primary resource (
-usually, your custom resource) is potentially impacted by that change.
-The framework uses [`SecondaryToPrimaryMapper`](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/SecondaryToPrimaryMapper.java)
-for this purpose. For `InformerEventSources`, which target Kubernetes resources, this mapping is typically done using
-either the owner reference or an annotation on the secondary resource. For external resources, other mechanisms need to
-be used and there are also cases where the default mechanisms provided by the SDK do not work, even for Kubernetes
-resources.
-
-However, once the event source has triggered a primary resource reconciliation, the associated reconciler needs to
-access the secondary resources which changes caused the reconciliation. Indeed, the information from the secondary
-resources might be needed during the reconciliation. For that purpose,  
-`InformerEventSource` maintains a reverse
-index [PrimaryToSecondaryIndex](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/informer/DefaultPrimaryToSecondaryIndex.java),
-based on the result of the `SecondaryToPrimaryMapper`result.
+The question is, how to trigger reconciliation of a primary resources (your custom resource),
+when Informer receives a new resource.
+For this purpose the framework uses [`SecondaryToPrimaryMapper`](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/SecondaryToPrimaryMapper.java)
+that tells (usually) based on the resource which primary resource reconciliation to trigger.
+The mapping is usually done based on the owner reference or annotation on the secondary resource. 
+(But not always, as we will see)
+
+It is important to realize that if a resource triggers the reconciliation of a primary resource, that
+resource naturally will be used during reconciliation. So the reconciler will need to access them. 
+Therefore, InformerEventSource maintains a revers index [PrimaryToSecondaryIndex](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/informer/DefaultPrimaryToSecondaryIndex.java), 
+based on the result of the `SecondaryToPrimaryMapper`result. 
 
 ## Unified API for Related Resources
 
-To access all related resources for a primary resource, the framework provides an API to access the related
-secondary resources using the `Set<R> getSecondaryResources(Class<R> expectedType)` method of the `Context` object
-provided as part of the `reconcile` method.
+To access all related resources for a primary resource, the framework provides an API to access the related 
+secondary resources using:
+
+```java
+Context.getSecondaryResources(Class<R> expectedType);
+```
 
-For `InformerEventSource`, this will leverage the associated `PrimaryToSecondaryIndex`. Resources are then retrieved
-from the informer's cache. Note that since all those steps work
+That will list all the related resources of a certain type, based on the `InformerEventSource`'s `PrimaryToSecondaryIndex`.
+Based on that index, it reads the resources from the Informers cache. Note that since all those steps work
 on top of indexes, those operations are very fast, usually O(1).
 
-While we've focused mostly on `InformerEventSource`, this concept can be extended to all `EventSources`, since
-[`EventSource`](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/EventSource.java#L93)
-actually implements the `Set<R> getSecondaryResources(P primary)` method that can be called from the `Context`.
+We mostly talk about InformerEventSource, but this works in similar ways for generalized EventSources concept, since
+the [`EventSource`](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/EventSource.java#L93)
+actually implements the `Set<R> getSecondaryResources(P primary);` method. That is just called from the context.
 
-As there can be multiple event sources for the same resource types, things are a little more complex: the union of each
-event source results is returned.
+It is a bit more complex than that, since there can be multiple event sources for the same type, in that case
+the union of the results is returned.
 
 ## Getting Resources Directly from Event Sources
 
-Note that nothing prevents you from directly accessing resources in the cache without going through
-`getSecondaryResources(...)`:
+Note that nothing stops you to directly access the resources in the cache (so not just through `getSecondaryResources(...)`):
 
 ```java
 public class WebPageReconciler implements Reconciler<WebPage> {
@@ -78,30 +74,35 @@ public class WebPageReconciler implements Reconciler<WebPage> {
 
     @Override
     public UpdateControl<WebPage> reconcile(WebPage webPage, Context<WebPage> context) {
-        // accessing resource directly from an event source 
-        var mySecondaryResource = configMapEventSource.get(new ResourceID("name", "namespace"));
-        // details omitted
+       // accessing resource directly from an event source 
+       var mySecondaryResource = configMapEventSource.get(new ResourceID("name","namespace"));
+       // details omitted
     }
-
+    
     @Override
     public List<EventSource<?, WebPage>> prepareEventSources(EventSourceContext<WebPage> context) {
-        configMapEventSource = new InformerEventSource<>(
+       configMapEventSource = new InformerEventSource<>(
                 InformerEventSourceConfiguration.from(ConfigMap.class, WebPage.class)
                         .withLabelSelector(SELECTOR)
                         .build(),
                 context);
-
+        
         return List.of(configMapEventSource);
     }
 }
 ```
 
 ## The Use Case for PrimaryToSecondaryMapper
 
+TL;DR: `PrimaryToSecondaryMapper` is used to access secondary resources in `InformerEventSource` instead 
+of the PrimaryToSecondaryIndex, thus `InfomerEventSource.getSecondaryResources(..)` will call this mapper
+to get the target secondary resources. This is usually required in cases when the `SecondaryToPrimaryMapper`
+is using the informer caches to list the target resources.
+
 As we discussed, we provide a unified API to access related resources using `Context.getSecondaryResources(...)`.
 The name `Secondary` refers to resources that a reconciler needs to take into account to properly reconcile a primary
 resource. These resources cover more than only `child` resources as resources created by a reconciler are sometimes
-called and which usually have a owner reference pointing to the primary (and, typically, custom) resource. These also
+called and which usually have an owner reference pointing to the primary (and, typically, custom) resource. These also
 cover `related` resources (which might or might not be managed by Kubernetes) that serve as input for reconciliations.
 
 There are cases where the SDK needs more information than what is readily available, in particular when some of these
@@ -118,81 +119,99 @@ resource.
 See full
 sample [here](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/baseapi/primarytosecondary).
 
-Even writing a `SecondaryToPrimaryMapper` is not trivial in this case, if the cluster is updated, we want to trigger
-all `Job`s that are referencing it. So we have to efficiently get the list of jobs, and return their ResourceIDs in
-the mapper. So we need an index that maps `Cluster` to `Job`s. Here we can use indexing capabilities of the Informers:
-
 ```java
+InformerEventSourceConfiguration
+        .from(Cluster.class, Job.class)
+        .withSecondaryToPrimaryMapper(cluster -> context.getPrimaryCache()
+              .list().filter(job -> job.getSpec().getClusterName().equals(cluster.getMetadata().getName()))
+              .map(ResourceID::fromResource)
+              .collect(Collectors.toSet()))
+```
+
+This will trigger all the related `Jobs` if the related cluster changes. Also, the maintaining the `PrimaryToSecondaryIndex`.
+So we can use the `getSecondaryResources` in the `Job` reconciler to access the cluster.
+However, there is an issue, what if now there is a new `Job` created? The new job does not propagate
+automatically to `PrimaryToSecondaryIndex` in the `InformerEventSource` of the `Cluster`. That re-indexing
+happens where there is an event received for the `Cluster` and triggers all the `Jobs` again.
+Until that would happen again you could not use `getSecondaryResources` for the new `Job`, since the new
+job won't bre present in the reverse index.
+
+You could access the Cluster directly from cache though in the reconciler:
+
+```java 
 
 @Override
-public List<EventSource<?, Job>> prepareEventSources(EventSourceContext<Job> context) {
+public UpdateControl<Job> reconcile(Job resource, Context<Job> context) {
 
-    context.getPrimaryCache()
-            .addIndexer(JOB_CLUSTER_INDEX,
-                    (job -> List.of(indexKey(job.getSpec().getClusterName(), job.getMetadata().getNamespace()))));
+    clusterInformer.get(new ResourceID(job.getSpec().getClusterName(), job.getMetadata().getNamespace()));
 
     // omitted details
 }
 ```
 
-where index key is a String that uniquely identifies a Cluster:
+But if you still want to use the unified API (thus `context.getSecondaryResources()`), we have to add 
+`PrimaryToSecondaryMapper`:
 
 ```java
-private String indexKey(String clusterName, String namespace) {
-    return clusterName + "#" + namespace;
-}
+clusterInformer.withPrimaryToSecondaryMapper( job -> 
+        Set.of(new ResourceID(job.getSpec().getClusterName(), job.getMetadata().getNamespace())));
 ```
 
-In the InformerEventSource for the cluster now we can get all the `Jobs` for the `Cluster` using this index:
+Using `PrimaryToSecondaryMapper` the InformerEventSource won't use the `PrimaryToSecondaryIndex`
+to get the resources, instead will call this mapper and will get the resources based on its result.
+In fact if this mapper is set the `PrimaryToSecondaryIndex` is not even initialized.
 
-```java
+### Using Informer Indexes to Improve Performance
 
-InformerEventSource<Job, Cluster> clusterInformer =
-        new InformerEventSource(
-                InformerEventSourceConfiguration.from(Cluster.class, Job.class)
-                        .withSecondaryToPrimaryMapper(
-                                cluster ->
-                                        context.getPrimaryCache()
-                                                .byIndex(
-                                                        JOB_CLUSTER_INDEX,
-                                                        indexKey(
-                                                                cluster.getMetadata().getName(),
-                                                                cluster.getMetadata().getNamespace()))
-                                                .stream()
-                                                .map(ResourceID::fromResource)
-                                                .collect(Collectors.toSet()))
-                        .withNamespacesInheritedFromController().build(), context);
-```
+In the `SecondaryToPrimaryMapper` above we are looping through all the resources in the cache:
 
-This will trigger all the related `Jobs` if a cluster changes. Also, the maintaining the `PrimaryToSecondaryIndex`.
-So we can use the `getSecondaryResources` in the `Job` reconciler to access the cluster.
-However, there is an issue, what if now there is a new `Job` created? The new job does not propagate
-automatically to `PrimaryToSecondaryIndex` in the `InformerEventSource` of the `Cluster`. That re-indexing
-happens where there is an event received for the `Cluster` and triggers all the `Jobs` again.
-Until that would happen again you could not use `getSecondaryResources` for the new `Job`.
+```java
+context.getPrimaryCache()
+              .list().filter(job -> job.getSpec().getClusterName().equals(cluster.getMetadata().getName()))
+```
 
-You could access the Cluster directly from cache though in the reconciler:
+This can be inefficient in case there is a large number of primary (Job) resources. To make it more efficient, we can
+ create an index in the underlying Informer, that indexed the target jobs for a cluster: 
 
-```java 
+```java
 
 @Override
-public UpdateControl<Job> reconcile(Job resource, Context<Job> context) {
-
-    clusterInformer.get(new ResourceID(job.getSpec().getClusterName(), job.getMetadata().getNamespace()));
+public List<EventSource<?, Job>> prepareEventSources(EventSourceContext<Job> context) {
 
+    context.getPrimaryCache()
+            .addIndexer(JOB_CLUSTER_INDEX,
+                    (job -> List.of(indexKey(job.getSpec().getClusterName(), job.getMetadata().getNamespace()))));
+    
     // omitted details
 }
 ```
 
-But if you still want to use the unified API (thus `context.getSecondaryResources()`), we can add 
-`PrimaryToSecondaryMapper`:
+where `indexKey` is a String that uniquely identifies a Cluster:
 
 ```java
-clusterInformer.withPrimaryToSecondaryMapper( job -> 
-        Set.of(new ResourceID(job.getSpec().getClusterName(), job.getMetadata().getNamespace())));
+private String indexKey(String clusterName, String namespace) {
+    return clusterName + "#" + namespace;
+  }
 ```
 
-That will get the `Cluster` for the `Job` from the cache of `Cluster`'s `InformerEventSource`.
-So it won't use the `PrimaryToSecondaryIndex`, that might be outdated, but instead will use the
-`PrimaryToSecondaryMapper` to get
-the target `Cluster` ids.
+From this point, we can use the index to get the target resources very efficiently:
+
+```java
+
+  InformerEventSource<Job,Cluster> clusterInformer =
+          new InformerEventSource(
+        InformerEventSourceConfiguration.from(Cluster.class, Job.class)
+            .withSecondaryToPrimaryMapper(
+                cluster ->
+                    context
+                        .getPrimaryCache()
+                        .byIndex(
+                            JOB_CLUSTER_INDEX,
+                            indexKey(
+                                cluster.getMetadata().getName(),
+                                cluster.getMetadata().getNamespace()))
+                        .stream()
+                        .map(ResourceID::fromResource)
+                        .collect(Collectors.toSet()))
+            .withNamespacesInheritedFromController().build(), context);
+```