docs: Adjust documentation according to breaking changes.

Author: buehler

docs/docs/controller.md

@@ -7,9 +7,12 @@ resources on kubernetes and queueing of the events.
 When you want to create a controller for your (or any) entity,
 read the following instructions.
 
-When you have controllers, don't forget to register them with
-<xref:KubeOps.Operator.Builder.IOperatorBuilder.AddController``1>
-to the DI system.
+When you have controllers, they are automatically added to the
+DI system via their <xref:KubeOps.Operator.Controller.IResourceController`1> interface.
+
+Controllers are registered as **scoped** elements in the DI system.
+Which means, they basically behave like asp.net api controllers.
+You can use dependency injection with all types of dependencies.
 
 ## Controller instance
 
@@ -18,16 +21,14 @@ or you want to reconcile a given entity (from the `k8s.Models` namespace,
 e.g. `V1ConfigMap`) you need to create a controller class
 as you would do for a MVC or API controller in asp.net.
 
-Make sure you have the correct baseclass
-(<xref:KubeOps.Operator.Controller.ResourceControllerBase`1>)
-inherited.
+Make sure you implement the <xref:KubeOps.Operator.Controller.IResourceController`1> interface.
 
 ```csharp
 [EntityRbac(typeof(MyCustomEntity), Verbs = RbacVerb.All)]
