vdaas · vankichi · Nov 8, 2023 · Oct 12, 2023 · Oct 12, 2023 · Oct 12, 2023
diff --git a/docs/api/mirror-gateway.md b/docs/api/mirror-gateway.md
@@ -2,13 +2,11 @@
 
 ## Overview
 
-Mirror Service is responsible for providing the `Register` and `Advertise` interface for the Vald Mirror Gateway.
+Mirror Service is responsible for providing the `Register` interface for the Vald Mirror Gateway.
 
 ```rpc
 service Mirror {
   rpc Register(payload.v1.Mirror.Targets) returns (payload.v1.Mirror.Targets) {}
-
-  rpc Advertise(payload.v1.Mirror.Targets) returns (payload.v1.Mirror.Targets) {}
 }
 ```
 
@@ -85,77 +83,3 @@ Register RPC is the method to register other Vald Mirror Gateway targets.
 |  3   | INVALID_ARGUMENT  |
 |  4   | DEADLINE_EXCEEDED |
 |  13  | INTERNAL          |
-
-## Advertise RPC
-
-Advertise RPC is the method to advertise Vald Mirror Gateway targets.
-
-### Input
-
-- the scheme of `payload.v1.Mirror.Targets`.
-
-  ```rpc
-  message Mirror {
-    message Target {
-      string host = 1;
-      uint32 port = 2;
-    }
-
-    message Targets {
-      repeated Target targets = 1;
-    }
-  }
-  ```
-
-  - Mirror.Targets
-
-    |  field  | type          | label                          | required | desc.                            |
-    | :-----: | :------------ | :----------------------------- | :------: | :------------------------------- |
-    | targets | Mirror.Target | repeated(Array[Mirror.Target]) |    \*    | The multiple target information. |
-
-  - Mirror.Target
-
-    | field | type   | label | required | desc.                |
-    | :---: | :----- | :---- | :------: | :------------------- |
-    | host  | string |       |    \*    | The target hostname. |
-    | port  | uint32 |       |    \*    | The target port.     |
-
-### Output
-
-- the scheme of `payload.v1.Mirror.Targets`.
-
-```rpc
-message Mirror {
-  message Target {
-    string host = 1;
-    uint32 port = 2;
-  }
-
-  message Targets {
-    repeated Target targets = 1;
-  }
-}
-```
-
-- Mirror.Targets
-
-  |  field  | type          | label                          | required | desc.                            |
-  | :-----: | :------------ | :----------------------------- | :------: | :------------------------------- |
-  | targets | Mirror.Target | repeated(Array[Mirror.Target]) |          | The multiple target information. |
-
-- Mirror.Target
-
-  | field | type   | label | required | desc.                |
-  | :---: | :----- | :---- | :------: | :------------------- |
-  | host  | string |       |    \*    | The target hostname. |
-  | port  | uint32 |       |    \*    | The target port.     |
-
-### Status Code
-
-| code | desc.             |
-| :--: | :---------------- |
-|  0   | OK                |
-|  1   | CANCELLED         |
-|  3   | INVALID_ARGUMENT  |
-|  4   | DEADLINE_EXCEEDED |
-|  13  | INTERNAL          |
diff --git a/docs/overview/component/mirror-gateway.md b/docs/overview/component/mirror-gateway.md
@@ -10,7 +10,7 @@ This component makes it possible to enhance availability during a cluster failur
 
 Vald Mirror Gateway is responsible for the followings:
 
