Skip to content

Commit

Permalink
Added Reference section, Glossary, removed non-inclusive language. (#…
Browse files Browse the repository at this point in the history 
…1389)

Co-authored-by: Dave Welsch <[email protected]>
Co-authored-by: Tom Kerkhove <[email protected]>
Co-authored-by: Nate W <[email protected]>
Co-authored-by: thisisobate <[email protected]>
  • Loading branch information
@dwelsch-esi @tomkerkhove
@nate-double-u @thisisobate
4 people authored Jun 28, 2024
1 parent 09a1763 commit a412049
Show file tree
Hide file tree
Showing 31 changed files with 1,570 additions and 676 deletions.
2 changes: 1 addition & 1 deletion config.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -188,7 +188,7 @@ parent = "docs"
weight = 5

[[menu.docs]]
url = "/docs/faq/"
url = "/docs/reference/faq/"
name = "FAQ"
parent = "docs"
weight = 6
Expand Down
116 changes: 116 additions & 0 deletions content/docs/2.14/operate/cloud-events.md
View file
Original file line number Diff line number Diff line change
@@ -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 |
13 changes: 13 additions & 0 deletions content/docs/2.14/reference/_index.md
View file
Original file line number Diff line number Diff line change
@@ -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)
28 changes: 28 additions & 0 deletions content/docs/2.14/reference/events.md
View file
Original file line number Diff line number Diff line change
@@ -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 | |
1 change: 1 addition & 0 deletions content/docs/2.15/faq.md → content/docs/2.14/reference/faq.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
+++
title = "FAQ"
weight = 2000
+++

{{< faq20 >}}
88 changes: 88 additions & 0 deletions content/docs/2.14/reference/glossary.md
View file
Original file line number Diff line number Diff line change
@@ -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.
Loading

0 comments on commit a412049

Please sign in to comment.