Merge pull request kubernetes-sigs#7933 from killianmuldoon/docs/add-runtime-extension-settings

📖 Add documentation of RuntimeExtension settings

Author: k8s-ci-robot

docs/book/src/tasks/experimental-features/runtime-sdk/implement-extensions.md

@@ -292,6 +292,16 @@ controllers processing those resource that might impact system stability.
 
 </aside>
 
+### Settings
+
+Settings can be added to the ExtensionConfig object in the form of a map with string keys and values. These settings are
+sent with each request to hooks registered by that ExtensionConfig. Extension developers can implement behavior in their
+extensions to alter behavior based on these settings. Settings should be well documented by extension developers so that 
+ClusterClass authors can understand usage and expected behaviour.
+
+Settings can be provided for individual external patches by providing them in the ClusterClass `.spec.patches[*].external.settings`.
+This can be used to overwrite settings at the ExtensionConfig level for that patch.
+
 ### Error management
 
 In case a Runtime Extension returns an error, the error will be handled according to the corresponding failure policy

docs/book/src/tasks/experimental-features/runtime-sdk/implement-lifecycle-hooks.md

@@ -46,6 +46,7 @@ determine/prepare add-ons for the Cluster and block the creation of those object
 ```yaml
 apiVersion: hooks.runtime.cluster.x-k8s.io/v1alpha1
 kind: BeforeClusterCreateRequest
+settings: <Runtime Extension settings>
 cluster:
   apiVersion: cluster.x-k8s.io/v1beta1
   kind: Cluster
@@ -84,6 +85,7 @@ possible once the Control Plane is available. This hook does not block any furth
 ```yaml
 apiVersion: hooks.runtime.cluster.x-k8s.io/v1alpha1
 kind: AfterControlPlaneInitializedRequest
+settings: <Runtime Extension settings>
 cluster:
   apiVersion: cluster.x-k8s.io/v1beta1
   kind: Cluster
@@ -118,6 +120,7 @@ can use this hook to execute pre-upgrade add-on tasks and block upgrades of the
 ```yaml
 apiVersion: hooks.runtime.cluster.x-k8s.io/v1alpha1
 kind: BeforeClusterUpgradeRequest
+settings: <Runtime Extension settings>
 cluster:
   apiVersion: cluster.x-k8s.io/v1beta1
   kind: Cluster
@@ -160,6 +163,7 @@ until everything is ready.
 ```yaml
 apiVersion: hooks.runtime.cluster.x-k8s.io/v1alpha1
 kind: AfterControlPlaneUpgradeRequest
+settings: <Runtime Extension settings>
 cluster:
   apiVersion: cluster.x-k8s.io/v1beta1
   kind: Cluster
@@ -196,6 +200,7 @@ This hook does not block any further changes or upgrades to the Cluster.
 ```yaml
 apiVersion: hooks.runtime.cluster.x-k8s.io/v1alpha1
 kind: AfterClusterUpgradeRequest
+settings: <Runtime Extension settings>
 cluster:
   apiVersion: cluster.x-k8s.io/v1beta1
   kind: Cluster
@@ -231,6 +236,7 @@ cleanup tasks for the add-ons and block deletion of the Cluster and descendant o
 ```yaml
 apiVersion: hooks.runtime.cluster.x-k8s.io/v1alpha1
 kind: BeforeClusterDeleteRequest
+settings: <Runtime Extension settings>
 cluster:
   apiVersion: cluster.x-k8s.io/v1beta1
   kind: Cluster

docs/book/src/tasks/experimental-features/runtime-sdk/implement-topology-mutation-hook.md

@@ -88,6 +88,7 @@ templates, the global variables and the template-specific variables. The respons
 ```yaml
 apiVersion: hooks.runtime.cluster.x-k8s.io/v1alpha1
 kind: GeneratePatchesRequest
+settings: <Runtime Extension settings>
 variables:
 - name: <variable-name>
   value: <variable-value>
@@ -151,6 +152,7 @@ contains the result of the validation.
 ```yaml
 apiVersion: hooks.runtime.cluster.x-k8s.io/v1alpha1
 kind: ValidateTopologyRequest
+settings: <Runtime Extension settings>
 variables:
 - name: <variable-name>
   value: <variable-value>

docs/proposals/20220221-runtime-SDK.md

@@ -310,6 +310,9 @@ spec:
   # NamespaceSelector decides whether to run the webhook on a Cluster based on whether the namespace for that Cluster matches the selector.
   # If not specified, the WebHook runs for all the namespaces.
   namespaceSelector: {}
+  # settings is a map[string]string which is sent with each request to a Runtime Extension. These settings can be used by
+  # to modify the behaviour of a Runtime Extension.
+  settings: {}
 ```
 
 Once the extension is registered the [discovery hook](#discovery-hook) is called and the above CR is updated with the list

docs/proposals/20220330-topology-mutation-hook.md

@@ -140,7 +140,9 @@ Once the extension is registered the discovery hook is called and the Extension
 
 A ClusterClass author can use an External Patch Extension by referencing it in a ClusterClass and adding the corresponding variable definitions.
 
-A ClusterClass can have external patches, inline patches or both. The patches will then be applied in the order in which they are defined. The extension fields of the external patch must match the unique name of RuntimeExtensions assigned during discovery.
+A ClusterClass can have external patches, inline patches or both. The patches will then be applied in the order in which 
+they are defined. The extension fields of the external patch must match the unique name of RuntimeExtensions assigned during discovery.
+External patches can provide settings in map with key and string values. Settings and their usage are defined by GeneratePatch hook authors.
 
 ```yaml
 apiVersion: cluster.x-k8s.io/v1beta1
@@ -154,7 +156,10 @@ spec:
     external:
       generateExtension: "http-proxy.my-awesome-patch"
       validateExtension: "http-proxy-validate.my-awesome-patch"
-  # inline patch
+      settings:
+        firstSetting: "red"
+        secondSettings: "blue"
+    # inline patch
   - name: region
     definitions:
     ...