SRVKE-1155: DP documentation of KafkaSource scaling, how to enable + …

…configure (#108)

* doc: documented KafkaSource scaling, how to enable + configure

Signed-off-by: Calum Murray <[email protected]>
Co-authored-by: Pierangelo Di Pilato <[email protected]>

antora.yml

@@ -10,6 +10,7 @@ asciidoc:
     smproductname: OpenShift Service Mesh
     product-title: OpenShift
     ocp: OpenShift Container Platform
+    custommetricsautoscaleroperatorname: OpenShift Custom Metrics Autoscaler Operator
     serverlessoperatorname: OpenShift Serverless Operator
     certmanageroperatorname: OpenShift Cert-Manager Operator
     serverlessproductname: OpenShift Serverless
@@ -82,4 +83,4 @@ asciidoc:
 
     minikube_url: https://minikube.sigs.k8s.io
     kogito_serverless_operator_url: https://github.com/apache/incubator-kie-kogito-serverless-operator/
-    docs_issues_url: https://github.com/kiegroup/kogito-docs/issues/new
+    docs_issues_url: https://github.com/kiegroup/kogito-docs/issues/new

modules/ROOT/nav.adoc

@@ -7,6 +7,7 @@
 *** xref:serverless:service-mesh/eventing-service-mesh-sinkbinding.adoc[Eventing: Using SinkBinding with OpenShift Service Mesh]
 ** Features
 *** xref:serverless:features/transport-encryption/transport-encryption-setup.adoc[Setup transport encryption in Eventing]
+*** xref:serverless:features/eventing-kafka-scaling/eventing-kafka-scaling-setup.adoc[Setup Autoscaling For Eventing Kafka Components]
 ** Serving
 *** xref:serverless:serving/serving-with-ingress-sharding.adoc[Use Serving with OpenShift ingress sharding]
 *** xref:serverless:serving/scaleability-and-performance-of-serving.adoc[Scalability and performance of {serverlessproductname} Serving]

modules/serverless/pages/features/eventing-kafka-scaling/eventing-kafka-scaling-setup.adoc

@@ -0,0 +1,108 @@
+= Setup Autoscaling For Eventing Kafka Components
+:compat-mode!:
+// Metadata:
+:description: Setup Autoscaling for Eventing Kafka components in {serverlessproductname}
+
+This page describes how to set up the Autoscaling feature for Eventing Kafka, which allows for the Eventing Kafka components to autoscale based on the consumer group lag.
+
+[INFO]
+====
+This is only currently for the KafkaSource.
+====
+
+[IMPORTANT]
+====
+{serverlessproductname} autoscaling for Eventing Kafka components is a Developer Preview feature only.
+Developer Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete.
+Red Hat does not recommend using them in production.
+These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
+
+For more information about the support scope of Red Hat Developer Preview features, see https://access.redhat.com/support/offerings/devpreview/.
+====
+
+== Prerequisites
+
+* You have access to an {product-title} account with cluster administrator access.
+
+* Install the OpenShift CLI (`oc`).
+
+* Install the {serverlessoperatorname}.
+
+* Install the {custommetricsautoscaleroperatorname}.
+
+== Enable Autoscaling of KafkaSources in `KnativeKafka`
+
+[IMPORTANT]
+====
+Enabling autoscaling of KafkaSources enables autoscaling on all `KafkaSources` by default. +
+You can disable autoscaling for a specific `KafkaSource` as described in the <<disable_autoscaling_for_specific_KafkaSource>> section.
+====
+
+. Configure `controller-autoscaling-keda` feature flag to `enabled`:
++
+[source,yaml]
+----
+apiVersion: operator.knative.dev/v1
+kind: KnativeKafka
+metadata:
+  name: knative-kafka
+  namespace: knative-eventing
+spec:
+  
+  # Other spec fields omitted ...
+  # ...
+
+  config:
+    config-kafka-features:
+      controller-autoscaling-keda: enabled <1>
+----
+<1> Enables autoscaling for all KafkaSources.
+
+. Apply the `KnativeKafka` resource:
++
+[source,terminal]
+----
+$ oc apply -f <filename>
+----
+
+== Customize Autoscaling for a KafkaSource [[customize_autoscaling_configuration]]
+
+If you want to customize how the Custom Metrics Autoscaler scales a KafkaSource, you can set annotations on the source:
+
+[source,yaml]
+----
+apiVersion: sources.knative.dev/v1
+kind: KafkaSource
+metadata:
+  annotations:
+    # The minimum number of replicas to scale down to
+    autoscaling.eventing.knative.dev/min-scale: "0"
+    # The maximum number of replicas to scale up to
+    autoscaling.eventing.knative.dev/max-scale: "50"
+    # The interval in seconds the autoscaler uses to poll metrics in order to inform its scaling decisions
+    autoscaling.eventing.knative.dev/polling-interval: "10"
+    # The period in seconds the autoscaler waits until it scales down
+    autoscaling.eventing.knative.dev/cooldown-period: "30"
+    # The lag that is used for scaling (1<->N)
+    autoscaling.eventing.knative.dev/lag-threshold: "100"
+    # The lag that is used for activation (0<->1)
+    autoscaling.eventing.knative.dev: "0"
+spec:
+  # KafkaSource spec fields ...
+----
+
+== Disable Autoscaling for a specific KafkaSource [[disable_autoscaling_for_specific_KafkaSource]]
+
+If you want to disable autoscaling for a KafkaSource, you need to set an annotation on the source:
+
+[source,yaml]
+----
+apiVersion: source.knative.dev/v1
+kind: KafkaSource
+metadata:
+  annotations:
+    autoscaling.eventing.knative.dev/class: disabled
+  # more metadata ...
+spec:
+  # spec fields ...
+----