feat: Add extension points for resource generation (#1118)

Closes #1114

### Summary

Introduces factory interfaces that let operators customize how CRDs,
events, and webhook configurations are generated. All factories are
registered with `TryAdd`, so users can register their own
implementations before calling `AddKubernetesOperator()` /
`AddDevelopmentTunnel()` / `UseCertificateProvider()` to override the
defaults.

### New abstractions (`KubeOps.Abstractions`)

| Interface | Purpose |
|---|---|
| `ICrdResourceFactory` | Controls how `V1CustomResourceDefinition`
resources are created from entity types |
| `IEventResourceFactory` | Controls how `Corev1Event` instances are
constructed when publishing events |
| `IWebhookConfigurationFactory` | Controls how
`V1MutatingWebhookConfiguration` and `V1ValidatingWebhookConfiguration`
are built |

Supporting types: `MutatingWebhookRegistration`,
`ValidatingWebhookRegistration` (records carrying entity metadata, URI,
and CA bundle).

### Default implementations

- **`KubeOpsCrdResourceFactory`** — Uses the transpiler with a single
shared `MetadataLoadContext` across all entity types. Exposes
`CreateCrdForEntityType()` as a virtual override point.
- **`KubeOpsEventResourceFactory`** — Builds `Corev1Event` with a
SHA-512 hashed name for Kubernetes naming compliance.
- **`KubeOpsWebhookConfigurationFactory`** — Constructs webhook configs
with virtual `CreateMutatingWebhook()` / `CreateValidatingWebhook()`
methods for per-webhook customization.

### Other changes

- **`IWebhookAttribute`** interface added to `KubeOps.Operator.Web` —
implemented by `MutationWebhookAttribute`, `ValidationWebhookAttribute`,
and `ConversionWebhookAttribute`. `WebhookServiceBase.GetWebHookUri()`
falls back to `RouteAttribute.Template` for backward compatibility with
custom attributes.
- **`CrdInstaller`** refactored to accept `ICrdResourceFactory` via DI
and includes retry logic with exponential backoff for transient API
server errors.
- **`KubeOpsEventPublisherFactory`** simplified — event construction
delegated to `IEventResourceFactory`; the publisher only handles
get-or-create, count increment, and save.
- Event name hashing and `originalName` annotation logic moved from the
publisher into `KubeOpsEventResourceFactory`.

### Breaking changes

None. All modified constructors are `internal`. New interfaces and types
are purely additive.

### Tests

- `CrdInstallerTest` — verifies custom factory DI override, transient
error retry, non-transient error handling, and stop cancellation.
- `KubeOpsCrdResourceFactoryTest` — verifies default CRD transpilation.
- `KubeOpsEventResourceFactoryTest` — verifies event properties and
namespace defaulting.
- `EventPublisherCustomResourceFactoryTest` — end-to-end test verifying
custom factory output flows through the publisher to the Kubernetes
client.

Author: BalassaMarton

docs/docs/operator/advanced-configuration.mdx

@@ -608,6 +608,262 @@ two events for *different* entities are never serialised by the UID lock; only e
 UID are affected by `ConflictStrategy`.
 :::
 
+## Customizing CRD generation
+
+:::note
+This section explains how you can customize CRD generation when using the built-in (runtime) `CrdInstaller`.
+CRD generation using the CLI is not affected.
+:::
+
+KubeOps uses `ICrdResourceFactory` to generate `V1CustomResourceDefinition` resources from your entity types. The default implementation (`KubeOpsCrdResourceFactory`) uses the transpiler to produce CRDs, but you can replace or extend this behavior.
+
+All factory interfaces are registered with `TryAddSingleton`, so registering your own implementation **before** calling `AddKubernetesOperator()` takes precedence over the default.
+
+### Replacing the factory
+
+Implement `ICrdResourceFactory` to take full control of CRD generation:
+
+```csharp
+public class CustomCrdResourceFactory : ICrdResourceFactory
+{
+    public IEnumerable<V1CustomResourceDefinition> CreateCustomResourceDefinitions(
+        IReadOnlyCollection<Type> entityTypes)
+    {
+        // Build CRDs however you need — from YAML files, a database, or custom logic.
+        foreach (var entityType in entityTypes)
+        {
+            yield return BuildCrdFromYaml(entityType);
+        }
+    }
+}
+```
+
+Register it before the operator:
+
+```csharp
+builder.Services.AddSingleton<ICrdResourceFactory, CustomCrdResourceFactory>();
+builder.Services.AddKubernetesOperator();
+```
+
+### Extending the default factory
+
+If you only need to tweak individual CRDs, inherit from `KubeOpsCrdResourceFactory` and override `CreateCrdForEntityType`:
+
+```csharp
+public class AnnotatedCrdResourceFactory : KubeOpsCrdResourceFactory
+{
+    protected override V1CustomResourceDefinition CreateCrdForEntityType(
+        MetadataLoadContext context, Type entityType)
+    {
+        var crd = base.CreateCrdForEntityType(context, entityType);
+
+        // Add custom labels to every generated CRD
+        crd.Metadata.Labels ??= new Dictionary<string, string>();
+        crd.Metadata.Labels["managed-by"] = "my-operator";
+
+        return crd;
+    }
+}
+```
+
+Register it the same way:
+
+```csharp
+builder.Services.AddSingleton<ICrdResourceFactory, AnnotatedCrdResourceFactory>();
+builder.Services.AddKubernetesOperator();
+```
+
+## Customizing webhook configuration generation
+
+KubeOps uses `IWebhookConfigurationFactory` to build the `V1MutatingWebhookConfiguration` and `V1ValidatingWebhookConfiguration` resources that are registered with the Kubernetes API server. The default implementation (`KubeOpsWebhookConfigurationFactory`) produces standard configurations, but you can replace or extend this behavior.
+
+All factory interfaces are registered with `TryAddSingleton`, so registering your own implementation **before** calling `UseCertificateProvider()` or `AddDevelopmentTunnel()` takes precedence over the default.
+
+### Replacing the Factory
+
+Implement `IWebhookConfigurationFactory` to take full control:
+
+```csharp
+public class CustomWebhookConfigurationFactory : IWebhookConfigurationFactory
+{
+    public V1MutatingWebhookConfiguration CreateMutatingConfiguration(
+        IEnumerable<MutatingWebhookRegistration> registrations)
+    {
+        // Build the configuration from scratch
+        return new V1MutatingWebhookConfiguration
+        {
+            Metadata = new() { Name = "my-operator-mutators" },
+            Webhooks = registrations.Select(r => new V1MutatingWebhook
+            {
+                Name = $"mutate.{r.Metadata.SingularName}",
+                // ... your custom configuration
+            }).ToList(),
+        }.Initialize();
+    }
+
+    public V1ValidatingWebhookConfiguration CreateValidatingConfiguration(
+        IEnumerable<ValidatingWebhookRegistration> registrations)
+    {
+        return new V1ValidatingWebhookConfiguration
+        {
+            Metadata = new() { Name = "my-operator-validators" },
+            Webhooks = registrations.Select(r => new V1ValidatingWebhook
+            {
+                Name = $"validate.{r.Metadata.SingularName}",
+                // ... your custom configuration
+            }).ToList(),
+        }.Initialize();
+    }
+}
+```
+
+Register it before the operator web configuration:
+
+```csharp
+builder.Services.AddSingleton<IWebhookConfigurationFactory, CustomWebhookConfigurationFactory>();
+builder.Services
+    .AddKubernetesOperator()
+    .RegisterComponents()
+    .UseCertificateProvider(/* ... */);
+```
+
+### Extending the Default Factory
+
+If you only need to customize individual webhooks, inherit from `KubeOpsWebhookConfigurationFactory` and override `CreateMutatingWebhook` or `CreateValidatingWebhook`:
+
+```csharp
+public class CustomWebhookFactory : KubeOpsWebhookConfigurationFactory
+{
+    protected override V1MutatingWebhook CreateMutatingWebhook(MutatingWebhookRegistration reg)
+    {
+        var webhook = base.CreateMutatingWebhook(reg);
+
+        // Customize the failure policy
+        webhook.FailurePolicy = "Ignore";
+
+        // Restrict to a specific namespace
+        webhook.NamespaceSelector = new V1LabelSelector
+        {
+            MatchLabels = new Dictionary<string, string>
+            {
+                ["kubernetes.io/metadata.name"] = "my-namespace",
+            },
+        };
+
+        return webhook;
+    }
+}
+```
+
+Register it the same way:
+
+```csharp
+builder.Services.AddSingleton<IWebhookConfigurationFactory, CustomWebhookFactory>();
+
+builder.Services
+    .AddKubernetesOperator()
+    .RegisterComponents()
+    .UseCertificateProvider(/* ... */);
+```
+
+Each registration record (`MutatingWebhookRegistration` / `ValidatingWebhookRegistration`) carries the entity `Metadata`, the webhook `Uri`, and the optional `CaBundle`, giving you all the information you need to build a fully customized webhook entry.
+
+## Customizing event generation
+
+KubeOps uses `IEventResourceFactory` to construct the `Corev1Event` instances that are published to Kubernetes. The default implementation (`KubeOpsEventResourceFactory`) creates events with a SHA-512 hashed name for Kubernetes naming compliance and populates standard fields from the operator settings. You can replace or extend this behavior.
+
+The factory is registered with `TryAddSingleton`, so registering your own implementation **before** calling `AddKubernetesOperator()` takes precedence over the default.
+
+### How the Default Works
+
+The default factory:
+
+1. Builds a composite string from the entity's UID, name, namespace, and the event's reason, message, and type.
+2. Hashes this string (SHA-512) to produce a deterministic, Kubernetes-compliant event name.
+3. Events with the same reason, message, and type for the same entity share the same name — the publisher increments `Count` and updates `LastTimestamp` instead of creating duplicates.
+
+### Replacing the Factory
+
+Implement `IEventResourceFactory` to take full control of event construction:
+
+```csharp
+public class CustomEventResourceFactory(OperatorSettings settings) : IEventResourceFactory
+{
+    public Corev1Event CreateEvent(
+        IKubernetesObject<V1ObjectMeta> entity,
+        string reason,
+        string message,
+        EventType type)
+    {
+        return new Corev1Event
+        {
+            Metadata = new()
+            {
+                Name = $"{entity.Name()}-{reason}-{Guid.NewGuid():N}",
+                NamespaceProperty = entity.Namespace() ?? "default",
+                Labels = new Dictionary<string, string>
+                {
+                    ["app.kubernetes.io/managed-by"] = settings.Name,
+                },
+            },
+            Type = type.ToString(),
+            Reason = reason,
+            Message = message,
+            ReportingComponent = settings.Name,
+            ReportingInstance = Environment.MachineName,
+            Source = new() { Component = settings.Name },
+            InvolvedObject = entity.MakeObjectReference(),
+        }.Initialize();
+    }
+}
+```
+
+Register it before the operator:
+
+```csharp
+builder.Services.AddSingleton<IEventResourceFactory, CustomEventResourceFactory>();
+builder.Services.AddKubernetesOperator();
+```
+
+Note that the above example will create a new distinct `Corev1Event` object for every event, because it is adding a new GUID to each event's name.
+
+### Extending the Default Factory
+
+Inherit from `KubeOpsEventResourceFactory` and override `CreateEvent` to add extra metadata while keeping the default naming and structure:
+
+```csharp
+public class EnrichedEventResourceFactory(OperatorSettings settings, ILogger<EventPublisher> logger)
+    : KubeOpsEventResourceFactory(settings, logger)
+{
+    public override Corev1Event CreateEvent(
+        IKubernetesObject<V1ObjectMeta> entity,
+        string reason,
+        string message,
+        EventType type)
+    {
+        var evt = base.CreateEvent(entity, reason, message, type);
+
+        // Add custom annotations
+        evt.Metadata.Annotations ??= new Dictionary<string, string>();
+        evt.Metadata.Annotations["my-operator/version"] = "1.0.0";
+
+        return evt;
+    }
+}
+```
+
+Register it the same way:
+
+```csharp
+builder.Services.AddSingleton<IEventResourceFactory, EnrichedEventResourceFactory>();
+builder.Services.AddKubernetesOperator();
+```
+
+:::note
+The `EventPublisher` handles get-or-create logic, count incrementing, and timestamp updates. Your factory only controls the initial shape of the `Corev1Event` — the publisher manages its lifecycle.
+To completely replace how events are published, add your own `IEventPublisherFactory` implementation to the service collection before calling `AddKubernetesOperator`.
+:::
+
 ## Best Practices
 
 ### Finalizer Management

examples/Operator/Program.cs

@@ -2,6 +2,7 @@
 // The .NET Foundation licenses this file to you under the Apache 2.0 License.
 // See the LICENSE file in the project root for more information.
 
+using KubeOps.Abstractions.Crds;
 using KubeOps.Operator;
 
 using Microsoft.Extensions.Hosting;

src/KubeOps.Abstractions/Crds/ICrdResourceFactory.cs

@@ -0,0 +1,21 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information.
+
+using k8s.Models;
+
+namespace KubeOps.Abstractions.Crds;
+
+/// <summary>
+/// Factory interface for creating <see cref="V1CustomResourceDefinition"/> instances.
+/// Implement this interface to customize the shape of CRDs generated by the operator.
+/// </summary>
+public interface ICrdResourceFactory
+{
+    /// <summary>
+    /// Creates the <see cref="V1CustomResourceDefinition"/> resources for the given entity types.
+    /// </summary>
+    /// <param name="entityTypes">The entity types to transpile into CRDs.</param>
+    /// <returns>The generated <see cref="V1CustomResourceDefinition"/> instances.</returns>
+    IEnumerable<V1CustomResourceDefinition> CreateCustomResourceDefinitions(IReadOnlyCollection<Type> entityTypes);
+}

src/KubeOps.Abstractions/Events/IEventResourceFactory.cs

@@ -0,0 +1,39 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information.
+
+using k8s;
+using k8s.Models;
+
+namespace KubeOps.Abstractions.Events;
+
+/// <summary>
+/// Factory interface for creating <see cref="Corev1Event"/> instances.
+/// Implement this interface to customize the shape of events published by the operator.
+/// </summary>
+/// <remarks>
+/// The default implementation of <see cref="EventPublisher"/> checks if an event with the same
+/// unique name already exists, and either updates the existing event or creates a new one accordingly.
+/// When updating an existing event, its <see cref="Corev1Event.Count"/> property is incremented and
+/// <see cref="Corev1Event.LastTimestamp"/> is updated to the current time.
+/// When creating a new event, <see cref="Corev1Event.Count"/> is set to 1 and <see cref="Corev1Event.FirstTimestamp"/>
+/// and <see cref="Corev1Event.LastTimestamp"/> are set to the current time.
+/// </remarks>
+public interface IEventResourceFactory
+{
+    /// <summary>
+    /// Creates a new <see cref="Corev1Event"/> for the given entity and event details.
+    /// </summary>
+    /// <param name="entity">The entity that is involved with the event.</param>
+    /// <param name="reason">The reason string. This should be a machine readable reason string.</param>
+    /// <param name="message">A human readable string for the event.</param>
+    /// <param name="type">The <see cref="EventType"/> of the event.</param>
+    /// <returns>A new <see cref="Corev1Event"/> instance.</returns>
+    /// <remarks>
+    /// The default implementation creates a unique event name by combining the entity's UID, name, namespace, reason,
+    /// message, and type, and then hashing this combination to ensure it fits Kubernetes naming constraints.
+    /// This means that events with the same reason, message, and type for the same entity will be considered the same
+    /// event and will have their count incremented.
+    /// </remarks>
+    Corev1Event CreateEvent(IKubernetesObject<V1ObjectMeta> entity, string reason, string message, EventType type);
+}

src/KubeOps.Abstractions/Webhooks/IWebhookConfigurationFactory.cs

@@ -0,0 +1,28 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information.
+
+using k8s.Models;
+
+namespace KubeOps.Abstractions.Webhooks;
+
+/// <summary>
+/// Factory interface for creating webhook configuration resources.
+/// Implement this interface to customize the shape of mutating and validating webhook configurations.
+/// </summary>
+public interface IWebhookConfigurationFactory
+{
+    /// <summary>
+    /// Creates a <see cref="V1MutatingWebhookConfiguration"/> from the given registrations.
+    /// </summary>
+    /// <param name="registrations">The collection of mutating webhook registrations.</param>
+    /// <returns>The generated <see cref="V1MutatingWebhookConfiguration"/>.</returns>
+    V1MutatingWebhookConfiguration CreateMutatingConfiguration(IEnumerable<MutatingWebhookRegistration> registrations);
+
+    /// <summary>
+    /// Creates a <see cref="V1ValidatingWebhookConfiguration"/> from the given registrations.
+    /// </summary>
+    /// <param name="registrations">The collection of validating webhook registrations.</param>
+    /// <returns>The generated <see cref="V1ValidatingWebhookConfiguration"/>.</returns>
+    V1ValidatingWebhookConfiguration CreateValidatingConfiguration(IEnumerable<ValidatingWebhookRegistration> registrations);
+}

src/KubeOps.Abstractions/Webhooks/MutatingWebhookRegistration.cs

@@ -0,0 +1,18 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information.
+
+using KubeOps.Abstractions.Entities;
+
+namespace KubeOps.Abstractions.Webhooks;
+
+/// <summary>
+/// Registration data for a mutating webhook.
+/// </summary>
+/// <param name="Metadata">The entity metadata for the webhook's target resource.</param>
+/// <param name="Uri">The absolute URI the webhook is reachable at.</param>
+/// <param name="CaBundle">The PEM-encoded CA bundle for validating the webhook's certificate, or null.</param>
+public record MutatingWebhookRegistration(
+    EntityMetadata Metadata,
+    Uri Uri,
+    byte[]? CaBundle);

src/KubeOps.Abstractions/Webhooks/ValidatingWebhookRegistration.cs

@@ -0,0 +1,18 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information.
+
+using KubeOps.Abstractions.Entities;
+
+namespace KubeOps.Abstractions.Webhooks;
+
+/// <summary>
+/// Registration data for a validating webhook.
+/// </summary>
+/// <param name="Metadata">The entity metadata for the webhook's target resource.</param>
+/// <param name="Uri">The absolute URI the webhook is reachable at.</param>
+/// <param name="CaBundle">The PEM-encoded CA bundle for validating the webhook's certificate, or null.</param>
+public record ValidatingWebhookRegistration(
+    EntityMetadata Metadata,
+    Uri Uri,
+    byte[]? CaBundle);