Merge pull request #86 from truefoundry/docs_website

Added config yml for docs website

Author: innoavator

_config.yml

@@ -0,0 +1 @@
+theme: jekyll-theme-midnight

docs/architecture.md

@@ -1,131 +1,48 @@
----
-title: Elasti Architecture
----
+# Elasti Architecture
 
-<!-- START doctoc generated TOC please keep comment here to allow auto update -->
-<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
-**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
 
-- [Elasti Project Documentation](#elasti-project-documentation)
-  - [1. Introduction](#1-introduction)
-    - [Overview](#overview)
-    - [Key Components](#key-components)
-  - [2. Architecture](#2-architecture)
-    - [Flow Description](#flow-description)
-  - [3. Controller](#3-controller)
-  - [4. Resolver](#4-resolver)
-  - [5. Helm Values](#5-helm-values)
+Elasti comprises of two main components: operator and resolver.
 
-<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+- **Controller**: A Kubernetes controller built using kubebuilder. It monitors ElastiService resources and scaled them to 0 or 1 as needed.
+- **Resolver**: A service that intercepts incoming requests for scaled-down services, queues them, and notifies the elasti-controller to scale up the target service.
 
-# Elasti Project Documentation
+## Flow Description
 
-## 1. Introduction
+When we enable Elasti on a service, the service operates in 3 modes:
 
-### Overview
-The Elasti project is designed to enable serverless capability for Kubernetes services by dynamically scaling services based on incoming requests. It comprises two main components: operator and resolver. The elasti-operator manages the scaling of target services, while the resolver intercepts and queues requests when the target service is scaled down to zero replicas.
-
-### Key Components
-- **Operator**: A Kubernetes controller built using kubebuilder. It monitors ElastiService resources and scales target services as needed.
-- **Resolver**: A service that intercepts incoming requests for scaled-down services, queues them, and notifies the elasti-operator to scale up the target service.
+1. **Steady State**: The service is receiving traffic and doesn't need to be scaled down to 0.
+2. **Scale Down to 0**: The service hasn't received any traffic for the configured duration and can be scaled down to 0.
+3. **Scale up from 0**: The service receives traffic again and can be scaled up to the configured minTargetReplicas.
 
 <div align="center">
-<img src="./assets/components.png" width="500px">
+<img src="./assets/architecture/flow.png" width="1000px">
 </div>
 
+### Steady state flow of requests to service
+
+In this mode, all the requests are handled directly by the service pods. The Elasti resolved doesn't come into the picture. Elasti controller keeps polling prometheus with the configured query and check the result with threshold value to see if the service can be scaled down.
 
-## 2. Architecture
 <div align="center">
-<img src="./assets/hld.png" width="1000px">
+<img src="./assets/architecture/1.png" width="1000px">
 </div>
 
-### Flow Description
-
-- **[CRD Created]** The Operator fetches details from the CRD.
-   1. Adds a finalizer to the CRD, ensuring it is only deleted by the Operator for proper cleanup.
-   2. Fetches the `ScaleTargetRef` and initiates a watch on it.
-   3. Adds the CRD details to a `crdDirectory`, caching the details of all CRDs.
-- **[ScaleTargetRef Watch]** When a watch is added to the `ScaleTargetRef`:
-   1. Identifies the kind of target and checks the available ready pods.
-   2. If `replicas == 0` -> Switches to **Proxy Mode**.
-   3. If `replicas > 0` -> Switches to **Serve Mode**.
-   4. Currently, it supports only `deployments` and `rollouts`.
-
-- **When pods scale to 0**
-
-- **[Switch to Proxy Mode]**
-   1. Creates a Private Service for the target service. This allows the resolver to reach the target pod, even when the public service has been modified, as described in the following steps.
-   2. Creates a watch on the public service to monitor changes in ports or selectors.
-   3. Creates a new `EndpointSlice` for the public service to redirect any traffic to the resolver.
-   4. Creates a watch on the resolver to monitor the addition of new pods.
-
-- **[In Proxy Mode]**
-    1. Traffic reaching the target service, which has no pods, is sent to the resolver, capable of handling requests on all endpoints.
-    2. [**In Resolver**]
-       1. Once traffic hits the resolver, it reaches the `handleAnyRequest` handler.
-       2. The host is extracted from the request. If it's a known host, the cache is retrieved from `hostManager`. If not, the service name is extracted from the host and saved in `hostManager`.
-       3. The service name is used to identify the private service.
-       4. Using `operatorRPC`, the controller is informed about the incoming request.
-       5. The request is sent to the `throttler`, which queues the requests. It checks if the pods for the private service are up.
-          1. If yes, a proxy request is made, and the response is sent back.
-          2. If no, the request is re-enqueued, and the check is retried after a configurable time interval (set in the Helm values file).
-       6. If the request is successful, traffic for this host is disabled temporarily (configurable). This prevents new incoming requests to the resolver, as the target is now verified to be up.
-    3. [**In Controller/Operator**]
-       1. ElastiServer processes requests from the resolver, containing the service experiencing traffic.
-       2. Matches the service with the `crdDirectory` entry to retrieve the `ScaleTargetRef`, which is then used to scale the target.
-       3. Evaluates triggers defined in the ElastiService:
-           - If **any** trigger indicates that the service should be scaled up -> Scales to minTargetReplicas
-       4. Once scaled up, switches to **Serve Mode**
-
-- **When pods scale to 1**
-
-- **[Switch to Serve Mode]**
-    1. The Operator stops the informer/watch on the resolver.
-    2. The Operator deletes the `EndpointSlice` pointing to the resolver.
-    3. The system switches to **Serve Mode**.
-- **[In Serve Mode]**
-    1. Traffic hits the gateway, is routed to the target service, then to the target pod, and resolves the request.
-    2. The Operator periodically evaluates triggers defined in the ElastiService.
-    3. If **all** triggers indicate that the service is to be scaled down and cooldownPeriod has elapsed since last scale-up:
-        - Scales down the target service to zero replicas
-        - Switches to **Proxy Mode**
-
-
-## 3. Controller
+### Scale down to 0 when there are no requests
+
+If the query from prometheus returns a value less than the threshold, Elasti will scale down the service to 0. Before it scales to 0, it redirects the requests to be forwarded to the Elasti resolver and then modified the Rollout/deployment to have 0 replicas. It also then pauses Keda (if Keda is being used) to prevent it from scaling the service up since Keda is configured with minReplicas as 1. 
 
 <div align="center">
-<img src="./assets/lld-operator.png" width="1000px">
+<img src="./assets/architecture/2.png" width="1000px">
 </div>
 
-## 4. Resolver
+### Scale up from 0 when the first request arrives.
+
+Since the service is scaled down to 0, all requests will hit the Elasti resolver. When the first request arrives, Elasti will scale up the service to the configured minTargetReplicas. It then resumes Keda to continue autoscaling in case there is a sudden burst of requests. It also changes the service to point to the actual service pods once the pod is up. The requests which came to ElastiResolver are retried till 5 mins and the response is sent back to the client. If the pod takes more than 5 mins to come up, the request is dropped.
 
 <div align="center">
-<img src="./assets/lld-resolver.png" width="800px">
+<img src="./assets/architecture/3.png" width="1000px">
 </div>
 
-## 5. Helm Values
-
-Values you can pass to elastiResolver env.
-```yaml
-
-# HeaderForHost is the header to look for to get the host. X-Envoy-Decorator-Operation is the key for istio
-headerForHost: X-Envoy-Decorator-Operation
-# InitialCapacity is the initial capacity of the semaphore
-initialCapacity: "500"
-maxIdleProxyConns: "100"
-maxIdleProxyConnsPerHost: "500"
-# MaxQueueConcurrency is the maximum number of concurrent requests
-maxQueueConcurrency: "100"
-# OperatorRetryDuration is the duration for which we don't inform the operator
-# about the traffic on the same host
-operatorRetryDuration: "10"
-# QueueRetryDuration is the duration after we retry the requests in queue
-queueRetryDuration: "3"
-# QueueSize is the size of the queue
-queueSize: "50000"
-# ReqTimeout is the timeout for each request
-reqTimeout: "120"
-# TrafficReEnableDuration is the duration for which the traffic is disabled for a host
-# This is also duration for which we don't recheck readiness of the service
-trafficReEnableDuration: "5"
-```
+
+<div align="center">
+<img src="./assets/architecture/4.png" width="1000px">
+</div>

docs/assets/architecture/1.png

@@ -0,0 +1,81 @@
+# Configure ElastiService
+
+To enable scale to 0 on any deployment, we will need to create an ElastiService custom resource for that deployment. 
+
+A ElastiService custom resource has the following structure:
+
+```yaml
+apiVersion: elasti.truefoundry.com/v1alpha1
+kind: ElastiService
+metadata:
+  name: <service-name>
+  namespace: <service-namespace>
+spec:
+  minTargetReplicas: <min-target-replicas>
+  service: <service-name>
+  cooldownPeriod: <cooldown-period>
+  scaleTargetRef:
+    apiVersion: <apiVersion>
+    kind: <kind>
+    name: <deployment-or-rollout-name>
+  triggers:
+  - type: <trigger-type>
+    metadata:
+      <trigger-metadata>
+  autoscaler:
+    name: <autoscaler-object-name>
+    type: <autoscaler-type>
+```
+The key fields to be specified in the spec are:
+
+- `<service-name>`: Replace it with the service you want managed by elasti.
+- `<service-namespace>`: Replace by namespace of the service.
+- `<min-target-replicas>`: Min replicas to bring up when first request arrives.
+- `<scaleTargetRef>`: Reference to the scale target similar to the one used in HorizontalPodAutoscaler.
+- `<kind>`: Replace by `rollouts` or `deployments`
+- `<apiVersion>`: Replace with `argoproj.io/v1alpha1` or `apps/v1`
+- `<deployment-or-rollout-name>`: Replace with name of the rollout or the deployment for the service. This will be scaled up to min-target-replicas when first request comes
+- `cooldownPeriod`: Minimum time (in seconds) to wait after scaling up before considering scale down
+- `triggers`: List of conditions that determine when to scale down (currently supports only Prometheus metrics)
+- `autoscaler`: **Optional** integration with an external autoscaler (HPA/KEDA) if needed
+  - `<autoscaler-type>`: keda
+  - `<autoscaler-object-name>`: Name of the KEDA ScaledObject
+
+
+## Configuration Explanation
+
+The section below explains how are the different configuration options used in Elasti.
+
+### Which service to apply elasti on
+
+This is defined using the `scaleTargetRef` field in the spec. 
+
+- `scaleTargetRef.kind`: should be either be  `deployments` or `rollouts` (in case you are using Argo Rollouts). 
+- `scaleTargetRef.apiVersion` will be `apps/v1` if you are using deployments or `argoproj.io/v1alpha1` in case you are using argo-rollouts. 
+- `scaleTargetRef.name` should exactly match the name of the deployment or rollout. 
+
+### When to scale down the service to 0
+
+This is defined uing the triggers field in the spec. Currently, Elasti supports only one trigger type - `prometheus`. The metadata field of the trigger defines the trigger data. The `query` field is the prometheus query to use for the trigger. The `serverAddress` field is the address of the prometheus server. The `threshold` field is the threshold value to use for the trigger. So we can define a query to check for the number of requests per second and the threshold to be 0. Elasti will check this metric every 30 seconds and if the values is less than 0(`threshold`) it will scale down the service to 0.
+
+An example trigger is as follows:
+
+```
+triggers:
+- type: prometheus
+    metadata:
+    query: sum(rate(nginx_ingress_controller_nginx_process_requests_total[1m])) or vector(0)
+    serverAddress: http://kube-prometheus-stack-prometheus.monitoring.svc.cluster.local:9090
+    threshold: 0.5
+```
+
+Once the service is scaled down to 0, we also need to pause the current autoscaler to make sure it doesn't scale up the service again. While this is not a problem with HPA, Keda will scale up the service again since the min replicas is 1. Hence Elasti needs to know about the Keda scaled object so that it can pause it. This information is provided in the `autoscaler` field of the ElastiService. The autoscaler type supported as of now is only keda. 
+
+- autoscaler.name: Name of the keda scaled object
+- autoscaler.type: keda
+
+### When to scale up the service to 1
+
+As soon as the service is scaled down to 0, Elasti resolved will start accepting requests for that service. On receiving the first request, it will scale up the service to `minTargetReplicas`. Once the pod is up, the new requests are handled by the service pods and do not pass through the elasti-resolver. The requests that came before the pod scaled up are held in memory of the elasti-resolver and are processed once the pod is up.
+
+We can configure the `cooldownPeriod` to specify the minimum time (in seconds) to wait after scaling up before considering scale down.

docs/assets/architecture/2.png

@@ -1,6 +1,6 @@
 # Getting Started
 
-With Elasti, you can easily manage and scale your Kubernetes services by using a proxy mechanism that queues and holds requests for scaled-down services, bringing them up only when needed. Get started by following below steps:
+Get started by following below steps:
 
 ## Prerequisites
 
@@ -12,12 +12,13 @@ With Elasti, you can easily manage and scale your Kubernetes services by using a
 
 ### 1. Install Elasti using helm
 
-Use Helm to install elasti into your Kubernetes cluster. Replace `<release-name>` with your desired release name and `<namespace>` with the Kubernetes namespace you want to use:
+Use Helm to install elasti into your Kubernetes cluster. 
 
 ```bash
 helm install elasti oci://tfy.jfrog.io/tfy-helm/elasti --namespace elasti --create-namespace
 ```
-Check out [values.yaml](./charts/elasti/values.yaml) to see config in the helm value file.
+
+Check out [values.yaml](https://github.com/truefoundry/elasti/blob/main/charts/elasti/values.yaml) to see config in the helm value file.
 
 ### 2. Verify the Installation
 
@@ -78,43 +79,6 @@ This will deploy a httpbin service in the `elasti-demo` namespace.
 ### 6. Define an ElastiService
 
 To configure a service to handle its traffic via elasti, you'll need to create and apply a `ElastiService` custom resource:
-```yaml
-apiVersion: elasti.truefoundry.com/v1alpha1
-kind: ElastiService
-metadata:
-  name: <service-name>-elasti
-  namespace: <service-namespace>
-spec:
-  minTargetReplicas: 1
-  service: <service-name>
-  cooldownPeriod: 300 
-  scaleTargetRef:
-    apiVersion: <api-version>
-    kind: <kind>
-    name: <deployment-or-rollout-name>
-  triggers:
-    - type: <trigger-type>
-      metadata:
-        query: <prometheus-query>
-        serverAddress: <prometheus-server-address>
-        threshold: <threshold>
-  autoscaler:
-    type: <autoscaler-type>
-    name: <autoscaler-object-name>
-```
-
-- `<service-name>`: Replace it with the service you want managed by elasti.
-- `<min-target-replicas>`: Min replicas to bring up when first request arrives.
-- `<service-namespace>`: Replace by namespace of the service.
-- `<scaleTargetRef>`: Reference to the scale target similar to the one used in HorizontalPodAutoscaler.
-- `<kind>`: Replace by `rollouts` or `deployments`
-- `<apiVersion>`: Replace with `argoproj.io/v1alpha1` or `apps/v1`
-- `<deployment-or-rollout-name>`: Replace with name of the rollout or the deployment for the service. This will be scaled up to min-target-replicas when first request comes
-- `cooldownPeriod`: Minimum time (in seconds) to wait after scaling up before considering scale down
-- `triggers`: List of conditions that determine when to scale down (currently supports only Prometheus metrics)
-- `autoscaler`: **Optional** integration with an external autoscaler (HPA/KEDA) if needed
-  - `<autoscaler-type>`: hpa/keda
-  - `<autoscaler-object-name>`: name of the KEDA ScaledObject or HPA HorizontalPodAutoscaler object
 
 Create a file named `httpbin-elasti.yaml` and apply the configuration.
 ```yaml
@@ -170,7 +134,7 @@ curl -v http://localhost:8080/httpbin
 ```
 
 You should see the pods being created and scaled up to 1 replica. A response from the httpbin service should be visible for the curl command.
-The service should be scaled down to 0 replicas if there is no traffic for `cooldownPeriod` seconds.
+The service should be scaled down to 0 replicas if there is no traffic for 5 (`cooldownPeriod` in elastiService) seconds.
 
 ## Uninstall
 

docs/assets/architecture/3.png

@@ -1,14 +1,17 @@
----
-layout: default
----
-
 # Elasti
+Enable Scale to 0 on Kubernetes while using HPA or Keda. 
 
 
-- [Introduction to Elasti](introduction.md)
+- [Introduction](introduction.md)
 - [Getting Started](getting-started.md)
-- [Monitoring Elasti](monitoring.md)
+- [Configure ElastiService](configure-elastiservice.md)
 - [Architecture](architecture.md)
+- [Monitoring Elasti](monitoring.md)
 - [Integrations](integrations.md)
+    - [HPA](integrations.md#hpa) 
+    - [Keda](integrations.md#keda)
 - [Comparisons](comparisons.md)
+    - [Knative](./comparisons.md#)
+    - [OpenFaas](./comparisons.md#openfaas)
+    - [Keda Http Add-on](./comparisons.md#keda-http-add-on)
 - [Development](../DEVELOPMENT.md)