kubedb · Bonusree · Jan 1, 2025 · Jan 30, 2025 · Jan 30, 2025 · Feb 27, 2025
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -67,6 +67,12 @@ jobs:
           kubectl create -f https://github.com/kubedb/installer/raw/master/crds/kubedb-crds.yaml
           kubectl create -f https://github.com/kubernetes-csi/external-snapshotter/raw/master/client/config/crd/snapshot.storage.k8s.io_volumesnapshotclasses.yaml
           kubectl create -f https://github.com/kubestash/installer/raw/master/crds/kubestash-crds.yaml
+          # recommendation
+          kubectl create -f https://github.com/kubeops/supervisor/raw/master/crds/supervisor.appscode.com_approvalpolicies.yaml
+          kubectl create -f https://github.com/kubeops/supervisor/raw/master/crds/supervisor.appscode.com_clustermaintenancewindows.yaml
+          kubectl create -f https://github.com/kubeops/supervisor/raw/master/crds/supervisor.appscode.com_maintenancewindows.yaml
+          kubectl create -f https://github.com/kubeops/supervisor/raw/master/crds/supervisor.appscode.com_recommendations.yaml
+          # gateway
           kubectl create -f https://github.com/appscode-cloud/catalog/raw/master/crds/catalog.appscode.com_mongodbbindings.yaml
           kubectl create -f https://raw.githubusercontent.com/envoyproxy/gateway/refs/heads/main/charts/gateway-helm/charts/crds/crds/generated/gateway.envoyproxy.io_envoyproxies.yaml
           kubectl create -f https://github.com/voyagermesh/installer/raw/master/charts/gateway-api/crds/gateway.networking.k8s.io_gatewayclasses.yaml

diff --git a/docs/README.md b/docs/README.md
@@ -25,6 +25,10 @@ From here you can learn all about KubeDB's architecture and how to deploy and us
 
 - [Guides](/docs/guides/). Guides to show you how to perform tasks with KubeDB.
 
+<<<<<<< om
+- [Operator Manual](/docs/operatormanual/). Guides to show you how to perform tasks with KubeDB.
+=======
+>>>>>>> master
 
 - Detailed exhaustive lists of command-line options, configuration options, API definitions, and procedures. Specially, [CLI](/docs/reference/cli/), [operator](/docs/reference/operator/) & [webhook-server](/docs/reference/webhook-server/).
 

diff --git a/docs/guides/cassandra/quickstart/guide/quickstart.md b/docs/guides/cassandra/quickstart/guide/quickstart.md
@@ -37,7 +37,7 @@ NAME                 STATUS   AGE
 demo                 Active   9s
 ```
 
-> Note: YAML files used in this tutorial are stored in [guides/cassandra/quickstart/overview/yamls](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/guides/cassandra/quickstart/overview/yamls) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs).
+> Note: YAML files used in this tutorial are stored in [guides/cassandra/quickstart](https://github.com/kubedb/docs/tree/{{< param "info.version" >}}/docs/guides/cassandra/quickstart) folder in GitHub repository [kubedb/docs](https://github.com/kubedb/docs).
 
 ## Find Available StorageClass
 

diff --git a/docs/guides/elasticsearch/quickstart/overview/elasticsearch/index.md b/docs/guides/elasticsearch/quickstart/overview/elasticsearch/index.md
@@ -46,9 +46,9 @@ demo                 Active   9s
 We will have to provide `StorageClass` in Elasticsearch CRD specification. Check available `StorageClass` in your cluster using the following command,
 
 ```bash
