📖 Explain what may happen when using OnlyMetadata and Get on the concrete type instead of PartialMetadataObject (#1747)

* Document in API the consequence of mixing concrete and metadata

* Consequence of mixing concrete and metadata: add pod.SetGroupVersionKind

Author: maelvls

pkg/builder/options.go

@@ -107,6 +107,29 @@ var (
 	// metav1.PartialObjectMetadata to the client when fetching objects in your
 	// reconciler, otherwise you'll end up with a duplicate structured or
 	// unstructured cache.
+	//
+	// When watching a resource with OnlyMetadata, for example the v1.Pod, you
+	// should not Get and List using the v1.Pod type. Instead, you should use
+	// the special metav1.PartialObjectMetadata type.
+	//
+	// ❌ Incorrect:
+	//
+	//   pod := &v1.Pod{}
+	//   mgr.GetClient().Get(ctx, nsAndName, pod)
+	//
+	// ✅ Correct:
+	//
+	//   pod := &metav1.PartialObjectMetadata{}
+	//   pod.SetGroupVersionKind(schema.GroupVersionKind{
+	//       Group:   "",
+	//       Version: "v1",
+	//       Kind:    "Pod",
+	//   })
+	//   mgr.GetClient().Get(ctx, nsAndName, pod)
+	//
+	// In the first case, controller-runtime will create another cache for the
+	// concrete type on top of the metadata cache; this increases memory
+	// consumption and leads to race conditions as caches are not in sync.
 	OnlyMetadata = projectAs(projectAsMetadata)
 
 	_ ForOption     = OnlyMetadata