-- Forward user requests ([Insert](https://vald.vdaas.org/docs/api/insert/) / [Upsert](https://vald.vdaas.org/docs/api/upsert/) / [Update](https://vald.vdaas.org/docs/api/update/) / [Remove](https://vald.vdaas.org/docs/api/remove/)) to the other Vald Mirror Gateways in the same group.
+- Forward user requests ([Insert](../../api/insert.md) / [Upsert](../../api/upsert.md) / [Update](../../api/update.md) / [Remove](../../api/remove.md)) to the other Vald Mirror Gateways in the same group.
 - Manages the state of indexes stored in all clusters to ensure they are consistent.
 
 ## Features
@@ -33,46 +33,49 @@ The `ValdMirrorTarget` is a Custom Resource related to the connection destinatio
 
 When two Vald clusters contain Vald Mirror Gateways, Vald Mirror Gateways can send the request to each other by applying `ValdMirrorTarget`.
 
-For more information about `ValdMirrorTarget` configuration, please refer to [Custom Resource Configuration](https://vald.vdaas.org/docs/user-guides/mirroring-configuration/).
+For more information about `ValdMirrorTarget` configuration, please refer to [Custom Resource Configuration](../../user-guides/mirroring-configuration.md).
 
 ### Request forwarding
 
 <img src="../../../assets/docs/overview/component/mirror-gateway/request-forwarding.png">
 
-The Vald Mirror Gateway forwards the incoming user request ([Insert](https://vald.vdaas.org/docs/api/insert/) / [Upsert](https://vald.vdaas.org/docs/api/upsert/) / [Update](https://vald.vdaas.org/docs/api/update/) / [Remove](https://vald.vdaas.org/docs/api/remove/)) to other Vald Mirror Gateways.
+The Vald Mirror Gateway forwards the incoming user request ([Insert](../../api/insert.md) / [Upsert](../../api/upsert.md) / [Update](../../api/update.md) / [Remove](../../api/remove.md)) to other Vald Mirror Gateways.
 Then, while forwarding the user request, the Vald Mirror Gateway bypasses the incoming user request to Vald LB Gateway in its own cluster.
 
-On the other hand, if the incoming user request is an [Object API](https://vald.vdaas.org/docs/api/object/) or [Search API](https://vald.vdaas.org/docs/api/search/), it is bypassed to only a Vald LB Gateway in its own cluster without forwarding it to other Vald Mirror Gateways.
+On the other hand, if the incoming user request is an [Object API](../../api/object.md) or [Search API](../../api/search.md), it is bypassed to only a Vald LB Gateway in its own cluster without forwarding it to other Vald Mirror Gateways.
 
-### Automatic rollback on failure
+### Continuous processing on failure
 
 The request may fail at the forwarding destination or the bypass destination.
 
-If some requests fail, the vector data will not be consistent across Vald clusters.
+If some of the requests fails, the processing continues based on their status code.
 
-To keep index state consistency, the Vald Mirror Gateway will send the rollback request for the failed request. After the rollback request succeeds, the index state will be the same as before requesting.
+Here's an overview of how the Mirror Gateway handles failures for each type of request.
 
-The following is the list of rollback types.
+For more information about status code, please refer to [Mirror Gateway Troubleshooting](../../troubleshooting/mirror-gateway.md).
 
 - Insert Request
-  - Rollback Condition/Trigger
-    - Status code other than `ALREADY_EXISTS` exists
-  - Rollback request to the successful request
-    - REMOVE request
-- Remove Request
-  - Rollback Condition/Trigger
-    - Status code other than `NOT_FOUND` exists
-  - Rollback request to the successful request
-    - UPSERT Request with old vector
+
+  - If the target host returns a status code of `ALREADY_EXISTS`, the Update request is sent to this host.
+  - If the target host returns a status code other than `OK`, `ALREADY_EXISTS`, the Mirror Gateway returns that status code without continuous processing.
+  - If all target hosts return a status code `ALREADY_EXISTS`, the Mirror Gateway returns `ALREADY_EXISTS`.
+  - If all target hosts return a status code `OK` or `ALREADY_EXISTS`, the Mirror Gateway returns `OK`.
+
 - Update Request
-  - Rollback Condition/Trigger
-    - Status code other than `ALREADY_EXISTS` exists
-  - Rollback request to the successful request
-    - REMOVE Request if there is no old vector data
-    - UPDATE Request if there is old vector data
+
+  - If the target host returns a status code `NOT_FOUND`, the Insert request is sent to this host.
+  - If the target host returns a status code other than `OK`, `ALREADY_EXISTS`, the Mirror Gateway returns that status code without continuous processing.
+  - If all target hosts return a status code `ALREADY_EXISTS`, the Mirror Gateway returns `ALREADY_EXISTS`.
+  - If all target hosts return a status code `OK` or `ALREADY_EXISTS`, the Mirror Gateway returns `OK`.
+
 - Upsert Request
-  - Rollback Condition/Trigger
-    - Status code other than `ALREADY_EXISTS` exists
-  - Rollback request to the successful request
-    - REMOVE Request if there is no old vector data
-    - UPDATE Request if there is old vector data
+
+  - If all target hosts return a status code `ALREADY_EXISTS`, the Mirror Gateway returns `ALREADY_EXISTS`.
+  - If the target host returns a status code other than `OK` or `ALREADY_EXISTS`, the Mirror Gateway returns that status code without continuous processing.
+  - If all target hosts return a status code `OK` or `ALREADY_EXISTS`, the Mirror Gateway returns `OK`.
+
+- Remove/RemoveByTimestamp Request
+
+  - If all target hosts return a status code `NOT_FOUND`, the Mirror Gateway returns `NOT_FOUND`.
+  - If the target host returns a status code other than `OK` or `NOT_FOUND`, the Mirror Gateway returns that status code without continuous processing.
+  - If all target hosts return a status code `OK` or `NOT_FOUND`, the Mirror Gateway returns `OK`.
diff --git a/docs/troubleshooting/mirror-gateway.md b/docs/troubleshooting/mirror-gateway.md
@@ -0,0 +1,75 @@
+# Mirror Gateway Troubleshooting
+
+This page introduces the popular troubleshooting for Mirror Gateway.
+
+Additionally, if you encounter some errors when using API, the [API status code](../api/status.md) helps you, too.
+
+## Insert Operation
+
+Mirror Gateway sends an Update request to its host if some requests are `ALREADY_EXISTS`.
+
+Therefore, in addition to the [Insert API status code](../api/insert.md#status-code), the [Update API status code](../api/update.md#status-code) may also be returned to the user.
+
+Here are some common reasons of error.
+
+| name              | common reason                                                                                                                                       |
+| :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- |
+| CANCELLED         | Executed cancel() of rpc from client/server-side or network problems between client and server.                                                     |
+| INVALID_ARGUMENT  | The Dimension of the request vector is NOT the same as Vald Agent's config, the requested vector's ID is empty, or some request payload is invalid. |
+| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side.                                                                                     |
+| ALREADY_EXISTS    | Request ID is already inserted. This status code is returned when all target hosts return `ALREADY_EXISTS`.                                         |
+| NOT_FOUND         | Requested ID is NOT inserted. This is the status code of the Update request.                                                                        |
+| INTERNAL          | Target Vald cluster or network route has some critical error.                                                                                       |
+
+`0 (OK)` is also returned when all target hosts return `OK` or `ALREADY_EXISTS`.
+
+## Update Operation
+
+Mirror Gateway sends an Update request to its host if some requests are `NOT_FOUND`.
+
+Therefore, in addition to the [Update API status code](../api/update.md#status-code), the [Insert API status code](../api/insert.md#status-code) may also be returned to the user.
+
+Here are some common reasons of error.
+
+| name              | common reason                                                                                                                                       |
+| :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- |
+| CANCELLED         | Executed cancel() of rpc from client/server-side or network problems between client and server.                                                     |
+| INVALID_ARGUMENT  | The Dimension of the request vector is NOT the same as Vald Agent's config, the requested vector's ID is empty, or some request payload is invalid. |
+| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side.                                                                                     |
+| NOT_FOUND         | Requested ID is NOT inserted. This status code is returned when all target hosts return `NOT_FOUND`.                                                |
+| ALREADY_EXISTS    | Request a pair of ID and vector is already inserted. This status code is returned when all hosts return `ALREADY_EXISTS`.                           |
+| INTERNAL          | Target Vald cluster or network route has some critical error.                                                                                       |
+
+`0 (OK)` is also returned when all target hosts return `OK` or `ALREADY_EXISTS`.
+
+## Upsert Operation
+
+The request process may not be completed when the response code is NOT `0 (OK)`.
+
+Here are some common reasons of error.
+
+| name              | common reason                                                                                                                                       |
+| :---------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- |
+| CANCELLED         | Executed cancel() of rpc from client/server-side or network problems between client and server.                                                     |
+| INVALID_ARGUMENT  | The Dimension of the request vector is NOT the same as Vald Agent's config, the requested vector's ID is empty, or some request payload is invalid. |
+| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side.                                                                                     |
+| ALREADY_EXISTS    | Requested pair of ID and vector is already inserted. This status code is returned when all target hosts return `ALREADY_EXISTS`.                    |
+| INTERNAL          | Target Vald cluster or network route has some critical error.                                                                                       |
+
+`0 (OK)` is also returned when all target hosts return `OK` or `ALREADY_EXISTS`.
+
+## Remove Operation
+
+The request process may not be completed when the response code is NOT `0 (OK)`.
+
+Here are some common reasons of error.
+
+| name              | common reason                                                                                        |
+| :---------------- | :--------------------------------------------------------------------------------------------------- |
+| CANCELLED         | Executed cancel() of rpc from client/server-side or network problems between client and server.      |
+| INVALID_ARGUMENT  | The Requested vector's ID is empty, or some request payload is invalid.                              |
+| DEADLINE_EXCEEDED | The RPC timeout setting is too short on the client/server side.                                      |
+| NOT_FOUND         | Requested ID is NOT inserted. This status code is returned when all target hosts return `NOT_FOUND`. |
+| INTERNAL          | Target Vald cluster or network route has some critical error.                                        |
+
+`0 (OK)` is also returned when all target hosts return `OK` or `NOT_FOUND`.
diff --git a/docs/user-guides/mirroring-configuration.md b/docs/user-guides/mirroring-configuration.md
@@ -2,7 +2,7 @@
 
 This page describes how to enable mirroring features on the Vald cluster.
 
-Before you use the mirroring functions, please look at [the Vald Mirror Gateway document](../../docs/overview/component/mirror-gateway.md) for what you can do.
+Before you use the mirroring functions, please look at [the Vald Mirror Gateway document](../overview/component/mirror-gateway.md) for what you can do.
 
 ## Requirement
 
@@ -41,8 +41,8 @@ gateway:
     ...
       # gRPC client configuration (overrides defaults.grpc.client)
       client: {}
-      # The interval to advertise addresses of Mirror Gateway to other Mirror Gateway.
-      advertise_interval: "1s"
+      # The duration to register other Mirror Gateways.
+      register_duration: "1s"
       # The target namespace to discover ValdMirrorTarget (CR) resource.
       # The default value is its own namespace.
       namespace: "vald"
@@ -58,7 +58,7 @@ gateway:
 
 The cluster role configuration is required when you deploy Vald clusters with Vald Mirror Gateway on multiple Namespaces in the Kubernetes cluster.
 
-Please refer to [Cluster Role Configuration](https://vald.vdaas.org/docs/user-guides/cluster-role-binding/) about cluster role settings for Mirror Gateway.
+Please refer to [Cluster Role Configuration](./cluster-role-binding.md) about cluster role settings for Mirror Gateway.
 
 ### Custom Resource Configuration