Add comments with context to apply and agent code

A couple of new comments should help our future selves, or our
successors, understand why this new logic has been added.

Author: weyfonk

internal/cmd/agent/controller/bundledeployment_controller.go

@@ -218,8 +218,14 @@ func (r *BundleDeploymentReconciler) Reconcile(ctx context.Context, req ctrl.Req
 		merr = append(merr, fmt.Errorf("failed refreshing drift detection: %w", err))
 	}
 
-	logger.V(1).Info("### ModifiedStatus", "orig", orig.Status.ModifiedStatus, "bd", bd.Status.ModifiedStatus)
-	// FIXME why would this run multiple times, e.g. every 5s?
+	// Check if this bundle deployment has overlapping resources with a previously deleted bundle (Overwrites
+	// field): if so, requeue to ensure the corresponding Helm release, and therefore its resources, are
+	// reinstalled.
+	// Overlaps are checked by namespace, kind and name. Resource contents do not matter in this context, as a
+	// resource would be deleted by Helm deleting its parent release based on its kind, name and namespace.
+	// This requires deleting the release beforehand, to force a new installation as the deployer would otherwise
+	// skip re-installing an existing release with no version change.
+	// See fleet#3770 for more context.
 	if len(orig.Status.ModifiedStatus) > 0 && len(orig.Spec.Options.Overwrites) > 0 {
 		for _, ms := range orig.Status.ModifiedStatus {
 			if !ms.Create { // missing

internal/cmd/cli/apply/apply.go

@@ -348,6 +348,13 @@ func pruneBundlesNotFoundInRepo(
 		if _, ok := gitRepoBundlesMap[bundle.Name]; !ok {
 			logrus.Debugf("Bundle to be deleted since it is not found in gitrepo %v anymore %v %v", repoName, bundle.Namespace, bundle.Name)
 
+			// Populate new bundles' `Overwrites` field with possible overlaps between the in-cluster bundle, to be deleted,
+			// and bundles which will be created in the cluster.
+			// Knowing about these overlaps, if any, the Fleet agent will then be able to:
+			// 1. match them against possible missing resources in a bundle deployment's status
+			// 2. trigger a new deployment, re-creating missing resources if those are overwritten by the
+			// bundle deployment
+			// See fleet#3770 for more context.
 			for _, inClusterRsc := range bundle.Spec.Resources {
 				for _, grb := range gitRepoBundlesMap {
 					logrus.Debugf("gitRepo bundle: %v", grb)