docs: keptn Scheduler architecture documentation (keptn#1777)

Signed-off-by: Yash Pimple <[email protected]>
mowies · Aug 26, 2023 · ce96200 · ce96200
1 parent cadb170
commit ce96200
Show file tree

Hide file tree

Showing 2 changed files with 64 additions and 64 deletions.
diff --git a/docs/content/en/docs/concepts/architecture/components/scheduler/_index.md b/docs/content/en/docs/concepts/architecture/components/scheduler/_index.md
@@ -6,11 +6,60 @@ weight: 80
 cascade:
 ---
 
-**Keptn's Lifecycle Scheduler** replaces the
-[Kubernetes scheduler](https://kubernetes.io/docs/concepts/scheduling-eviction/kube-scheduler/)
-to allow users to schedule events and tasks to occur
-at specific times during the application lifecycle.
-The Lifecycle Scheduler can trigger events such as
-deployment, testing, and remediation at specific times or intervals.
-The Keptn Scheduler guarantees that Pods are initiated only after
-the Pre-Deployment checks are completed.
+The **Keptn Scheduler** is an integral component of the Keptn Lifecycle Toolkit that orchestrates
+the deployment process.
+The **Keptn Scheduler** works by registering itself as a Permit plugin within the Kubernetes
+scheduling cycle that ensures that Pods are scheduled to a node until and unless the
+pre-deployment checks have finished successfully.
+This helps to prevent Pods from being scheduled to nodes that are not yet ready for them,
+which can lead to errors and downtime.
+Furthermore, it also allows users to control the deployment of an application based on
+customized rules that can take into consideration more parameters than what the default
+scheduler has (typically CPU and memory values).
+
+The Keptn Scheduler uses the Kubernetes
+[Scheduler Framework](https://kubernetes.io/docs/concepts/scheduling-eviction/scheduling-framework/) and is based on the
+[Scheduler Plugins Repository](https://github.com/kubernetes-sigs/scheduler-plugins/tree/master).
+Additionally it registers itself as a [Permit plugin](https://kubernetes.io/docs/concepts/scheduling-eviction/scheduling-framework/#permit).
+
+## How does the Keptn Scheduler works
+
+Firstly the Mutating Webhook checks for annotations on Pods to see if it is annotated with
+[Keptn specific annotations](https://main.lifecycle.keptn.sh/docs/implementing/integrate/#basic-annotations).
+If the annotations are present, the Webhook assigns the **Keptn Scheduler** to the Pod.
+This ensures that the Keptn Scheduler only gets Pods that have been annotated for it.
+
+If the Pod is annotated with Keptn specific annotations, the Keptn Scheduler retrieves
+the WorkloadInstance CRD that is associated with the Pod.
+The **WorkloadInstance CRD** contains information about the `pre-deployment` checks that
+need to be performed before the Pod can be scheduled.
+
+The Keptn Scheduler then checks the status of the WorkloadInstance CRD to see
+if the `pre-deployment` checks have finished successfully.
+If the pre-deployment checks have finished successfully, the **Keptn Scheduler** allows
+the Pod to be scheduled to a node.
+If the `pre-deployment` checks have not yet finished, the Keptn Scheduler tells Kubernetes to check again later.
+
+It is important to note that the Keptn Scheduler is a plugin to the default Kubernetes scheduler.
+This means that all of the checks that are performed by the default Kubernetes scheduler
+will also be performed by the **Keptn Scheduler**.
+For example, if there is not enough capacity on any node to schedule the Pod,
+the Keptn Scheduler will not be able to schedule it, even if the `pre-deployment`
+checks have finished successfully.
+
+The Keptn Scheduler processes the following information from the WorkloadInstance CRD:
+
+- The name of the pre-deployment checks that need to be performed.
+- The status of the pre-deployment checks.
+- The deadline for the pre-deployment checks to be completed.
+- The Keptn Scheduler checks the status of the `pre-deployment` checks every 10 seconds.
+If the checks have not finished successfully within 5 minutes, the Keptn Scheduler will not allow the Pod to be scheduled.
+
+If all of the `pre-deployment` checks have finished successfully and the deadline has not been reached,
+the Keptn Scheduler allows the Pod to be scheduled.
+If any of the `pre-deployment` checks have not finished successfully or the deadline has
+been reached, the Keptn Scheduler tells Kubernetes to check again later.
+
+Also the Keptn Scheduler will not schedule Pods to nodes that have failed `pre-deployment`
+checks in the past.
+This helps to prevent Pods from being scheduled to nodes that are not ready for them.
diff --git a/scheduler/README.md b/scheduler/README.md
@@ -1,58 +1,9 @@
-# scheduler
+# Scheduler
 
-// TODO(user): Add simple overview of use/purpose
+The **scheduler** is a pivotal component within the
+[Keptn Lifecycle Toolkit](https://main.lifecycle.keptn.sh/) that plays a crucial role in orchestrating the deployment process.
+By ensuring that Pods are scheduled onto nodes only after successful pre-deployment checks,
+the scheduler minimizes errors and downtimes.
 
-## Description
-
-// TODO(user): An in-depth paragraph about your project and overview of use
-
-## Getting Started
-
-You’ll need a Kubernetes cluster v0.24.0 or higher to run against.
-You can use [KIND](https://sigs.k8s.io/kind) to get a
-local cluster for testing, or run against a remote cluster.
-
-> **Note**
-Your controller will automatically use the current context in your kubeconfig file (i.e. whatever
-cluster `kubectl cluster-info` shows).
-
-### Running on the cluster
-
-1. Build and push your image to the location specified by `RELEASE_REGISTRY`:
-
-```sh
-make build-and-push-local RELEASE_REGISTRY=<some-registry>
-```
-
-> **Note**
-Run `make --help` for more information on all potential `make` targets
-
-1. Generate your release manifest
-
-```sh
-make release-manifests RELEASE_REGISTRY=<some-registry>
-```
-
-1. Deploy the scheduler using kubectl:
-
-```sh
-kubectl apply -f ./config/rendered/release.yaml # install the scheduler
-```
-
-### Uninstall
-
-To delete the scheduler:
-
-```sh
-kubectl delete -f ./config/rendered/release.yaml # uninstall the scheduler
-```
-
-## Contributing
-
-// TODO(user): Add detailed information on how you would like others to contribute to this project
-
-### How it works
-
-This project uses the
-Kubernetes [Scheduler Framework](https://kubernetes.io/docs/concepts/scheduling-eviction/scheduling-framework/)
-and is based on the [Scheduler Plugins Repository](https://github.com/kubernetes-sigs/scheduler-plugins/tree/master).
+For detailed information about scheduler's functionality and how it works, please refer to
+the [Keptn Lifecycle Toolkit Scheduler Documentation](https://main.lifecycle.keptn.sh/docs/concepts/architecture/components/scheduler/).