Preserve deployment and template metadata during reconcile

When running `kubectl rollout restart deployment`, Kubernetes adds the
`kubectl.kubernetes.io/restartedAt` annotation to the deployment's pod
template to trigger a rolling restart. However, Knative's reconciler was
removing this annotation by completely replacing the deployment spec,
causing new pods to be immediately terminated instead of completing the
rollout.

This change preserves externally-added metadata at both the deployment
level and template level during reconciliation by filtering Knative-controlled
keys (*.knative.dev and app label) from the current state before merging with
the desired state. This ensures Knative maintains full control over its own
metadata while preserving external additions.

Author: linkvt

pkg/reconciler/revision/cruds.go

@@ -19,13 +19,14 @@ package revision
 import (
 	"context"
 	"fmt"
+	"strings"
 
 	appsv1 "k8s.io/api/apps/v1"
 	"k8s.io/apimachinery/pkg/api/equality"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 
 	caching "knative.dev/caching/pkg/apis/caching/v1alpha1"
-	"knative.dev/pkg/kmeta"
+	"knative.dev/pkg/kmap"
 	"knative.dev/pkg/kmp"
 	"knative.dev/pkg/logging"
 	autoscalingv1alpha1 "knative.dev/serving/pkg/apis/autoscaling/v1alpha1"
@@ -71,8 +72,13 @@ func (c *Reconciler) checkAndUpdateDeployment(ctx context.Context, rev *v1.Revis
 	desiredDeployment := have.DeepCopy()
 	desiredDeployment.Spec = deployment.Spec
 
-	// Carry over new labels.
-	desiredDeployment.Labels = kmeta.UnionMaps(deployment.Labels, desiredDeployment.Labels)
+	// Carry over new labels and annotations at deployment level.
+	desiredDeployment.Labels = mergeMetadata(deployment.Labels, have.Labels)
+	desiredDeployment.Annotations = mergeMetadata(deployment.Annotations, have.Annotations)
+
+	// Carry over template-level labels and annotations (e.g., kubectl.kubernetes.io/restartedAt from rollout restart).
+	desiredDeployment.Spec.Template.Labels = mergeMetadata(deployment.Spec.Template.Labels, have.Spec.Template.Labels)
+	desiredDeployment.Spec.Template.Annotations = mergeMetadata(deployment.Spec.Template.Annotations, have.Spec.Template.Annotations)
 
 	d, err := c.kubeclient.AppsV1().Deployments(deployment.Namespace).Update(ctx, desiredDeployment, metav1.UpdateOptions{})
 	if err != nil {
@@ -94,6 +100,16 @@ func (c *Reconciler) checkAndUpdateDeployment(ctx context.Context, rev *v1.Revis
 	return d, nil
 }
 
+// mergeMetadata merges Knative-managed metadata with external metadata.
+// Knative controls knative.dev keys and the app label; other keys are preserved from current.
+func mergeMetadata(desired, current map[string]string) map[string]string {
+	isKnativeKey := func(key string) bool {
+		return key == resources.AppLabelKey || strings.Contains(key, "knative.dev/")
+	}
+	external := kmap.Filter(current, isKnativeKey)
+	return kmap.Union(desired, external)
+}
+
 func (c *Reconciler) createImageCache(ctx context.Context, rev *v1.Revision, containerName, imageDigest string) (*caching.Image, error) {
 	image := resources.MakeImageCache(rev, containerName, imageDigest)
 	return c.cachingclient.CachingV1alpha1().Images(image.Namespace).Create(ctx, image, metav1.CreateOptions{})

pkg/reconciler/revision/cruds_test.go

@@ -0,0 +1,72 @@
+/*
+Copyright 2025 The Knative Authors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package revision
+
+import (
+	"testing"
+
+	"github.com/google/go-cmp/cmp"
+)
+
+func TestMergeMetadata(t *testing.T) {
+	tests := []struct {
+		name    string
+		desired map[string]string
+		current map[string]string
+		want    map[string]string
+	}{
+		{
+			name:    "preserve external annotations",
+			desired: map[string]string{"serving.knative.dev/creator": "kubernetes-admin"},
+			current: map[string]string{"kubectl.kubernetes.io/restartedAt": "2025-11-27T12:14:41+01:00"},
+			want:    map[string]string{"serving.knative.dev/creator": "kubernetes-admin", "kubectl.kubernetes.io/restartedAt": "2025-11-27T12:14:41+01:00"},
+		},
+		{
+			name:    "knative annotations from desired win",
+			desired: map[string]string{"serving.knative.dev/lastModifier": "kubernetes-admin"},
+			current: map[string]string{"serving.knative.dev/lastModifier": "old-user"},
+			want:    map[string]string{"serving.knative.dev/lastModifier": "kubernetes-admin"},
+		},
+		{
+			name:    "delete knative annotations not in desired",
+			desired: map[string]string{"serving.knative.dev/creator": "kubernetes-admin"},
+			current: map[string]string{"serving.knative.dev/creator": "kubernetes-admin", "autoscaling.knative.dev/min-scale": "2"},
+			want:    map[string]string{"serving.knative.dev/creator": "kubernetes-admin"},
+		},
+		{
+			name:    "app label from desired wins",
+			desired: map[string]string{"app": "new-revision"},
+			current: map[string]string{"app": "old-revision"},
+			want:    map[string]string{"app": "new-revision"},
+		},
+		{
+			name:    "mixed knative and external metadata",
+			desired: map[string]string{"autoscaling.knative.dev/min-scale": "1", "app": "my-revision"},
+			current: map[string]string{"autoscaling.knative.dev/target-burst-capacity": "0", "deployment.kubernetes.io/revision": "2", "kubectl.kubernetes.io/restartedAt": "2025-11-27T12:14:41+01:00"},
+			want:    map[string]string{"autoscaling.knative.dev/min-scale": "1", "app": "my-revision", "deployment.kubernetes.io/revision": "2", "kubectl.kubernetes.io/restartedAt": "2025-11-27T12:14:41+01:00"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := mergeMetadata(tt.desired, tt.current)
+			if diff := cmp.Diff(tt.want, got); diff != "" {
+				t.Errorf("mergeMetadata() mismatch (-want +got):\n%s", diff)
+			}
+		})
+	}
+}

pkg/reconciler/revision/table_test.go

@@ -210,6 +210,19 @@ func TestReconcile(t *testing.T) {
 			Object: deploy(t, "foo", "fix-containers"),
 		}},
 		Key: "foo/fix-containers",
+	}, {
+		Name: "preserve external deployment and template annotations and labels",
+		Objects: []runtime.Object{
+			Revision("foo", "preserve-annotations",
+				WithLogURL, allUnknownConditions, withDefaultContainerStatuses(), WithRevisionObservedGeneration(1)),
+			pa("foo", "preserve-annotations", WithReachabilityUnknown),
+			addDeploymentMetadata(deploy(t, "foo", "preserve-annotations"), true),
+			image("foo", "preserve-annotations"),
+		},
+		WantUpdates: []clientgotesting.UpdateActionImpl{{
+			Object: addDeploymentMetadata(deploy(t, "foo", "preserve-annotations"), false),
+		}},
+		Key: "foo/preserve-annotations",
 	}, {
 		Name: "failure updating deployment",
 		// Test that we handle an error updating the deployment properly.
@@ -945,6 +958,25 @@ func changeContainers(deploy *appsv1.Deployment) *appsv1.Deployment {
 	return deploy
 }
 
+func addDeploymentMetadata(deploy *appsv1.Deployment, addInternalLabels bool) *appsv1.Deployment {
+	setValue := func(m map[string]string, scope string) {
+		m["external.io/"+scope] = "external-" + scope
+		if addInternalLabels {
+			m[resources.AppLabelKey] = "app"
+			m["internal.knative.dev/foo"] = "bar"
+		}
+	}
+	// Deployment-level metadata
+	setValue(deploy.Annotations, "annotation")
+	setValue(deploy.Labels, "label")
+
+	// Template-level metadata (e.g. from kubectl restart)
+	setValue(deploy.Spec.Template.Annotations, "template-annotation")
+	setValue(deploy.Spec.Template.Labels, "template-label")
+
+	return deploy
+}
+
 func withDefaultContainerStatuses() RevisionOption {
 	return func(r *v1.Revision) {
 		r.Status.ContainerStatuses = []v1.ContainerStatus{{