feat: Extended PatchAsync with SSA parameters (fieldManager, force, dryRun)

[torjue]

Adds Kubernetes Server-Side Apply (SSA) to enable declarative resource management with field ownership tracking. This lets operators use SSA's benefits, such as field ownership tracking, conflict detection, and safer concurrent updates.

All SSA parameters are optional for backward compatibility.

When using ApplyAsync, server-managed metadata fields (resourceVersion, creationTimestamp, etc) are temporarily cleared during serialization as required by Kubernetes, then restored to prevent mutation of the original entity. Feedback on this is point is appreciated! Maybe not needed?

Changes:

• Extended PatchAsync with SSA parameters (fieldManager, force, dryRun)
• Added explicit ApplyAsync method for Server-Side Apply
• Updated all PatchAsync overloads to support SSA parameters
• Added docs and examples to README.md
• Tests cover basic apply, updates, force apply, dry-run, and metadata handling.

[kimpenhaus]

hey @torjue - to be honest I haven't been in touch with ssa yet. but as you asked for feedback for the ApplyAsync these are my thoughts on that:

wouldn't it make more sense to have a different base-metadata-object than V1ObjectMeta which wouldn't have all these metadata fields that actually must not to be serialized to the server? this could then lead into having a separet set of interface methods and implementation in the client. what do you think about that?

[Copilot]

Pull request overview

Adds Kubernetes Server-Side Apply (SSA) support to KubernetesClient to enable declarative apply workflows with field ownership tracking, plus related Patch enhancements, docs, and tests.

Changes:

• Extends PatchAsync APIs with SSA-related query parameters (fieldManager, force, dryRun).
• Adds ApplyAsync / Apply APIs that send SSA apply patches and handle server-managed metadata during serialization.
• Adds README documentation and new test coverage for apply/patch SSA behaviors.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 6 comments.

File	Description
test/KubeOps.KubernetesClient.Test/KubernetesClientAsync.Test.cs	Adds SSA-focused tests for apply, force, dry-run, and managed metadata behavior.
src/KubeOps.KubernetesClient/README.md	Documents SSA usage patterns and examples.
src/KubeOps.KubernetesClient/KubernetesClient.cs	Implements SSA apply and extends patch to pass SSA query params.
src/KubeOps.KubernetesClient/IKubernetesClient.cs	Updates PatchAsync overloads to flow SSA params; adds ApplyAsync/Apply to the public interface.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[buehler]

Personally, when I started with all this, SSA was in its beginnings. So maybe now it may be useful enough :)

I do like the input of @kimpenhaus. An extension of the current interface could possibly improve usability. Either an extension or with a different set of methods / base objects.
What is your opinion on this?

Thank you for the contribution!

[torjue]

To be honest, ApplyAsync is just a convenience method I put together quite quickly. My main goal with this PR is to extend PatchAsync with SSA parameters (fieldManager, force, dryRun).

I do see @kimpenhaus's point, but I guess that will require a bit more work and some exploration? And is it smart to deviate from the original models from k8s.Models?

I propose we start with the extension of PatchAsync, and then revisit a more well-thought-out interface for SSA?

I will have a look at the feedback from CoPilot soon.

[buehler]

Fair enough :) since we do not break anything with those parameters it's ok. We can have a breaking change later on if we decide to change the interface. Personally, I do not mind breaking changes ;) if they are versioned correctly.

[torjue]

PR updated to only include PatchAsync changes. I'll try to use some time on a proposal for a better SSA interface quite soon. That will be in a separate PR.

For others stopping by: I now use this with the following helper method those few times I want to re-apply an object fetched from Kubernetes:

/// <summary>
/// Replaces the object's metadata with a copy that has server-managed fields stripped,
/// preparing it for server-side apply. This removes fields like resourceVersion, uid, 
/// creationTimestamp, generation, and managedFields that should not be included in 
/// server-side apply patches.
/// </summary>
public static TEntity WithoutServerManagedFields<TEntity>(this TEntity entity) 
    where TEntity : IKubernetesObject<V1ObjectMeta>
{
    entity.Metadata = new V1ObjectMeta
    {
        Name = entity.Metadata.Name,
        NamespaceProperty = entity.Metadata.NamespaceProperty,
        Labels = entity.Metadata.Labels,
        Annotations = entity.Metadata.Annotations,
        OwnerReferences = entity.Metadata.OwnerReferences,
        Finalizers = entity.Metadata.Finalizers,
        // Explicitly exclude server-managed fields:
        // ResourceVersion, Uid, CreationTimestamp, Generation, ManagedFields, SelfLink, DeletionTimestamp, DeletionGracePeriodSeconds
    };
    return entity;
}