Skip to content

Commit

Permalink
- Added Reference section to table of contents, issue kedacore#1366
Browse files Browse the repository at this point in the history 
  - Moved some content from KEDA concept topics to Reference.
- Added a glossary, issue kedacore#1367
- Removed non-inclusive language, issue kedacore#1373

kedacore#1366
kedacore#1367
kedacore#1373

Umbrella issue for CNCF tech docs recommendations:
kedacore#1361

Signed-off-by: David Welsch <[email protected]>
  • Loading branch information
@dwelsch-esi @nate-double-u
dwelsch-esi authored and nate-double-u committed May 30, 2024
1 parent 6fdd89b commit 3e68d94
Show file tree
Hide file tree
Showing 18 changed files with 705 additions and 555 deletions.
18 changes: 15 additions & 3 deletions content/docs/2.15/_index.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,20 @@
+++
title = "The KEDA Documentation"
title = "Getting Started"
weight = 1
+++

Welcome to the documentation for **KEDA**, the Kubernetes Event-driven Autoscaler. Use the navigation to the left to learn more about how to use KEDA and its components.
Welcome to the documentation for **KEDA**, the Kubernetes Event-driven Autoscaler.

Additions and contributions to these docs are managed on [the keda-docs GitHub repo](https://github.com/kedacore/keda-docs).
Use the navigation bar on the left to learn more about KEDA's architecture and how to deploy and use KEDA.

Where to go
===========

What is your involvement with KEDA?

| Role | Documentation |
| --- | --- |
| User | This documentation is for users who want to deploy KEDA to scale Kubernetes. |
| Core Contributor | To contribute to the core KEDA project see the [KEDA GitHub repo](https://github.com/kedacore/keda). |
| Documentation Contributor | To add or contribute to these docs, or to build and serve the documentation locally, see the [keda-docs GitHub repo](https://github.com/kedacore/keda-docs). |
| Other Contributor | See the [KEDA project on GitHub](https://github.com/kedacore/) for other KEDA repos, including project governance, testing, and external scalers. |
4 changes: 2 additions & 2 deletions content/docs/2.15/authentication-providers/aws.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,15 +35,15 @@ If you would like to use the same IAM credentials as your workload is currently

## AssumeRole or AssumeRoleWithWebIdentity?

This authentication uses automatically both, doing a fallback from [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) to [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) if the first one fails. This extends the capabilities because KEDA doesn't need `sts:AssumeRole` permission if you are already working with [WebIdentities](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html), you just need to add KEDA service account to the trusted relations of the role.
This authentication automatically uses both, falling back from [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html) to [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) if the first one fails. This extends the capabilities because KEDA doesn't need `sts:AssumeRole` permission if you are already working with [WebIdentities](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html); in this case, you can add a KEDA service account to the trusted relations of the role.

## Setting up KEDA role and policy

The [official AWS docs](https://aws.amazon.com/es/blogs/opensource/introducing-fine-grained-iam-roles-service-accounts/) explain how to set up a a basic configuration for an IRSA role. The policy changes depend if you are using the KEDA role (`podIdentity.roleArn` is not set) or workload role (`podIdentity.roleArn` sets a RoleArn or `podIdentity.identityOwner` sets to `workload`).

### Using KEDA role to access infrastructure

This is the easiest case and you just need to attach to KEDA's role the desired policy/policies, granting the access permissions that you want to provide. For example, this could be a policy to use with SQS:
Attach the desired policies to KEDA's role, granting the access permissions that you want to provide. For example, this could be a policy to use with SQS:

```json
{
Expand Down
287 changes: 24 additions & 263 deletions content/docs/2.15/concepts/scaling-deployments.md
View file

Large diffs are not rendered by default.

245 changes: 15 additions & 230 deletions content/docs/2.15/concepts/scaling-jobs.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,10 @@ title = "Scaling Jobs"
weight = 300
+++

This page describes the job scaling behavior of KEDA. See the [Scaled Job specification](../reference/scaledjob-spec.md) for details on how to set the behaviors described below.

## Overview

# Overview

As an alternate to [scaling event-driven code as deployments](../scaling-deployments) you can also run and scale your code as Kubernetes Jobs. The primary reason to consider this option is to handle processing long-running executions. Rather than processing multiple events within a deployment, for each detected event a single Kubernetes Job is scheduled. That job will initialize, pull a single event from the message source, and process to completion and terminate.

Expand All @@ -16,250 +18,33 @@ For example, if you wanted to use KEDA to run a job for each message that lands
1. As additional messages arrive, additional jobs are created. Each job processes a single message to completion.
1. Periodically remove completed/failed job by the `SuccessfulJobsHistoryLimit` and `FailedJobsHistoryLimit.`

## ScaledJob spec

This specification describes the `ScaledJob` custom resource definition which is used to define how KEDA should scale your application and what the triggers are.

[`scaledjob_types.go`](https://github.com/kedacore/keda/blob/main/apis/keda/v1alpha1/scaledjob_types.go)

```yaml
apiVersion: keda.sh/v1alpha1
kind: ScaledJob
metadata:
name: {scaled-job-name}
labels:
my-label: {my-label-value} # Optional. ScaledJob labels are applied to child Jobs
annotations:
autoscaling.keda.sh/paused: true # Optional. Use to pause autoscaling of Jobs
my-annotation: {my-annotation-value} # Optional. ScaledJob annotations are applied to child Jobs
spec:
jobTargetRef:
parallelism: 1 # [max number of desired pods](https://kubernetes.io/docs/concepts/workloads/controllers/job/#controlling-parallelism)
completions: 1 # [desired number of successfully finished pods](https://kubernetes.io/docs/concepts/workloads/controllers/job/#controlling-parallelism)
activeDeadlineSeconds: 600 # Specifies the duration in seconds relative to the startTime that the job may be active before the system tries to terminate it; value must be positive integer
backoffLimit: 6 # Specifies the number of retries before marking this job failed. Defaults to 6
template:
# describes the [job template](https://kubernetes.io/docs/concepts/workloads/controllers/job)
pollingInterval: 30 # Optional. Default: 30 seconds
successfulJobsHistoryLimit: 5 # Optional. Default: 100. How many completed jobs should be kept.
failedJobsHistoryLimit: 5 # Optional. Default: 100. How many failed jobs should be kept.
envSourceContainerName: {container-name} # Optional. Default: .spec.JobTargetRef.template.spec.containers[0]
minReplicaCount: 10 # Optional. Default: 0
maxReplicaCount: 100 # Optional. Default: 100
rolloutStrategy: gradual # Deprecated: Use rollout.strategy instead (see below).
rollout:
strategy: gradual # Optional. Default: default. Which Rollout Strategy KEDA will use.
propagationPolicy: foreground # Optional. Default: background. Kubernetes propagation policy for cleaning up existing jobs during rollout.
scalingStrategy:
strategy: "custom" # Optional. Default: default. Which Scaling Strategy to use.
customScalingQueueLengthDeduction: 1 # Optional. A parameter to optimize custom ScalingStrategy.
customScalingRunningJobPercentage: "0.5" # Optional. A parameter to optimize custom ScalingStrategy.
pendingPodConditions: # Optional. A parameter to calculate pending job count per the specified pod conditions
- "Ready"
- "PodScheduled"
- "AnyOtherCustomPodCondition"
multipleScalersCalculation : "max" # Optional. Default: max. Specifies how to calculate the target metrics when multiple scalers are defined.
triggers:
# {list of triggers to create jobs}
```

You can find all supported triggers [here](../scalers).

## Details

```yaml
jobTargetRef:
parallelism: 1 # Optional. Max number of desired instances ([docs](https://kubernetes.io/docs/concepts/workloads/controllers/job/#controlling-parallelism))
completions: 1 # Optional. Desired number of successfully finished instances ([docs](https://kubernetes.io/docs/concepts/workloads/controllers/job/#controlling-parallelism))
activeDeadlineSeconds: 600 # Optional. Specifies the duration in seconds relative to the startTime that the job may be active before the system tries to terminate it; value must be positive integer
backoffLimit: 6 # Optional. Specifies the number of retries before marking this job failed. Defaults to 6
```
The `jobTargetRef` is a batch/v1 `JobSpec` object; refer to the Kubernetes API for [more details](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/job-v1/#JobSpec) about the fields. The `template` field is required.

---

```yaml
pollingInterval: 30 # Optional. Default: 30 seconds
```

This is the interval to check each trigger on. By default, KEDA will check each trigger source on every ScaledJob every 30 seconds.

---

```yaml
successfulJobsHistoryLimit: 5 # Optional. Default: 100. How many completed jobs should be kept.
failedJobsHistoryLimit: 5 # Optional. Default: 100. How many failed jobs should be kept.
```

The `successfulJobsHistoryLimit` and `failedJobsHistoryLimit` fields are optional. These fields specify how many completed and failed jobs should be kept. By default, they are set to 100.

This concept is similar to [Jobs History Limits](https://kubernetes.io/docs/tasks/job/automated-tasks-with-cron-jobs/#jobs-history-limits) allowing you to learn what the outcomes of your jobs are.

The actual number of jobs could exceed the limit in a short time. However, it is going to resolve in the cleanup period. Currently, the cleanup period is the same as the Polling interval.

---


```yaml
envSourceContainerName: {container-name} # Optional. Default: .spec.JobTargetRef.template.spec.containers[0]
```

This optional property specifies the name of container in the Job, from which KEDA should try to get environment properties holding secrets etc. If it is not defined it, KEDA will try to get environment properties from the first Container, ie. from `.spec.JobTargetRef.template.spec.containers[0]`.

___
```yaml
minReplicaCount: 10 # Optional. Default: 0
```

The min number of jobs that is created by default. This can be useful to avoid bootstrapping time of new jobs. If minReplicaCount is greater than maxReplicaCount, minReplicaCount will be set to maxReplicaCount.

New messages may create new jobs - within the limits imposed by maxReplicaCount - in order to reach the state where minReplicaCount jobs are always running. For example, if one sets minReplicaCount to 2 then there will be 2 jobs running permanently. Using a targetValue of 1, if 3 new messages are sent, 2 of those messages will be processed on the already running jobs but another 3 jobs will be created in order to fulfill the desired state dictated by the minReplicaCount parameter that is set to 2.
___

---

```yaml
maxReplicaCount: 100 # Optional. Default: 100
```

The max number of pods that is created within a single polling period. If there are running jobs, the number of running jobs will be deducted. This table is an example of the scaling logic.

| Queue Length | Max Replica Count | Target Average Value | Running Job Count | Number of the Scale |
| ------- | ------ | ------- | ------ | ----- |
| 10 | 3 | 1 | 0 | 3 |
| 10 | 3 | 2 | 0 | 3 |
| 10 | 3 | 1 | 1 | 2 |
| 10 | 100 | 1 | 0 | 10 |
| 4 | 3 | 5 | 0 | 1 |

* **Queue Length:** The number of items in the queue.
* **Target Average Value:** The number of messages that will be consumed on a job. It is defined on the scaler side. e.g. `queueLength` on `Azure Storage Queue` scaler.
* **Running Job Count:** How many jobs are running.
* **Number of the Scale:** The number of the job that is created.

---

```yaml
rollout:
strategy: gradual # Optional. Default: default. Which Rollout Strategy KEDA will use.
propagationPolicy: foreground # Optional. Default: background. Kubernetes propagation policy for cleaning up existing jobs during
```

The optional property rollout.strategy specifies the rollout strategy KEDA will use while updating an existing ScaledJob.
Possible values are `default` or `gradual`. \
When using the `default` rolloutStrategy, KEDA will terminate existing Jobs whenever a ScaledJob is being updated. Then, it will recreate those Jobs with the latest specs. The order in which this termination happens can be configured via the rollout.propagationPolicy property. By default, the kubernetes background propagation is used. To change this behavior specify set propagationPolicy to `foreground`. For further information see [Kubernetes Documentation](https://kubernetes.io/docs/tasks/administer-cluster/use-cascading-deletion/#use-foreground-cascading-deletion).
On the `gradual` rolloutStartegy, whenever a ScaledJob is being updated, KEDA will not delete existing Jobs. Only new Jobs will be created with the latest specs.


---

```yaml
scalingStrategy:
strategy: "default" # Optional. Default: default. Which Scaling Strategy to use.
```

Select a Scaling Strategy. Possible values are `default`, `custom`, or `accurate`. The default value is `default`.
# Pausing autoscaling

> 💡 **NOTE:**
>
>`maxScale` is not the running Job count. It is measured as follows:
>```go
>maxScale = min(scaledJob.MaxReplicaCount(), divideWithCeil(queueLength, targetAverageValue))
>```
>That means it will use the value of `queueLength` divided by `targetAvarageValue` unless it is exceeding the `MaxReplicaCount`.
>
>`RunningJobCount` represents the number of jobs that are currently running or have not finished yet.
>
>It is measured as follows:
>```go
>if !e.isJobFinished(&job) {
> runningJobs++
>}
>```
>`PendingJobCount` provides an indication of the amount of jobs that are in pending state. Pending jobs can be calculated in two ways:
> - Default behavior - Job that have not finished yet **and** the underlying pod is either not running or has not been completed yet
> - Setting `pendingPodConditions` - Job that has not finished yet **and** all specified pod conditions of the underlying pod mark as `true` by kubernetes.
>
>It is measured as follows:
>```go
>if !e.isJobFinished(&job) {
> if len(scaledJob.Spec.ScalingStrategy.PendingPodConditions) > 0 {
> if !e.areAllPendingPodConditionsFulfilled(&job, scaledJob.Spec.ScalingStrategy.PendingPodConditions) {
> pendingJobs++
> }
> } else {
> if !e.isAnyPodRunningOrCompleted(&job) {
> pendingJobs++
> }
> }
>}
>```
It can be useful to instruct KEDA to pause the autoscaling of objects, to do to cluster maintenance or to avoid resource starvation by removing non-mission-critical workloads.

**default**
This logic is the same as Job for V1. The number of the scale will be calculated as follows.
This is preferable to deleting the resource because it removes the instances it is running from operation without touching the applications themselves. When ready, you can then reenable scaling.

_The number of the scale_

```go
maxScale - runningJobCount
```

**custom**
You can customize the default scale logic. You need to configure the following parameters. If you don't configure it, then the strategy will be `default.`
You can pause autoscaling by adding this annotation to your `ScaledJob` definition:

```yaml
customScalingQueueLengthDeduction: 1 # Optional. A parameter to optimize custom ScalingStrategy.
customScalingRunningJobPercentage: "0.5" # Optional. A parameter to optimize custom ScalingStrategy.
```

_The number of the scale_

```go
min(maxScale-int64(*s.CustomScalingQueueLengthDeduction)-int64(float64(runningJobCount)*(*s.CustomScalingRunningJobPercentage)), maxReplicaCount)
```

**accurate**
If the scaler returns `queueLength` (number of items in the queue) that does not include the number of locked messages, this strategy is recommended. `Azure Storage Queue` is one example. You can use this strategy if you delete a message once your app consumes it.

```go
if (maxScale + runningJobCount) > maxReplicaCount {
return maxReplicaCount - runningJobCount
}
return maxScale - pendingJobCount
```
For more details, you can refer to [this PR](https://github.com/kedacore/keda/pull/1227).

---

```yaml
scalingStrategy:
multipleScalersCalculation : "max" # Optional. Default: max. Specifies how to calculate the target metrics (`queueLength` and `maxScale`) when multiple scalers are defined.
metadata:
annotations:
autoscaling.keda.sh/paused: true
```
Select a behavior if you have multiple triggers. Possible values are `max`, `min`, `avg`, or `sum`. The default value is `max`.

* **max:** - Use metrics from the scaler that has the max number of `queueLength`. (default)
* **min:** - Use metrics from the scaler that has the min number of `queueLength`.
* **avg:** - Sum up all the active scalers metrics and divide by the number of active scalers.
* **sum:** - Sum up all the active scalers metrics.
### Pause autoscaling

It can be useful to instruct KEDA to pause the autoscaling of objects, if you want to do to cluster maintenance or you want to avoid resource starvation by removing non-mission-critical workloads.

This is a great alternative to deleting the resource, because we do not want to touch the applications themselves but simply remove the instances it is running from an operational perspective. Once everything is good to go, we can enable it to scale again.

You can enable this by adding the below annotation to your `ScaledJob` definition:
To reenable autoscaling, remove the annotation from the `ScaledJob` definition or set the value to `false`.

```yaml
metadata:
annotations:
autoscaling.keda.sh/paused: true
autoscaling.keda.sh/paused: false
```

The above annotation will pause autoscaling. To enable autoscaling again, simply remove the annotation from the `ScaledJob` definition or set the value to `false`.

# Sample
## Example

An example configuration for autoscaling jobs using a RabbitMQ scaler is given below.

```yaml
apiVersion: v1
Expand Down
6 changes: 3 additions & 3 deletions content/docs/2.15/deploy.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Don't see what you need? Feel free to [create an issue](https://github.com/kedac

### Install

Deploying KEDA with Helm is very simple:
To deploy KEDA with Helm:

1. Add Helm repo

Expand Down Expand Up @@ -147,15 +147,15 @@ VERSION=2.15.0 make undeploy

### Install

If you want to try KEDA v2 on [MicroK8s](https://microk8s.io/) from `1.20` channel, KEDA is included into MicroK8s addons.
If you want to try KEDA v2 on [MicroK8s](https://microk8s.io/) from `1.20` channel, KEDA is included into MicroK8s add-ons.

```sh
microk8s enable keda
```

### Uninstall

To uninstall KEDA in MicroK8s, simply disable the addon as shown below.
To uninstall KEDA in MicroK8s, disable the add-on as shown below.

```sh
microk8s disable keda
Expand Down
4 changes: 2 additions & 2 deletions content/docs/2.15/operate/_index.md
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
+++
title = "Operate"
description = "Guidance & requirements for operating KEDA"
description = "Guidance and requirements for operating KEDA"
weight = 1
+++

We provide guidance & requirements around various areas to operate KEDA:
We provide guidance and requirements around various areas to operate KEDA:

- Admission Webhooks ([link](./admission-webhooks))
- Cluster ([link](./cluster))
Expand Down
Loading

0 comments on commit 3e68d94

Please sign in to comment.