Skip to content

Commit e40e726

Browse files
tomkerkhovetomkerkhove
authored
feat: Ship KEDA v2.12 docs (kedacore#1233)
1 parent accd230 commit e40e726

File tree

96 files changed

+13183
-1
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

96 files changed

+13183
-1
lines changed

‎config.toml

+1-1
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ alpine_js_version = "2.2.1"
2929
favicon = "favicon.png"
3030

3131
[params.versions]
32-
docs = ["2.11", "2.10", "2.9", "2.8", "2.7", "2.6", "2.5", "2.4", "2.3", "2.2", "2.1", "2.0", "1.5", "1.4"]
32+
docs = ["2.12", "2.11", "2.10", "2.9", "2.8", "2.7", "2.6", "2.5", "2.4", "2.3", "2.2", "2.1", "2.0", "1.5", "1.4"]
3333

3434
# Site fonts. For more options see https://fonts.google.com.
3535
[[params.fonts]]

‎content/docs/2.13/_index.md

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
+++
2+
title = "The KEDA Documentation"
3+
weight = 1
4+
+++
5+
6+
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.
7+
8+
Additions and contributions to these docs are managed on [the keda-docs GitHub repo](https://github.com/kedacore/keda-docs).

‎content/docs/2.13/authentication-providers/_index.md

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
+++
2+
title = "Authentication Providers"
3+
weight = 5
4+
+++
5+
6+
Available authentication providers for KEDA:
7+
8+
{{< authentication-providers >}}

‎content/docs/2.13/authentication-providers/aws-eks.md

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
+++
2+
title = "EKS Pod Identity Webhook for AWS"
3+
+++
4+
5+
[**EKS Pod Identity Webhook**](https://github.com/aws/amazon-eks-pod-identity-webhook), which is described more in depth [here](https://aws.amazon.com/blogs/opensource/introducing-fine-grained-iam-roles-service-accounts/), allows you to provide the role name using an annotation on a service account associated with your pod.
6+
7+
You can tell KEDA to use EKS Pod Identity Webhook via `podIdentity.provider`.
8+
9+
```yaml
10+
podIdentity:
11+
provider: aws-eks # Optional. Default: none
12+
```

‎content/docs/2.13/authentication-providers/aws-kiam.md

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
+++
2+
title = "Kiam Pod Identity for AWS"
3+
+++
4+
5+
[**Kiam**](https://github.com/uswitch/kiam/) lets you bind an AWS IAM Role to a pod using an annotation on the pod.
6+
7+
You can tell KEDA to use Kiam via `podIdentity.provider`.
8+
9+
```yaml
10+
podIdentity:
11+
provider: aws-kiam # Optional. Default: none
12+
```

‎content/docs/2.13/authentication-providers/azure-ad-pod-identity.md

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
+++
2+
title = "Azure AD Pod Identity"
3+
+++
4+
5+
Azure Pod Identity is an implementation of [**Azure AD Pod Identity**](https://github.com/Azure/aad-pod-identity) which lets you bind an [**Azure Managed Identity**](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/) to a Pod in a Kubernetes cluster as delegated access - *Don't manage secrets, let Azure AD do the hard work*.
6+
7+
You can tell KEDA to use Azure AD Pod Identity via `podIdentity.provider`.
8+
9+
```yaml
10+
podIdentity:
11+
provider: azure # Optional. Default: none
12+
identityId: <identity-id> # Optional. Default: Identity linked with the label set when installing KEDA.
13+
```
14+
15+
Azure AD Pod Identity will give access to containers with a defined label for `aadpodidbinding`. You can set this label on the KEDA operator deployment. This can be done for you during deployment with Helm with `--set podIdentity.activeDirectory.identity={your-label-name}`.
16+
17+
You can override the identity that was assigned to KEDA during installation, by specifying an `identityId` parameter under the `podIdentity` field. This allows end-users to use different identities to access various resources which is more secure than using a single identity that has access to multiple resources.

‎content/docs/2.13/authentication-providers/azure-ad-workload-identity.md

+25
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
+++
2+
title = "Azure AD Workload Identity"
3+
+++
4+
5+
[**Azure AD Workload Identity**](https://github.com/Azure/azure-workload-identity) is the newer version of [**Azure AD Pod Identity**](https://github.com/Azure/aad-pod-identity). It lets your Kubernetes workloads access Azure resources using an
6+
[**Azure AD Application**](https://docs.microsoft.com/en-us/azure/active-directory/develop/app-objects-and-service-principals)
7+
without having to specify secrets, using [federated identity credentials](https://azure.github.io/azure-workload-identity/docs/topics/federated-identity-credential.html) - *Don't manage secrets, let Azure AD do the hard work*.
8+
9+
You can tell KEDA to use Azure AD Workload Identity via `podIdentity.provider`.
10+
11+
```yaml
12+
podIdentity:
13+
provider: azure-workload # Optional. Default: none
14+
identityId: <identity-id> # Optional. Default: ClientId From annotation on service-account.
15+
```
16+
17+
Azure AD Workload Identity will give access to pods with service accounts having appropriate labels and annotations. Refer
18+
to these [docs](https://azure.github.io/azure-workload-identity/docs/topics/service-account-labels-and-annotations.html) for more information. You can set these labels and annotations on the KEDA Operator service account. This can be done for you during deployment with Helm with the
19+
following flags -
20+
21+
1. `--set podIdentity.azureWorkload.enabled=true`
22+
2. `--set podIdentity.azureWorkload.clientId={azure-ad-client-id}`
23+
3. `--set podIdentity.azureWorkload.tenantId={azure-ad-tenant-id}`
24+
25+
You can override the identity that was assigned to KEDA during installation, by specifying an `identityId` parameter under the `podIdentity` field. This allows end-users to use different identities to access various resources which is more secure than using a single identity that has access to multiple resources.

‎content/docs/2.13/authentication-providers/azure-key-vault.md

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
+++
2+
title = "Azure Key Vault secret"
3+
+++
4+
5+
6+
You can pull secrets from Azure Key Vault into the trigger by using the `azureKeyVault` key.
7+
8+
The `secrets` list defines the mapping between the key vault secret and the authentication parameter.
9+
10+
Currently, `azure` and `azure-workload` pod identity providers are supported for Azure Key Vault using `podIdentity` inside `azureKeyVault`.
11+
12+
Service principal authentication is also supported, needing to register an [application](https://docs.microsoft.com/en-us/azure/active-directory/develop/app-objects-and-service-principals) with Azure Active Directory and specifying its credentials. The `clientId` and `tenantId` for the application are to be provided as part of the spec. The `clientSecret` for the application is expected to be within a kubernetes secret in the same namespace as the authentication resource.
13+
14+
Ensure that "read secret" permissions have been granted to the Azure AD application on the Azure Key Vault. Learn more in the Azure Key Vault [documentation](https://docs.microsoft.com/en-us/azure/key-vault/general/assign-access-policy?tabs=azure-portal).
15+
16+
The `cloud` parameter can be used to specify cloud environments besides `Azure Public Cloud`, such as known Azure clouds like
17+
`Azure China Cloud`, etc. and even Azure Stack Hub or Air Gapped clouds.
18+
19+
```yaml
20+
azureKeyVault: # Optional.
21+
vaultUri: {key-vault-address} # Required.
22+
podIdentity: # Optional.
23+
provider: azure | azure-workload # Required.
24+
identityId: <identity-id> # Optional
25+
credentials: # Optional.
26+
clientId: {azure-ad-client-id} # Required.
27+
clientSecret: # Required.
28+
valueFrom: # Required.
29+
secretKeyRef: # Required.
30+
name: {k8s-secret-with-azure-ad-secret} # Required.
31+
key: {key-within-the-secret} # Required.
32+
tenantId: {azure-ad-tenant-id} # Required.
33+
cloud: # Optional.
34+
type: AzurePublicCloud | AzureUSGovernmentCloud | AzureChinaCloud | AzureGermanCloud | Private # Required.
35+
keyVaultResourceURL: {key-vault-resource-url-for-cloud} # Required when type = Private.
36+
activeDirectoryEndpoint: {active-directory-endpoint-for-cloud} # Required when type = Private.
37+
secrets: # Required.
38+
- parameter: {param-name-used-for-auth} # Required.
39+
name: {key-vault-secret-name} # Required.
40+
version: {key-vault-secret-version} # Optional.
41+
```

‎content/docs/2.13/authentication-providers/environment-variable.md

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
+++
2+
title = "Environment variable"
3+
+++
4+
5+
You can pull information via one or more environment variables by providing the `name` of the variable for a given `containerName`.
6+
7+
```yaml
8+
env: # Optional.
9+
- parameter: region # Required - Defined by the scale trigger
10+
name: my-env-var # Required.
11+
containerName: my-container # Optional. Default: scaleTargetRef.envSourceContainerName of ScaledObject
12+
```
13+
14+
**Assumptions:** `containerName` is in the same resource as referenced by `scaleTargetRef.name` in the ScaledObject, unless specified otherwise.

‎content/docs/2.13/authentication-providers/gcp-workload-identity.md

+69
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
+++
2+
title = "GCP Workload Identity"
3+
+++
4+
5+
[**GCP Workload Identity**](https://cloud.google.com/kubernetes-engine/docs/concepts/workload-identity) allows workloads in your GKE clusters to impersonate Identity and Access Management (IAM) service accounts to access Google Cloud services.
6+
7+
You can tell KEDA to use GCP Workload Identity via `podIdentity.provider`.
8+
9+
```yaml
10+
podIdentity:
11+
provider: gcp # Optional. Default: none
12+
```
13+
### Steps to set up Workload Identity
14+
If you are using podIdentity provider as `gcp`, you need to set up workload identity as below and your GKE cluster must have Workload Identity enabled.
15+
16+
* You need to create a GCP IAM service account with proper permissions to retrive metrics for particular scalers.
17+
18+
```shell
19+
gcloud iam service-accounts create GSA_NAME \
20+
--project=GSA_PROJECT
21+
```
22+
23+
Replace the following: \
24+
GSA_NAME: the name of the new IAM service account.\
25+
GSA_PROJECT: the project ID of the Google Cloud project for your IAM service account.
26+
27+
28+
* Ensure that your IAM service account has the [roles](https://cloud.google.com/iam/docs/understanding-roles) you need. You can grant additional roles using the following command:
29+
30+
```shell
31+
gcloud projects add-iam-policy-binding PROJECT_ID \
32+
--member "serviceAccount:GSA_NAME@GSA_PROJECT.iam.gserviceaccount.com" \
33+
--role "ROLE_NAME"
34+
```
35+
36+
Replace the following:
37+
38+
PROJECT_ID: your Google Cloud project ID. \
39+
GSA_NAME: the name of your IAM service account. \
40+
GSA_PROJECT: the project ID of the Google Cloud project of your IAM service account. \
41+
ROLE_NAME: the IAM role to assign to your service account, like roles/monitoring.viewer.
42+
43+
* Allow the Kubernetes service account to impersonate the IAM service account by adding an IAM policy binding between the two service accounts. This binding allows the Kubernetes service account to act as the IAM service account.
44+
```shell
45+
gcloud iam service-accounts add-iam-policy-binding GSA_NAME@GSA_PROJECT.iam.gserviceaccount.com \
46+
--role roles/iam.workloadIdentityUser \
47+
--member "serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME]"
48+
```
49+
Replace the following:
50+
51+
PROJECT_ID: your Google Cloud project ID. \
52+
GSA_NAME: the name of your IAM service account. \
53+
GSA_PROJECT: the project ID of the Google Cloud project of your IAM service account. \
54+
NAMESPACE: Namespace where keda operator is installed; defaults to `keda` . \
55+
KSA_NAME: Kubernetes service account name of the keda; defaults to `keda-operator` .
56+
* Then you need to annotate the Kubernetes service account with the email address of the IAM service account.
57+
58+
```shell
59+
kubectl annotate serviceaccount keda-operator \
60+
--namespace keda \
61+
iam.gke.io/gcp-service-account=GSA_NAME@GSA_PROJECT.iam.gserviceaccount.com
62+
```
63+
Replace the following: \
64+
65+
GSA_NAME: the name of your IAM service account. \
66+
GSA_PROJECT: the project ID of the Google Cloud project of your IAM service account.
67+
68+
69+
Refer to GCP official [documentation](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity#authenticating_to) for more.

‎content/docs/2.13/authentication-providers/hashicorp-vault.md

+28
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
+++
2+
title = "Hashicorp Vault secret"
3+
+++
4+
5+
6+
You can pull one or more Hashicorp Vault secrets into the trigger by defining the authentication metadata such as Vault `address` and the `authentication` method (token | kubernetes). If you choose kubernetes auth method you should provide `role` and `mount` as well.
7+
`credential` defines the Hashicorp Vault credentials depending on the authentication method, for kubernetes you should provide path to service account token (/var/run/secrets/kubernetes.io/serviceaccount/token) and for token auth method provide the token.
8+
`secrets` list defines the mapping between the path and the key of the secret in Vault to the parameter.
9+
`namespace` may be used to target a given Vault Enterprise namespace.
10+
11+
> Since version `1.5.0` Vault secrets backend **version 2** is supported.
12+
> The support for Vault secrets backend **version 1** was added on version `2.10`.
13+
14+
```yaml
15+
hashiCorpVault: # Optional.
16+
address: {hashicorp-vault-address} # Required.
17+
namespace: {hashicorp-vault-namespace} # Optional. Default is root namespace. Useful for Vault Enterprise
18+
authentication: token | kubernetes # Required.
19+
role: {hashicorp-vault-role} # Optional.
20+
mount: {hashicorp-vault-mount} # Optional.
21+
credential: # Optional.
22+
token: {hashicorp-vault-token} # Optional.
23+
serviceAccount: {path-to-service-account-file} # Optional.
24+
secrets: # Required.
25+
- parameter: {scaledObject-parameter-name} # Required.
26+
key: {hasicorp-vault-secret-key-name} # Required.
27+
path: {hasicorp-vault-secret-path} # Required.
28+
```

‎content/docs/2.13/authentication-providers/secret.md

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
+++
2+
title = "Secret"
3+
+++
4+
5+
You can pull one or more secrets into the trigger by defining the `name` of the Kubernetes Secret and the `key` to use.
6+
7+
```yaml
8+
secretTargetRef: # Optional.
9+
- parameter: connectionString # Required - Defined by the scale trigger
10+
name: my-keda-secret-entity # Required.
11+
key: azure-storage-connectionstring # Required.
12+
```
13+
14+
**Assumptions:** `namespace` is in the same resource as referenced by `scaleTargetRef.name` in the ScaledObject, unless specified otherwise.

‎content/docs/2.13/concepts/_index.md

+49
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
+++
2+
title = "KEDA Concepts"
3+
description = "What KEDA is and how it works"
4+
weight = 1
5+
+++
6+
7+
## What is KEDA?
8+
9+
**KEDA** is a [Kubernetes](https://kubernetes.io)-based Event Driven Autoscaler. With KEDA, you can drive the scaling of any container in Kubernetes based on the number of events needing to be processed.
10+
11+
**KEDA** is a single-purpose and lightweight component that can be added into any Kubernetes cluster. KEDA works alongside standard Kubernetes components like the [Horizontal Pod Autoscaler](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/) and can extend functionality without overwriting or duplication. With KEDA you can explicitly map the apps you want to use event-driven scale, with other apps continuing to function. This makes KEDA a flexible and safe option to run alongside any number of any other Kubernetes applications or frameworks.
12+
13+
## How KEDA works
14+
15+
KEDA performs three key roles within Kubernetes:
16+
17+
1. **Agent** — KEDA activates and deactivates Kubernetes [Deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment) to scale to and from zero on no events. This is one of the primary roles of the `keda-operator` container that runs when you install KEDA.
18+
2. **Metrics** — KEDA acts as a [Kubernetes metrics server](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/#support-for-custom-metrics) that exposes rich event data like queue length or stream lag to the Horizontal Pod Autoscaler to drive scale out. It is up to the Deployment to consume the events directly from the source. This preserves rich event integration and enables gestures like completing or abandoning queue messages to work out of the box. The metric serving is the primary role of the `keda-operator-metrics-apiserver` container that runs when you install KEDA.
19+
3. **Admission Webhooks** - Automatically validate resource changes to prevent misconfiguration and enforce best practices by using an [admission controller](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/). As an example, it will prevent multiple ScaledObjects to target the same scale target.
20+
21+
## Architecture
22+
23+
The diagram below shows how KEDA works in conjunction with the Kubernetes Horizontal Pod Autoscaler, external event sources, and Kubernetes' [etcd](https://etcd.io) data store:
24+
25+
![KEDA architecture](/img/keda-arch.png)
26+
27+
### Event sources and scalers
28+
29+
KEDA has a wide range of [**scalers**](/scalers) that can both detect if a deployment should be activated or deactivated, and feed custom metrics for a specific event source. The following scalers are available:
30+
31+
{{< scalers-compact >}}
32+
33+
### Custom Resources (CRD)
34+
35+
When you install KEDA, it creates four custom resources:
36+
37+
1. `scaledobjects.keda.sh`
38+
1. `scaledjobs.keda.sh`
39+
1. `triggerauthentications.keda.sh`
40+
1. `clustertriggerauthentications.keda.sh`
41+
42+
These custom resources enable you to map an event source (and the authentication to that event source) to a Deployment, StatefulSet, Custom Resource or Job for scaling.
43+
- `ScaledObjects` represent the desired mapping between an event source (e.g. Rabbit MQ) and the Kubernetes Deployment, StatefulSet or any Custom Resource that defines `/scale` subresource.
44+
- `ScaledJobs` represent the mapping between event source and Kubernetes Job.
45+
- `ScaledObject`/`ScaledJob` may also reference a `TriggerAuthentication` or `ClusterTriggerAuthentication` which contains the authentication configuration or secrets to monitor the event source.
46+
47+
## Deploy KEDA
48+
49+
See the [Deployment](../deploy) documentation for instructions on how to deploy KEDA into any cluster using tools like [Helm](../deploy/#helm).

‎content/docs/2.13/concepts/admission-webhooks.md

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
+++
2+
title = "Admission Webhooks"
3+
description = "Automatically validate resource changes to prevent misconfiguration and enforce best practices"
4+
weight = 600
5+
+++
6+
7+
There are some several misconfiguration scenarios that can produce scaling problems in productive workloads, for example: in Kubernetes a single workload should never be scaled by 2 or more HPA because that will produce conflicts and unintended behaviors.
8+
9+
Some errors with data format can be detected during the model validation, but these misconfigurations can't be detected in that step because the model is correct indeed. For trying to avoid those misconfigurations at data plane detecting them early, admission webhooks validate all the incoming (KEDA) resources (new or updated) and reject any resource that doesn't match the rules below.
10+
11+
### Prevention Rules
12+
13+
KEDA will block all incoming changes to `ScaledObject` that don't match these rules:
14+
15+
- The scaled workload (`scaledobject.spec.scaleTargetRef`) is already autoscaled by another other sources (other ScaledObject or HPA).
16+
- CPU and/or Memory trigger are used and the scaled workload doesn't have the requests defined. **This rule doesn't apply to all the workload types, only to `Deployment` and `StatefulSet`.**
17+
- CPU and/or Memory trigger are **the only used triggers** and the ScaledObject defines `minReplicaCount:0`. **This rule doesn't apply to all the workload types, only to `Deployment` and `StatefulSet`.**
18+
19+
KEDA will block all incoming changes to `TriggerAuthentication`/`ClusterTriggerAuthentication` that don't match these rules:
20+
21+
- The specified identity ID for Azure AD Workload Identity and/or Pod Identity is empty. (Default/unset identity ID will be passed through.)
22+
> NOTE: This only applies if the `TriggerAuthentication/ClusterTriggerAuthentication` is overriding the default identityId provided to KEDA during the installation

0 commit comments

Comments
 (0)