-public class FooCtrl: ResourceControllerBase<MyCustomEntity>
+public class FooCtrl : IResourceController<MyCustomEntity>
 {
-    protected override async Task<TimeSpan?> Created(MyCustomEntity resource){}
-    // overwrite other methods here.
+    // Implement the needed methods here.
+    // The interface provides default implementation which do a NOOP.
     // Possible overwrites:
     // "Created" (i.e. when the operator sees the entity for the first time),
     // "Updated" (i.e. when the operator knows the entity and it was updated),
@@ -86,27 +87,27 @@ which takes a list of api groups, resources, versions and a selection of
 
 ## Requeue
 
-The controller's methods have a return value of `TimeSpan?`. This means
-you can return a time span to automatically requeue the event for the
-given entity. If requeued and nothing changed, it will most likely fire
-a `NotModified` event.
+The controller's methods have a return value of <xref:KubeOps.Operator.Controller.Results.ResourceControllerResult>.
+There are multiple ways how a result of a controller can be created:
 
-This can be useful if you want to periodically check for a database
-connection for example and update the status of a given entity.
+- `null`: The controller will not requeue your entity / event.
+- <xref:KubeOps.Operator.Controller.Results.ResourceControllerResult.RequeueEvent(System.TimeSpan)>:
+  Return a result object with a <xref:System.TimeSpan> that will requeue
+  the event and the entity after the time has passed.
 
-If you return `null` in an event function, the event is not requeued.
-If you return a timespan, then the event is requeued after this delay.
+The requeue mechanism can be useful if you want to periodically check for a database
+connection for example and update the status of a given entity.
 
 ```csharp
 /* snip... */
-protected override async Task<TimeSpan?> Created(MyCustomEntity resource){
-    // do something useful.
-    return TimeSpan.FromSeconds(15); // This will retrigger an event in 15 secs.
+public Task<ResourceControllerResult> CreatedAsync(V1TestEntity resource)
+{
+    return Task.FromResult(ResourceControllerResult.RequeueEvent(TimeSpan.FromSeconds(15)); // This will requeue the event in 15 seconds.
 }
 
-protected override async Task<TimeSpan?> Updated(MyCustomEntity resource){
-    // do something useful.
-    return null; // This will not retrigger an event.
+public Task<ResourceControllerResult> CreatedAsync(V1TestEntity resource)
+{
+    return Task.FromResult<ResourceControllerResult>(null); // This wont trigger a requeue.
 }
 /* snip... */
 ```
@@ -117,22 +118,11 @@ If the function throws an error, the event is requeued with an exponential backo
 
 ```csharp
 /* snip... */
-protected override async Task<TimeSpan?> Created(MyCustomEntity resource){
+public Task<ResourceControllerResult> CreatedAsync(V1TestEntity resource)
     // do something useful.
     throw new Exception("¯\\_(ツ)_/¯");
 }
 /* snip... */
 ```
 
-The backoff function is defined as follows:
-
-```csharp
-private const double MaxRetrySeconds = 64;
-private TimeSpan ExponentialBackoff(int retryCount) => TimeSpan
-            .FromSeconds(Math.Min(Math.Pow(2, retryCount), MaxRetrySeconds))
-            .Add(TimeSpan.FromMilliseconds(_rnd.Next(0, 1000)));
-```
-
-Which means with each retry, it calculates the new backoff time
-to a max of 64. To each of those times a random number of milliseconds
-is added to add a certain fuzzying.
+Each event that errors will be retried **four times**.

docs/docs/entities.md

@@ -1,5 +1,10 @@
 # Custom Entities
 
+The words `entity` and `resource` are kind of interchangeable. It strongly
+depends on the context. The resource is the type of an object in kubernetes
+which is defined by the default api or a CRD. While an entity is a class
+in C# of such a resource. (CRD means "custom resource definition").
+
 To write your own kubernetes entities, use the interfaces
 provided by `k8s` or use the <xref:KubeOps.Operator.Entities.CustomKubernetesEntity>.
 
@@ -39,7 +44,7 @@ If you don't use the <xref:KubeOps.Operator.Entities.CustomKubernetesEntity`1> b
 
 ### Ignoring Entities
 
-There are usecases when you want to model / watch a custom entity from another
+There are use-cases when you want to model / watch a custom entity from another
 software engineer that are not part of the base models in `k8s`.
 
 To prevent the generator from creating yamls for CRDs you don't own, use

docs/docs/events.md

@@ -24,7 +24,7 @@ IEventManager manager = services.GetRequiredService<IEventManager>;
 // If the event was previously published, it is fetched
 // and the "count" number is increased. This essentially
 // creates an event-series.
-await manager.Publish(resource, "reason", "my fancy message");
+await manager.PublishAsync(resource, "reason", "my fancy message");
 ```
 
 If you want full control over the event:
@@ -39,19 +39,19 @@ var @event = new Corev1Event
 
 // Publish the event.
 // This essentially calls IKubernetesClient.Save.
-await manager.Publish(@event);
+await manager.PublishAsync(@event);
 ```
 
 ### Use publisher delegates
 
 If you don't want to call the
-@"KubeOps.Operator.Events.IEventManager.Publish(k8s.IKubernetesObject{k8s.Models.V1ObjectMeta},System.String,System.String,KubeOps.Operator.Events.EventType)"
+@"KubeOps.Operator.Events.IEventManager.PublishAsync(k8s.IKubernetesObject{k8s.Models.V1ObjectMeta},System.String,System.String,KubeOps.Operator.Events.EventType)"
 all the time with the same arguments, you can create delegates.
 
 There exist two different delegates:
-- @"KubeOps.Operator.Events.IEventManager.StaticPublisher": Predefined event
+- @"KubeOps.Operator.Events.IEventManager.AsyncStaticPublisher": Predefined event
   on a predefined resource.
-- @"KubeOps.Operator.Events.IEventManager.Publisher": Predefined event
+- @"KubeOps.Operator.Events.IEventManager.AsyncPublisher": Predefined event
   on a variable resource.
 
 Both are created with their specific overload:
@@ -80,22 +80,21 @@ The dynamic publisher can be used to predefine the event for your resources.
 
 As an example in a controller:
 ```c#
-public class TestController : ResourceControllerBase<V1TestEntity>
+public class TestController : IResourceController<V1TestEntity>
 {
     private readonly IEventManager.Publisher _publisher;
 
-    public TestController(IEventManager eventManager, IResourceServices<V1TestEntity> services)
-        : base(services)
+    public TestController(IEventManager eventManager)
     {
         _publisher = eventManager.CreatePublisher("reason", "my fancy message");
     }
 
-    protected override async Task<TimeSpan?> Created(V1TestEntity resource)
+    public Task<ResourceControllerResult> CreatedAsync(V1TestEntity resource)
     {
         // Here, the event is published with predefined strings
         // but for a "variable" resource.
         await _publisher(resource);
-        return await base.Created(resource);
+        return Task.FromResult<ResourceControllerResult>(null);
     }
 }
 ```

docs/docs/features.md

@@ -14,7 +14,6 @@ As of now, the operator sdk supports - roughly - the following features:
   - NotModified
   - StatusModified
   - Deleted
-  - AddFinalizer
 - Finalizers for entities
 - Webhooks
   - Validation / validators

docs/docs/finalizer.md

@@ -3,48 +3,65 @@
 A finalizer is a special type of software that can asynchronously
 cleanup stuff for an entity that is being deleted.
 
-A finalizer is registered as an identifier in the kubernetes
-resource (i.e. in the yaml / json structure) and an object
+A finalizer is registered as an identifier in a kubernetes
+object (i.e. in the yaml / json structure) and the object
 wont be removed from the api until all finalizers are removed.
 
-If you write finalizer, don't forget to register them with
-<xref:KubeOps.Operator.Builder.IOperatorBuilder.AddFinalizer``1>
-to the DI system.
+If you write finalizer, they will be automatically added to the
+DI system via their type <xref:KubeOps.Operator.Finalizer.IResourceFinalizer`1>
 
 ## Write a finalizer
 
-Use the correct base class (<xref:KubeOps.Operator.Finalizer.ResourceFinalizerBase`1>).
+Use the correct interface (<xref:KubeOps.Operator.Finalizer.IResourceFinalizer`1>).
 
 A finalizer can be as simple as:
 
 ```csharp
-public class FooFinalizer : ResourceFinalizerBase<Foo>
+public class TestEntityFinalizer : IResourceFinalizer<V1TestEntity>
 {
-    public override async Task Finalize(Foo resource)
+    private readonly IManager _manager;
+
+    public TestEntityFinalizer(IManager manager)
     {
-        // do something with the resource.
-        // like deleting a database.
+        _manager = manager;
+    }
+
+    public Task FinalizeAsync(V1TestEntity resource)
+    {
+        _manager.Finalized(resource);
+        return Task.CompletedTask;
     }
 }
 ```
 
+The interface also provides a way of overwriting the
+<xref:KubeOps.Operator.Finalizer.IResourceFinalizer`1.Identifier> of the finalizer if you feed like it.
+
 When the finalizer successfully completed his job, it is automatically removed
-from the finalizers list of the resource. The finalizers are registered
-as transient resources in DI.
+from the finalizers list of the entity. The finalizers are registered
+as scoped resources in DI.
 
 ## Register a finalizer
 
 To attach a finalizer for a resource, call the
-<xref:KubeOps.Operator.Controller.ResourceControllerBase`1.AttachFinalizer``1(`0)>
+<xref:KubeOps.Operator.Finalizer.IFinalizerManager`1.RegisterFinalizerAsync``1(`0)>
 method in the controller during reconciliation.
 
 ```csharp
-public class TestController : ResourceControllerBase<V1TestEntity>
+public class TestController : IResourceController<V1TestEntity>
 {
-    protected override async Task<TimeSpan?> Created(V1TestEntity resource)
+    private readonly IFinalizerManager<V1TestEntity> _manager;
+
+    public TestController(IFinalizerManager<V1TestEntity> manager)
+    {
+        _manager = manager;
+    }
+
+    public async Task<ResourceControllerResult> CreatedAsync(V1TestEntity resource)
     {
-        await AttachFinalizer<TestEntityFinalizer>(resource);
-        return await base.Created(resource);
+        // The type MyFinalizer must be an IResourceFinalizer<V1TestEntity>
+        await _manager.RegisterFinalizerAsync<MyFinalizer>(resource);
+        return null;
     }
 }
 ```

