feat(webhooks): Add mutation webhooks. (#167)

This closes #135.

This adds the possibility to have mutation webhooks
which are able to modify an object before it is validated
and stored into the master api.

BREAKING CHANGE: `ValidatedOperations` is renamed to
`AdmissionOperations`.

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

Author: buehler

config/CodeAnalysis.targets

@@ -11,4 +11,4 @@
         <TreatWarningsAsErrors Condition="'$(Configuration)' == 'Release'">true</TreatWarningsAsErrors>
     </PropertyGroup>
 
-</Project>
+</Project>

docs/docs/webhooks.md

@@ -6,6 +6,7 @@ of the master api. Those are documented on the
 
 `KubeOps` supports the following webhooks out of the box:
 - Validator / Validation
+- Mutator / Mutation
 
 The following documentation should give the user an overview
 on how to implement a webhook what this implies to the written operator.
@@ -82,13 +83,13 @@ 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.
+Webhooks are registered in a **scoped** manner to the DI system.
 They behave like asp.net api controller.
 
-The implementation of a webhook is fairly simple:
+The implementation of a validator is fairly simple:
 - Create a class somewhere in your project.
 - Implement the @"KubeOps.Operator.Webhooks.IValidationWebhook`1" interface.
-- Define the @"KubeOps.Operator.Webhooks.IValidationWebhook`1.Operations"
+- Define the @"KubeOps.Operator.Webhooks.IAdmissionWebhook`2.Operations"
   (from the interface) that the validator is interested in.
 - Overwrite the corresponding methods.
 
@@ -112,7 +113,7 @@ as well as a custom error message that is presented to the user.
 ```c#
 public class TestValidator : IValidationWebhook<EntityClass>
  {
-     public ValidatedOperations Operations => ValidatedOperations.Create | ValidatedOperations.Update;
+     public AdmissionOperations Operations => AdmissionOperations.Create | AdmissionOperations.Update;
 
      public ValidationResult Create(EntityClass newEntity, bool dryRun) =>
          CheckSpec(newEntity)
@@ -127,3 +128,34 @@ public class TestValidator : IValidationWebhook<EntityClass>
      private static bool CheckSpec(EntityClass entity) => entity.Spec.Username != "foobar";
  }
 ```
+
+## Mutation webhook
+
+Mutators are similar to validators but instead of defining if an object is
+valid or not, they are able to modify an object on the fly. The result
+of a mutator may generate a JSON Patch (http://jsonpatch.com) that patches
+the object that is later passed to the validators and to the Kubernetes
+API.
+
+The implementation of a mutator is fairly simple:
+- Create a class somewhere in your project.
+- Implement the @"KubeOps.Operator.Webhooks.IMutationWebhook`1" interface.
+- Define the @"KubeOps.Operator.Webhooks.IAdmissionWebhook`2.Operations"
+  (from the interface) that the validator is interested in.
+- Overwrite the corresponding methods.
+
+> [!WARNING]
+> The interface contains default implementations for _ALL_ methods.
+> The default of the async methods are to call the sync ones.
+> The default of the sync methods is to return a "not implemented"
+> result.
+> The async methods take precedence over the synchronous ones.
+
+The return value of the mutation methods do indicate if
+there has been a change in the model or not. If there is no
+change, return a result from @"KubeOps.Operator.Webhooks.MutationResult.NoChanges"
+and if there are changes, modify the object that is passed to the
+method and return the changed object with
+@"KubeOps.Operator.Webhooks.MutationResult.Modified(System.Object)".
+The system then calculates the diff and creates a JSON patch for
+the object.

src/KubeOps.Templates/KubeOps.Templates.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
-    <Import Project="..\..\config\Common.targets"/>
-    <Import Project="..\..\config\CodeAnalysis.targets"/>
+    <Import Project="..\..\config\Common.targets" />
+    <Import Project="..\..\config\CodeAnalysis.targets" />
 
     <PropertyGroup>
         <IsPackable>true</IsPackable>
@@ -24,8 +24,8 @@
     </PropertyGroup>
 
     <ItemGroup>
-        <Content Include="Templates\**\*" Exclude="Templates\**\bin\**;Templates\**\obj\**"/>
-        <Compile Remove="**\*"/>
+        <Content Include="Templates\**\*" Exclude="Templates\**\bin\**;Templates\**\obj\**" />
+        <Compile Remove="**\*" />
     </ItemGroup>
 
 </Project>

src/KubeOps.Templates/Templates/EmptyOperator.CSharp/GeneratedOperatorProject.csproj

@@ -6,4 +6,4 @@
         <Nullable>enable</Nullable>
     </PropertyGroup>
 
-</Project>
+</Project>

src/KubeOps.Templates/Templates/Operator.CSharp/GeneratedOperatorProject.csproj

@@ -6,4 +6,4 @@
         <Nullable>enable</Nullable>
     </PropertyGroup>
 
-</Project>
+</Project>

src/KubeOps.Templates/Templates/Operator.CSharp/Webhooks/DemoMutator.cs

@@ -0,0 +1,17 @@
+using GeneratedOperatorProject.Entities;
+using KubeOps.Operator.Webhooks;
+using Microsoft.AspNetCore.Http;
+
+namespace GeneratedOperatorProject.Webhooks
+{
+    public class DemoMutator : IMutationWebhook<V1DemoEntity>
+    {
+        public AdmissionOperations Operations => AdmissionOperations.Create;
+
+        public MutationResult Create(V1DemoEntity newEntity, bool dryRun)
+        {
+            newEntity.Spec.Username = "not foobar";
+            return MutationResult.Modified(newEntity);
+        }
+    }
+}

src/KubeOps.Templates/Templates/Operator.CSharp/Webhooks/DemoValidator.cs

@@ -6,7 +6,7 @@ namespace GeneratedOperatorProject.Webhooks
 {
     public class DemoValidator : IValidationWebhook<V1DemoEntity>
     {
-        public ValidatedOperations Operations => ValidatedOperations.Create;
+        public AdmissionOperations Operations => AdmissionOperations.Create;
 
         public ValidationResult Create(V1DemoEntity newEntity, bool dryRun)
             => newEntity.Spec.Username == "forbiddenUsername"

src/KubeOps.Templates/Templates/Operator.FSharp/Webhooks/DemoMutator.fs

@@ -0,0 +1,13 @@
+namespace GeneratedOperatorProject.Webhooks
+
+open GeneratedOperatorProject.Entities
+open KubeOps.Operator.Webhooks
+open Microsoft.AspNetCore.Http
+
+type DemoMutator() =
+    interface IMutationWebhook<V1DemoEntity> with
+        member this.Operations = AdmissionOperations.Create
+
+        member this.Create(newEntity, _) =
+            newEntity.Spec.Username <- "not foobar"
+            MutationResult.Modified(newEntity)

src/KubeOps.Templates/Templates/Operator.FSharp/Webhooks/DemoValidator.fs

@@ -6,7 +6,7 @@ open Microsoft.AspNetCore.Http
 
 type DemoValidator() =
     interface IValidationWebhook<V1DemoEntity> with
-        member this.Operations = ValidatedOperations.Create
+        member this.Operations = AdmissionOperations.Create
 
         member this.Create(newEntity, _) =
             if newEntity.Spec.Username = "forbiddenUsername"

src/KubeOps/KubeOps.csproj

@@ -25,7 +25,8 @@
 
     <ItemGroup>
         <PackageReference Include="CompareNETObjects" Version="4.72.0" />
-        <PackageReference Include="DotnetKubernetesClient" Version="1.1.0" />
+        <PackageReference Include="DotnetKubernetesClient" Version="1.1.1" />
+        <PackageReference Include="JsonDiffPatch" Version="2.0.52" />
         <PackageReference Include="McMaster.Extensions.CommandLineUtils" Version="3.1.0" />
         <PackageReference Include="McMaster.Extensions.Hosting.CommandLine" Version="3.1.0" />
         <PackageReference Include="Microsoft.Extensions.Diagnostics.HealthChecks" Version="5.0.3" />