diff --git a/assets/images/storageexplorer.png b/assets/images/storageexplorer.png new file mode 100644 index 000000000..8d1443779 Binary files /dev/null and b/assets/images/storageexplorer.png differ diff --git a/content/docs/2.14/_index.md b/content/docs/2.14/_index.md index a3c18da2f..f8f62fcde 100644 --- a/content/docs/2.14/_index.md +++ b/content/docs/2.14/_index.md @@ -1,5 +1,5 @@ +++ -title = "The KEDA Documentation" +title = "Getting Started" weight = 1 +++ diff --git a/content/docs/2.14/deploy.md b/content/docs/2.14/deploy.md index 2465fd436..102957071 100644 --- a/content/docs/2.14/deploy.md +++ b/content/docs/2.14/deploy.md @@ -8,12 +8,25 @@ We provide a few approaches to deploy KEDA runtime in your Kubernetes clusters: - [Operator Hub](#operatorhub) - [YAML declarations](#yaml) -> 💡 **NOTE:** KEDA requires Kubernetes cluster version 1.27 and higher +**Prerequisites** + +Before installing KEDA, ensure you have the following prerequisites: + +- [Kubernetes cluster version 1.27 or higher](https://kubernetes.io/docs/setup/) +- [`kubectl`](https://kubernetes.io/docs/tasks/tools/) configured to connect to the Kubernetes cluster +- For Helm installation: + - [Helm v3](https://helm.sh/docs/intro/install/) installed on your machine +- For Operator Hub installation: + - Access to the [Operator Hub](https://operatorhub.io/) in your Kubernetes cluster +- For YAML installation: + - No additional prerequisites Don't see what you need? Feel free to [create an issue](https://github.com/kedacore/keda/issues/new) on our GitHub repo. ## Deploying with Helm {#helm} +Using [Helm Charts](https://helm.sh/) is the recommended method for most users. Helm simplifies the installation process and makes it easier to manage and upgrade KEDA. Helm handles deploying all the necessary components, including Custom Resource Definitions (CRDs). + ### Install Deploying KEDA with Helm is very simple: @@ -68,6 +81,9 @@ done ## Deploying with Operator Hub {#operatorhub} + +This method utilizes the Operator Hub, a centralized repository for Kubernetes Operators. An Operator extends the functionality of Kubernetes. With this approach, you install the KEDA Operator from the Operator Hub and then create a `KedaController` resource to manage the deployment of KEDA components. + ### Install 1. On Operator Hub Marketplace locate and install KEDA operator to namespace `keda` @@ -81,6 +97,8 @@ Locate installed KEDA Operator in `keda` namespace, then remove created `KedaCon ## Deploying using the deployment YAML files {#yaml} +If Helm or Operator Hub is not available or preferred in your environment, you can deploy KEDA manually by applying YAML files containing the necessary resource definitions. The YAML files are available in the KEDA GitHub releases or can be generated from the KEDA repository. + ### Install If you want to try KEDA on [Minikube](https://minikube.sigs.k8s.io) or a different Kubernetes deployment without using Helm you can still deploy it with `kubectl`. diff --git a/content/docs/2.14/hellokeda.md b/content/docs/2.14/hellokeda.md new file mode 100644 index 000000000..43249b12c --- /dev/null +++ b/content/docs/2.14/hellokeda.md @@ -0,0 +1,215 @@ ++++ +title = "Hello, KEDA" ++++ + +## Hello, KEDA + +This guide will help you create an Azure Function that triggers on new messages in an Azure Storage Queue. You’ll also learn how to deploy it to Kubernetes with KEDA for event-driven activation and scaling. + +## What You'll Need + +- [Azure Function Core Tools v3](https://github.com/azure/azure-functions-core-tools#installing) (version > 3.0.3216) +- An Azure Subscription ([get a free account](http://azure.com/free)) +- A Kubernetes cluster (e.g., [AKS](https://docs.microsoft.com/en-us/azure/aks/kubernetes-walkthrough-portal), GKE, EKS, OpenShift) with [`kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/), be sure to [enable Virtual Nodes](https://docs.microsoft.com/en-us/azure/aks/virtual-nodes-portal) at create. +- Docker and a Docker registry + +## Step-by-Step Guide + +1. **Create a new directory for the function app** + +```sh +mkdir hello-keda +cd hello-keda +``` + +2. **Initialize the Directory for Functions** + +```sh +func init . --docker +``` + +Select **node** and **JavaScript**. + +3. **Add a New Queue Triggered Function** + +```sh +func new +``` + +Select **Azure Queue Storage Trigger** and use the default name `QueueTrigger`. + +> 💡 **NOTE:** You can use the [Azure CLI](https://docs.microsoft.com/cli/azure/install-azure-cli?view=azure-cli-latest), the [Azure cloud shell](https://shell.azure.com), or [the Azure portal](https://docs.microsoft.com/azure/storage/common/storage-quickstart-create-account#create-a-storage-account-1). The following is how you do it using Azure CLI. + +4. **Create an Azure Storage Queue:** Create a storage account and a queue named `js-queue-items`. Replace `` with a unique name for your storage account. + +```sh +az group create -l westus -n hello-keda +az storage account create --sku Standard_LRS --location westus -g hello-keda -n + +CONNECTION_STRING=$(az storage account show-connection-string --name --query connectionString -o tsv) + +az storage queue create -n js-queue-items --connection-string $CONNECTION_STRING +``` + +5. **Update Function Settings with Storage Account Info**: Open the `hello-keda` directory in an editor. We'll need to update the connection string info for the queue trigger, and make sure the queue trigger capabilities are installed. + +Copy the current storage account connection string (HINT: don't include the `"`) + +```sh +az storage account show-connection-string --name --query connectionString +``` + +Open `local.settings.json` and replace `{AzureWebJobsStorage}` with your connection string: + +**local.settings.json** +```json +{ + "IsEncrypted": false, + "Values": { + "FUNCTIONS_WORKER_RUNTIME": "node", + "AzureWebJobsStorage": "DefaultEndpointsProtocol=https;EndpointSuffix=core.windows.net;AccountName=mystorageaccount;AccountKey=shhhh===" + } +} +``` + +Open `QueueTrigger/function.json` and set the `connection` value to `AzureWebJobsStorage`: + +**function.json** +```json +{ + "bindings": [ + { + "name": "myQueueItem", + "type": "queueTrigger", + "direction": "in", + "queueName": "js-queue-items", + "connection": "AzureWebJobsStorage" + } + ] +} +``` + +6. **Enable Storage Queue Support**: Update `host.json` to include the storage queue extension bundle: + +**host.json** +```json +{ + "version": "2.0", + "extensionBundle": { + "id": "Microsoft.Azure.Functions.ExtensionBundle", + "version": "[1.*, 2.0.0)" + } +} +``` + +7. **Test Your Function Locally (Optional)**: Start your function locally: + +```sh +func start +``` + +Use the Azure Portal’s Storage Explorer to add a message to the `js-queue-items` queue. Your function should process the message and display the output in the console. + +```cli +[5/1/19 6:00:53 AM] Executing 'Functions.QueueTrigger' (Reason='New queue message detected on 'js-queue-items'.', Id=2beeca56-4c7a-4af9-b15a-86d896d55a92) +[5/1/19 6:00:53 AM] Trigger Details: MessageId: 60c80a55-e941-4f78-bb93-a1ef006c3dc5, DequeueCount: 1, InsertionTime: 5/1/19 6:00:53 AM +00:00 +[5/1/19 6:00:53 AM] JavaScript queue trigger function processed work item Hello KEDA +[5/1/19 6:00:53 AM] Executed 'Functions.QueueTrigger' (Succeeded, Id=2beeca56-4c7a-4af9-b15a-86d896d55a92) +``` + +8. **Install KEDA:** Follow the [KEDA installation guide](/deploy.md) to deploy KEDA to your Kubernetes cluster. Confirm KEDA is installed by running: + +```sh +kubectl get customresourcedefinition +``` + +You should see `scaledobjects.keda.sh` and `scaledjobs.keda.sh`. + +**9a. Deploy Your Function App to Kubernetes with KEDA (Standard):** Log in to Docker: + +```sh +docker login +``` + +Make sure you have created a private repo in docker.io to which your container image will be pushed. Then deploy your function to Kubernetes: + +```sh +func kubernetes deploy --name hello-keda --registry +``` + +This will build the docker container, push it to the specified registry, and deploy it to Kubernetes. You can see the actual generated deployment with the `--dry-run` flag. + + +9b. **Deploy Your Function App to Kubernetes with KEDA (Virtual Nodes)**: To deploy your function Kubernetes with Azure Virtual Nodes, you need to modify the details of the deployment to allow the selection of virtual nodes. + +Generate a deployment yaml for the function. + +```sh +func kubernetes deploy --name hello-keda --registry --javascript --dry-run > deploy.yaml +``` + +Modify `deploy.yaml` to allow scheduling on virtual nodes: + +```yaml +spec: + containers: + - name: hello-keda + image: /hello-keda + env: + - name: AzureFunctionsJobHost__functions__0 + value: QueueTrigger + envFrom: + - secretRef: + name: hello-keda + tolerations: + - operator: Exists +``` + +Build and deploy your container image: + +```sh +docker build -t /hello-keda . +docker push /hello-keda + +kubectl apply -f deploy.yaml +``` + +10. **Verify Your Function Scales with KEDA**:Initially, you should see 0 pods: + +```sh +kubectl get deploy +``` + +Add a queue message to the queue (using the Storage Explorer shown in step 7 above). KEDA will detect the event and add a pod. By default the polling interval set is 30 seconds on the `ScaledObject` resource, so it may take up to 30 seconds for the queue message to be detected and activate your function. This can be [adjusted on the `ScaledObject` resource](https://github.com/kedacore/keda/wiki/ScaledObject-spec). + +```sh +kubectl get pods -w +``` + +The queue message will be consumed. You can validate the message was consumed by using `kubectl logs` on the activated pod. New queue messages will be consumed and if enough queue messages are added the function will autoscale. After all messages are consumed and the cooldown period has elapsed (default 300 seconds), the last pod should scale back down to zero. + +## Cleaning Up + +#### Delete the Function Deployment + +```sh +kubectl delete deploy hello-keda +kubectl delete ScaledObject hello-keda +kubectl delete Secret hello-keda +``` + +#### Delete the Storage Account + +```sh +az storage account delete --name +``` + +#### Uninstall KEDA + +```sh +func kubernetes remove --namespace keda +``` + +## Source Code + +You can find the source code for this tutorial on KEDA’s GitHub: [sample-hello-world-azure-functions](https://github.com/kedacore/sample-hello-world-azure-functions). diff --git a/content/docs/2.15/deploy.md b/content/docs/2.15/deploy.md index 4e78035e4..f3c3157ff 100644 --- a/content/docs/2.15/deploy.md +++ b/content/docs/2.15/deploy.md @@ -8,12 +8,25 @@ We provide a few approaches to deploy KEDA runtime in your Kubernetes clusters: - Operator Hub - YAML declarations -> 💡 **NOTE:** KEDA requires Kubernetes cluster version 1.27 and higher +**Prerequisites** + +Before installing KEDA, ensure you have the following prerequisites: + +- [Kubernetes cluster version 1.27 or higher](https://kubernetes.io/docs/setup/) +- [`kubectl`](https://kubernetes.io/docs/tasks/tools/) configured to connect to the Kubernetes cluster +- For Helm installation: + - [Helm v3](https://helm.sh/docs/intro/install/) installed on your machine +- For Operator Hub installation: + - Access to the [Operator Hub](https://operatorhub.io/) in your Kubernetes cluster +- For YAML installation: + - No additional prerequisites Don't see what you need? Feel free to [create an issue](https://github.com/kedacore/keda/issues/new) on our GitHub repo. ## Deploying with Helm {#helm} +Using [Helm Charts](https://helm.sh/) is the recommended method for most users. Helm simplifies the installation process and makes it easier to manage and upgrade KEDA. Helm handles deploying all the necessary components, including Custom Resource Definitions (CRDs). + ### Install To deploy KEDA with Helm: @@ -68,6 +81,8 @@ done ## Deploying with Operator Hub {#operatorhub} +This method utilizes the Operator Hub, a centralized repository for Kubernetes Operators. An Operator extends the functionality of Kubernetes. With this approach, you install the KEDA Operator from the Operator Hub and then create a `KedaController` resource to manage the deployment of KEDA components. + ### Install 1. On Operator Hub Marketplace locate and install KEDA operator to namespace `keda` @@ -81,6 +96,8 @@ Locate installed KEDA Operator in `keda` namespace, then remove created `KedaCon ## Deploying using the deployment YAML files {#yaml} +If Helm or Operator Hub is not available or preferred in your environment, you can deploy KEDA manually by applying YAML files containing the necessary resource definitions. The YAML files are available in the KEDA GitHub releases or can be generated from the KEDA repository. + ### Install If you want to try KEDA on [Minikube](https://minikube.sigs.k8s.io) or a different Kubernetes deployment without using Helm you can still deploy it with `kubectl`. diff --git a/content/docs/2.15/hellokeda.md b/content/docs/2.15/hellokeda.md new file mode 100644 index 000000000..43249b12c --- /dev/null +++ b/content/docs/2.15/hellokeda.md @@ -0,0 +1,215 @@ ++++ +title = "Hello, KEDA" ++++ + +## Hello, KEDA + +This guide will help you create an Azure Function that triggers on new messages in an Azure Storage Queue. You’ll also learn how to deploy it to Kubernetes with KEDA for event-driven activation and scaling. + +## What You'll Need + +- [Azure Function Core Tools v3](https://github.com/azure/azure-functions-core-tools#installing) (version > 3.0.3216) +- An Azure Subscription ([get a free account](http://azure.com/free)) +- A Kubernetes cluster (e.g., [AKS](https://docs.microsoft.com/en-us/azure/aks/kubernetes-walkthrough-portal), GKE, EKS, OpenShift) with [`kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/), be sure to [enable Virtual Nodes](https://docs.microsoft.com/en-us/azure/aks/virtual-nodes-portal) at create. +- Docker and a Docker registry + +## Step-by-Step Guide + +1. **Create a new directory for the function app** + +```sh +mkdir hello-keda +cd hello-keda +``` + +2. **Initialize the Directory for Functions** + +```sh +func init . --docker +``` + +Select **node** and **JavaScript**. + +3. **Add a New Queue Triggered Function** + +```sh +func new +``` + +Select **Azure Queue Storage Trigger** and use the default name `QueueTrigger`. + +> 💡 **NOTE:** You can use the [Azure CLI](https://docs.microsoft.com/cli/azure/install-azure-cli?view=azure-cli-latest), the [Azure cloud shell](https://shell.azure.com), or [the Azure portal](https://docs.microsoft.com/azure/storage/common/storage-quickstart-create-account#create-a-storage-account-1). The following is how you do it using Azure CLI. + +4. **Create an Azure Storage Queue:** Create a storage account and a queue named `js-queue-items`. Replace `` with a unique name for your storage account. + +```sh +az group create -l westus -n hello-keda +az storage account create --sku Standard_LRS --location westus -g hello-keda -n + +CONNECTION_STRING=$(az storage account show-connection-string --name --query connectionString -o tsv) + +az storage queue create -n js-queue-items --connection-string $CONNECTION_STRING +``` + +5. **Update Function Settings with Storage Account Info**: Open the `hello-keda` directory in an editor. We'll need to update the connection string info for the queue trigger, and make sure the queue trigger capabilities are installed. + +Copy the current storage account connection string (HINT: don't include the `"`) + +```sh +az storage account show-connection-string --name --query connectionString +``` + +Open `local.settings.json` and replace `{AzureWebJobsStorage}` with your connection string: + +**local.settings.json** +```json +{ + "IsEncrypted": false, + "Values": { + "FUNCTIONS_WORKER_RUNTIME": "node", + "AzureWebJobsStorage": "DefaultEndpointsProtocol=https;EndpointSuffix=core.windows.net;AccountName=mystorageaccount;AccountKey=shhhh===" + } +} +``` + +Open `QueueTrigger/function.json` and set the `connection` value to `AzureWebJobsStorage`: + +**function.json** +```json +{ + "bindings": [ + { + "name": "myQueueItem", + "type": "queueTrigger", + "direction": "in", + "queueName": "js-queue-items", + "connection": "AzureWebJobsStorage" + } + ] +} +``` + +6. **Enable Storage Queue Support**: Update `host.json` to include the storage queue extension bundle: + +**host.json** +```json +{ + "version": "2.0", + "extensionBundle": { + "id": "Microsoft.Azure.Functions.ExtensionBundle", + "version": "[1.*, 2.0.0)" + } +} +``` + +7. **Test Your Function Locally (Optional)**: Start your function locally: + +```sh +func start +``` + +Use the Azure Portal’s Storage Explorer to add a message to the `js-queue-items` queue. Your function should process the message and display the output in the console. + +```cli +[5/1/19 6:00:53 AM] Executing 'Functions.QueueTrigger' (Reason='New queue message detected on 'js-queue-items'.', Id=2beeca56-4c7a-4af9-b15a-86d896d55a92) +[5/1/19 6:00:53 AM] Trigger Details: MessageId: 60c80a55-e941-4f78-bb93-a1ef006c3dc5, DequeueCount: 1, InsertionTime: 5/1/19 6:00:53 AM +00:00 +[5/1/19 6:00:53 AM] JavaScript queue trigger function processed work item Hello KEDA +[5/1/19 6:00:53 AM] Executed 'Functions.QueueTrigger' (Succeeded, Id=2beeca56-4c7a-4af9-b15a-86d896d55a92) +``` + +8. **Install KEDA:** Follow the [KEDA installation guide](/deploy.md) to deploy KEDA to your Kubernetes cluster. Confirm KEDA is installed by running: + +```sh +kubectl get customresourcedefinition +``` + +You should see `scaledobjects.keda.sh` and `scaledjobs.keda.sh`. + +**9a. Deploy Your Function App to Kubernetes with KEDA (Standard):** Log in to Docker: + +```sh +docker login +``` + +Make sure you have created a private repo in docker.io to which your container image will be pushed. Then deploy your function to Kubernetes: + +```sh +func kubernetes deploy --name hello-keda --registry +``` + +This will build the docker container, push it to the specified registry, and deploy it to Kubernetes. You can see the actual generated deployment with the `--dry-run` flag. + + +9b. **Deploy Your Function App to Kubernetes with KEDA (Virtual Nodes)**: To deploy your function Kubernetes with Azure Virtual Nodes, you need to modify the details of the deployment to allow the selection of virtual nodes. + +Generate a deployment yaml for the function. + +```sh +func kubernetes deploy --name hello-keda --registry --javascript --dry-run > deploy.yaml +``` + +Modify `deploy.yaml` to allow scheduling on virtual nodes: + +```yaml +spec: + containers: + - name: hello-keda + image: /hello-keda + env: + - name: AzureFunctionsJobHost__functions__0 + value: QueueTrigger + envFrom: + - secretRef: + name: hello-keda + tolerations: + - operator: Exists +``` + +Build and deploy your container image: + +```sh +docker build -t /hello-keda . +docker push /hello-keda + +kubectl apply -f deploy.yaml +``` + +10. **Verify Your Function Scales with KEDA**:Initially, you should see 0 pods: + +```sh +kubectl get deploy +``` + +Add a queue message to the queue (using the Storage Explorer shown in step 7 above). KEDA will detect the event and add a pod. By default the polling interval set is 30 seconds on the `ScaledObject` resource, so it may take up to 30 seconds for the queue message to be detected and activate your function. This can be [adjusted on the `ScaledObject` resource](https://github.com/kedacore/keda/wiki/ScaledObject-spec). + +```sh +kubectl get pods -w +``` + +The queue message will be consumed. You can validate the message was consumed by using `kubectl logs` on the activated pod. New queue messages will be consumed and if enough queue messages are added the function will autoscale. After all messages are consumed and the cooldown period has elapsed (default 300 seconds), the last pod should scale back down to zero. + +## Cleaning Up + +#### Delete the Function Deployment + +```sh +kubectl delete deploy hello-keda +kubectl delete ScaledObject hello-keda +kubectl delete Secret hello-keda +``` + +#### Delete the Storage Account + +```sh +az storage account delete --name +``` + +#### Uninstall KEDA + +```sh +func kubernetes remove --namespace keda +``` + +## Source Code + +You can find the source code for this tutorial on KEDA’s GitHub: [sample-hello-world-azure-functions](https://github.com/kedacore/sample-hello-world-azure-functions).