Add documentation for autoscaling

appuio · Dec 13, 2024 · f5777d2 · f5777d2
1 parent 8677ddb
commit f5777d2
Showing 1 changed file with 159 additions and 58 deletions.
diff --git a/docs/modules/ROOT/pages/references/parameters.adoc b/docs/modules/ROOT/pages/references/parameters.adoc
@@ -195,6 +195,165 @@ This gives you the full control over the resulting `MachineSet` or `ControlPlane
 Values given here will be merged with precedence with the defaults configured in <<defaultSpec>>.
 The values can be everything that's accepted in the `spec` field of a `machinesets.machine.openshift.io` object.
 
+== `machineSets`
+
+[horizontal]
+type:: dictionary
+default:: `{}`
+example::
++
+[source,yaml]
+----
+machineSets:
+  worker:
+    metadata:
+      labels:
+        machine.openshift.io/cluster-api-cluster: c-cluster-1
+    spec:
+      deletePolicy: Oldest
+      replicas: 3
+      selector:
+        matchLabels:
+          machine.openshift.io/cluster-api-cluster: c-cluster-1
+          machine.openshift.io/cluster-api-machineset: worker
+      template:
+        metadata:
+          labels:
+            machine.openshift.io/cluster-api-cluster: c-cluster-1
+            machine.openshift.io/cluster-api-machine-role: app
+            machine.openshift.io/cluster-api-machine-type: app
+            machine.openshift.io/cluster-api-machineset: worker
+        spec:
+          lifecycleHooks: {}
+          metadata:
+            labels:
+              node-role.kubernetes.io/app: ""
+              node-role.kubernetes.io/worker: ""
+          providerSpec:
+            value:
+              antiAffinityKey: worker
+              baseDomain: c-cluster-1.vshnmanaged.net
+              flavor: plus-16-4
+              image: custom:rhcos-4.16
+              interfaces:
+                - addresses:
+                    - subnetUUID: 1971d4c3-0065-41fc-82f4-c26cf2fe4f9a
+                  type: Private
+              rootVolumeSizeGB: 100
+              tokenSecret:
+                name: cloudscale-rw-token
+              userDataSecret:
+                name: cloudscale-user-data
+              zone: lpg1
+----
+
+A dictionary of machine sets to create on the cluster.
+The resulting `MachineSet` object will have the key as the name and the value is merged into the resource.
+
+The MachineSet will will have the namespace from `machine_api_namespace` applied.
+
+== `autoscaling`
+
+[horizontal]
+type:: dictionary
+
+The fields in this parameter can be used to configure OpenShift's cluster autoscaling.
+See the https://docs.openshift.com/container-platform/4.16/machine_management/applying-autoscaling.html[upstream documentation] for a detailed description.
+
+=== `autoscaling.enabled`
+
+[horizontal]
+type:: bool
+default:: `false`
+
+Whether to configure autoscaling for the cluster.
+
+=== `autoscaling.clusterAutoscaler`
+
+[horizontal]
+type:: dictionary
+default:: `{}`
+
+The value of this parameter is merged into the default `.spec` of the `ClusterAutoscaler` resource which is generated by the component.
+
+The component deploys the following default `ClusterAutoscaler` `.spec`:
+
+[source,yaml]
+----
+spec:
+  podPriorityThreshold: -10
+  resourceLimits:
+    maxNodesTotal: 24
+    cores:
+      min: 8
+      max: 128
+    memory:
+      min: 4
+      max: 256
+  logVerbosity: 1
+  scaleDown:
+    enabled: true
+    delayAfterAdd: 10m
+    delayAfterDelete: 5m
+    delayAfterFailure: 30s
+    unneededTime: 5m
+    utilizationThreshold: '0.4'
+  expanders: [ 'Random' ]
+----
+
+See the upstream https://docs.openshift.com/container-platform/4.16/machine_management/applying-autoscaling.html#configuring-clusterautoscaler_applying-autoscaling[configuring the cluster autoscaler] documentation for details on each configuration option.
+
+NOTE: The component doesn't validate the provided configuration.
+
+NOTE: The fields in the cluster autoscaler's `spec.resourceLimits` must be configured to account for the non-autoscaled nodes in the cluster, such as control plane nodes, since they'll also count against the overall cluster size.
+
+=== `autoscaling.machineAutoscalers`
+
+[horizontal]
+type:: dictionary
+default:: `{}`
+
+Each key value pair in this parameter is used to create a `MachineAutoscaler` resource in the namespace indicated by parameter `machine_api_namespace`.
+
+The component expects that each key matches a `MachineSet` which is configured through one of the parameters `nodeGroups` or `machineSets`.
+The component will raise an error if it finds a key which doesn't have a matching entry in `nodeGroups` or `machineSets`.
+
+The value associated with each key is used as the base configuration for `.spec` of the resulting `MachineAutoscaler` resource.
+The component will always configure `.spec.scaleTargetRef.name` with the key to ensure the `MachineAutoscaler` resource targets the desired `MachineSet`.
+
+The component will raise an error if a value doesn't have the exact keys `minReplicas` and `maxReplicas`
+
+See the upstream https://docs.openshift.com/container-platform/4.16/machine_management/applying-autoscaling.html#configuring-machineautoscaler_applying-autoscaling[configuring machine autoscalers] documentation for more details.
+
+=== `autoscaling.priorityExpanderConfig`
+
+[horizontal]
+type:: dictionary
+default:: `{}`
+
+If this parameter has any fields set, the component will generate a configmap `cluster-autoscaler-priority-expander` in the namespace indicated by parameter `machine_api_namespace`.
+
+When the parameter has any fields set, the component will default parameter `.spec.expanders` of the `ClusterAutoscaler` to `['Priority']`.
+
+The component will render the provided dictionary as YAML and write it to `data.priorities` in the `cluster-autoscaler-priority-expander` configmap.
+
+=== Example configuration
+
+This configuration assumes that a `MachineSet` named `app` is configured through either `nodePools` or `machineSets`.
+
+[source,yaml]
+----
+autoscaling:
+  enabled: true
+  clusterAutoscaler:
+    logVerbosity: 4 <1>
+  machineAutoscalers:
+    app:
+      minReplicas: 2
+      maxReplicas: 6
+----
+<1> Enable debug logging by setting `logVerbosity=4` if you need to troubleshoot the autoscaling behavior.
+
 == `machineConfigPools`
 
 [horizontal]
@@ -488,64 +647,6 @@ See the documentation for http://localhost:2020/cilium/references/parameters.htm
 
 The script expects the ConfigMap to have a key matching each node name on which egress dummy interfaces should be configured.
 
-
-== `machineSets`
-
-[horizontal]
-type:: dictionary
-default:: `{}`
-example::
-+
-[source,yaml]
-----
-machineSets:
-  worker:
-    metadata:
-      labels:
-        machine.openshift.io/cluster-api-cluster: c-cluster-1
-    spec:
-      deletePolicy: Oldest
-      replicas: 3
-      selector:
-        matchLabels:
-          machine.openshift.io/cluster-api-cluster: c-cluster-1
-          machine.openshift.io/cluster-api-machineset: worker
-      template:
-        metadata:
-          labels:
-            machine.openshift.io/cluster-api-cluster: c-cluster-1
-            machine.openshift.io/cluster-api-machine-role: app
-            machine.openshift.io/cluster-api-machine-type: app
-            machine.openshift.io/cluster-api-machineset: worker
-        spec:
-          lifecycleHooks: {}
-          metadata:
-            labels:
-              node-role.kubernetes.io/app: ""
-              node-role.kubernetes.io/worker: ""
-          providerSpec:
-            value:
-              antiAffinityKey: worker
-              baseDomain: c-cluster-1.vshnmanaged.net
-              flavor: plus-16-4
-              image: custom:rhcos-4.16
-              interfaces:
-                - addresses:
-                    - subnetUUID: 1971d4c3-0065-41fc-82f4-c26cf2fe4f9a
-                  type: Private
-              rootVolumeSizeGB: 100
-              tokenSecret:
-                name: cloudscale-rw-token
-              userDataSecret:
-                name: cloudscale-user-data
-              zone: lpg1
-----
-
-A dictionary of machine sets to create on the cluster.
-The resulting `MachineSet` object will have the key as the name and the value is merged into the resource.
-
-The MachineSet will will have the namespace from `machine_api_namespace` applied.
-
 === Example
 
 [source,yaml]