book: extend Runtime SDK documentation & update proposals

Author: sbueringer

docs/book/src/SUMMARY.md

@@ -26,7 +26,11 @@
             - [Writing a ClusterClass](./tasks/experimental-features/cluster-class/write-clusterclass.md)
             - [Changing a ClusterClass](./tasks/experimental-features/cluster-class/change-clusterclass.md)
             - [Operating a managed Cluster](./tasks/experimental-features/cluster-class/operate-cluster.md)
-        - [Runtime SDK](./tasks/experimental-features/runtime-sdk.md)
+        - [Runtime SDK](tasks/experimental-features/runtime-sdk/index.md)
+            - [Implementing Runtime Extensions](./tasks/experimental-features/runtime-sdk/implement-extensions.md)
+            - [Implementing Lifecycle Hook Extensions](./tasks/experimental-features/runtime-sdk/implement-lifecycle-hooks.md)
+            - [Implementing Topology Mutation Hook Extensions](./tasks/experimental-features/runtime-sdk/implement-topology-mutation-hook.md)
+            - [Deploying Runtime Extensions](./tasks/experimental-features/runtime-sdk/deploy-runtime-extension.md)
         - [Ignition Bootstrap configuration](./tasks/experimental-features/ignition.md)
 - [Security Guidelines](./security/index.md)
     - [Pod Security Standards](./security/pod-security-standards.md)

docs/book/src/images/runtime-sdk-lifecycle-hooks.png

@@ -0,0 +1,56 @@
+@startuml
+title Figure 1. Cluster topology reconciliation
+
+
+' -- GROUPS START ---
+
+box #LightGreen
+participant "API Server"
+end box
+
+box #LightBlue
+participant "Cluster Topology Controller"
+end box
+
+box #LightBlue
+participant "External Patch Extensions"
+end box
+
+' -- GROUPS END ---
+
+"API Server" --> "Cluster Topology Controller": Cluster reconcile event
+activate "Cluster Topology Controller"
+
+"Cluster Topology Controller" -> "API Server": Get current Cluster topology
+activate "API Server"
+"API Server" -> "Cluster Topology Controller":
+deactivate "API Server"
+
+group Compute desired State
+  "Cluster Topology Controller" -> "Cluster Topology Controller": Compute desired State
+  loop Ordered list of Patches
+    alt
+      "Cluster Topology Controller" -> "Cluster Topology Controller": Generate inline patches
+    else
+      "Cluster Topology Controller" -> "External Patch Extensions": Generate external patches
+      activate "External Patch Extensions"
+      "External Patch Extensions" -> "Cluster Topology Controller":
+      deactivate "External Patch Extensions"
+    end
+    "Cluster Topology Controller" -> "Cluster Topology Controller": Apply patches to desired State
+  end loop
+
+  loop External Patches
+    "Cluster Topology Controller" -> "External Patch Extensions": ValidateTopology
+    activate "External Patch Extensions"
+    "External Patch Extensions" -> "Cluster Topology Controller":
+    deactivate "External Patch Extensions"
+  end loop
+end group
+
+"Cluster Topology Controller" -> "API Server": Reconcile Cluster topology
+
+deactivate "Cluster Topology Controller"
+
+hide footbox
+@enduml

docs/book/src/images/runtime-sdk-topology-mutation.plantuml

@@ -16,7 +16,7 @@ In order to use the ClusterClass (alpha) experimental feature the Kubernetes Ver
 **Variable name to enable/disable the feature gate**: `CLUSTER_TOPOLOGY`
 
 Additional documentation:
-* Background information:  [ClusterClass and Managed Topologies CAEP](https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20210526-cluster-class-and-managed-topologies.md)
+* Background information: [ClusterClass and Managed Topologies CAEP](https://github.com/kubernetes-sigs/cluster-api/blob/main/docs/proposals/20210526-cluster-class-and-managed-topologies.md)
 * For ClusterClass authors:
     * [Writing a ClusterClass](./write-clusterclass.md)
     * [Changing a ClusterClass](./change-clusterclass.md)

docs/book/src/images/runtime-sdk-topology-mutation.png

@@ -78,7 +78,7 @@ kubectl describe -n capi-system deployment.apps/capi-controller-manager
 * [ClusterResourceSet](./cluster-resource-set.md)
 * [ClusterClass](./cluster-class/index.md)
 * [Ignition Bootstrap configuration](./ignition.md)
-* [Runtime SDK](./runtime-sdk.md)
+* [Runtime SDK](runtime-sdk/index.md)
 
 **Warning**: Experimental features are unreliable, i.e., some may one day be promoted to the main repository, or they may be modified arbitrarily or even disappear altogether.
 In short, they are not subject to any compatibility or deprecation promise.

docs/book/src/tasks/experimental-features/cluster-class/index.md

@@ -0,0 +1,47 @@
+# Deploy Runtime Extensions
+
+<aside class="note warning">
+
+<h1>Caution</h1>
+
+Please note Runtime SDK is an advanced feature. If implemented incorrectly, a failing Runtime Extension can severely impact the Cluster API runtime.
+
+</aside>
+
+Cluster API requires that each Runtime Extension must be deployed using an endpoint accessible from the Cluster API
+controllers. The recommended deployment model is to deploy a Runtime Extension in the management cluster by:
+
+- Packing the Runtime Extension in a container image.
+- Using a Kubernetes Deployment to run the above container inside the Management Cluster.
+- Using a Cluster IP Service to make the Runtime Extension instances accessible via a stable DNS name.
+- Using a cert-manager generated Certificate to protect the endpoint.
+
+For an example, please see our [test extension](https://github.com/kubernetes-sigs/cluster-api/tree/main/test/extension)
+which follows, as closely as possible, the kubebuilder setup used for controllers in Cluster API.
+
+There are a set of important guidelines that must be considered while choosing the deployment method:
+
+## Availability
+
+It is recommended that Runtime Extensions should leverage some form of load-balancing, to provide high availability
+and performance benefits. You can run multiple Runtime Extension servers behind a Kubernetes Service to leverage the
+load-balancing that services support.
+
+## Identity and access management
+
+The security model for each Runtime Extension should be carefully defined, similar to any other application deployed
+in the Cluster. If the Runtime Extension requires access to the apiserver the deployment must use a dedicated service 
+account with limited RBAC permission. Otherwise no service account should be used.
+
+On top of that, the container image for the Runtime Extension should be carefully designed in order to avoid
+privilege escalation (e.g using [distroless](https://github.com/GoogleContainerTools/distroless) base images).
+The Pod spec in the Deployment manifest should enforce security best practices (e.g. do not use privileged pods).
+
+##  Alternative deployments methods
+
+Alternative deployment methods can be used as long as the HTTPs endpoint is accessible, like e.g.:
+
+- deploying the HTTPS Server as a part of another component, e.g. a controller.
+- deploying the HTTPS Server outside the Management Cluster.
+
+In those cases recommendations about availability and identity and access management still apply.