wip

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

Author: csviri

docs/content/en/blog/news/primary-cache-for-next-recon.md

@@ -10,9 +10,10 @@ author: >-
 Read-cache-after-write consistency feature replaces this functionality. (since version 5.3.0)
 
 > It provides this functionality also for secondary resources and optimistic locking
-is not required anymore. See [details here](./../../docs/documentation/reconciler.md#read-cache-after-write-consistency-and-event-filtering).
-{{% /alert %}}
+is not required anymore. See the [docs](./../../docs/documentation/reconciler.md#read-cache-after-write-consistency-and-event-filtering) and
+related [blog post](read-after-write-consistency.md) for details.
 
+{{% /alert %}}
 
 We recently released v5.1 of Java Operator SDK (JOSDK). One of the highlights of this release is related to a topic of
 so-called

docs/content/en/blog/news/read-after-write-consistency.md

@@ -89,7 +89,7 @@ it is not. Websocket can be disconnected (actually happens on purpose sometimes)
 
 ## The problem(s) we try to solve
 
-Let's consider the following operator:
+Let's consider an operator with the following requirements:
  - we have a custom resource `PodPrefix` where the spec contains only one field: `podNamePrexix`,
  - goal of the operator is to create a pod with name that has the prefix and a random sequence suffix
  - it should never run two pods at once, if the `podNamePrefix` changes it should delete
@@ -155,13 +155,88 @@ So can we have stronger guarantees regarding caches? It turns out we can now...
 
 ## Achieving read-cache-after-write consistency
 
+When we send an update (applies also on various create and patch) requests to Kubernetes API, in the response
+we receive the up-to-date resource, with the resource version that is the most recent at that point.
+The idea of the implementation is that we can cache the response in a cache on top the Informer's cache. 
+We call this cache `TemporaryResourceCache` (TRC) and among caching such responses has also role for event filtering
+as we will see later.
 
+Note that the challenge here was in the past, when to evict this response from the TRC. We eventually
+will receive an event in informer and the informer cache will be propagated with an up-to-date resource.
+But was not possible to tell reliably about an event that it contains a resource that it was a result 
+of an update prior or after our update. The reason is that Kubernetes documentation stated that the
+`metadata.resourceVersion` should be considered as a string, and should be matched only with equality.
+Although with optimistic locking we were able to overcome this issue, see [this blogpost](primary-cache-for-next-recon.md).
 
+{{% alert color=success %}}
+This changed in Kubernetes guidelines. Now if we are able to pars the `resourceVersion` as an integer
+we can use numerical comparison. See related [KEP](https://github.com/michaelasp/enhancements/tree/master/keps/sig-api-machinery/5504-comparable-resource-version)
+{{% /alert %}}
+
+From this point the idea of the algorithm is very simple:
 
+1. After update kubernetes resource cache the response in TRC if the Informer's cache.
+2. If the informer propagates an event, check if it's resource version is same or larger 
+   or equals than the one in the TRC, if yes, evict the resource from TRC.
+3. If the controller reads a resource from the cache first it checks if it in TRC then in Informers cache.
+    
+
+```mermaid
+sequenceDiagram
+    box rgba(50,108,229,0.1)
+        participant K8S as ⎈ Kubernetes API Server
+    end
+    box rgba(232,135,58,0.1)
+        participant R as Reconciler
+    end
+    box rgba(58,175,169,0.1)
+        participant I as Informer
+        participant IC as Informer Cache
+        participant TRC as Temporary Resource Cache
+    end
+
+    R->>K8S: 1. Update resource
+    K8S-->>R: Updated resource (with new resourceVersion)
+    R->>TRC: 2. Cache updated resource in TRC
+
+    I-)K8S: 3. Watch event (resource updated)
+    I->>TRC: On event: event resourceVersion ≥ TRC version?
+    alt Yes: event is up-to-date
+        I-->>TRC: Evict resource from TRC       
+    else No: stale event        
+        Note over TRC: TRC entry retained
+    end
+
+    R->>TRC: 4. Read resource from cache
+    alt Resource found in TRC
+        TRC-->>R: Return cached resource
+    else Not in TRC
+        R->>IC: Read from Informer Cache
+        IC-->>R: Return resource
+    end
+```
 
 ## Filtering events for our own updates
 
+When update a resource, eventually the informer will propagate an event that will trigger the reconciliation.
+However, this is mostly not something that is desired. Since we know we already know that point the up-to-date
+resource, we would like to be notified only if that resource is changed after our change.
+Therefore, in addition to the caching of the resource we also filter out the events which contains a resource
+version that is older or has the same resource version as our cached resource.
+
+Note that the implementation of this is relatively complex. Since while doing the update we want to record all the 
+events that we received meanwhile, and make a decision to propagate any further if the update request if complete.
+
+However, this way we significantly reduce the number of reconciliations, thus making the whole process much more efficient.  
+
+## Additional considerations and alternatives
+
+## Conclusion
+
+## Notes
+
 
 TODO:
+- alternatives => deferring reconciliation, this is optimized for throughput
 - filter events
 - reschedule