book: extend Runtime SDK documentation & update proposal

docs/book/src/SUMMARY.md

@@ -24,7 +24,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-topology-mutation.plantuml

@@ -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/tasks/experimental-features/cluster-class/index.md

@@ -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/tasks/experimental-features/experimental-features.md

@@ -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/runtime-sdk/deploy-runtime-extension.md

@@ -0,0 +1,51 @@
+# Deploy Runtime Extensions
+
+<aside class="note warning">
+
+Please note Runtime SDK is an advanced feature. If implemented incorrectly a failing Runtime Extension can severly 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; additionally, Runtime Extensions must always be executed out of process (not in the same process as
+the Cluster API runtime).
+
+This proposal assumes that the default solution that implementers are going to adopt is to deploy 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.
+
+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 backends behind a service to leverage the
+load-balancing that services support.
+
+## Identity and access management
+
+The security model for each Runtime Extensions should be carefully defined, similar to any other application deployed
+in the Cluster: the deployment must use a dedicated service account with limited RBAC permission.
+
+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) and
+the Pod spec in the Deployment manifest should enforce security best practices (e.g. do not use privileged pods etc.).
+
+##  Alternative deployments methods
+
+Alternative deployment methods can be used given that the requirement about the HTTP endpoint accessibility
+is satisfied, like e.g.
+
+- deploying the HTTP Server as a part of another component, e.g. a controller;
+- deploying the HTTP Server outside the Management Cluster.
+
+In these cases above recommendations about availability and identity and access management apply as well.
+
+## Example
+
+For an example, please see our [test extension](https://github.com/kubernetes-sigs/cluster-api/tree/main/test/extension)
+which follows the kubebuilder setup we usually use for our controllers as close as possible.