docs: add better documentation for webhooks

Author: buehler

docs/docfx.json

@@ -3,7 +3,9 @@
     {
       "src": [
         {
-          "files": ["**/*.csproj"],
+          "files": [
+            "**/*.csproj"
+          ],
           "src": "../src/KubeOps"
         }
       ],
@@ -12,7 +14,9 @@
     {
       "src": [
         {
-          "files": ["**/*.csproj"],
+          "files": [
+            "**/*.csproj"
+          ],
           "src": "../src/KubeOps.Testing"
         }
       ],
@@ -22,24 +26,47 @@
   "build": {
     "content": [
       {
-        "files": ["kube-ops/**.yml", "kube-ops/index.md"]
+        "files": [
+          "kube-ops/**.yml",
+          "kube-ops/index.md"
+        ]
       },
       {
-        "files": ["kube-ops-testing/**.yml", "kube-ops-testing/index.md"]
+        "files": [
+          "kube-ops-testing/**.yml",
+          "kube-ops-testing/index.md"
+        ]
       },
       {
-        "files": ["docs/**.md", "docs/**/toc.yml", "toc.yml", "*.md"]
+        "files": [
+          "docs/**.md",
+          "docs/**/toc.yml",
+          "toc.yml",
+          "*.md"
+        ]
       }
     ],
     "resource": [
       {
-        "files": ["images/**"]
+        "files": [
+          "images/**"
+        ]
       }
     ],
+    "xrefService": [
+      "https://xref.docs.microsoft.com/query?uid={uid}"
+    ],
+    "globalMetadata": {
+      "_appTitle": "KubeOps Documentation",
+      "_appFooter": "© Copyright 2021 Christoph Bühler",
+      "_appFaviconPath": "images/favicon.png"
+    },
     "dest": "public",
     "sitemap": {
       "baseUrl": "https://buehler.github.io/dotnet-operator-sdk/"
     },
-    "template":["default","templates/discordfx"]
+    "template": [
+      "statictoc"
+    ]
   }
 }

docs/docs/commands.md

@@ -29,11 +29,14 @@ Here is a brief overview over the available commands:
 - `uninstall`: uninstall the CRDs for the solution from the cluster
 - `generator`: entry command for generator commands (i.e. has subcommands), all commands
   output their result to the stdout or the given output path
-  - `crd`: Generate the CRDs
-  - `docker`: Generate the dockerfile
-  - `installer`: Generate the installer files (i.e. kustomization yaml) for the operator
-  - `operator`: Generate the deployment for the operator
-  - `rbac`: Generate the needed rbac roles / role bindings for the operator
+  - `crd`: generate the CRDs
+  - `docker`: generate the dockerfile
+  - `installer`: generate the installer files (i.e. kustomization yaml) for the operator
+  - `operator`: generate the deployment for the operator
+  - `rbac`: generate the needed rbac roles / role bindings for the operator
+- `webhook`: entry command for webhook related operations
+  - `install`: generate the server certificate and install the service / webhook registration
+  - `register`: register the currently implemented webhooks to the currently selected cluster
 
 ## Code Generation
 

docs/docs/features.md

@@ -16,6 +16,8 @@ As of now, the operator sdk supports - roughly - the following features:
   - Deleted
   - AddFinalizer
 - Finalizers for entities
+- Webhooks
+  - Validation / validators
 - Prometheus metrics for queues / caches / watchers
 - Healthchecks, split up to "readiness" and "liveness" (or both)
 - Commands for the operator (for exact documentation run: `dotnet run -- --help`)

docs/docs/getting_started.md

@@ -105,8 +105,9 @@ public class Startup
 
 When you completed this basic setup instructions, the next steps may or may not include:
 
-- Writting entities: Find more under ["Entites"](./entities.md)
-- Writting controllers: Find more under ["Controller"](./controller.md)
-- Writting finalizer: Find more under ["Finalizer"](./finalizer.md)
+- Writing entities: Find more under ["Entites"](./entities.md)
+- Writing controllers: Find more under ["Controller"](./controller.md)
+- Writing finalizer: Find more under ["Finalizer"](./finalizer.md)
+- Writing webhooks: Find more under ["Webhooks"](./webhooks.md)
 - Customize the operator: Find more under ["Settings"](./settings.md)
-- Writting and using utilities: Find more under ["Utilities"](./utilities.md)
+- Writing and using utilities: Find more under ["Utilities"](./utilities.md)

docs/docs/ms_build.md

@@ -9,7 +9,7 @@ You'll find the configurations and targets here:
 
 An example of such a target is:
 
-[!code-xml[KubeOps.targets](../../src/KubeOps/Build/KubeOps.targets?range=2-17&dedent=4&highlight=2-7)]
+[!code-xml[KubeOps.targets](../../src/KubeOps/Build/KubeOps.targets?range=45-53&dedent=4&highlight=2-7)]
 
 They can be configured with the prop settings described below.
 The props file just defines the defaults.

docs/docs/testing.md

@@ -60,8 +60,6 @@ All methods do return `null` or the object that was passed
 into the mocked class. There are five different object
 references that can be set to return certain results upon calling the client.
 
-[!code-csharp[TestStartup.cs](../../src/KubeOps.Testing/MockKubernetesClient.cs?range=13-14,17-25,88&highlight=3-11)]
-
 > [!WARNING]
 > The mocked client is injected as singleton, this means
 > the used "result" references can vary. Be aware of that

docs/docs/webhooks.md

@@ -10,6 +10,11 @@ of the master api. Those are documented on the
 The following documentation should give the user an overview
 on how to implement a webhook what this implies to the written operator.
 
+At the courtesy of the kubernetes website, here is a diagram of the
+process that runs for admission controllers and api requests:
+
+![admission controller phases](https://d33wubrfki0l68.cloudfront.net/af21ecd38ec67b3d81c1b762221b4ac777fcf02d/7c60e/images/blog/2019-03-21-a-guide-to-kubernetes-admission-controllers/admission-controller-phases.png)
+
 ## General
 
 In general, if your operator contains _any_ registered (registered in the
@@ -34,6 +39,11 @@ to the normal deployment of the operator will happen:
 When a webhook is registered, the specified operations will
 trigger a POST call to the operator.
 
+> [!NOTE]
+> The certificates are generated with [cfssl](https://github.com/cloudflare/cfssl),
+> an amazing tool from cloudflare that helps with the general hassle
+> of creating CAs and certificates in general.
+
 > [!NOTE]
 > Make sure you commit the `ca.pem` / `ca-key.pem` file.
 > During operator startup (init container) those files
@@ -74,11 +84,12 @@ before it is definitely created / updated or deleted.
 
 The implementation of a webhook is fairly simple:
 - Create a class somewhere in your project.
-- Implement the `IValidationWebhook{TEntity}` interface.
-- Define the `Operations` (from the interface) that the validator
-  is interested in.
+- Implement the @"KubeOps.Operator.Webhooks.IValidationWebhook`1" interface.
+- Define the @"KubeOps.Operator.Webhooks.IValidationWebhook.Operations"
+  (from the interface) that the validator is interested in.
 - Overwrite the corresponding methods.
-- Register it in the `IOperatorBuilder` with `AddValidationWebhook`.
+- Register it in the @"KubeOps.Operator.Builder.IOperatorBuilder"
+  with @"KubeOps.Operator.Builder.IOperatorBuilder.AddValidationWebhook``1".
 
 > [!WARNING]
 > The interface contains default implementations for _ALL_ methods.
@@ -87,7 +98,8 @@ The implementation of a webhook is fairly simple:
 > result.
 > The async methods take precedence over the synchronous ones.
 
-The return value of the validation methods are `ValidationResult`
+The return value of the validation methods are
+@"KubeOps.Operator.Webhooks.ValidationResult"
 objects. A result contains a boolean flag if the entity / operation
 is valid or not. It may contain additional warnings (if it is valid)
 that are presented to the user if the kubernetes api supports it.
@@ -97,21 +109,21 @@ as well as a custom error message that is presented to the user.
 ### Example
 
 ```c#
-public class TestValidator : IValidationWebhook<V2TestEntity>
+public class TestValidator : IValidationWebhook<EntityClass>
  {
      public ValidatedOperations Operations => ValidatedOperations.Create | ValidatedOperations.Update;
 
-     public ValidationResult Create(V2TestEntity newEntity, bool dryRun) =>
+     public ValidationResult Create(EntityClass newEntity, bool dryRun) =>
          CheckSpec(newEntity)
              ? ValidationResult.Success("The username may not be foobar.")
              : ValidationResult.Fail(StatusCodes.Status400BadRequest, @"Username is ""foobar"".");
 
-     public ValidationResult Update(V2TestEntity _, V2TestEntity newEntity, bool dryRun) =>
+     public ValidationResult Update(EntityClass _, EntityClass newEntity, bool dryRun) =>
          CheckSpec(newEntity)
              ? ValidationResult.Success("The username may not be foobar.")
              : ValidationResult.Fail(StatusCodes.Status400BadRequest, @"Username is ""foobar"".");
 
-     private static bool CheckSpec(V2TestEntity entity) => entity.Spec.Username != "foobar";
+     private static bool CheckSpec(EntityClass entity) => entity.Spec.Username != "foobar";
  }
 ```
 

docs/images/favicon.png

@@ -8,4 +8,4 @@
   href: kube-ops-testing/
   homepage: kube-ops-testing/index.md
 - name: Changelog
-  href: CHANGELOG.md
+  href: https://github.com/buehler/dotnet-operator-sdk/releases