doc: add witness related docs

ref tikv/tikv#12876

Signed-off-by: Wenbo Zhang <[email protected]>

Author: ethercflow

configure-placement-rules.md

@@ -39,6 +39,7 @@ Placement Rules 示意图如下所示：
 | `StartKey`        | `string`，十六进制编码                | 适用 Range 起始 key                 |
 | `EndKey`          | `string`，十六进制编码                | 适用 Range 终止 key                 |
 | `Role`            | `string` | 副本角色，包括 voter/leader/follower/learner                           |
+| `IsWitness`       | `true`/`false` | 副本是否为 witness                          |
 | `Count`           | `int`，正整数                     | 副本数量                            |
 | `LabelConstraint` | `[]Constraint`                    | 用于按 label 筛选节点               |
 | `LocationLabels`  | `[]string`                        | 用于物理隔离                        |
@@ -490,3 +491,34 @@ table ttt ranges: (NOTE: key range might be changed after DDL)
   "override": true,
 }
 ```
+
+### 场景六：在高可靠的存储环境下，配置 witness 副本
+
+这个例子展示了 `IsWitness` 配置，下面的例子是在 AWS EBS 环境下配置 witness 副本节约成本。
+
+规则：
+
+{{< copyable "" >}}
+
+```json
+[
+    {
+        "group_id": "pd",
+        "id": "default",
+        "start_key": "",
+        "end_key": "",
+        "role": "voter",
+        "is_witness": false,
+        "count": 2
+    },
+    {
+        "group_id": "pd",
+        "id": "witness",
+        "start_key": "",
+        "end_key": "",
+        "role": "voter",
+        "is_witness": true,
+        "count": 1
+    }
+]
+```

pd-configuration-file.md

@@ -203,6 +203,11 @@ PD 配置文件比命令行参数支持更多的选项。你可以在 [conf/conf
 + 控制对同一个 Region 做 split 和 merge 操作的间隔，即对于新 split 的 Region 一段时间内不会被 merge。
 + 默认：1h
 
+### `switch-witness-interval`
+
++ 控制同一个 Region 做 switch to witness 和 switch to non-witness 操作的间隔，即对于一个新 non-witness 的 Region 在一段时间内不会被 switch to witness。
++ 默认：1h
+
 ### `max-snapshot-count`
 
 + 控制单个 store 最多同时接收或发送的 snapshot 数量，调度受制于这个配置来防止抢占正常业务的资源。
@@ -253,6 +258,16 @@ PD 配置文件比命令行参数支持更多的选项。你可以在 [conf/conf
 + 同时进行的 Region Merge 调度的任务，设置为 0 则关闭 Region Merge。
 + 默认值：8
 
+### `witness-schedule-limit`
+
++ 同时进行的 witness 调度的任务个数。
+
+### `enable-witness`
+
++ 打开 `witness`
++ 默认值：false
++ 参考 [Witness 使用文档](/witness.md)
+
 ### `high-space-ratio`
 
 + 设置 store 空间充裕的阈值。当节点的空间占用比例小于该阈值时，PD 调度时会忽略节点的剩余空间，主要根据实际数据量进行均衡。此配置仅在 `region-score-formula-version = v1` 时生效。

pd-control.md

@@ -1433,6 +1433,12 @@ unsafe remove-failed-stores show
 ]
 ```
 
+### `config set enable-witness true`
+
+> **警告：**
+>
+> - 通过 placement rule 配置 witness 节点后，witness 节点不应用 Raft 日志，请确保存储具有高可用性（99.9%+）
+
 ## jq 格式化 JSON 输出示例
 
 ### 简化 `store` 的输出

witness.md

