Added Reference section, Glossary, removed non-inclusive language. (k…

…edacore#1389) Co-authored-by: Dave Welsch <116022979+dwelsch-esi@users.noreply.github.com> Co-authored-by: Tom Kerkhove <kerkhove.tom@gmail.com> Co-authored-by: Nate W <natew@cncf.io> Co-authored-by: thisisobate <obasiuche62@gmail.com> Signed-off-by: shubhusion <shubham27.sharma03@gmail.com>
shubhusion · Aug 5, 2024 · eba4f53 · eba4f53
1 parent a5d80c0
commit eba4f53
Show file tree

Hide file tree

Showing 31 changed files with 1,570 additions and 676 deletions.
diff --git a/config.toml b/config.toml
@@ -188,7 +188,7 @@ parent = "docs"
 weight = 5
 
 [[menu.docs]]
-url = "/docs/faq/"
+url = "/docs/reference/faq/"
 name = "FAQ"
 parent = "docs"
 weight = 6

diff --git a/content/docs/2.14/operate/cloud-events.md b/content/docs/2.14/operate/cloud-events.md
@@ -0,0 +1,116 @@
++++
+title = "CloudEvent Support"
+description = "Experimental support for cloud events"
+weight = 100
++++
+
+## Subscribing to events with `CloudEventSource`
+`CloudEventSource` resource can be used in KEDA for subscribing to events that are emitted to the user's defined CloudEvent sink.
+
+> 📝 Event will be emitted to both Kubernetes Events and CloudEvents Destination if CloudEventSource resource is created.
+
+Here is a the schema of the `CloudEventSource` CRD:
+
+```yaml
+apiVersion: eventing.keda.sh/v1alpha1
+kind: CloudEventSource
+metadata:
+  name: {cloud-event-name}
+spec:
+  clusterName: {cluster-name} #Optional. Will be used in the source/subject to specify where the event comes from. The default value is 'kubernetes-default' and it can also be set during the installation of KEDA with --k8sClusterName. This one will overwrite others if set.
+  authenticationRef: 
+    name: {trigger-authentication-name} #Optional. Used to reference a `TriggerAuthentication` for authentication. 
+    kind: TriggerAuthentication # Optional. Used to choose the authentication scopes. https://keda.sh/docs/latest/concepts/authentication/#authentication-scopes-namespace-vs-cluster
+  destination:
+    http:
+      uri: http://foo.bar
+    azureEventGridTopic:
+      endpoint: https://my-topic.eastus-1.eventgrid.azure.net/api/events
+
+  eventSubscription: #Optional. Submit included/excluded event types will filter events when emitting events. 
+    includedEventTypes: #Optional. Only events in this section will be emitted.
+    - keda.scaledobject.failed.v1
+    excludedEventTypes: #Optional. Events in this section will not be emitted.       
+    - keda.scaledobject.ready.v1
+```
+
+In general, an event emitted by KEDA would fundamentally come down to the following structure:
+```json
+{
+    "specversion" : "1.0",
+    "type" : "com.cloudeventsource.keda",
+    "source" : "/{cluster-name}/{keda-namespace}/keda",
+    "subject" : "/{cluster-name}/{namespace}/{object-type}/{object-name}",
+    "id" : "<guid>",
+    "time" : "2018-04-05T17:31:00Z",
+    "datacontenttype" : "application/json",
+    "data" : {
+      "reason":"<event-reason>",
+      "message":"<event-message>"
+   }
+}
+```
+
+## Event Sinks
+
+There will be multiple types of destination to emit KEDA events to.
+
+Here is an overview of the supported destinations:
+
+- [HTTP endpoint](#http-endpoint).
+- [Azure Event Grid endpoint](#azure-event-grid).
+
+### HTTP endpoint
+```yaml
+  destination:
+    http:
+      uri: http://foo.bar  #An http endpoint that can receive cloudevent
+```
+
+### Azure Event Grid
+
+```yaml
+  destination:
+    azureEventGrid:
+      endpoint: foo.bar #endpoint from AzureEventGrid Topic
+```
+
+Authentication information must be provided by using `authenticationRef` which allows you to provide the access key or managed identity for Azure Event Grid authentication by providing a `TriggerAuthentication`.
+
+Here is an overview of the supported authentication types:
+
+#### Connection String Authentication
+
+- `accessKey` - Access key string for the Azure Event Grid connection auth.
+
+#### Pod identity based authentication
+[Azure AD Workload Identity](https://azure.github.io/azure-workload-identity/docs/) providers can be used.
+
+```yaml
+apiVersion: keda.sh/v1alpha1
+kind: TriggerAuthentication
+metadata:
+  name: nameOfTriggerAuth
+  namespace: default
+spec:
+  podIdentity:
+    provider: azure-workload
+```
+
+## Event Filter
+
+You can include filter(s) to define what event types you are interested in, or want to ignore. This is done by using `includedEventTypes` or `excludedEventTypes` respectively for a given sink.
+
+```yaml
+eventSubscription: #Optional. Submit included/excluded event types will filter events when emitting events. 
+  includedEventTypes: #Optional. Only events in this section will be emitted.
+  - keda.scaledobject.failed.v1
+  excludedEventTypes: #Optional. Events in this section will not be emitted.       
+  - keda.scaledobject.ready.v1
+```
+
+## Supported Event List
+| Event Type                    | Scenario Description                                                                                                        | 
+|-------------------------------|-----------------------------------------------------------------------------------------------------------------------------| 
+| `keda.scaledobject.ready.v1`  | On the first time a ScaledObject is ready, or if the previous ready condition status of the object was `Unknown` or `False` |  
+| `keda.scaledobject.failed.v1` | If the check validation for a ScaledObject fails                                                                            |      
diff --git a/content/docs/2.14/reference/_index.md b/content/docs/2.14/reference/_index.md
@@ -0,0 +1,13 @@
++++
+title = "Reference"
+weight = 2
++++
+
+Reference information for the KEDA autoscaler.
+
+- [ScaledObject specification](./scaledobject-spec)
+- [ScaledJob specification](./scaledjob-spec)
+- [Events](./events)
+- [Firewall requirements](../operate/cluster#firewall)
+- [FAQ](./faq.md)
+- [Glossary](./glossary.md)
diff --git a/content/docs/2.14/reference/events.md b/content/docs/2.14/reference/events.md
@@ -0,0 +1,28 @@
++++
+title = "Events reference"
+description = "Kubernetes Events emitted by KEDA"
+weight = 2500
++++
+
+KEDA emits the following [Kubernetes Events](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#event-v1-core):
+
+| Event                                 | Type      | Description                                                                                                                 |
+|---------------------------------------|-----------|-----------------------------------------------------------------------------------------------------------------------------|
+| `ScaledObjectReady`                   | `Normal`  | On the first time a ScaledObject is ready, or if the previous ready condition status of the object was `Unknown` or `False` | 
+| `ScaledJobReady`                      | `Normal`  | On the first time a ScaledJob is ready, or if the previous ready condition status of the object was `Unknown` or `False`    | 
+| `ScaledObjectCheckFailed`             | `Warning` | If the check validation for a ScaledObject fails                                                                            |                                                                           |
+| `ScaledJobCheckFailed`                | `Warning` | If the check validation for a ScaledJob fails                                                                               |                                                                     |
+| `ScaledObjectDeleted`                 | `Normal`  | When a ScaledObject is deleted and removed from KEDA watch                                                                  |                                                                    |
+| `ScaledJobDeleted`                    | `Normal`  | When a ScaledJob is deleted and removed from KEDA watch                                                                     |                                                                       |
+| `KEDAScalersStarted`                  | `Normal`  | When Scalers watch loop have started for a ScaledObject or ScaledJob                                                        |                                                           |
+| `KEDAScalersStopped`                  | `Normal`  | When Scalers watch loop have stopped for a ScaledObject or a ScaledJob                                                      |                                                         |
+| `KEDAScalerFailed`                    | `Warning` | When a Scaler fails to create or check its event source                                                                     |                                                                       |
+| `KEDAScaleTargetActivated`            | `Normal`  | When the scale target (Deployment, StatefulSet, etc) of a ScaledObject is scaled to 1, triggered by {scalers1;scalers2;...} |                                         |
+| `KEDAScaleTargetDeactivated`          | `Normal`  | When the scale target (Deployment, StatefulSet, etc) of a ScaledObject is scaled to 0                                       |                                        |
+| `KEDAScaleTargetActivationFailed`     | `Warning` | When KEDA fails to scale the scale target of a ScaledObject to 1                                                            |                                                              |
+| `KEDAScaleTargetDeactivationFailed`   | `Warning` | When KEDA fails to scale the scale target of a ScaledObject to 0                                                            |                                                              |
+| `KEDAJobsCreated`                     | `Normal`  | When KEDA creates jobs for a ScaledJob                                                                                      |                                                                                       |
+| `TriggerAuthenticationAdded`          | `Normal`  | When a new TriggerAuthentication is added                                                                                   |                                                                                     |
+| `TriggerAuthenticationDeleted`        | `Normal`  | When a TriggerAuthentication is deleted                                                                                     |                                                                                       |
+| `ClusterTriggerAuthenticationAdded`   | `Normal`  | When a new ClusterTriggerAuthentication is added                                                                            |                                                                              |
+| `ClusterTriggerAuthenticationDeleted` | `Normal`  | When a ClusterTriggerAuthentication is deleted                                                                              |                                                                                |
diff --git a/content/docs/2.15/faq.md → content/docs/2.14/reference/faq.md b/content/docs/2.15/faq.md → content/docs/2.14/reference/faq.md
@@ -1,5 +1,6 @@
 +++
 title = "FAQ"
+weight = 2000
 +++
 
 {{< faq20 >}}
diff --git a/content/docs/2.14/reference/glossary.md b/content/docs/2.14/reference/glossary.md
@@ -0,0 +1,88 @@
++++
+title = "Glossary"
+weight = 1000
++++
+
+This document defines the various terms needed to understand the documentation and set up and use KEDA.
+
+## Admission Webhook
+
+[In Kubernetes](https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/), an HTTP callback that handle admission requests. KEDA uses an admission webhook to validate and mutate ScaledObject resources.
+
+## Agent
+
+A primary role held by the KEDA operator. The Agent activates and deactivates Kubernetes Deployments to scale to and from zero.
+
+## Cluster
+
+[In Kubernetes](https://kubernetes.io/docs/reference/glossary/?fundamental=true#term-cluster), a set of one or more nodes that run containerized applications.
+
+## CRD 
+
+Custom Resource Definition. [In Kubernetes](https://kubernetes.io/docs/reference/glossary/?fundamental=true#term-CustomResourceDefinition), a custom resource that extends the Kubernetes API with custom resources like ScaledObjects that have custom fields and behavior.
+
+## Event
+
+A notable occurrence captured by an event source that KEDA may use as a trigger to scale a container or deployment.
+
+## Event Source
+
+An external system like Kafka, RabbitMQ, that generates events that KEDA can monitor using a scaler.
+
+## Grafana
+
+An open-source monitoring platform that can visualize metrics collected by KEDA.
+
+## GRPC
+
+Go Remote Procedure Call. An open-source remote procedure call framework used by KEDA components to communicate.
+
+## HPA 
+
+Horizontal Pod Autoscaler. Kubernetes autoscaler. By default, scales based on CPU/memory usage. KEDA uses HPA to scale Kubernetes clusters and deployments.
+
+## KEDA 
+
+Kubernetes Event-Driven Autoscaling. A single-purpose, lightweight autoscaler that can scale a Kubernetes workload based on event metrics.
+
+## Metric
+
+Measurement of an event source such as queue length or response lag that KEDA uses to determine scaling.
+
+## OpenTelemetry 
+
+An observability framework used by KEDA to instrument applications and collect metrics.
+
+## Operator
+
+The core KEDA component that monitors metrics and scales workloads accordingly.
+
+## Prometheus
+
+An open-source monitoring system that can scrape and store metrics from KEDA.
+
+## Scaled Object
+
+A custom resource that defines how KEDA should scale a workload based on events.
+
+## Scaled Job
+
+A custom resource KEDA uses to scale an application.
+
+## Scaler
+
+A component that integrates KEDA with a specific event source to collect metrics.
+
+## Stateful Set
+
+A Kubernetes workload with persistent data. KEDA can scale stateful sets.
+
+## TLS
+
+Transport Layer Security. KEDA uses TLS to encrypt communications between KEDA components.
+
+## Webhook
+
+An HTTP callback used to notify KEDA of events from external sources.
+
+[In Kubernetes](https://kubernetes.io/docs/reference/access-authn-authz/webhook/), an HTTP callback used as an event notification mechanism.