feat(patch): Patch of entity filters volatile metadata fields like UID which are not relevant for Diffs (#925)

Fields like "metadata.uid" and resourceversion
are ever-changing. Those fields should be filtered
during patch to reduce API load.

Author: buehler

src/KubeOps.Abstractions/Entities/JsonPatchExtensions.cs

@@ -18,6 +18,54 @@ namespace KubeOps.Abstractions.Entities;
 /// </summary>
 public static class JsonPatchExtensions
 {
+    /// <summary>
+    /// <para>
+    /// Ignored properties that should not be included (by default) in the JSON Patch diff.
+    /// This mainly concerns metadata properties that are not relevant for the diff,
+    /// like the UID of the object and resource version.
+    /// </para>
+    /// <para>Currently, contains the following properties:</para>
+    /// <list type="bullet">
+    /// <item><term>/metadata/creationTimestamp</term></item>
+    /// <item><term>/metadata/deletionGracePeriodSeconds</term></item>
+    /// <item><term>/metadata/deletionTimestamp</term></item>
+    /// <item><term>/metadata/generation</term></item>
+    /// <item><term>/metadata/managedFields</term></item>
+    /// <item><term>/metadata/resourceVersion</term></item>
+    /// <item><term>/metadata/selfLink</term></item>
+    /// <item><term>/metadata/uid</term></item>
+    /// </list>
+    /// </summary>
+    public static readonly string[] DefaultIgnoredProperties =
+    [
+        "/metadata/creationTimestamp",
+        "/metadata/deletionGracePeriodSeconds",
+        "/metadata/deletionTimestamp",
+        "/metadata/generation",
+        "/metadata/managedFields",
+        "/metadata/resourceVersion",
+        "/metadata/selfLink",
+        "/metadata/uid",
+    ];
+
+    /// <summary>
+    /// Default operations filter that filters out operations that are listed in <see cref="DefaultIgnoredProperties"/>.
+    /// This filters out most properties in the metadata section of the entity that are not relevant for diffing.
+    /// Currently, this filters out the following properties (<see cref="DefaultIgnoredProperties"/>):
+    /// <list type="bullet">
+    /// <item><term>/metadata/creationTimestamp</term></item>
+    /// <item><term>/metadata/deletionGracePeriodSeconds</term></item>
+    /// <item><term>/metadata/deletionTimestamp</term></item>
+    /// <item><term>/metadata/generation</term></item>
+    /// <item><term>/metadata/managedFields</term></item>
+    /// <item><term>/metadata/resourceVersion</term></item>
+    /// <item><term>/metadata/selfLink</term></item>
+    /// <item><term>/metadata/uid</term></item>
+    /// </list>
+    /// </summary>
+    public static readonly Func<IReadOnlyList<PatchOperation>, IReadOnlyList<PatchOperation>> DefaultOperationsFilter =
+        operations => operations.Where(o => !DefaultIgnoredProperties.Contains(o.Path.ToString())).ToList();
+
     /// <summary>
     /// Convert a <see cref="IKubernetesObject{TMetadata}"/> into a <see cref="JsonNode"/>.
     /// </summary>
@@ -30,21 +78,37 @@ public static class JsonPatchExtensions
     /// Computes the JSON Patch diff between two Kubernetes entities implementing <see cref="IKubernetesObject{V1ObjectMeta}"/>.
     /// This method serializes both entities to JSON and calculates the difference as a JSON Patch document.
     /// </summary>
+    /// <typeparam name="TEntity">The entity type.</typeparam>
     /// <param name="from">The source entity to compare from.</param>
     /// <param name="to">The target entity to compare to.</param>
+    /// <param name="operationsFilter">An optional filter action that filters the <see cref="PatchOperation"/>s that are contained in the <see cref="JsonPatch"/>.</param>
     /// <returns>A <see cref="JsonNode"/> representing the JSON Patch diff between the two entities.</returns>
     /// <exception cref="InvalidOperationException">Thrown if the diff could not be created.</exception>
-    public static JsonPatch CreateJsonPatch(
-        this IKubernetesObject<V1ObjectMeta> from,
-        IKubernetesObject<V1ObjectMeta> to)
+    public static JsonPatch CreateJsonPatch<TEntity>(
+        this TEntity from,
+        TEntity to,
+        Func<IReadOnlyList<PatchOperation>, IReadOnlyList<PatchOperation>>? operationsFilter = null)
+        where TEntity : IKubernetesObject<V1ObjectMeta>
     {
         var fromNode = from.ToNode();
         var toNode = to.ToNode();
         var patch = fromNode.CreatePatch(toNode);
 
-        return patch;
+        return new JsonPatch((operationsFilter ?? DefaultOperationsFilter).Invoke(patch.Operations));
     }
 
+    /// <summary>
+    /// Checks if two Kubernetes entities implementing <see cref="IKubernetesObject{V1ObjectMeta}"/> have changes.
+    /// </summary>
+    /// <typeparam name="TEntity">The entity type.</typeparam>
+    /// <param name="from">Original object.</param>
+    /// <param name="to">Changed object.</param>
+    /// <returns>True if there are changes detected. Otherwise false.</returns>
+    public static bool HasChanges<TEntity>(
+        this TEntity from,
+        TEntity to)
+        where TEntity : IKubernetesObject<V1ObjectMeta> => from.CreateJsonPatch(to).Operations.Count > 0;
+
     /// <summary>
     /// Create a <see cref="V1Patch"/> out of a <see cref="JsonPatch"/>.
     /// This can be used to apply the patch to a Kubernetes entity using the Kubernetes client.

src/KubeOps.KubernetesClient/IKubernetesClient.cs

@@ -329,13 +329,19 @@ TEntity UpdateStatus<TEntity>(TEntity entity)
     /// <summary>
     /// Patch a given entity on the Kubernetes API by calculating the diff between the current entity and the provided entity.
     /// This method fetches the current entity from the API, computes the patch, and applies it.
+    /// The patch does return the same object if there were no changes detected.
+    /// If no operationsFilter is provided, the default filter (<see cref="JsonPatchExtensions.DefaultOperationsFilter"/> is applied.
     /// </summary>
     /// <typeparam name="TEntity">The type of the Kubernetes entity.</typeparam>
     /// <param name="entity">The entity containing the desired updates.</param>
+    /// <param name="operationsFilter">The filter that is applied to the <see cref="PatchOperation"/>s in the <see cref="JsonPatch"/> to determine if changes are present.</param>
     /// <param name="cancellationToken">Cancellation token to monitor for cancellation requests.</param>
     /// <returns>The patched entity.</returns>
     /// <exception cref="InvalidOperationException">Thrown if the entity to be patched does not exist on the API.</exception>
-    Task<TEntity> PatchAsync<TEntity>(TEntity entity, CancellationToken cancellationToken = default)
+    Task<TEntity> PatchAsync<TEntity>(
+        TEntity entity,
+        Func<IReadOnlyList<PatchOperation>, IReadOnlyList<PatchOperation>>? operationsFilter = null,
+        CancellationToken cancellationToken = default)
         where TEntity : IKubernetesObject<V1ObjectMeta>
     {
         var currentEntity = Get<TEntity>(entity.Name(), entity.Namespace());
@@ -347,21 +353,35 @@ Task<TEntity> PatchAsync<TEntity>(TEntity entity, CancellationToken cancellation
 
         return PatchAsync(
             currentEntity,
-            entity.WithResourceVersion(currentEntity.ResourceVersion()),
+            entity,
+            operationsFilter,
             cancellationToken);
     }
 
     /// <summary>
     /// Patch a given entity on the Kubernetes API by calculating the diff between two provided entities.
+    /// Returns the patched entity if changes were detected, otherwise returns the original entity.
+    /// Detection of changes is done by creating a <see cref="JsonPatch"/> object
+    /// and then applying the operationsFilter. Defaults to the <see cref="JsonPatchExtensions.DefaultOperationsFilter"/>.
     /// </summary>
     /// <typeparam name="TEntity">The type of the Kubernetes entity.</typeparam>
     /// <param name="from">The current/original entity.</param>
     /// <param name="to">The updated entity with desired changes.</param>
+    /// <param name="operationsFilter">The filter that is applied to the <see cref="PatchOperation"/>s in the <see cref="JsonPatch"/> to determine if changes are present.</param>
     /// <param name="cancellationToken">Cancellation token to monitor for cancellation requests.</param>
     /// <returns>The patched entity.</returns>
-    Task<TEntity> PatchAsync<TEntity>(TEntity from, TEntity to, CancellationToken cancellationToken = default)
-        where TEntity : IKubernetesObject<V1ObjectMeta> =>
-        PatchAsync(from, from.CreateJsonPatch(to), cancellationToken);
+    Task<TEntity> PatchAsync<TEntity>(
+        TEntity from,
+        TEntity to,
+        Func<IReadOnlyList<PatchOperation>, IReadOnlyList<PatchOperation>>? operationsFilter = null,
+        CancellationToken cancellationToken = default)
+        where TEntity : IKubernetesObject<V1ObjectMeta>
+    {
+        var patch = from.CreateJsonPatch(to, operationsFilter);
+        return patch.Operations.Count == 0
+            ? Task.FromResult(from)
+            : PatchAsync(from, from.CreateJsonPatch(to), cancellationToken);
+    }
 
     /// <summary>
     /// Patch a given entity on the Kubernetes API using a <see cref="JsonPatch"/> object.

test/KubeOps.Abstractions.Test/Entities/JsonPatchExtensions.Test.cs

@@ -188,4 +188,13 @@ public void GetJsonDiff_Removes_Object_From_Containers_List()
         diff.ToJsonString().Should().Contain("/spec/template/spec/containers/1");
         diff.ToJsonString().Should().Contain("remove");
     }
+
+    [Fact]
+    public void GetJsonDiff_Filters_Metadata_Fields()
+    {
+        var from = new V1ConfigMap { Metadata = new V1ObjectMeta { Name = "test", ResourceVersion = "1" } };
+        var to = new V1ConfigMap { Metadata = new V1ObjectMeta { Name = "test", ResourceVersion = "2" } };
+        var diff = from.CreateJsonPatch(to);
+        diff.Operations.Should().HaveCount(0);
+    }
 }