@@ -0,0 +1,97 @@
+---
+title: Witness 使用文档
+summary: 如何使用 Witness。
+---
+
+# Witness 使用文档
+
+> **警告：**
+> - 此功能开启且通过 PD placement rule 设置 witness 后，witness 副本只存储 Raft 日志但不应用，请在存储可靠性高的环境下使用；当此功能开启，但没有通过 PD placement rule 设置 witness 副本时，不受存储可靠性约束，可提高 TiKV Down 场景下的可用性。
+> - 由于 witness 副本没有应用 Raft 日志，因此无法对外提供读写服务，当其为 leader 且无法及时 transfer leader 出去时，客户端 Backoff 超时后，应用可能收到 IsWitness 错误。
+> - 该功能自 v6.6.0 版本开始引入，与低版本不兼容，因此不支持降级。
+
+## 功能说明
+
+在云环境上，TiKV 为单节点配备了 AWS EBS 存储，提供 99.9% 的持久性。此外，TiKV 使用了 3 个 Raft 副本，这对于保证耐用性来说可能有点矫枉过正。为了降低成本，我们可以引入一种名为 “2 Replicas With 1 Log Only” 的机制，即 Witness，而不是标准 3 个副本，以节省 30% 的存储资源，并根据经验在云端减少大约 100%（1 核）的 CPU 使用率。与原来的3副本架​​构相比，“1 Log Only” 副本存储 Raft 日志但不 apply，仍然通过 Raft 协议保证了数据的一致性。
+
+除上述描述的存储可靠性高的场景外，witness 可用于快速恢复 Failover 来提高可用性。例如对于 3 缺 1 的情况，虽然也满足多数派，但是这个时候的系统是很脆弱的，而要完整恢复一个新的成员的时间通常是比较长的（先拷贝 Snapshot 然后 Apply 最新的日志），尤其是 Region Snapshot 比较大的情况，且拷贝副本的过程可能会对本就不健康的 Group member 造成更多的压力，因此通过先添加一个 witness，快速下掉不健康的节点，保证恢复数据的过程中日志的安全性，后续再由 PD 的 rule checker 将 witness 变为普通的 Voter。
+
+## 适用场景
+
+Witness 功能适用于一下场景：
+
+* 高可靠的存储环境（99.9%+），比如 AWS EBS 存储，使能并配置 Witness 节点来节约成本。
+* 快速恢复 Failover 提高可用性的场景，使能但不配置 Witness 节点。
+
+## 使用步骤
+
+### 第 1 步：使能 Witness
+
+使用 PD Control 执行 [`config set enable-witness true`](/pd-control.md#config-set-enable-witness-true) 命令使能 Witness。
+
+{{< copyable "shell-regular" >}}
+
+```bash
+pd-ctl config set enable-witness true 
+```
+
+命令输出 `Success` 表示使能成功。如果 Placement rule 没有配置 witness 副本，则默认不会有 Witness 产生，只有当出现 TiKV down 后，会立刻添加一个 witness 节点，后续会根据 PD placement rule 规则将其转换为普通的 Voter。
+
+### 第 2 步：使能 transfer witness leader scheduler
+
+使用 PD Control 执行 
+
+{{< copyable "shell-regular" >}}
+
+```bash
+pd-ctl scheduler add transfer-witness-leader-scheduler
+```
+
+命令输出 `Success` 表示使能成功。通常情况下 witness 的选举优先级比普通 Voter 低，且在 Leader 发起 transfer leader 时会拒绝掉，但当 Leader down，另一个 Voter 的 Raft 日志数量小于 witness 时，Raft 会选举 witness 成为 leader，由于 witness 没有应用 Raft 日志，无法对外提供读写服务，因此我们需要让 PD 在 witness leader 上报 region 信息时迅速 transfer 出去，也就是 `transfer-witness-leader-scheduler` 的职责。若在 witness transfer leader 的过程中 TiKV 内部出现了问题，Back off 重试失败后，客户端将返回 IsWitness 错误。
+
+如果仅将 Witness 用于快速恢复 Failover 提高可用性的场景，执行到这一步就结束了。若确定使用的存储环境为高可靠（99.9%+），且有节约成本的需求，则可继续执行后续操作。
+
+### 第 3 步：配置 Witness 副本 (注意：仅适用于高可靠存储)
+
+以三副本为例，修改 rule.json 为 [场景六在高可靠的存储环境下配置-witness-副本](/configure-placement-rules.md#场景六在高可靠的存储环境下配置-witness-副本)。
+
+使用 PD Control 执行
+
+{{< copyable "shell-regular" >}}
+
+```bash
+pd-ctl config placement-rules save --in=rule.json
+```
+
+使能更新后的配置。
+
+
+## 功能兼容性说明
+
+1. TiFlash
+在 PD 侧会禁止 TiFlash 成为 witness。
+
+2. Resolve TS
+当 witness 是 leader 时，会跳过更新 safe ts。
+
+3. CDC
+当 witness 成为 leader 时，CDC 会不断重试，直到 witness 将 leader 身份 transfer 出去。
+
+4. Stale Read
+Witnes 禁止读，TiKV 客户端选择副本时会过滤掉 witness。
+
+5. Online unsafe recovery
+Choose witness as force leader if witness has latest log。
+
+6. BR
+当 witness 成为 leader 时，会拒绝 br。
+
+7. PITR
+
+当 witness 成为 leader 时，会拒绝 PITR。
+
+8. Lightning
+无影响
+
+9. Flashback
+无影响