docs/docs/getting_started.md

@@ -10,13 +10,15 @@ that activate and start the operator as a web application.
 
 ## Terminology
 
-- `Entity`: A (C#) model - an entity - that is used in kubernetes. An entity defines the CRD.
-- `Resource`: An instance of an entity.
+- `Entity`: A (C#) model - an entity - that is used in kubernetes.
+  An entity is the class for a kubernetes resource.
+- `Resource` (or `TResource`): The type of a kubernetes resource.
 - `Controller` or `ResourceController`: An instance of a resource manager
   that is responsible for the reconciliation of an entity.
 - `Finalizer`: A special resource manager that is attached to the entity
   via identifier. The finalizers are called when an entity is deleted
   on kubernetes.
+- `Validator`: An implementation for a validation admission webhook.
 - `CRD`: CustomResourceDefinition of kubernetes.
 
 ## How To Start
@@ -82,9 +84,7 @@ public class Startup
     public void ConfigureServices(IServiceCollection services)
     {
         services
-            .AddKubernetesOperator() // config / settings here
-            .AddFinalizer<TestEntityFinalizer>()
-            .AddController<TestController>(); // Add controllers / finalizers / ... here
+            .AddKubernetesOperator(); // config / settings here
 
         // your own dependencies
         services.AddTransient<IManager, TestManager.TestManager>();

docs/docs/testing.md

@@ -12,7 +12,7 @@ have a look at the test code in the repository:
 > For normal unit testing, you can just mock all the things.
 
 The main entry point for testing your custom operator is the
-@"KubeOps.Testing.KubernetesOperatorFactory`1". It is ment to be
+@"KubeOps.Testing.KubernetesOperatorFactory`1". It is meant to be
 injected into your test.
 
 > [!NOTE]
@@ -24,34 +24,34 @@ The following steps are needed for integration testing the controller:
 
 - Create a `TestStartup.cs` file (or any other name you want)
 - Inject the @"KubeOps.Testing.KubernetesOperatorFactory`1"
-- Use the mocked client / queues to test your operator
+- Use the mocked client and helper functions to test your operator
 
 ## Test Startup
 
 This file is very similar to a "normal" `Startup.cs` file of an
 asp.net application. Either you subclass it and replace your test mocked
 services, or you create a new one.
 
-[!code-csharp[TestStartup.cs](../../tests/KubeOps.TestOperator.Test/TestStartup.cs?highlight=20-21)]
+[!code-csharp[TestStartup.cs](../../tests/KubeOps.TestOperator.Test/TestStartup.cs)]
 
 ## Mocked elements
 
 The main part of this operator factory does mock the used kubernetes client
-and the resource event queues.
+and helper functions to enqueue events and finalizer events.
 
 Both mocked elements can be retrieved via the operator factory with:
 
-- @"KubeOps.Testing.KubernetesOperatorFactory`1.GetMockedEventQueue``1"
 - @"KubeOps.Testing.KubernetesOperatorFactory`1.MockedKubernetesClient"
+- @"KubeOps.Testing.KubernetesOperatorFactory`1.EnqueueEvent``1(KubeOps.Operator.Kubernetes.ResourceEventType,``0)"
+- @"KubeOps.Testing.KubernetesOperatorFactory`1.EnqueueFinalization``1(``0)"
 
-### Mocked event queue
+### Mocked events
 
-The event queue does not use a channel to read and write event but directly fire
-the given events.
+With the mentioned factory functions (@"KubeOps.Testing.KubernetesOperatorFactory`1.EnqueueEvent``1(KubeOps.Operator.Kubernetes.ResourceEventType,``0)"
+and @"KubeOps.Testing.KubernetesOperatorFactory`1.EnqueueFinalization``1(``0)")
+one can fire events for entities. This can be used to test your controllers.
 
-Also, the @"KubeOps.Operator.Queue.IResourceEventQueue`1.Enqueue(`0,System.Nullable{System.TimeSpan})"
-method does not actually enqueue anything but just adds the resource to a list
-of resources.
+The controllers are normally instantiated via the scope of the DI system.
 
 ### Mocked IKubernetesClient
 
@@ -73,4 +73,4 @@ You probably need to set the solution relative content root for
 asp.net testing. But then you can run the factory
 and create a test.
 
-[!code-csharp[TestStartup.cs](../../tests/KubeOps.TestOperator.Test/TestController.Test.cs?range=10-31,84&highlight=7,13)]
+[!code-csharp[TestStartup.cs](../../tests/KubeOps.TestOperator.Test/TestController.Test.cs)]

docs/docs/webhooks.md

@@ -82,14 +82,15 @@ It is suggested one uses `Docker Desktop` with kubernetes.
 The general idea of this webhook type is to validate an entity
 before it is definitely created / updated or deleted.
 
+Webhooks are registered in a **scoped** maner to the DI system.
+They behave like asp.net api controller.
+
 The implementation of a webhook is fairly simple:
 - Create a class somewhere in your project.
 - Implement the @"KubeOps.Operator.Webhooks.IValidationWebhook`1" interface.
-- Define the @"KubeOps.Operator.Webhooks.IValidationWebhook.Operations"
+- Define the @"KubeOps.Operator.Webhooks.IValidationWebhook`1.Operations"
   (from the interface) that the validator is interested in.
 - Overwrite the corresponding methods.
-- Register it in the @"KubeOps.Operator.Builder.IOperatorBuilder"
-  with @"KubeOps.Operator.Builder.IOperatorBuilder.AddValidationWebhook``1".
 
 > [!WARNING]
 > The interface contains default implementations for _ALL_ methods.
@@ -126,15 +127,3 @@ public class TestValidator : IValidationWebhook<EntityClass>
      private static bool CheckSpec(EntityClass entity) => entity.Spec.Username != "foobar";
  }
 ```
-
-And then register the webhook in `Startup.cs`:
-
-```c#
-public void ConfigureServices(IServiceCollection services)
-{
-    services
-        .AddKubernetesOperator()
-        // ...
-        .AddValidationWebhook<TestValidator>();
-}
-```