⬆️ add read replica and rotator documents (#189)

* ⬆️ add read replica and rotator documents Signed-off-by: Kosuke Morimoto <ksk@vdaas.org> * 🤖 auto update stage ⬆️ Signed-off-by: vdaas-ci <ci@vdaas.org> * fix Signed-off-by: Kosuke Morimoto <ksk@vdaas.org> * 🤖 auto update stage ⬆️ Signed-off-by: vdaas-ci <ci@vdaas.org> * fix typo Signed-off-by: Kosuke Morimoto <ksk@vdaas.org> * 🤖 auto update stage ⬆️ Signed-off-by: vdaas-ci <ci@vdaas.org> --------- Signed-off-by: Kosuke Morimoto <ksk@vdaas.org> Signed-off-by: vdaas-ci <ci@vdaas.org> Co-authored-by: vdaas-ci <ci@vdaas.org>
vdaas · May 21, 2024 · 93ea65d · 93ea65d
1 parent 5fd0d70
commit 93ea65d
Show file tree

Hide file tree

Showing 14 changed files with 388 additions and 35 deletions.
diff --git a/VERSIONS/GO_VERSION b/VERSIONS/GO_VERSION
@@ -1 +1 @@
-1.22.2
+1.22.3
diff --git a/content/docs/api/filter-gateway.md b/content/docs/api/filter-gateway.md
@@ -1,6 +1,6 @@
 ---
 title: "Filter Gateway_api"
-date: 2024-04-25T20:33:03+09:00
+date: 2024-05-21T15:09:37+09:00
 draft: false
 weight: 800
 description: How to use CRUD API with filter gateway
@@ -1488,6 +1488,17 @@ service Filter {
     |    id    | string |       | the vector ID                                         |
     | distance | float  |       | the distance between result vector and request vector |
 
+### Status Code
+
+| code | desc.             |
+| :--: | :---------------- |
+|  0   | OK                |
+|  1   | CANCELLED         |
+|  3   | INVALID_ARGUMENT  |
+|  4   | DEADLINE_EXCEEDED |
+|  5   | NOT_FOUND         |
+|  13  | INTERNAL          |
+
 ## MultiSearch RPC
 
 MultiSearch RPC is the method to search objects with multiple objects in **1** request.

diff --git a/content/docs/api/remove.md b/content/docs/api/remove.md
@@ -1,6 +1,6 @@
 ---
 title: "Remove_api"
-date: 2024-04-25T20:33:02+09:00
+date: 2024-05-21T15:09:37+09:00
 draft: false
 weight: 500
 description: Remove indexes from the Vald cluster
@@ -380,7 +380,7 @@ gRPC has a message size limitation.<br>
 Please be careful that the size of the request exceeds the limit.
 </div>
 
-## Input
+### Input
 
 - the scheme of `payload.v1.Remove.MultiRequest`
 

diff --git a/content/docs/api/search.md b/content/docs/api/search.md
@@ -1,6 +1,6 @@
 ---
 title: "Search_api"
-date: 2024-04-25T20:33:02+09:00
+date: 2024-05-21T15:09:37+09:00
 draft: false
 weight: 400
 description: Search ANN vectors from the Vald cluster
@@ -711,7 +711,7 @@ Here are some common reasons and how to resolve each error.
 | NOT_FOUND         | Search result is empty or insufficient to request result length.                                                | Send a request with another vector or set min_num to a smaller value.                    |
 | INTERNAL          | Target Vald cluster or network route has some critical error.                                                   | Check target Vald cluster first and check network route including ingress as second.     |
 
-### MultiSearchByID RPC
+## MultiSearchByID RPC
 
 MultiSearchByID RPC is the method to search vectors with multiple IDs in **1** request.
 
@@ -1496,7 +1496,7 @@ Here are some common reasons and how to resolve each error.
 | NOT_FOUND         | Search result is empty or insufficient to request result length.                                                | Send a request with another vector or set min_num to a smaller value.                    |
 | INTERNAL          | Target Vald cluster or network route has some critical error.                                                   | Check target Vald cluster first and check network route including ingress as second.     |
 
-### MultiLinearSearchByID RPC
+## MultiLinearSearchByID RPC
 
 MultiLinearSearchByID RPC is the method to linear search vectors with multiple IDs in **1** request.
 

diff --git a/content/docs/performance/continuous-benchmark.md b/content/docs/performance/continuous-benchmark.md
diff --git a/content/docs/tutorial/get-started.md b/content/docs/tutorial/get-started.md
@@ -1,6 +1,6 @@
 ---
 title: "Get Started_tutorial"
-date: 2024-04-25T20:33:02+09:00
+date: 2024-05-21T13:22:43+09:00
 draft: false
 weight: 100
 description: Running Vald cluster with NGT Agent on Kubernetes and execute client codes
@@ -46,7 +46,7 @@ If Helm or HDF5 is not installed, please install [Helm](https://helm.sh/docs/int
 <details><summary>Installation command for Helm</summary><br>
 
 ```bash
-curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
+curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
 ```
 
 </details>
@@ -454,8 +454,8 @@ If you are interested, please refer to [SDKs](/docs/user-guides/sdks).<br>
           ```go
           _, err := client.Flush(ctx, &payload.Flush_Request{})
           if err != nil {
-		            glg.Fatal(err)
-		        }
+              glg.Fatal(err)
+          }
           ```
 
             </details>

diff --git a/content/docs/tutorial/vald-agent-standalone-on-k8s.md b/content/docs/tutorial/vald-agent-standalone-on-k8s.md
@@ -1,6 +1,6 @@
 ---
 title: "Vald Agent Standalone on K8s_tutorial"
-date: 2024-02-15T17:10:12+09:00
+date: 2024-05-20T15:12:59+09:00
 draft: false
 weight: 300
 description: Running only Vald Agent on Kubernetes and execute client codes
@@ -47,7 +47,7 @@ If Helm or HDF5 is not installed, please install [Helm](https://helm.sh/docs/int
 <details><summary>Installation command for Helm</summary><br>
 
 ```bash
-curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
+curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
 ```
 
 </details>

diff --git a/content/docs/tutorial/vald-multicluster-on-k8s.md b/content/docs/tutorial/vald-multicluster-on-k8s.md
@@ -1,6 +1,6 @@
 ---
 title: "Vald Multicluster on K8s_tutorial"
-date: 2024-02-15T17:10:13+09:00
+date: 2024-05-20T15:12:59+09:00
 draft: false
 weight: 500
 description: Running Multi Vald Clusters with Mirror Gateway on Kubernetes and execute client codes
@@ -40,7 +40,7 @@ If Helm or HDF5 is not installed, please install [Helm](https://helm.sh/docs/int
 <details><summary>Installation command for Helm</summary><br>
 
 ```bash
-curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
+curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
 ```
 
 </details>

diff --git a/content/docs/user-guides/deployment.md b/content/docs/user-guides/deployment.md
@@ -1,6 +1,6 @@
 ---
 title: "Deployment_user Guides"
-date: 2024-02-15T17:10:14+09:00
+date: 2024-05-20T15:12:58+09:00
 draft: false
 weight: 600
 description: How to launch Vald cluster on your Kubernetes cluster
@@ -38,7 +38,7 @@ If Helm is not installed, please install [Helm](https://helm.sh/docs/intro/insta
 <details><summary>Installation command for Helm</summary><br>
 
 ```bash
-curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
+curl -fsSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
 ```
 
 </details>

diff --git a/content/docs/user-guides/read-replica-and-rotator.md b/content/docs/user-guides/read-replica-and-rotator.md
@@ -0,0 +1,116 @@
+---
+title: "Read Replica and Rotator_user Guides"
+date: 2024-05-21T13:22:43+09:00
+draft: false
+weight: 1500
+description: How to improve search request speed
+menu:
+  userguides:
+    parent: User Guides
+---
+
+# Read Replica and Rotator
+
+Read replica enhances the search QPS (Queries Per Second) of the Vald cluster by deploying read-only agents in addition to the regular agents and distributing the requests among them. Read replica is deployed as Kubernetes deployments, and depending on the number of replicas (N), QPS increases by approximately 1.7 to 1.8 times \* N.
+
+<div class="notice">
+The increase in QPS is possible with sufficient infrastructure (see <a href="#important-notes">Important notes</a>).
+</div>
+
+## How to deploy read replica
+
+The read replica is managed with a separate chart from the Vald cluster and is deployed as an addon to the Vald cluster. The Vald cluster should be deployed first, followed by the deployment of the read replica.
+
+> The reason Vald and Vald-readreplica are in separate charts is to avoid conflicts between the read replica's restart and the Helm operator's processes when Vald is managed by a helm operator. Therefore, the read replica will always be deployed using Helm commands.
+
+### When you deploy Vald with Helm command
+
+1. Edit `values.yaml` like below (Please refer to [deployment](/docs/user-guides/deployment) for other fields.)
+
+   ```yaml
+   agent:
+   ngt:
+       export_index_info_to_k8s: true
+   readreplica:
+       enabled: true
+       minReplicas: 1 # if you don't use hpa, this will be the replicas of the Deployment
+       maxReplicas: 3
+       hpa:
+       enabled: true # if you prefer to use hpa
+       targetCPUUtilizationPercentage: 80
+   manager:
+   index:
+       operator:
+       enabled: true
+       rotation_job_concurrency: 2
+   ```
+
+1. Deploy Vald cluster
+
+   ```bash
+   helm install vald vald/vald --values values.yaml
+   ```
+
+1. Deploy `vald-readreplica` with the same `values.yaml`
+
+   ```bash
+   helm install vald-readreplica vald/vald-readreplica --values values.yaml
+   ```
+
+### When you deploy Vald cluster with `vald-helm-operator`
+
+1. Edit `valdrelease.yaml` with the same fields as above
+
+1. Deploy Vald cluster
+
+   ```bash
+   helm install vald-helm-operator-release vald/vald-helm-operator
+   kubectl apply -f valdrelease.yaml
+   ```
+
+1. Deploy `vald-readreplica`
+
+   ```bash
+   helm install vald-readreplica vald/vald-readreplica --values <YOUR VALUES YAML FILE PATH>
+   ```
+
+## Architecture
+
+Read replica mainly consists of the following four parts.
+
+<img src="/images/guides/read-replica-and-rotator/architecture.png" alt="Read Replica Architecture" />
+
+### Read replica deployment
+
+The deployment that generates Pods where the actual processing of read replica takes place. Read replica accepts read requests (search) and reads the index from the read replica PVC.
+
+### Read replica PVC
+
+The PVC for read replica Pods is used to read the index. It is generated based on the latest snapshot from the PVC of the regular agent. Unlike the agent PVC, it is generated as ROX, allowing it to be read from multiple Pods.
+
+### Index operator
+
+The operator handles the following processes:
+
+1. Monitoring the time when the agent saved the index to the PVC and when the read replica performed index rotation
+1. Generating [Read replica rotator](#read-replica-rotator) job when an index save occurs after the most recent rotation
+
+> The Index operator also manages the timing of index create/save operations other than those mentioned above. Please refer to another document for details.
+
+### Read replica rotator
+
+The Kubernetes job handles the following processes:
+
+1. Creating a snapshot from the agent's PVC
+1. Generating a PVC for read replica from the snapshot
+1. Rolling update of the read replica deployment to launch a group of read replica pods with the latest index
+
+## Important notes
+
+Result consistency is guaranteed
+
+There is a time lag between index insertion, agent save, and the completion of read replica rotation. During this time, there may be inconsistencies between the index in the agent itself and the index in the read replica.
+
+- Sufficient infrastructure is required for QPS scaling
+
+  Even if read replicas are deployed, QPS will not scale if sufficient resources are not available in the Kubernetes cluster. Specifically, agent resources and read replica resources should be deployed on separate nodes. Vald sets `podAntiAffinity` to ensure that agent resources and read replica resources are deployed on separate nodes as much as possible.
diff --git a/description.json b/description.json
@@ -223,6 +223,10 @@
     "sdks": {
       "weight": 1400,
       "description": "Sends request and receives response from the Vald cluster"
+    },
+    "read-replica-and-rotator": {
+      "weight": 1500,
+      "description": "How to improve search request speed"
     }
   }
-}
+}
diff --git a/preview b/preview
diff --git a/static/images/guides/read-replica-and-rotator/architecture.png b/static/images/guides/read-replica-and-rotator/architecture.png
diff --git a/static/images/performance/benchmark-grafana.png b/static/images/performance/benchmark-grafana.png