feat(operator): add CRD installer utility for development purposes (#908)

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

Author: buehler

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

@@ -154,43 +154,3 @@ 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.

docs/docs/operator/utilities.mdx

@@ -0,0 +1,75 @@
+---
+title: Utilities
+description: Utilities for your Operator and Development
+sidebar_position: 9
+---
+
+# Development and Operator Utilities
+
+## Serialization Helper
+
+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.
+
+## CRD Installer Utility
+
+:::warning Destructive Utility
+The CRD Installer is a powerful utility intended **only for development environments**. Depending on its settings, it can overwrite or delete existing CRDs, which may lead to data loss or cluster instability. **Never use this in production!**
+:::
+
+When developing operators, you may want to quickly install or update CustomResourceDefinitions (CRDs) in your cluster. The `CrdInstaller` service automates this process, making it easier to iterate on CRD changes during development.
+
+### How to Add the CRD Installer
+
+To enable the CRD installer, add the following to your operator's `Program.cs`:
+
+```csharp
+builder.Services
+    .AddKubernetesOperator()
+#if DEBUG
+    .AddCrdInstaller(c =>
+    {
+        c.OverwriteExisting = true;
+        c.DeleteOnShutdown = true;
+    })
+#endif
+    .RegisterComponents();
+```
+
+- `OverwriteExisting`: If `true`, existing CRDs with the same name will be **overwritten**. This is useful for development but can be destructive if used in production, as it may cause data loss.
+- `DeleteOnShutdown`: If `true`, all CRDs installed by the operator will be **deleted** when the operator shuts down. This is extremely destructive and should only be used in disposable development environments.

examples/ConversionWebhookOperator/Program.cs

@@ -18,7 +18,7 @@
 // Configure Kestrel to listen on IPv4, use port 443, and use the server certificate
 builder.WebHost.ConfigureKestrel(serverOptions =>
 {
-    serverOptions.Listen(IPAddress.Any, port, async listenOptions =>
+    serverOptions.Listen(IPAddress.Any, port, listenOptions =>
     {
         listenOptions.UseHttps(cert);
     });

examples/Operator/Program.cs

@@ -9,6 +9,13 @@
 
 builder.Services
     .AddKubernetesOperator()
+#if DEBUG
+    .AddCrdInstaller(c =>
+    {
+        c.OverwriteExisting = true;
+        c.DeleteOnShutdown = true;
+    })
+#endif
     .RegisterComponents();
 
 using var host = builder.Build();

examples/WebhookOperator/Program.cs

@@ -17,7 +17,7 @@
 
 builder.WebHost.ConfigureKestrel(serverOptions =>
 {
-    serverOptions.Listen(IPAddress.Any, port, async listenOptions =>
+    serverOptions.Listen(IPAddress.Any, port, listenOptions =>
     {
         listenOptions.UseHttps(cert);
     });

src/KubeOps.Abstractions/Builder/IOperatorBuilder.cs

@@ -2,6 +2,7 @@
 using k8s.Models;
 
 using KubeOps.Abstractions.Controller;
+using KubeOps.Abstractions.Crds;
 using KubeOps.Abstractions.Entities;
 using KubeOps.Abstractions.Finalizer;
 
@@ -60,4 +61,18 @@ IOperatorBuilder AddController<TImplementation, TEntity, TLabelSelector>()
     IOperatorBuilder AddFinalizer<TImplementation, TEntity>(string identifier)
         where TImplementation : class, IEntityFinalizer<TEntity>
         where TEntity : IKubernetesObject<V1ObjectMeta>;
+
+    /// <summary>
+    /// Adds a hosted service to the operator that installs the CRDs for the operator
+    /// on startup. Note that this will only install the CRDs in the current assembly.
+    /// Also, the operator may be destructive if current installed CRDs are overwritten!
+    /// This is intended for development purposes only.
+    /// </summary>
+    /// <param name="configure">
+    /// Configuration action for the <see cref="CrdInstallerSettings"/>.
+    /// Determines the behavior of the CRD installer, such as whether existing CRDs
+    /// should be overwritten or deleted on shutdown.
+    /// </param>
+    /// <returns>The builder for chaining.</returns>
+    IOperatorBuilder AddCrdInstaller(Action<CrdInstallerSettings>? configure = null);
 }

src/KubeOps.Abstractions/Crds/CrdInstallerSettings.cs

@@ -0,0 +1,20 @@
+namespace KubeOps.Abstractions.Crds;
+
+/// <summary>
+/// Settings for the CRD installer.
+/// </summary>
+public sealed class CrdInstallerSettings
+{
+    /// <summary>
+    /// Determines whether existing CRDs should be overwritten.
+    /// This is useful for development purposes and should be used with caution.
+    /// It is a destructive operation that may lead to data loss.
+    /// </summary>
+    public bool OverwriteExisting { get; set; } = false;
+
+    /// <summary>
+    /// Determines whether the installed CRDs should be deleted when the operator shuts down.
+    /// This is a very destructive operation and should only be used in development environments.
+    /// </summary>
+    public bool DeleteOnShutdown { get; set; } = false;
+}

src/KubeOps.Operator/Builder/OperatorBuilder.cs

@@ -5,11 +5,13 @@
 
 using KubeOps.Abstractions.Builder;
 using KubeOps.Abstractions.Controller;
+using KubeOps.Abstractions.Crds;
 using KubeOps.Abstractions.Entities;
 using KubeOps.Abstractions.Events;
 using KubeOps.Abstractions.Finalizer;
 using KubeOps.Abstractions.Queue;
 using KubeOps.KubernetesClient;
+using KubeOps.Operator.Crds;
 using KubeOps.Operator.Events;
 using KubeOps.Operator.Finalizer;
 using KubeOps.Operator.LeaderElection;
@@ -95,6 +97,15 @@ public IOperatorBuilder AddFinalizer<TImplementation, TEntity>(string identifier
         return this;
     }
 
+    public IOperatorBuilder AddCrdInstaller(Action<CrdInstallerSettings>? configure = null)
+    {
+        var settings = new CrdInstallerSettings();
+        configure?.Invoke(settings);
+        Services.AddSingleton(settings);
+        Services.AddHostedService<CrdInstaller>();
+        return this;
+    }
+
     private void AddOperatorBase()
     {
         Services.AddSingleton(_settings);
@@ -117,8 +128,8 @@ private void AddOperatorBase()
         Services.TryAddSingleton<IKubernetesClient, KubernetesClient.KubernetesClient>();
 
         Services.TryAddTransient<IEventPublisherFactory, KubeOpsEventPublisherFactory>();
-        Services.TryAddTransient<EventPublisher>(
-            services => services.GetRequiredService<IEventPublisherFactory>().Create());
+        Services.TryAddTransient<EventPublisher>(services =>
+            services.GetRequiredService<IEventPublisherFactory>().Create());
 
         Services.AddSingleton(typeof(IEntityLabelSelector<>), typeof(DefaultEntityLabelSelector<>));
 

src/KubeOps.Operator/Crds/CrdInstaller.cs

@@ -0,0 +1,93 @@
+using System.Reflection;
+using System.Runtime.InteropServices;
+
+using k8s.Models;
+
+using KubeOps.Abstractions.Crds;
+using KubeOps.Abstractions.Entities.Attributes;
+using KubeOps.KubernetesClient;
+using KubeOps.Transpiler;
+
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+
+namespace KubeOps.Operator.Crds;
+
+internal class CrdInstaller(ILogger<CrdInstaller> logger, CrdInstallerSettings settings, IKubernetesClient client)
+    : IHostedService
+{
+    private List<V1CustomResourceDefinition> _crds = [];
+
+    public async Task StartAsync(CancellationToken cancellationToken)
+    {
+        logger.LogInformation("Execute CRD installer with overwrite: {Overwrite}", settings.OverwriteExisting);
+        var assembly = Assembly.GetEntryAssembly();
+        if (assembly is null)
+        {
+            logger.LogError("No entry assembly found, cannot install CRDs.");
+            return;
+        }
+
+        var entities = assembly
+            .DefinedTypes
+            .Where(t => t is { IsInterface: false, IsAbstract: false, IsGenericType: false })
+            .Select(t => (t, attrs: CustomAttributeData.GetCustomAttributes(t)))
+            .Where(e => e.attrs.Any(a => a.AttributeType.Name == nameof(KubernetesEntityAttribute)) &&
+                        e.attrs.All(a => a.AttributeType.Name != nameof(IgnoreAttribute)))
+            .Select(e => e.t);
+
+        using var mlc = ContextCreator.Create(
+            Directory
+                .GetFiles(RuntimeEnvironment.GetRuntimeDirectory(), "*.dll")
+                .Concat(
+                    Directory.GetFiles(Path.GetDirectoryName(assembly.Location)!, "*.dll"))
+                .Distinct(),
+            coreAssemblyName: typeof(object).Assembly.GetName().Name);
+        _crds = mlc.Transpile(entities).ToList();
+
+        foreach (var crd in _crds)
+        {
+            var existing =
+                await client.GetAsync<V1CustomResourceDefinition>(crd.Name(), cancellationToken: cancellationToken);
+            if (existing is not null && !settings.OverwriteExisting)
+            {
+                logger.LogDebug("CRD {Name} already exists, skipping installation.", crd.Name());
+            }
+            else if (existing is not null)
+            {
+                logger.LogDebug("CRD {Name} already exists.", crd.Name());
+                logger.LogInformation("Overwriting existing CRD {Name}.", crd.Name());
+                crd.Metadata.ResourceVersion = existing.ResourceVersion();
+                await client.UpdateAsync(crd, cancellationToken);
+            }
+            else
+            {
+                logger.LogInformation("Installing CRD {Name}.", crd.Name());
+                await client.CreateAsync(crd, cancellationToken);
+            }
+        }
+    }
+
+    public async Task StopAsync(CancellationToken cancellationToken)
+    {
+        if (!settings.DeleteOnShutdown)
+        {
+            logger.LogDebug("Skipping CRD deletion on shutdown as per settings.");
+            return;
+        }
+
+        logger.LogInformation("Deleting CRDs on shutdown.");
+        foreach (var crd in _crds)
+        {
+            try
+            {
+                logger.LogInformation("Deleting CRD {Name}.", crd.Name());
+                await client.DeleteAsync(crd, cancellationToken);
+            }
+            catch (Exception ex)
+            {
+                logger.LogError(ex, "Failed to delete CRD {Name}.", crd.Name());
+            }
+        }
+    }
+}