✨ (deploy-image/v1-alpha1): Add comments to clarify resource watching and reconciliation logic

Added detailed comments in the SetupManager scaffold within the controller to explain how the resource watching and reconciliation process works. These comments clarify how the controller watches for changes in Custom Resources and Deployments, ensuring that the cluster maintains the desired state.

Author: camilamacedo86

docs/book/src/getting-started/testdata/project/internal/controller/memcached_controller.go

@@ -427,11 +427,22 @@ func imageForMemcached() (string, error) {
 }
 
 // SetupWithManager sets up the controller with the Manager.
-// Note that the Deployment will be also watched in order to ensure its
-// desirable state on the cluster
+// The whole idea is to be watching the resources that matter for the controller.
+// When a resource that the controller is interested in changes, the Watch triggers
+// the controller’s reconciliation loop, ensuring that the actual state of the resource
+// matches the desired state as defined in the controller’s logic.
+//
+// Notice how we configured the Manager to monitor events such as the creation, update,
+// or deletion of a Custom Resource (CR) of the Memcached kind, as well as any changes
+// to the Deployment that the controller manages and owns.
 func (r *MemcachedReconciler) SetupWithManager(mgr ctrl.Manager) error {
 	return ctrl.NewControllerManagedBy(mgr).
+		// Watch the Memcached CR(s) and trigger reconciliation whenever it
+		// is created, updated, or deleted
 		For(&cachev1alpha1.Memcached{}).
+		// Watch the Deployment managed by the MemcachedReconciler. If any changes occur to the Deployment
+		// owned and managed by this controller, it will trigger reconciliation, ensuring that the cluster
+		// state aligns with the desired state. See that the ownerRef was set when the Deployment was created.
 		Owns(&appsv1.Deployment{}).
 		Complete(r)
 }

pkg/plugins/golang/deploy-image/v1alpha1/scaffolds/internal/templates/controllers/controller.go

@@ -460,16 +460,27 @@ func imageFor{{ .Resource.Kind }}() (string, error) {
 }
 
 // SetupWithManager sets up the controller with the Manager.
-// Note that the Deployment will be also watched in order to ensure its
-// desirable state on the cluster
+// The whole idea is to be watching the resources that matter for the controller.
+// When a resource that the controller is interested in changes, the Watch triggers
+// the controller’s reconciliation loop, ensuring that the actual state of the resource
+// matches the desired state as defined in the controller’s logic.
+//
+// Notice how we configured the Manager to monitor events such as the creation, update,
+// or deletion of a Custom Resource (CR) of the {{ .Resource.Kind }} kind, as well as any changes 
+// to the Deployment that the controller manages and owns.
 func (r *{{ .Resource.Kind }}Reconciler) SetupWithManager(mgr ctrl.Manager) error {
 	return ctrl.NewControllerManagedBy(mgr).
 		{{ if not (isEmptyStr .Resource.Path) -}}
+		// Watch the {{ .Resource.Kind }} CR(s) and trigger reconciliation whenever it
+		// is created, updated, or deleted
 		For(&{{ .Resource.ImportAlias }}.{{ .Resource.Kind }}{}).
 		{{- else -}}
 		// Uncomment the following line adding a pointer to an instance of the controlled resource as an argument
 		// For().
 		{{- end }}
+		// Watch the Deployment managed by the {{ .Resource.Kind }}Reconciler. If any changes occur to the Deployment
+		// owned and managed by this controller, it will trigger reconciliation, ensuring that the cluster
+		// state aligns with the desired state. See that the ownerRef was set when the Deployment was created.
 		Owns(&appsv1.Deployment{}).
 		Complete(r)
 }

testdata/project-v4-with-deploy-image/internal/controller/busybox_controller.go

@@ -421,11 +421,22 @@ func imageForBusybox() (string, error) {
 }
 
 // SetupWithManager sets up the controller with the Manager.
-// Note that the Deployment will be also watched in order to ensure its
-// desirable state on the cluster
+// The whole idea is to be watching the resources that matter for the controller.
+// When a resource that the controller is interested in changes, the Watch triggers
+// the controller’s reconciliation loop, ensuring that the actual state of the resource
+// matches the desired state as defined in the controller’s logic.
+//
+// Notice how we configured the Manager to monitor events such as the creation, update,
+// or deletion of a Custom Resource (CR) of the Busybox kind, as well as any changes
+// to the Deployment that the controller manages and owns.
 func (r *BusyboxReconciler) SetupWithManager(mgr ctrl.Manager) error {
 	return ctrl.NewControllerManagedBy(mgr).
+		// Watch the Busybox CR(s) and trigger reconciliation whenever it
+		// is created, updated, or deleted
 		For(&examplecomv1alpha1.Busybox{}).
+		// Watch the Deployment managed by the BusyboxReconciler. If any changes occur to the Deployment
+		// owned and managed by this controller, it will trigger reconciliation, ensuring that the cluster
+		// state aligns with the desired state. See that the ownerRef was set when the Deployment was created.
 		Owns(&appsv1.Deployment{}).
 		Complete(r)
 }

testdata/project-v4-with-deploy-image/internal/controller/memcached_controller.go

@@ -427,11 +427,22 @@ func imageForMemcached() (string, error) {
 }
 
 // SetupWithManager sets up the controller with the Manager.
-// Note that the Deployment will be also watched in order to ensure its
-// desirable state on the cluster
+// The whole idea is to be watching the resources that matter for the controller.
+// When a resource that the controller is interested in changes, the Watch triggers
+// the controller’s reconciliation loop, ensuring that the actual state of the resource
+// matches the desired state as defined in the controller’s logic.
+//
+// Notice how we configured the Manager to monitor events such as the creation, update,
+// or deletion of a Custom Resource (CR) of the Memcached kind, as well as any changes
+// to the Deployment that the controller manages and owns.
 func (r *MemcachedReconciler) SetupWithManager(mgr ctrl.Manager) error {
 	return ctrl.NewControllerManagedBy(mgr).
+		// Watch the Memcached CR(s) and trigger reconciliation whenever it
+		// is created, updated, or deleted
 		For(&examplecomv1alpha1.Memcached{}).
+		// Watch the Deployment managed by the MemcachedReconciler. If any changes occur to the Deployment
+		// owned and managed by this controller, it will trigger reconciliation, ensuring that the cluster
+		// state aligns with the desired state. See that the ownerRef was set when the Deployment was created.
 		Owns(&appsv1.Deployment{}).
 		Complete(r)
 }