From 32b10c19913598fb72564889f91abd5a0d528059 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Attila=20M=C3=A9sz=C3=A1ros?= <a_meszaros@apple.com>
Date: Fri, 27 Jun 2025 09:07:49 +0200
Subject: [PATCH] docs: add faq entry regarding event filtering
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Attila Mészáros <a_meszaros@apple.com>
---
 docs/content/en/docs/faq/_index.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/docs/content/en/docs/faq/_index.md b/docs/content/en/docs/faq/_index.md
index 10a15c0eac..23a6ea2743 100644
--- a/docs/content/en/docs/faq/_index.md
+++ b/docs/content/en/docs/faq/_index.md
@@ -95,6 +95,32 @@ to make sure an updated status is present for the next reconciliation.
 
 Dependent Resources feature supports the [first approach](../documentation/dependent-resource-and-workflows/dependent-resources.md#external-state-tracking-dependent-resources).
     
+### How can I make the status update of my custom resource trigger a reconciliation?
+
+For the primary resource, the framework by default specially checks if the change on the primary 
+resource is increased the `generation` field in the metadata, and filters out the related event if not. 
+This field is increased when `.spec` of the resource is changed. Therefore, a change in the `.status` field
+will not trigger a reconciliation. 
+
+To change this behavior, you can set the [`generationAwareEventProcessing`](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/ControllerConfiguration.java#L43)
+to `false`:
+
+```java
+@ControllerConfiguration(generationAwareEventProcessing = false)
+  static class TestCustomReconciler implements Reconciler<TestCustomResource> {
+
+    @Override
+    public UpdateControl<TestCustomResource> reconcile(TestCustomResource resource, Context<TestCustomResource> context) {
+        // code omitted
+    }
+  }
+```
+
+For secondary resources, every change should trigger a reconciliation by default. 
+Except when you add explicit filter or use dependent resources that by default filter out own changes,
+see [related docs](../documentation/dependent-resource-and-workflows/dependent-resources.md#caching-and-event-handling-in-kubernetesdependentresource).
+
+
 ### How can I skip the reconciliation of a dependent resource?
 
 Skipping workflow reconciliation altogether is possible with the explicit invocation feature since v5.