-$ kubectl get storageclass
-NAME                 PROVISIONER             RECLAIMPOLICY   VOLUMEBINDINGMODE      ALLOWVOLUMEEXPANSION   AGE
-standard (default)   rancher.io/local-path   Delete          WaitForFirstConsumer   false                  14h
+$  kubectl get storageclass
+NAME                   PROVISIONER             RECLAIMPOLICY   VOLUMEBINDINGMODE      ALLOWVOLUMEEXPANSION   AGE
+local-path (default)   rancher.io/local-path   Delete          WaitForFirstConsumer   false                  5d2h
 ```
 
 Here, we have `standard` StorageClass in our cluster from [Local Path Provisioner](https://github.com/rancher/local-path-provisioner).
@@ -63,7 +63,7 @@ NAME                        VERSION   DISTRIBUTION   DB_IMAGE
 kubedb-searchguard-5.6.16   5.6.16    KubeDB         kubedb/elasticsearch:5.6.16-searchguard-v2022.02.22                4h24m
 kubedb-xpack-7.12.0         7.12.0    KubeDB         kubedb/elasticsearch:7.12.0-xpack-v2021.08.23                      4h24m
 kubedb-xpack-7.13.2         7.13.2    KubeDB         kubedb/elasticsearch:7.13.2-xpack-v2021.08.23                      4h24m
-xpack-8.19.9         7.14.0    KubeDB         kubedb/elasticsearch:7.14.0-xpack-v2021.08.23                      4h24m
+xpack-8.19.9                7.14.0    KubeDB         kubedb/elasticsearch:7.14.0-xpack-v2021.08.23                      4h24m
 kubedb-xpack-8.19.9         7.16.2    KubeDB         kubedb/elasticsearch:7.16.2-xpack-v2021.12.24                      4h24m
 kubedb-xpack-7.9.1          7.9.1     KubeDB         kubedb/elasticsearch:7.9.1-xpack-v2021.08.23                       4h24m
 kubedb-xpack-8.2.3          8.2.0     KubeDB         kubedb/elasticsearch:8.2.0-xpack-v2022.05.24                       4h24m
@@ -99,12 +99,12 @@ searchguard-7.0.1-v1        7.0.1     SearchGuard    floragunncom/sg-elasticsear
 searchguard-7.1.1           7.1.1     SearchGuard    floragunncom/sg-elasticsearch:7.1.1-oss-35.0.0                     4h24m
 searchguard-7.1.1-v1        7.1.1     SearchGuard    floragunncom/sg-elasticsearch:7.1.1-oss-35.0.0                     4h24m
 searchguard-7.10.2          7.10.2    SearchGuard    floragunncom/sg-elasticsearch:7.10.2-oss-49.0.0                    4h24m
-xpack-8.19.9          7.14.2    SearchGuard    floragunncom/sg-elasticsearch:7.14.2-52.3.0                        4h24m
+xpack-8.19.9                7.14.2    SearchGuard    floragunncom/sg-elasticsearch:7.14.2-52.3.0                        4h24m
 searchguard-7.3.2           7.3.2     SearchGuard    floragunncom/sg-elasticsearch:7.3.2-oss-37.0.0                     4h24m
 searchguard-7.5.2           7.5.2     SearchGuard    floragunncom/sg-elasticsearch:7.5.2-oss-40.0.0                     4h24m
-xpack-8.19.9        7.5.2     SearchGuard    floragunncom/sg-elasticsearch:7.5.2-oss-40.0.0                     4h24m
+xpack-8.19.9                7.5.2     SearchGuard    floragunncom/sg-elasticsearch:7.5.2-oss-40.0.0                     4h24m
 searchguard-7.8.1           7.8.1     SearchGuard    floragunncom/sg-elasticsearch:7.8.1-oss-43.0.0                     4h24m
-xpack-8.19.9           7.9.3     SearchGuard    floragunncom/sg-elasticsearch:7.9.3-oss-47.1.0                     4h24m
+xpack-8.19.9                7.9.3     SearchGuard    floragunncom/sg-elasticsearch:7.9.3-oss-47.1.0                     4h24m
 xpack-6.8.10-v1             6.8.10    ElasticStack   elasticsearch:6.8.10                                               4h24m
 xpack-6.8.16                6.8.16    ElasticStack   elasticsearch:6.8.16                                               4h24m
 xpack-6.8.22                6.8.22    ElasticStack   elasticsearch:6.8.22                                               4h24m
@@ -123,7 +123,7 @@ xpack-7.5.2-v1              7.5.2     ElasticStack   elasticsearch:7.5.2
 xpack-7.6.2-v1              7.6.2     ElasticStack   elasticsearch:7.6.2                                                4h24m
 xpack-7.7.1-v1              7.7.1     ElasticStack   elasticsearch:7.7.1                                                4h24m
 xpack-7.8.0-v1              7.8.0     ElasticStack   elasticsearch:7.8.0                                                4h24m
-xpack-8.19.9              7.9.1     ElasticStack   elasticsearch:7.9.1                                                4h24m
+xpack-8.19.9                7.9.1     ElasticStack   elasticsearch:7.9.1                                                4h24m
 xpack-7.9.1-v2              7.9.1     ElasticStack   elasticsearch:7.9.1                                                4h24m
 xpack-8.2.3                 8.2.0     ElasticStack   elasticsearch:8.2.0                                                4h24m
 xpack-8.5.2                 8.5.2     ElasticStack   elasticsearch:8.5.2                                                4h24m

diff --git a/docs/guides/elasticsearch/recommendation/index.md b/docs/guides/elasticsearch/recommendation/index.md
@@ -0,0 +1,193 @@
+---
+title: Elasticsearch Recommendation
+menu:
+  docs_{{ .version }}:
+    identifier: es-recommendation-elasticsearch
+    name: Recommendation
+    parent: es-elasticsearch-guides
+    weight: 130
+menu_name: docs_{{ .version }}
+section_menu_id: guides
+---
+
+> New to KubeDB? Please start [here](/docs/README.md).
+
+---
+
+## Elasticsearch Recommendation
+
+### Overview
+
+`Elasticsearch Recommendation` is a Kubernetes Custom Resource Definition (CRD) generated by the KubeDB Ops Manager. It continuously analyzes managed Elasticsearch clusters and produces actionable recommendations for essential maintenance and lifecycle operations.
+
+These recommendations help operators proactively manage their database systems by identifying when to perform tasks such as:
+- Version upgrades  
+- TLS certificate rotation  
+- Authentication credential rotation  
+
+Each recommendation can be reviewed and executed manually or integrated into automated operational workflows, improving overall system reliability, security, and maintainability.
+
+<p align="center">
+  <img alt="Recommendation Lifecycle" src="/docs/operatormanual/recommendation/images/recommendation-generation.png">
+</p>
+
+---
+
+## Prerequisites
+
+Before proceeding, ensure that the following requirements are met:
+
+- A running Kubernetes cluster  
+- `kubectl` configured to communicate with the cluster  
+- A cluster provisioned using tools like [kind](https://kind.sigs.k8s.io/docs/user/quick-start/) (if not already available)  
+
+- KubeDB operator installed following the guide [here](/docs/setup/install/_index.md)  
+
+- Supervisor component enabled during installation:
+```bash
+  --set supervisor.enabled=true
+````
+
+* A dedicated namespace for running examples:
+
+```bash
+$ kubectl create namespace demo
+$ kubectl get namespace
+
+```
+
+## Find Available StorageClass
+
+We will have to provide `StorageClass` in Elasticsearch CRD specification. Check available `StorageClass` in your cluster using the following command,
+
+```bash
+$ kubectl get storageclass
+NAME                   PROVISIONER             RECLAIMPOLICY   VOLUMEBINDINGMODE      ALLOWVOLUMEEXPANSION   AGE
+local-path (default)   rancher.io/local-path   Delete          WaitForFirstConsumer   false                  5d2h
+```
+
+Here, we have `standard` StorageClass in our cluster from [Local Path Provisioner](https://github.com/rancher/local-path-provisioner).
+
+> This document provides a high-level overview with illustrative examples. To fully understand and apply these recommendations in your database, follow the linked guides and the [Recommendation Overview](/docs/operatormanual/recommendation/overview.md)
+---
+
+## Recommendation Types
+
+KubeDB currently supports the following recommendation categories for Elasticsearch:
+
+1. [Version Update Recommendation](/docs/operatormanual/recommendation/version-update-recommendation.md)
+2. [TLS Certificate Rotation Recommendation](/docs/operatormanual/recommendation/rotate-tls-recommendation.md)
+3. [Authentication Secret Rotation Recommendation](/docs/operatormanual/recommendation/rotate-auth-recommendation.md)
+
+These recommendations are generated based on cluster configuration, resource lifecycle, and predefined thresholds.
+
+---
+
+## How Recommendations Are Generated
+
+The recommendation engine evaluates specific fields within the Elasticsearch resource specification and triggers recommendations when defined thresholds are reached. In most cases, recommendations are generated after approximately two-thirds (2/3) of a resource’s lifecycle has elapsed.
+
+---
+
+## Authentication Secret Rotation
+
+```yaml
+apiVersion: kubedb.com/v1
+kind: Elasticsearch
+metadata:
+  name: es-combined
+  namespace: demo
+spec:
+  version: xpack-9.1.9
+  authSecret:
+    kind: secret
+    name: es-auth
+    rotateAfter: 1h
+  replicas: 1
+  storageType: Durable
+  storage:
+    storageClassName: local-path
+    accessModes:
+      - ReadWriteOnce
+    resources:
+      requests:
+        storage: 1Gi
+  deletionPolicy: WipeOut
+```
+
+In this configuration:
+
+* The `rotateAfter` field defines the validity period of the authentication secret
+* A rotation recommendation is generated after approximately **40 minutes** (i.e., 2/3 of 1 hour)
+
+---
+
+## TLS Certificate Rotation
+
+```yaml
+apiVersion: kubedb.com/v1
+kind: Elasticsearch
+metadata:
+  name: es-combined
+  namespace: demo
+spec:
+  version: xpack-9.1.9
+  enableSSL: true
+  tls:
+    issuerRef:
+      apiGroup: cert-manager.io
+      kind: Issuer
+      name: ca-issuer
+    certificates:
+      - alias: client
+        duration: 1h20m
+      - alias: http
+        duration: 2h10m
+  replicas: 1
+  storageType: Durable
+  storage:
+    storageClassName: local-path
+    accessModes:
+      - ReadWriteOnce
+    resources:
+      requests:
+        storage: 1Gi
+  deletionPolicy: WipeOut
+```
+
+In this case:
+
+* Certificate durations define their lifecycle
+* Recommendations are generated after approximately 2/3 of each certificate’s validity period
+* For example, a `1h20m` certificate triggers a recommendation after roughly `54 minutes`
+
+---
+
+## Version Update Recommendation
+
+```yaml
+apiVersion: kubedb.com/v1
+kind: Elasticsearch
+metadata:
+  name: es-combined
+  namespace: demo
+spec:
+  version: xpack-9.1.9
+  enableSSL: true
+  replicas: 1
+  storageType: Durable
+  storage:
+    storageClassName: local-path
+    accessModes:
+      - ReadWriteOnce
+    resources:
+      requests:
+        storage: 1Gi
+  deletionPolicy: WipeOut
+```
+
+For version updates:
+
+* The recommendation engine continuously monitors the running version
+* It suggests upgrades when newer, supported, or more secure versions become available
+
diff --git a/docs/operatormanual/README.md b/docs/operatormanual/README.md
@@ -0,0 +1,14 @@
+---
+title: operatormanual | KubeDB
+menu:
+  docs_{{ .version }}:
+    identifier: operatormanual-readme
+    name: Readme
+    parent: operatormanual
+    weight: -1
+menu_name: docs_{{ .version }}
+section_menu_id: operatormanual
+url: /docs/{{ .version }}/operatormanual/
+aliases:
+  - /docs/{{ .version }}/operatormanual/README/
+---
diff --git a/docs/operatormanual/_index.md b/docs/operatormanual/_index.md
@@ -0,0 +1,11 @@
+---
+title: Operator Manual
+description: KubeDB Operator Manual
+menu:
+  docs_{{ .version }}:
+    identifier: operatormanual
+    name: Operator Manual
+    weight: 2000
+    pre: dropdown
+menu_name: docs_{{ .version }}
+---
diff --git a/docs/operatormanual/recommendation/README.md b/docs/operatormanual/recommendation/README.md
@@ -0,0 +1,12 @@
+---
+menu:
+  docs_{{ .version }}:
+    identifier: readme-recommendation
+    parent: recommendation
+    weight: 10
+menu_name: docs_{{ .version }}
+section_menu_id: operatormanual
+url: /docs/{{ .version }}/operatormanual/recommendation/
+aliases:
+  - /docs/{{ .version }}/operatormanual/recommendation/README/
+---
diff --git a/docs/operatormanual/recommendation/_index.md b/docs/operatormanual/recommendation/_index.md
@@ -0,0 +1,11 @@
+---
+title: Recommendation
+description: Recommendation
+menu:
+  docs_{{ .version }}:
+    identifier: recommendation
+    name: Recommendation
+    weight: 10
+    parent: Operatormanual
+menu_name: docs_{{ .version }}
+---
diff --git a/docs/operatormanual/recommendation/images/recommendation-generation.png b/docs/operatormanual/recommendation/images/recommendation-generation.png
diff --git a/docs/operatormanual/recommendation/overview.md b/docs/operatormanual/recommendation/overview.md
@@ -0,0 +1,34 @@
+---
+title: Recommendation overview
+menu:
+  docs_{{ .version }}:
+    identifier: overview
+    name: Overview
+    parent: operatormanual
+    weight: 10
+menu_name: docs_{{ .version }}
+section_menu_id: 
+---
+
+> New to KubeDB? Please start [here](/docs/README.md).
+
+# Recommendation for KubeDB 
+Databases on Kubernetes in production grade infrastructure often need to go through several administrative operations depending on specific resource requirements. Such operations include vertical scaling (cpu, memory) and storage expansion. Autoscaling support for KubeDB managed databases takes care of it. However, databases also need to go through some maintenance operations in order to ensure security, enhance performance, getting bug fixes and new features etc. Such operations mostly require organization's manual intervention. Even if these operations are automated, they need to be done in surveillance. KubeDB simplifies this by generating K8s Native Recommendations. 
+
+## Overview
+
+Recommendation is a custom resource definition (CRD) object which is created by KubeDB ops-manager controller and managed by supervisor. So, You need to have KubeDB and Supervisor installed first. You can simply install supervisor along with other KubeDB components using `--set supervisor.enabled=true` flag while installing KubeDB via helm chart.
+
+<p align="center">
+<img alt="Recommendation Generation"  src="/docs/operatormanual/recommendation/images/recommendation-generation.png">
+</p>
+
+KubeDB provisioner watches user provided database custom resource spec and creates/sync all the necessary DB resources. Once the Database is ready KubeDB Ops-manager watches the DB and creates Recommendation if it requires. KubeDB Supervisor then watches the Recommendation, updates status of the recommendation, creates recommended operation via OpsRequest if deadline reaches or manually triggered and watches the OpsRequest status to update accordingly in Recommendation custom resource.
+
+KubeDB provides Three types of recommendation for KubeDB Databases:
+1. [Version Update Recommendation](/docs/operatormanual/recommendation/version-update-recommendation.md)
+2. [TLS Certificate Rotation Recommendation](/docs/operatormanual/recommendation/rotate-tls-recommendation.md)
+3. [Authentication Secret Rotation Recommendation](/docs/operatormanual/recommendation/rotate-auth-recommendation.md)
+
+The next page describes these recommendations, how to approve/reject them, their generation mechanism and usability.
+