diff --git a/ADOPTERS.md b/ADOPTERS.md index 91280d96..f436b0dd 100644 --- a/ADOPTERS.md +++ b/ADOPTERS.md @@ -1,6 +1,6 @@ -# KEDA HTTP Add-On Adopters +# KEDA HTTP Add-on Adopters -This page contains a list of organizations who are using KEDA's HTTP Add-On in production or at stages of testing. +This page contains a list of organizations who are using KEDA's HTTP Add-on in production or at stages of testing. ## Adopters @@ -12,7 +12,7 @@ This page contains a list of organizations who are using KEDA's HTTP Add-On in p You can easily become an adopter by sending a pull request to this file. -These are the adoption statusses that you can use: +These are the adoption statuses that you can use: - ![production](https://img.shields.io/badge/-production-blue?style=flat) - ![testing](https://img.shields.io/badge/-development%20&%20testing-green?style=flat) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5b264bbe..88c04a2f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -42,36 +42,43 @@ Please find it at [docs/developing.md](./docs/developing.md). ### Pre-requisite: -- A running cluster with Keda installed. +- A running Kubernetes cluster with KEDA installed. - [Mage](https://magefile.org/) - [Helm](https://helm.sh/) -- [k9s](https://github.com/derailed/k9s) +- [k9s](https://github.com/derailed/k9s) (_optional_) - Set the required environment variables explained [here](https://github.com/kedacore/http-add-on/blob/main/docs/developing.md#required-environment-variables). -### Building: +### Building: -- Fork & clone the repo : https://github.com/kedacore/http-add-on.git -- cd http-add-on -- Use Mage to build with : - ``` - mage build: build local binaries - mage dockerBuild: build docker images of the components +- Fork & clone the repo: + ```console + $ git clone https://github.com//http-add-on.git + ``` +- Change into the repo directory: + ```console + $ cd http-add-on + ``` +- Use Mage to build with: + ```console + $ mage build # build local binaries + $ mage dockerBuild # build docker images of the components ``` If the environment variables are not setup , the docker build will fail so remember to export the right variable values. ### Deploying: -Custom KEDA-http-addon as an image +Custom HTTP Add-on as an image - Make your changes in the code -- Build and publish images with your changes, remember to set your environment variables for images as per the registry of your choice and run - ``` +- Build and publish images with your changes, remember to set your environment variables for images as per the registry of your choice and run + ```console $ mage dockerBuild ``` - If you want to deploy with docker or any other registry of your choice then use right address in setting the images. + If you want to deploy with docker or any other registry of your choice then use right address in setting the images. + + There are local clusters with local registries provided, in such cases make sure to use and push your images to its local registry. In the case of MicroK8s, the address is `localhost:32000` and the helm install command would look like the following. - There are local clusters with local registries provided, in such cases make sure to use and push your images to its local registry. In the case of MicroK8s, the address is localhost:32000 and the helm install command would look like the following. -``` +```console $ helm repo add kedacore https://kedacore.github.io/charts $ helm repo update $ helm pull kedacore/keda-add-ons-http --untar --untardir ./charts @@ -82,22 +89,22 @@ $ helm upgrade kedahttp ./charts/keda-add-ons-http \ --set image=localhost:32000/keda-http-operator \ --set images.scaler=localhost:32000/keda-http-scaler \ --set images.interceptor=localhost:32000/keda-http-interceptor -``` - If you want to install the latest build of the HTTP Add on, set version to canary: - ``` +``` + If you want to install the latest build of the HTTP Add-on, set version to `canary`: + ```console $ helm install http-add-on kedacore/keda-add-ons-http --create-namespace --namespace ${NAMESPACE} --set images.tag=canary ``` ### Load testing with k9s: K9s integrates Hey, a CLI tool to benchmark HTTP endpoints similar to AB bench. This preliminary feature currently supports benchmarking port-forwards and services. You can use this feature in load testing as follows: -- Install an application to scale: we used the sample provided for which you have to clone - ``` +- Install an application to scale, we use the provided sample - + ```console $ helm install xkcd ./examples/xkcd -n ${NAMESPACE} ``` -- You'll need to clone the repository to get access to this chart. If you have your own Deployment and Service installed, you can go right to creating an HTTPScaledObject by +- You'll need to clone the repository to get access to this chart. If you have your own Deployment and Service installed, you can go right to creating an HTTPScaledObject. We use the provided sample HTTPScaledObject - ``` - $ kubectl create -n $NAMESPACE -f examples/v0.2.0/httpscaledobject.yaml + $ kubectl create -n $NAMESPACE -f examples/v0.3.0/httpscaledobject.yaml ``` - Testing Your Installation using k9s: ``` @@ -112,7 +119,7 @@ K9s integrates Hey, a CLI tool to benchmark HTTP endpoints similar to AB bench. (e) Enter the port-forward and apply to start a benchmark (f) You can enter the port-forward to see the run stat details and performance. - ``` + ``` >You can customize the benchmark in k9s also. It's explained well in [here](https://k9scli.io/topics/bench/). ## Developer Certificate of Origin: Signing your work @@ -143,7 +150,7 @@ Signed-off-by: Random J Developer Git even has a `-s` command line option to append this automatically to your commit message: -``` +```console $ git commit -s -m 'This is my commit message' ``` @@ -153,10 +160,10 @@ Each Pull Request is checked whether or not commits in a Pull Request do contain No worries - You can easily replay your changes, sign them and force push them! -``` -git checkout -git reset $(git merge-base main ) -git add -A -git commit -sm "one commit on " -git push --force +```console +$ git checkout +$ git reset $(git merge-base main ) +$ git add -A +$ git commit -sm "one commit on " +$ git push --force ``` diff --git a/README.md b/README.md index 1ed43e42..f72966f3 100644 --- a/README.md +++ b/README.md @@ -7,11 +7,11 @@ The KEDA HTTP Add-on allows Kubernetes users to automatically scale their HTTP s | 🚧 **Project status: beta** 🚧| |---------------------------------------------| -| ⚠ The HTTP Add-on currently is in [beta](https://github.com/kedacore/http-add-on/releases/tag/v0.1.0). We can't yet recommend it for production usage because we are still developing and testing it. It may have "rough edges" including missing documentation, bugs and other issues. It is currently provided as-is without support. +| ⚠ The HTTP Add-on currently is in [beta](https://github.com/kedacore/http-add-on/releases/latest). We can't yet recommend it for production usage because we are still developing and testing it. It may have "rough edges" including missing documentation, bugs and other issues. It is currently provided as-is without support. ## HTTP Autoscaling Made Simple -[KEDA](https://github.com/kedacore/keda) provides a reliable and well tested solution to scaling your workloads based on external events. The project supports a wide variety of [scalers](https://keda.sh/docs/2.2/scalers/) - sources of these events, in other words. These scalers are systems that produce precisely measurable events via an API. +[KEDA](https://github.com/kedacore/keda) provides a reliable and well tested solution to scaling your workloads based on external events. The project supports a wide variety of [scalers](https://keda.sh/docs/latest/scalers/) - sources of these events, in other words. These scalers are systems that produce precisely measurable events via an API. KEDA does not, however, include an HTTP-based scaler out of the box for several reasons: @@ -25,13 +25,13 @@ This project, often called KEDA-HTTP, exists to provide that scaling. It is comp ## Adopters - Become a listed KEDA user! -We are always happy to start list users who run KEDA's HTTP Add-On in production or are evaluating it, learn more about it [here](ADOPTERS.md). +We are always happy to start list users who run KEDA's HTTP Add-on in production or are evaluating it, learn more about it [here](ADOPTERS.md). We welcome pull requests to list new adopters. ## Walkthrough -Although this is currently a **beta release** project, we have prepared a walkthrough document that with instructions on getting started for basic usage. +Although this is currently a **beta release** project, we have prepared a walkthrough document with instructions on getting started for basic usage. See that document at [docs/walkthrough.md](./docs/walkthrough.md) diff --git a/RELEASE-PROCESS.md b/RELEASE-PROCESS.md index 8f00e283..f23eacd4 100644 --- a/RELEASE-PROCESS.md +++ b/RELEASE-PROCESS.md @@ -6,7 +6,7 @@ The process of releasing a new version of the KEDA HTTP Add-on involves a few st ## 1: Current and new versions -Please go to the [releases page](https://github.com/kedacore/http-add-on/releases) and observe what the most recent release is. Specifically, note what the _tag_ of the release is. For example, if [version 0.1.0](https://github.com/kedacore/http-add-on/releases/tag/v0.1.0) is the latest release (it is as the time of this writing), the tag for that is `v0.1.0`. +Please go to the [releases page](https://github.com/kedacore/http-add-on/releases) and observe what the most recent release is. Specifically, note what the _tag_ of the release is. For example, if [version 0.3.0](https://github.com/kedacore/http-add-on/releases/tag/v0.3.0) is the latest release (it is as the time of this writing), the tag for that is `v0.3.0`. To determine the new version, follow [SemVer guidelines](https://semver.org). Most releases will increment the PATCH or MINOR version number. @@ -16,7 +16,7 @@ To determine the new version, follow [SemVer guidelines](https://semver.org). Mo The title of the release should be "Version 1.2.3", substituting `1.2.3` with the new version number, and the Git tag should be `v1.2.3`, again substituting `1.2.3` with your new version number. -The release description should be a short to medium length summary of what has changed since the last release. The following link will give you a list of commits made since the `v0.1.0` tag: [github.com/kedacore/http-add-on/compare/v0.1.0...main](https://github.com/kedacore/http-add-on/compare/v0.1.0...main). Replace `v0.1.0` for your appropriate most recent last tag to get the commit list and base your release summary on that list. +The release description should be a short to medium length summary of what has changed since the last release. The following link will give you a list of commits made since the `v0.3.0` tag: [github.com/kedacore/http-add-on/compare/v0.3.0...main](https://github.com/kedacore/http-add-on/compare/v0.3.0...main). Replace `v0.3.0` for your appropriate most recent last tag to get the commit list and base your release summary on that list. After you create the new release, automation in a GitHub action will build and deploy new container images. @@ -44,7 +44,7 @@ images: tag: 1.2.3 ``` ->Note: the container images generated by CI/CD in step 2 will have the same tag as the tag you created in the release, minus the `v` prefix. You can always see what images created by going to the container registry page for the [interceptor](https://github.com/orgs/kedacore/packages/container/package/http-add-on-interceptor), [operator](https://github.com/kedacore/http-add-on/pkgs/container/http-add-on-operator) or [scaler](https://github.com/kedacore/http-add-on/pkgs/container/http-add-on-scaler) +>Note: The container images generated by CI/CD in step 2 will have the same tag as the tag you created in the release, minus the `v` prefix. You can always see what images created by going to the container registry page for the [interceptor](https://github.com/orgs/kedacore/packages/container/package/http-add-on-interceptor), [operator](https://github.com/kedacore/http-add-on/pkgs/container/http-add-on-operator) or [scaler](https://github.com/kedacore/http-add-on/pkgs/container/http-add-on-scaler) Once you've made changes to the chart, here's how to do submit the change to the charts repository: diff --git a/docs/design.md b/docs/design.md index 57daf726..28e93625 100644 --- a/docs/design.md +++ b/docs/design.md @@ -8,7 +8,7 @@ There are three major components in this system. You can find more detail and di - [Operator](../operator) - This component listens for events related to `HTTPScaledObject`s and creates, updates or removes internal machinery as appropriate. - [Interceptor](../interceptor) - This component accepts and routes external HTTP traffic to the appropriate internal application, as appropriate. -- [Scaler](../scaler) - This component tracks the size of the pending HTTP request queue for a given app and reports it to KEDA. It acts as an [external scaler](https://keda.sh/docs/2.1/scalers/external-push/). +- [Scaler](../scaler) - This component tracks the size of the pending HTTP request queue for a given app and reports it to KEDA. It acts as an [external scaler](https://keda.sh/docs/latest/scalers/external-push/). - [KEDA](https://keda.sh) - KEDA acts as the scaler for the user's HTTP application. ## Functionality Areas @@ -35,7 +35,7 @@ The interceptor keeps track of the number of pending HTTP requests - HTTP reques #### The Horizontal Pod Autoscaler -The HTTP Add-on works with the Kubernetes [Horizonal Pod Autoscaler](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/#algorithm-details) (HPA) -- via KEDA itself -- to execute scale-up and scale-down operations (except for scaling between zero and non-zero replicas). The add-on furnishes KEDA with two metrics - the current number of pending requests for a host, and the desired number (called `targetPendingRequests` in the [HTTPScaledObject](./ref/v0.2.0/http_scaled_object.md)). KEDA then sends these metrics to the HPA, which uses them as the `currentMetricValue` and `desiredMetricValue`, respectively, in the [HPA Algorithm](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/#algorithm-details). +The HTTP Add-on works with the Kubernetes [Horizonal Pod Autoscaler](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/#algorithm-details) (HPA) -- via KEDA itself -- to execute scale-up and scale-down operations (except for scaling between zero and non-zero replicas). The add-on furnishes KEDA with two metrics - the current number of pending requests for a host, and the desired number (called `targetPendingRequests` in the [HTTPScaledObject](./ref/v0.3.0/http_scaled_object.md)). KEDA then sends these metrics to the HPA, which uses them as the `currentMetricValue` and `desiredMetricValue`, respectively, in the [HPA Algorithm](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/#algorithm-details). The net effect is that the add-on scales up when your app grows to more pending requests than the `targetPendingRequests` value, and scales down when it has fewer than that value. diff --git a/docs/developing.md b/docs/developing.md index ef8b30e7..30652557 100644 --- a/docs/developing.md +++ b/docs/developing.md @@ -52,9 +52,9 @@ The most useful and common commands from the root directory are listed below. Pl - `mage build`: Builds all the binaries for local testing. - `mage test`: Tests the entire codebase -- `mage dockerbuild`: Builds all docker images +- `mage dockerBuild`: Builds all docker images - Please see the below "Environment Variables" section for more information on this command -- `mage dockerpush`: Pushes all docker images, without building them first +- `mage dockerPush`: Pushes all docker images, without building them first - Please see the below "Environment Variables" section for more information on this command ### In the Operator Directory @@ -88,7 +88,7 @@ We'll also assume that you have set the `$NAMESPACE` environment variable in you To establish one, run the following command in a separate terminal window: -```shell +```console kubectl proxy -p 9898 ``` @@ -98,9 +98,9 @@ kubectl proxy -p 9898 The second way to communicate with these services is almost the opposite as the previous. Instead of bringing the API server to you with `kubectl proxy`, you'll be creating an execution environment closer to the API server. -First, launch a container with an interactive shell in Kubernetes with the following command (substituting your namespace in for `$NAMESPACE`): +First, launch a container with an interactive console in Kubernetes with the following command (substituting your namespace in for `$NAMESPACE`): -```shell +```console kubectl run -it alpine --image=alpine -n $NAMESPACE ``` @@ -119,7 +119,7 @@ The admin server also performs following tasks: Run the following `curl` command to get the running configuration of the interceptor: -```shell +```console curl -L localhost:9898/api/v1/namespaces/$NAMESPACE/services/keda-add-ons-http-interceptor-admin:9090/proxy/config ``` @@ -127,13 +127,13 @@ curl -L localhost:9898/api/v1/namespaces/$NAMESPACE/services/keda-add-ons-http-i To prompt the interceptor to fetch the routing table, then print it out: -```shell +```console curl -L localhost:9898/api/v1/namespaces/$NAMESPACE/services/keda-add-ons-http-interceptor-admin:9090/proxy/routing_ping ``` Or, to just ask the interceptor to print out its routing table: -```shell +```console curl -L localhost:9898/api/v1/namespaces/$NAMESPACE/services/keda-add-ons-http-interceptor-admin:9090/proxy/routing_table ``` @@ -141,7 +141,7 @@ curl -L localhost:9898/api/v1/namespaces/$NAMESPACE/services/keda-add-ons-http-i To fetch the state of an individual interceptor's pending HTTP request queue: -```shell +```console curl -L localhost:9898/api/v1/namespaces/$NAMESPACE/services/keda-add-ons-http-interceptor-admin:9090/proxy/queue ``` @@ -149,7 +149,7 @@ curl -L localhost:9898/api/v1/namespaces/$NAMESPACE/services/keda-add-ons-http-i To fetch the current state of an individual interceptor's deployment queue: -```shell +```console curl -L localhost:9898/api/v1/namespaces/$NAMESPACE/services/keda-add-ons-http-interceptor-admin:9090/proxy/deployments ``` @@ -163,7 +163,7 @@ Like the interceptor, the operator has an admin server that has HTTP endpoints a Run the following `curl` command to get the running configuration of the operator: -```shell +```console curl -L localhost:9898/api/v1/namespaces/$NAMESPACE/services/keda-add-ons-http-operator-admin:9090/proxy/config ``` @@ -173,7 +173,7 @@ The operator has a similar `/routing_table` endpoint as the interceptor. That da Fetch the operator's routing table with the following command: -```shell +```console curl -L localhost:9898/api/v1/namespaces/$NAMESPACE/services/keda-add-ons-http-operator-admin:9090/proxy/routing_table ``` @@ -183,9 +183,9 @@ Like the interceptor, the scaler has an HTTP admin interface against which you c #### Configuration -Run the following `curl` command to get the running configuration of the interceptor: +Run the following `curl` command to get the running configuration of the scaler: -```shell +```console curl -L localhost:9898/api/v1/namespaces/$NAMESPACE/services/keda-add-ons-http-external-scaler:9091/proxy/config ``` @@ -195,12 +195,12 @@ The external scaler fetches pending queue counts from each interceptor in the sy For convenience, the scaler also provides a plain HTTP server from which you can also fetch these metrics. Fetch the queue counts from this HTTP server with the following command: -```shell +```console curl -L localhost:9898/api/v1/namespaces/$NAMESPACE/services/keda-add-ons-http-external-scaler:9091/proxy/queue ``` Alternatively, you can prompt the scaler to fetch counts from all interceptors, aggregate, store, and return counts: -```shell +```console curl -L localhost:9898/api/v1/namespaces/$NAMESPACE/services/keda-add-ons-http-external-scaler:9091/proxy/queue_ping ``` diff --git a/docs/faq.md b/docs/faq.md index e5a60b80..bdbf5404 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,10 +1,10 @@ # KEDA-HTTP Frequently Asked Questions -## Why Does This Project Route HTTP Requests? +## Why does this project route HTTP requests? In order to autoscale a `Deployment`, KEDA-HTTP needs to be involved with routing HTTP requests. However, the project is minimally involved with routing and we're working on ways to get out of the "critical path" of an HTTP request as much as possible. For more information, please see our [scope](./scope.md) document. -## How is this Project Similar or Different from [Osiris](https://github.com/deislabs/osiris)? +## How is this project similar or different from [Osiris](https://github.com/deislabs/osiris)? Osiris and KEDA-HTTP have similar features: @@ -15,26 +15,26 @@ However, Osiris and KEDA-HTTP differ in several ways: - Autoscaling concerns are implemented separately from the application resources - `Service`, `Ingress`, `Deployment` and more in KEDA-HTTP. With Osiris, those concerns are baked into each app resource. - The KEDA-HTTP operator can automatically deploy and configure networking and compute resources necessary for an HTTP application to autoscale. Osiris does not have this functionality. -- Osiris is currently archived in GitHub +- Osiris is currently archived in GitHub. -## How is this Project Similar or Different from [Knative](https://knative.dev/)? +## How is this project similar or different from [Knative](https://knative.dev/)? Knative Serving and KEDA-HTTP both have core support for autoscaling, including scale-to-zero of compute workloads. KEDA-HTTP is focused solely on deploying production-grade autoscaling HTTP applications, while Knative builds in additional functionality: - Pure [event-based workloads](https://knative.dev/docs/eventing/). [KEDA core](https://github.com/kedacore/keda), without KEDA-HTTP, can support such workloads natively. -- Complex deployment strategies like [blue-green](https://knative.dev/docs/serving/samples/blue-green-deployment/) -- Supporting other autoscaling mechanisms beyond the built-in [HPA](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/), such as the [Knative Pod Autoscaler (KPA)](https://knative.dev/docs/serving/autoscaling/autoscaling-concepts/#knative-pod-autoscaler-kpa) +- Complex deployment strategies like [blue-green](https://knative.dev/docs/serving/samples/blue-green-deployment/). +- Supporting other autoscaling mechanisms beyond the built-in [HPA](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/), such as the [Knative Pod Autoscaler (KPA)](https://knative.dev/docs/serving/autoscaling/autoscaling-concepts/#knative-pod-autoscaler-kpa). Additionally, Knative supports a service mesh, while KEDA-HTTP does not out of the box (support for that is forthcoming). -## How is this Project Similar or Different from [OpenFaaS](https://www.openfaas.com/) +## How is this project similar or different from [OpenFaaS](https://www.openfaas.com/) OpenFaaS and KEDA-HTTP both can deploy and autoscale HTTP workloads onto Kubernetes, but they have several important differences that make them suitable for different use cases: -- OpenFaaS requires the use of a CLI to deploy code to production +- OpenFaaS requires the use of a CLI to deploy code to production. - OpenFaaS primarily supports the event-based "functions as a service" pattern. This means: - - You deploy code, in a supported language, to handle an HTTP request and OpenFaaS takes care of serving and invoking your code for you - - You deploy complete containers with your HTTP server process in them to KEDA-HTTP -- You don't need to build a container image to deploy code to OpenFaaS, while you do to deploy to KEDA-HTTP -- OpenFaaS can run either on or off Kubernetes, while KEDA-HTTP is Kubernetes-only -- OpenFaaS requires several additional components when running in Kubernetes, like Prometheus. The documentation refers to this as the [PLONK stack](https://docs.openfaas.com/deployment/#plonk-stack) + - You deploy code, in a supported language, to handle an HTTP request and OpenFaaS takes care of serving and invoking your code for you. + - You deploy complete containers with your HTTP server process in them to KEDA-HTTP. +- You don't need to build a container image to deploy code to OpenFaaS, while you do to deploy to KEDA-HTTP. +- OpenFaaS can run either on or off Kubernetes, while KEDA-HTTP is Kubernetes-only. +- OpenFaaS requires several additional components when running in Kubernetes, like Prometheus. The documentation refers to this as the [PLONK stack](https://docs.openfaas.com/deployment/#plonk-stack). diff --git a/docs/install.md b/docs/install.md index d10d56bd..563c33c9 100644 --- a/docs/install.md +++ b/docs/install.md @@ -5,10 +5,9 @@ The HTTP Add-on is highly modular and, as expected, builds on top of KEDA core. - **Operator** - watches for `ScaledHTTPObject` CRD resources and creates necessary backing Kubernetes resources (e.g. `Deployment`s, `Service`s, `ScaledObject`s, and so forth) - **Scaler** - communicates scaling-related metrics to KEDA. By default, the operator will install this for you as necessary. - **Interceptor** - a cluster-internal proxy that proxies incoming HTTP requests, communicating HTTP queue size metrics to the scaler, and holding requests in a temporary request queue when there are not yet any available app `Pod`s ready to serve. By default, the operator will install this for you as necessary. + >There is [pending work](https://github.com/kedacore/http-add-on/issues/354) that may eventually make this component optional. ->There is [pending work](https://github.com/kedacore/http-add-on/issues/354) that may eventually make this component optional. - -## Before You Start: Cluster-global vs. Namespaced installation +## Before You Start: Cluster-global vs. Namespaced Installation Both KEDA and the HTTP Add-on can be installed in either cluster-global or namespaced mode. In the former case, your `ScaledObject`s and `HTTPScaledObject`s (respectively) can be installed in any namespace, and one installation will detect and process it. In the latter case, you must install your `ScaledObject`s and `HTTPScaledObject`s in a specific namespace. @@ -17,17 +16,17 @@ You have the option of installing KEDA and the HTTP Add-on in either mode, but i Before you install any of these components, you need to install KEDA. Below are simplified instructions for doing so with [Helm](https://helm.sh), but if you need anything more customized, please see the [official KEDA deployment documentation](https://keda.sh/docs/2.0/deploy/). If you need to install Helm, refer to the [installation guide](https://helm.sh/docs/intro/install/). ->This document will rely on environment variables such as `${NAMESPACE}` to indicate a value you should customize and provide to the relevant command. In the below `helm install` command, `${NAMESPACE}` should be the namespace you'd like to install KEDA into. KEDA and the HTTP Add-on provide scaling functionality to only one namespace per installation. +>This document will rely on environment variables such as `${NAMESPACE}` to indicate a value you should customize and provide to the relevant command. In the below `helm install` command, `${NAMESPACE}` should be the namespace you'd like to install KEDA into. ```console -helm repo add kedacore https://kedacore.github.io/charts -helm repo update -helm install keda kedacore/keda --namespace ${NAMESPACE} --create-namespace +$ helm repo add kedacore https://kedacore.github.io/charts +$ helm repo update +$ helm install keda kedacore/keda --namespace ${NAMESPACE} --create-namespace ``` >The above command installs KEDA in cluster-global mode. Add `--set watchNamespace=` to install KEDA in namespaced mode. -## Install via Helm Chart +## Install the Add-on via Helm Chart The Helm chart for this project is within KEDA's default helm repository at [kedacore/charts](http://github.com/kedacore/charts), you can install it by running: @@ -50,7 +49,7 @@ There are a few values that you can pass to the above `helm install` command by >If you want to install the latest build of the HTTP Add-on, set `version` to `canary`: ```console -helm install http-add-on kedacore/keda-add-ons-http --create-namespace --namespace ${NAMESPACE} --set images.tag=canary +$ helm install http-add-on kedacore/keda-add-ons-http --create-namespace --namespace ${NAMESPACE} --set images.tag=canary ``` For an exhaustive list of configuration options, see the official HTTP Add-on chart [values.yaml file](https://github.com/kedacore/charts/blob/master/http-add-on/values.yaml). @@ -59,11 +58,11 @@ For an exhaustive list of configuration options, see the official HTTP Add-on ch Local clusters like [Microk8s](https://microk8s.io/) offer in-cluster image registries. These are popular tools to speed up and ease local development. If you use such a tool for local development, we recommend that you use and push your images to its local registry. When you do, you'll want to set your `images.*` variables to the address of the local registry. In the case of MicroK8s, that address is `localhost:32000` and the `helm install` command would look like the following: -```shell -helm repo add kedacore https://kedacore.github.io/charts -helm repo update -helm pull kedacore/keda-add-ons-http --untar --untardir ./charts -helm upgrade kedahttp ./charts/keda-add-ons-http \ +```console +$ helm repo add kedacore https://kedacore.github.io/charts +$ helm repo update +$ helm pull kedacore/keda-add-ons-http --untar --untardir ./charts +$ helm upgrade kedahttp ./charts/keda-add-ons-http \ --install \ --namespace ${NAMESPACE} \ --create-namespace \ diff --git a/docs/ref/v0.3.0/http_scaled_object.md b/docs/ref/v0.3.0/http_scaled_object.md new file mode 100644 index 00000000..d8ba4185 --- /dev/null +++ b/docs/ref/v0.3.0/http_scaled_object.md @@ -0,0 +1,53 @@ +# The `HTTPScaledObject` + +>This document reflects the specification of the `HTTPScaledObject` resource for the `v0.3.0` version. + +Each `HTTPScaledObject` looks approximately like the below: + +```yaml +kind: HTTPScaledObject +apiVersion: http.keda.sh/v1alpha1 +metadata: + name: xkcd +spec: + host: "myhost.com" + targetPendingRequests: 100 + scaleTargetRef: + deployment: xkcd + service: xkcd + port: 8080 +``` + +This document is a narrated reference guide for the `HTTPScaledObject`, and we'll focus on the `spec` field. + +## `host` + +This is the host to apply this scaling rule to. All incoming requests with this value in their `Host` header will be forwarded to the `Service` and port specified in the below `scaleTargetRef`, and that same `scaleTargetRef`'s `Deployment` will be scaled accordingly. + +## `scaleTargetRef` + +This is the primary and most important part of the `spec` because it describes: + +1. The incoming host to apply this scaling rule to. +2. What `Deployment` to scale. +3. The service to which to route HTTP traffic. + +### `deployment` + +This is the name of the `Deployment` to scale. It must exist in the same namespace as this `HTTPScaledObject` and shouldn't be managed by any other autoscaling system. This means that there should not be any `ScaledObject` already created for this `Deployment`. The HTTP Add-on will manage a `ScaledObject` internally. + +### `service` + +This is the name of the service to route traffic to. The add-on will create autoscaling and routing components that route to this `Service`. It must exist in the same namespace as this `HTTPScaledObject` and should route to the same `Deployment` as you entered in the `deployment` field. + +### `port` + +This is the port to route to on the service that you specified in the `service` field. It should be exposed on the service and should route to a valid `containerPort` on the `Deployment` you gave in the `deployment` field. + +### `targetPendingRequests` + +>Default: 100 + +This is the number of _pending_ (or in-progress) requests that your application needs to have before the HTTP Add-on will scale it. Conversely, if your application has below this number of pending requests, the HTTP add-on will scale it down. + +For example, if you set this field to 100, the HTTP Add-on will scale your app up if it sees that there are 200 in-progress requests. On the other hand, it will scale down if it sees that there are only 20 in-progress requests. Note that it will _never_ scale your app to zero replicas unless there are _no_ requests in-progress. Even if you set this value to a very high number and only have a single in-progress request, your app will still have one replica. diff --git a/docs/scope.md b/docs/scope.md index f54c288c..4e19e916 100644 --- a/docs/scope.md +++ b/docs/scope.md @@ -2,8 +2,8 @@ Running production HTTP servers in Kubernetes is complicated and involves many pieces of infrastructure. The HTTP Add-on (called the "add-on" hereafter) aims to autoscale these HTTP servers, but does not aim to extend beyond that scope. Generally, this project only aims to do two things: -1. Autoscale arbitrary HTTP servers based on the volume of traffic incoming to it, including to zero -2. Route HTTP traffic from a given source to an arbitrary HTTP server, as far as we need to efficiently accomplish (1) +1. Autoscale arbitrary HTTP servers based on the volume of traffic incoming to it, including to zero. +2. Route HTTP traffic from a given source to an arbitrary HTTP server, as far as we need to efficiently accomplish (1). The add-on only provides this functionality to workloads that _opt in_ to it. We provide more detail below. diff --git a/docs/walkthrough.md b/docs/walkthrough.md index d924ac62..1b40d9fe 100644 --- a/docs/walkthrough.md +++ b/docs/walkthrough.md @@ -10,8 +10,8 @@ If you haven't installed KEDA and the HTTP Add-on (this project), please do so f You'll need to install a `Deployment` and `Service` first. You'll tell the add-on to begin scaling it up and down after this step. We've provided a [Helm](https://helm.sh) chart in this repository that you can use to try it out. Use this command to create the resources you need. -```shell -helm install xkcd ./examples/xkcd -n ${NAMESPACE} +```console +$ helm install xkcd ./examples/xkcd -n ${NAMESPACE} ``` You'll need to clone the repository to get access to this chart. If you have your own `Deployment` and `Service` installed, you can go right to creating an `HTTPScaledObject` in the next section. @@ -24,25 +24,25 @@ You'll need to clone the repository to get access to this chart. If you have you You interact with the operator via a CRD called `HTTPScaledObject`. This CRD object instructs interceptors to forward requests for a given host to your app's backing `Service`. To get an example app up and running, read the notes below and then run the subsequent command from the root of this repository. -```shell -kubectl create -n $NAMESPACE -f examples/v0.2.0/httpscaledobject.yaml +```console +$ kubectl create -n $NAMESPACE -f examples/v0.3.0/httpscaledobject.yaml ``` ->If you'd like to learn more about this object, please see the [`HTTPScaledObject` reference](./ref/v0.2.0/http_scaled_object.md). +>If you'd like to learn more about this object, please see the [`HTTPScaledObject` reference](./ref/v0.3.0/http_scaled_object.md). ## Testing Your Installation You've now installed a web application and activated autoscaling by creating an `HTTPScaledObject` for it. For autoscaling to work properly, HTTP traffic needs to route through the `Service` that the add-on has set up. You can use `kubectl port-forward` to quickly test things out: -```shell -kubectl port-forward svc/keda-add-ons-http-interceptor-proxy -n ${NAMESPACE} 8080:80 +```console +$ kubectl port-forward svc/keda-add-ons-http-interceptor-proxy -n ${NAMESPACE} 8080:80 ``` ### Routing to the Right `Service` As said above, you need to route your HTTP traffic to the `Service` that the add-on has created. If you have existing systems - like an ingress controller - you'll need to anticipate the name of these created `Service`s. Each one will be named consistently like so, in the same namespace as the `HTTPScaledObject` and your application (i.e. `$NAMESPACE`): -```shell +```console keda-add-ons-http-interceptor-proxy ``` @@ -56,7 +56,7 @@ While you can access it via the `kubectl port-forward` command above, we recomme First, install the controller using the commands below. These commands use Helm v3. For other installation methods, see the [installation page](https://kubernetes.github.io/ingress-nginx/deploy/). -```shell +```console helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx helm repo update helm install ingress-nginx ingress-nginx/ingress-nginx -n ${NAMESPACE} @@ -74,7 +74,7 @@ Now that you have your application running and your ingress configured, you can Regardless, you can use the below `curl` command to make a request to your application: -```shell +```console curl -H "Host: myhost.com" ```