Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Prepare docs for 2.14 #1290

Merged
merged 5 commits into from
Jan 19, 2024
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
copy 2.13 to 2.14
$ cp -rf content/docs/2.13 content/docs/2.14

Signed-off-by: Jan Wozniak <[email protected]>
  • Loading branch information
wozniakjan committed Jan 19, 2024
commit ed2f0183de2ee21ffdf245810b87cbbbb418b173
8 changes: 8 additions & 0 deletions content/docs/2.14/_index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
+++
title = "The KEDA Documentation"
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.

Additions and contributions to these docs are managed on [the keda-docs GitHub repo](https://github.com/kedacore/keda-docs).
8 changes: 8 additions & 0 deletions content/docs/2.14/authentication-providers/_index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
+++
title = "Authentication Providers"
weight = 5
+++

Available authentication providers for KEDA:

{{< authentication-providers >}}
14 changes: 14 additions & 0 deletions content/docs/2.14/authentication-providers/aws-eks.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
+++
title = "AWS EKS Pod Identity Webhook"
+++

[**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.

> ⚠️ **WARNING:** [`aws-eks` auth has been deprecated](https://github.com/kedacore/keda/discussions/5343) and support for it will be removed from KEDA on v3. We strongly encourage the migration to [`aws` auth](./aws.md).

You can tell KEDA to use EKS Pod Identity Webhook via `podIdentity.provider`.

```yaml
podIdentity:
provider: aws-eks # Optional. Default: none
```
14 changes: 14 additions & 0 deletions content/docs/2.14/authentication-providers/aws-kiam.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
+++
title = "AWS Kiam Pod Identity"
+++

[**Kiam**](https://github.com/uswitch/kiam/) lets you bind an AWS IAM Role to a pod using an annotation on the pod.

> ⚠️ **WARNING:** `aws-kiam` auth has been deprecated given [AWS KIAM is no longer maintained](https://github.com/uswitch/kiam/#-%EF%B8%8Fthis-project-is-now-being-abandoned-%EF%B8%8F-). As a result, [support for it will be removed from KEDA on v2.15](https://github.com/kedacore/keda/discussions/5342). We strongly encourage the migration to [`aws` auth](./aws.md).

You can tell KEDA to use Kiam via `podIdentity.provider`.

```yaml
podIdentity:
provider: aws-kiam # Optional. Default: none
```
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
+++
title = "AWS Secret Manager"
+++

You can integrate AWS Secret Manager secrets into your trigger by configuring the `awsSecretManager` key in your KEDA scaling specification.

The `podIdentity` section configures the usage of AWS pod identity with the provider set to AWS.

The `credentials` section specifies AWS credentials, including the `accessKey` and `secretAccessKey`.

- **accessKey:** Configuration for the AWS access key.
- **secretAccessKey:** Configuration for the AWS secret access key.

The `region` parameter is optional and represents the AWS region where the secret resides, defaulting to the default region if not specified.

The `secrets` list within `awsSecretManager` defines the mapping between the AWS Secret Manager secret and the authentication parameter used in your application, including the parameter name, AWS Secret Manager secret name, and an optional version parameter, defaulting to the latest version if unspecified.

### Configuration

```yaml
awsSecretManager:
podIdentity: # Optional.
provider: aws # Required.
credentials: # Optional.
accessKey: # Required.
valueFrom: # Required.
secretKeyRef: # Required.
name: {k8s-secret-with-aws-credentials} # Required.
key: {key-in-k8s-secret} # Required.
accessSecretKey: # Required.
valueFrom: # Required.
secretKeyRef: # Required.
name: {k8s-secret-with-aws-credentials} # Required.
key: {key-in-k8s-secret} # Required.
region: {aws-region} # Optional.
secrets: # Required.
- parameter: {param-name-used-for-auth} # Required.
name: {aws-secret-name} # Required.
version: {aws-secret-version} # Optional.
```
140 changes: 140 additions & 0 deletions content/docs/2.14/authentication-providers/aws.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,140 @@
+++
title = "AWS (IRSA) Pod Identity Webhook"
+++

[**AWS IAM Roles for Service Accounts (IRSA) Pod Identity Webhook**](https://github.com/aws/amazon-eks-pod-identity-webhook) ([documentation](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.

You can tell KEDA to use AWS Pod Identity Webhook via `podIdentity.provider`.

```yaml
podIdentity:
provider: aws
roleArn: <role-arn> # Optional.
identityOwner: keda|workload # Optional. If not set, 'keda' is default value. Mutually exclusive with 'roleArn' (if set)
```

**Parameter list:**

- `roleArn` - Role ARN to be used by KEDA. If not set the IAM role which the KEDA operator uses will be used. Mutually exclusive with `identityOwner: workload`
- `identityOwner` - Owner of the identity to be used. (Values: `keda`, `workload`, Default: `keda`, Optional)

> ⚠️ **NOTE:** `podIdentity.roleArn` and `podIdentity.identityOwner` are mutually exclusive, setting both is not supported.

## How to use

AWS IRSA will give access to pods with service accounts having appropriate annotations. ([official docs](https://aws.amazon.com/es/blogs/opensource/introducing-fine-grained-iam-roles-service-accounts/)) You can set these annotations on the KEDA Operator service account.

This can be done for you during deployment with Helm with the following flags:

1. `--set podIdentity.aws.irsa.enabled=true`
2. `--set podIdentity.aws.irsa.roleArn={aws-arn-role}`

You can override the default KEDA operator IAM role by specifying an `roleArn` parameter under the `podIdentity` field. This allows end-users to use different roles to access various resources which allows for more granular access than having a single IAM role that has access to multiple resources.

If you would like to use the same IAM credentials as your workload is currently using, `podIdentity.identityOwner` can be set with the value `workload` and KEDA will inspect the workload service account to check if IRSA annotation is there and KEDA will assume that role.

## 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.

## 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:

```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "sqs:GetQueueAttributes",
"Resource": "arn:aws:sqs:*:YOUR_ACCOUNT:YOUR_QUEUE"
}
]
}
```

### Using KEDA role to assume workload role using AssumeRoleWithWebIdentity
In this case, KEDA will use its own (k8s) service account to assume workload role (and to use workload's role attached policies). This scenario requires that KEDA service account is trusted for requesting the role using AssumeRoleWithWebIdentity.

This is an example of how role policy could look like:

```json
{
"Version": "2012-10-17",
"Statement": [
{
... YOUR WORKLOAD TRUSTED RELATION ...
},
{
"Effect": "Allow",
"Principal": {
"Federated": "YOUR_OIDC_ARN"
},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {
"StringEquals": {
"YOUR_OIDC:sub": "system:serviceaccount:keda:keda-operator",
"YOUR_OIDC:aud": "sts.amazonaws.com"
}
}
}
]
}
```

### Using KEDA role to assume workload role using AssumeRole

In this case, KEDA will use its own role to assume the workload role (and to use workload's role attached policies). This scenario is a bit more complex because we need to establish a trusted relationship between both roles and we need to grant to KEDA's role the permission to assume other roles.

This is an example of how KEDA's role policy could look like:

```json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": [
"arn:aws:iam::ACCOUNT_1:role/ROLE_NAME"
]
},
{
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": [
"arn:aws:iam::ACCOUNT_2:role/*"
]
}
]
}
```
This can be extended so that KEDA can assume multiple workload roles, either as an explicit array of role ARNs, or with a wildcard.
This policy attached to KEDA's role will allow KEDA to assume other roles, now you have to allow the workload roles you want to use all allow to being assumed by the KEDA operator role. To achieve this, you have to add a trusted relation to the workload role:

```json
{
"Version": "2012-10-17",
"Statement": [
{
// Your already existing relations
"Sid": "",
"Effect": "Allow",
// ...
},
{
"Sid": "",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::ACCOUNT:role/KEDA_ROLE_NAME"
},
"Action": "sts:AssumeRole"
}
]
}
```
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
+++
title = "Azure AD Pod Identity"
+++

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*.

> ⚠️ **WARNING:** [Azure AD Pod Identity was archived](https://github.com/Azure/aad-pod-identity#-announcement) and support for it will be removed from KEDA on v2.15. We strongly encourage the migration to [Azure Workload Identity](https://azure.github.io/azure-workload-identity).

You can tell KEDA to use Azure AD Pod Identity via `podIdentity.provider`.

```yaml
podIdentity:
provider: azure # Optional. Default: none
identityId: <identity-id> # Optional. Default: Identity linked with the label set when installing KEDA.
```

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}`.

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.
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
+++
title = "Azure AD Workload Identity"
+++

[**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
[**Azure AD Application**](https://docs.microsoft.com/en-us/azure/active-directory/develop/app-objects-and-service-principals)
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*.

You can tell KEDA to use Azure AD Workload Identity via `podIdentity.provider`.

```yaml
podIdentity:
provider: azure-workload # Optional. Default: none
identityId: <identity-id> # Optional. Default: ClientId From annotation on service-account.
```

Azure AD Workload Identity will give access to pods with service accounts having appropriate labels and annotations. Refer
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
following flags -

1. `--set podIdentity.azureWorkload.enabled=true`
2. `--set podIdentity.azureWorkload.clientId={azure-ad-client-id}`
3. `--set podIdentity.azureWorkload.tenantId={azure-ad-tenant-id}`

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.

## Considerations about Federations and Overrides

The concept of "overrides" can be somewhat confusing in certain scenarios, as it may not always be clear which service account needs to be federated with a specific Azure identity to ensure proper functionality.

Let's clarify this with two examples:

### Case 1

Imagine you have an identity for KEDA that has access to ServiceBus A, ServiceBus B, and ServiceBus C. Additionally, you have separate identities for various workloads, resulting in the following setup:

- KEDA's identity with access to ServiceBus A, ServiceBus B, and ServiceBus C (the identity set during installation and not overridden).
- Workload A's identity with access to Service Bus A.
- Workload B's identity with access to Service Bus B.
- Workload C's identity with access to Service Bus C.

In this case, KEDA's Managed Service Identity should only be federated with KEDA's service account.

### Case 2

To avoid granting too many permissions to KEDA's identity, you have a KEDA identity without access to any Service Bus (perhaps unrelated, such as Key Vault). Similar to the previous scenario, you also have separate identities for your workloads:

- KEDA's identity without access to any Service Bus.
- Workload A's identity with access to Service Bus A.
- Workload B's identity with access to Service Bus B.
- Workload C's identity with access to Service Bus C.

In this case, you are overriding the default identity set during installation through the "TriggerAuthentication" option (`.spec.podIdentity.identityId`). Each "ScaledObject" now uses its own "TriggerAuthentication," with each specifying an override (Workload A's TriggerAuthentication sets the identityId for Workload A, Workload B's for Workload B, and so on). Consequently, you don't need to stack excessive permissions on KEDA's identity. However, in this scenario, KEDA's service account must be federated with all the identities it may attempt to assume:

- TriggerAuthentications without overrides will use KEDA's identity (for tasks such as accessing the Key Vault).
- TriggerAuthentications with overrides will use the identity specified in the TriggerAuthentication (requiring KEDA's service account to be federated with them).
41 changes: 41 additions & 0 deletions content/docs/2.14/authentication-providers/azure-key-vault.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
+++
title = "Azure Key Vault secret"
+++


You can pull secrets from Azure Key Vault into the trigger by using the `azureKeyVault` key.

The `secrets` list defines the mapping between the key vault secret and the authentication parameter.

Currently, `azure` and `azure-workload` pod identity providers are supported for Azure Key Vault using `podIdentity` inside `azureKeyVault`.

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.

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).

The `cloud` parameter can be used to specify cloud environments besides `Azure Public Cloud`, such as known Azure clouds like
`Azure China Cloud`, etc. and even Azure Stack Hub or Air Gapped clouds.

```yaml
azureKeyVault: # Optional.
vaultUri: {key-vault-address} # Required.
podIdentity: # Optional.
provider: azure | azure-workload # Required.
identityId: <identity-id> # Optional
credentials: # Optional.
clientId: {azure-ad-client-id} # Required.
clientSecret: # Required.
valueFrom: # Required.
secretKeyRef: # Required.
name: {k8s-secret-with-azure-ad-secret} # Required.
key: {key-within-the-secret} # Required.
tenantId: {azure-ad-tenant-id} # Required.
cloud: # Optional.
type: AzurePublicCloud | AzureUSGovernmentCloud | AzureChinaCloud | AzureGermanCloud | Private # Required.
keyVaultResourceURL: {key-vault-resource-url-for-cloud} # Required when type = Private.
activeDirectoryEndpoint: {active-directory-endpoint-for-cloud} # Required when type = Private.
secrets: # Required.
- parameter: {param-name-used-for-auth} # Required.
name: {key-vault-secret-name} # Required.
version: {key-vault-secret-version} # Optional.
```
14 changes: 14 additions & 0 deletions content/docs/2.14/authentication-providers/configmap.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
+++
title = "Config Map"
+++

You can pull information into the trigger by defining the `name` of the Kubernetes `ConfigMap` and the `key` to use.

```yaml
configMapTargetRef: # Optional.
- parameter: connectionString # Required - Defined by the scale trigger
name: my-keda-configmap-resource-name # Required.
key: azure-storage-connectionstring # Required.
```

**Assumptions:** `namespace` is in the same resource as referenced by `scaleTargetRef.name` in the `ScaledObject`, unless specified otherwise.
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
+++
title = "Environment variable"
+++

You can pull information via one or more environment variables by providing the `name` of the variable for a given `containerName`.

```yaml
env: # Optional.
- parameter: region # Required - Defined by the scale trigger
name: my-env-var # Required.
containerName: my-container # Optional. Default: scaleTargetRef.envSourceContainerName of ScaledObject
```

**Assumptions:** `containerName` is in the same resource as referenced by `scaleTargetRef.name` in the ScaledObject, unless specified otherwise.
Loading