feat: add KubernetesJson wrapper that allows more deserialize options (#907)

Signed-off-by: Christoph Bühler <[email protected]>

Author: buehler

docs/docs/operator/building-blocks/entities.mdx

@@ -154,3 +154,43 @@ public class V1DemoEntity : CustomKubernetesEntity<V1DemoEntity.V1DemoEntitySpec
     }
 }
 ```
+
+## Serialization Helper: KubernetesJsonSerializer
+
+When working with custom entities, you may need to serialize or deserialize them to and from JSON, especially when interacting with the Kubernetes API or for testing purposes. KubeOps provides a helper class, `KubernetesJsonSerializer`, to make this process straightforward and consistent with Kubernetes conventions.
+
+### Example Usage
+
+#### Get the Kubernetes specific JsonSerializerOptions
+
+```csharp
+var options = KubernetesJsonSerializer.SerializerOptions;
+```
+
+#### Serialize an Entity
+
+```csharp
+var entity = new V1DemoEntity { /* ... initialize ... */ };
+string json = KubernetesJsonSerializer.Serialize(entity);
+```
+
+#### Deserialize an Entity
+
+```csharp
+string json = /* JSON string from Kubernetes */;
+var entity = KubernetesJsonSerializer.Deserialize<V1DemoEntity>(json);
+```
+
+#### With Custom JsonSerializerOptions
+
+```csharp
+var options = new JsonSerializerOptions { WriteIndented = true };
+string json = KubernetesJsonSerializer.Serialize(entity, options);
+```
+
+### API Overview
+
+- `Serialize(object value, JsonSerializerOptions? options = null)`: Serializes an object to a JSON string.
+- `Deserialize<T>(...)`: Deserializes JSON (from string, stream, `JsonDocument`, `JsonElement`, or `JsonNode`) to a strongly-typed object.
+
+This helper ensures your custom entities are always serialized and deserialized in a way that's compatible with Kubernetes expectations.

src/KubeOps.Operator/Serialization/KubernetesJsonSerializer.cs

@@ -0,0 +1,43 @@
+using System.Text.Json;
+using System.Text.Json.Nodes;
+
+using k8s;
+
+namespace KubeOps.Operator.Serialization;
+
+/// <summary>
+/// This is a wrapper around <see cref="KubernetesJson"/> to allow for
+/// more flexible configuration and serialization/deserialization of Kubernetes objects.
+/// </summary>
+public static class KubernetesJsonSerializer
+{
+    private static readonly Lazy<JsonSerializerOptions> Options = new(() =>
+    {
+        JsonSerializerOptions options = null!;
+        KubernetesJson.AddJsonOptions(c => options = c);
+        return options;
+    });
+
+    public static JsonSerializerOptions SerializerOptions => Options.Value;
+
+    public static TValue Deserialize<TValue>(string json, JsonSerializerOptions? options = null) =>
+        KubernetesJson.Deserialize<TValue>(json, options ?? Options.Value);
+
+    public static TValue Deserialize<TValue>(Stream json, JsonSerializerOptions? options = null) =>
+        KubernetesJson.Deserialize<TValue>(json, options ?? Options.Value);
+
+    public static TValue Deserialize<TValue>(JsonDocument json, JsonSerializerOptions? options = null) =>
+        json.Deserialize<TValue>(options ?? Options.Value) ??
+        throw new JsonException("Deserialization returned null.");
+
+    public static TValue Deserialize<TValue>(JsonElement json, JsonSerializerOptions? options = null) =>
+        json.Deserialize<TValue>(options ?? Options.Value) ??
+        throw new JsonException("Deserialization returned null.");
+
+    public static TValue Deserialize<TValue>(JsonNode json, JsonSerializerOptions? options = null) =>
+        json.Deserialize<TValue>(options ?? Options.Value) ??
+        throw new JsonException("Deserialization returned null.");
+
+    public static string Serialize(object value, JsonSerializerOptions? options = null) =>
+        KubernetesJson.Serialize(value, options ?? Options.Value);
+}