fix: Preserve user changes to deployment pod templates

Fixes OLM reverting user changes like kubectl rollout restart.
OLM no longer stores pod template metadata, allowing user changes o annotations, labels, and other fields to persist.

Generate-by: Cursor/Claude

Author: camilamacedo86

internal/operator-controller/applier/boxcutter.go

@@ -12,6 +12,7 @@ import (
 	"slices"
 	"strings"
 
+	"github.com/go-logr/logr"
 	"helm.sh/helm/v3/pkg/release"
 	"helm.sh/helm/v3/pkg/storage/driver"
 	apierrors "k8s.io/apimachinery/pkg/api/errors"
@@ -153,8 +154,53 @@ func (r *SimpleRevisionGenerator) GenerateRevision(
 	return r.buildClusterExtensionRevision(objs, ext, revisionAnnotations), nil
 }
 
+// removePodTemplateMetadata removes annotations from a Deployment's pod template metadata.
+// This prevents OLM from claiming ownership of pod template annotations via Server-Side Apply,
+// while preserving labels (which are required for selector matching and chart functionality).
+func removePodTemplateMetadata(unstr *unstructured.Unstructured, l logr.Logger) {
+	if unstr.GetKind() != "Deployment" || unstr.GroupVersionKind().Group != "apps" {
+		return
+	}
+
+	obj := unstr.Object
+	spec, ok := obj["spec"].(map[string]any)
+	if !ok {
+		return
+	}
+
+	template, ok := spec["template"].(map[string]any)
+	if !ok {
+		return
+	}
+
+	templateMeta, ok := template["metadata"].(map[string]any)
+	if !ok {
+		return
+	}
+
+	// Remove ONLY annotations from pod template metadata.
+	// Keep labels because they are needed for:
+	// 1. Deployment selector matching (API server validates this)
+	// 2. Chart-provided labels that other resources may depend on
+	// Removing annotations allows users to add custom annotations (like kubectl rollout restart)
+	// without OLM overwriting them.
+	if _, hasAnnotations := templateMeta["annotations"]; hasAnnotations {
+		delete(templateMeta, "annotations")
+		l.V(1).Info("removed pod template annotations from Deployment to preserve user changes",
+			"deployment", unstr.GetName())
+	}
+}
+
 // sanitizedUnstructured takes an unstructured obj, removes status if present, and returns a sanitized copy containing only the allowed metadata entries set below.
 // If any unallowed entries are removed, a warning will be logged.
+//
+// For Deployment objects, this function removes pod template annotations (but keeps labels).
+// This prevents OLM from overwriting user-added annotations while preserving required labels.
+// Examples: "kubectl rollout restart", "kubectl annotate", or any custom annotations users add.
+// Labels are kept because: (1) deployment selector must match template labels, and
+// (2) chart-provided labels may be referenced by other resources.
+// This fixes the issue where user changes to pod template annotations would be undone by OLM.
+// See: https://github.com/operator-framework/operator-lifecycle-manager/issues/3392
 func sanitizedUnstructured(ctx context.Context, unstr *unstructured.Unstructured) {
 	l := log.FromContext(ctx)
 	obj := unstr.Object
@@ -193,6 +239,13 @@ func sanitizedUnstructured(ctx context.Context, unstr *unstructured.Unstructured
 		l.Info("warning: extraneous values removed from manifest metadata", "allowed metadata", allowedMetadata)
 	}
 	obj["metadata"] = metadataSanitized
+
+	// For Deployment objects, remove pod template annotations (but keep labels).
+	// This prevents OLM from overwriting user-added annotations.
+	// Examples: kubectl rollout restart, kubectl annotate, custom annotations, etc.
+	// Labels are preserved because the deployment selector must match template labels,
+	// and chart-provided labels may be needed by other resources.
+	removePodTemplateMetadata(unstr, l)
 }
 
 func (r *SimpleRevisionGenerator) buildClusterExtensionRevision(

test/e2e/features/rollout-restart.feature

@@ -0,0 +1,80 @@
+Feature: Rollout Restart User Changes
+
+  # This test checks that OLMv1 does not undo user-added annotations on deployed resources.
+  # It uses "kubectl rollout restart" as an example, but the fix works for ANY pod template annotations.
+  #
+  # Background:
+  # - In OLMv0, user changes to pod template annotations would be undone by OLM.
+  # - In OLMv1, OLM should only manage the fields it owns, allowing user changes to stay.
+  #
+  # This test makes sure OLMv1 works correctly and does not have the OLMv0 problem.
+  # See: https://github.com/operator-framework/operator-lifecycle-manager/issues/3392
+
+  Background:
+    Given OLM is available
+    And ClusterCatalog "test" serves bundles
+    And ServiceAccount "olm-sa" with needed permissions is available in ${TEST_NAMESPACE}
+
+  # WHAT THIS TEST DOES:
+  # This test checks that the fix for issue #3392 works correctly.
+  # The test uses "kubectl rollout restart" as an example, but the fix works for ANY annotations.
+  #
+  # THE PROBLEM (now fixed):
+  # When users added annotations to pod templates, Boxcutter would undo the changes:
+  #   1. User adds annotation (kubectl rollout restart, kubectl annotate, custom annotations)
+  #   2. Boxcutter runs and removes the annotation
+  #   3. User changes are lost
+  #
+  # THE FIX:
+  # We changed the code in applier/boxcutter.go to NOT save pod template annotations.
+  # This way, OLM won't overwrite user annotations when it runs.
+  # Now ANY user annotations added to pod templates will stay in place.
+  # (Labels are kept because they're needed for deployment selector matching.)
+  #
+  # UPSTREAM ISSUE: https://github.com/operator-framework/operator-lifecycle-manager/issues/3392
+  @BoxcutterRuntime
+  Scenario: User-initiated deployment changes persist after OLM reconciliation
+    When ClusterExtension is applied
+      """
+      apiVersion: olm.operatorframework.io/v1
+      kind: ClusterExtension
+      metadata:
+        name: ${NAME}
+      spec:
+        namespace: ${TEST_NAMESPACE}
+        serviceAccount:
+          name: olm-sa
+        source:
+          sourceType: Catalog
+          catalog:
+            packageName: test
+            selector:
+              matchLabels:
+                "olm.operatorframework.io/metadata.name": test-catalog
+      """
+    Then ClusterExtension is rolled out
+    And ClusterExtension is available
+    And resource "deployment/test-operator" is installed
+    And deployment "test-operator" is ready
+
+    # User runs "kubectl rollout restart deployment/test-operator"
+    # This adds a restart annotation to trigger a rolling restart of pods.
+    # Note: This test uses restart as an example, but the fix works for ANY pod template annotations.
+    # In OLMv0, OLM would undo this annotation and stop the rollout.
+    # In OLMv1, the annotation should stay because kubectl owns it.
+    When user performs rollout restart on "deployment/test-operator"
+
+    # Wait for the rollout to finish - new pods created and running
+    Then deployment "test-operator" rollout completes successfully
+    And resource "deployment/test-operator" has restart annotation
+
+    # Wait for OLM to run its checks (OLM checks every 10 seconds)
+    # This is the important part: does OLM undo what the user did?
+    And I wait for "30" seconds
+
+    # After OLM runs, check that the rollout is STILL working
+    # In OLMv0, this would fail because OLM undoes the annotation
+    # and the new pods would be stopped and old pods would come back
+    Then deployment "test-operator" rollout is still successful
+    And resource "deployment/test-operator" has restart annotation
+    And deployment "test-operator" has expected number of ready replicas