From 6925e7d718a9cdbed4e4fdac93b8a577e024f703 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Attila=20M=C3=A9sz=C3=A1ros?= <a_meszaros@apple.com>
Date: Thu, 16 Jul 2026 14:41:48 +0200
Subject: [PATCH] docs: improve javadoc for ResourceOperation on resource
 cloning and matching
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add java doc remark that the desired resource has to be clone (or fresh instance created)
in order to have the maching work correctly

Signed-off-by: Attila Mészáros <a_meszaros@apple.com>
---
 .../operator/api/reconciler/ResourceOperations.java      | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/ResourceOperations.java b/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/ResourceOperations.java
index fdbac2db17..c4532aa284 100644
--- a/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/ResourceOperations.java
+++ b/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/ResourceOperations.java
@@ -99,6 +99,15 @@
  * from the desired one, thus also reducing the number of requests made against the Kubernetes API
  * server.
  *
+ * <p><strong>Matching against cached resources.</strong> When matching the actual resource (in most
+ * cases read from the cache) against the desired one for secondary resources, the matching must be
+ * done on a <em>cloned</em> version of the actual resource. Secondary resources are not cloned by
+ * default when read from the cache (see {@link
+ * io.javaoperatorsdk.operator.api.config.ConfigurationService#cloneSecondaryResourcesWhenGettingFromCache()}),
+ * so mutating the resource obtained from the cache while matching would also mutate the copy stored
+ * in the cache. Either clone the resource explicitly before matching, or enable {@link
+ * io.javaoperatorsdk.operator.api.config.ConfigurationService#cloneSecondaryResourcesWhenGettingFromCache()}.
+ *
  * @param <P> the primary resource type on which this object operates
  */
 public class ResourceOperations<P extends HasMetadata> {