Add documentation for version 7.1 (#349)

* add version 7.1 Signed-off-by: Ping Yu <[email protected]> * polish Signed-off-by: Ping Yu <[email protected]> --------- Signed-off-by: Ping Yu <[email protected]>
tikv · Nov 20, 2023 · 0eaf3ca · 0eaf3ca
1 parent 4da9460
commit 0eaf3ca
Show file tree

Hide file tree

Showing 80 changed files with 11,076 additions and 37 deletions.
diff --git a/.gitignore b/.gitignore
@@ -12,3 +12,6 @@ resources/
 # Ruby assets
 .bundle/
 vendor/bundle/
+
+# Temporary files generated during preview
+*.md-e
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -176,6 +176,29 @@ author: The author
 ---
 ```
 
-### Adding an adopter
+### Add an adopter
 
 Add the adopter to `data/adopters.yaml` using the format of existing datums.
+
+### Add a version
+
+#### For a new [Long-Term Support](https://docs.pingcap.com/tidb/stable/versioning#long-term-support-releases) (LTS) version
+
+To add a new version of Long-Term Support (LTS) release, follow these steps using version 7.1 as an example:
+
+1. Copy pages from `dev` to `7.1` and update the page identifiers and menu hierarchy links by running the following command in your terminal:
+
+    ```sh
+    cp -rp content/docs/dev content/docs/7.1
+    sed -i -e '5,8s/dev/7.1/g' content/docs/7.1/**/*.md
+    ```
+
+1. Update `params.versions.all` in [config.yaml](config.yaml) to include the new version and ensure that `params.versions.latest` is updated if necessary.
+
+1. Add the major changes of this version to `content/docs/7.1/new-features/overview.md`
+
+#### For [Development Milestone Release](https://docs.pingcap.com/tidb/stable/versioning#development-milestone-releases) (DMR) and patch versions
+
+To add a Development Milestone Release (DMR) or patch versions, follow these steps:
+
+1. Add major changes to [`content/docs/$VERSION/new-features/overview.md`](content/docs/dev/new-features/overview.md), while `$VERSION` is the closest earlier LTS version.
diff --git a/config.yaml b/config.yaml
@@ -34,9 +34,10 @@ params:
     favicon: "favicon.png"
     googleAnalyticsId: "UA-130734531-1"
     versions:
-        latest: "6.5"
+        latest: "7.1"
         all:
         - "dev"
+        - "7.1"
         - "6.5"
         - "6.1"
         - "5.1"

diff --git a/content/docs/7.1/concepts/explore-tikv-features/api-v2.md b/content/docs/7.1/concepts/explore-tikv-features/api-v2.md
@@ -0,0 +1,133 @@
+---
+title: TiKV API v2
+description: What's TiKV API v2 and how to use it
+menu:
+    "7.1":
+        parent: Features-7.1
+        weight: 6
+        identifier: TiKV API v2-7.1
+---
+
+This page introduces what's TiKV API v2 and how to use it.
+
+## TiKV API v2
+
+Before TiKV v6.1.0, RawKV interfaces just store the raw data from clients, so it only provides basic read/write ability of key-values. Besides, due to different encoding and lacking of isolation, TiDB, TxnKV, and RawKV can not be used simultaneously in the same TiKV cluster. In this scenario, multiple clusters must be deployed, and make costs of resource and maintenance increase.
+
+TiKV API v2 provides new storage format, including:
+
+- RawKV organizes data as [MVCC], records update timestamp of every entry, and provides [CDC] feature based on the timestamp (RawKV [CDC] is an experimental feature provided by another component, see [TiKV-CDC]).
+- Data in TiKV is separated by modes, supports using TiDB, TxnKV, and RawKV in a single cluster at the same time.
+- `Key Space` field is reserved, to support multi-tenant in the future.
+
+To use TiKV API v2, please add or modify `api-version = 2` & `enable-ttl = true` in `[storage]` section of TiKV. See [configuration file](https://docs.pingcap.com/tidb/dev/tikv-configuration-file#api-version-new-in-v610) for detail.
+
+Besides, when API V2 is enabled, you need to deploy at least one tidb-server instance to reclaim expired data of [MVCC]. To ensure high availability, you can deploy multiple tidb-server instances. Note that these tidb-server instances can also be used as normal TiDB database.
+
+> Warning
+>   - Due to the significant change on storage format, **only if** the existing TiKV cluster is empty or storing **only** TiDB data, you can enable or disable API v2 smoothly. In other scenario, you must deploy a new cluster, and migrate data using [TiKV-BR].
+>   - After API V2 is enabled, you **cannot** downgrade the TiKV cluster to a version earlier than v6.1.0. Otherwise, data corruption might occur.
+
+## Usage Demonstration
+
+### Prerequisites
+
+Before you start, ensure that you have installed TiUP according to [TiKV in 5 Minutes](../../tikv-in-5-minutes).
+
+### Step 1: Config TiKV to enable API v2
+
+To enable API v2, create a file `tikv.yaml` using the following configuration.
+
+```yaml
+[storage]
+api-version = 2
+enable-ttl = true
+```
+
+### Step 2: Start TiKV Cluster
+
+```bash
+tiup playground nightly --db 1 --tiflash 0 --pd 1 --kv 1 --kv.config tikv.yaml
+```
+
+### Step 3: Write the code to test API v2
+
+Take [Go client] as example, save the following script to file `test_api_v2.go`.
+
+```go
+package main
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/pingcap/kvproto/pkg/kvrpcpb"
+	"github.com/tikv/client-go/v2/rawkv"
+)
+
+func main() {
+	cli, err := rawkv.NewClientWithOpts(context.TODO(), []string{"127.0.0.1:2379"},
+		rawkv.WithAPIVersion(kvrpcpb.APIVersion_V2))
+	if err != nil {
+		panic(err)
+	}
+	defer cli.Close()
+
+	fmt.Printf("cluster ID: %d\n", cli.ClusterID())
+
+	key := []byte("Company")
+	val := []byte("PingCAP")
+
+	// put key into tikv
+	err = cli.Put(context.TODO(), key, val)
+	if err != nil {
+		panic(err)
+	}
+	fmt.Printf("Successfully put %s:%s to tikv\n", key, val)
+
+	// get key from tikv
+	val, err = cli.Get(context.TODO(), key)
+	if err != nil {
+		panic(err)
+	}
+	fmt.Printf("found val: %s for key: %s\n", val, key)
+
+	// delete key from tikv
+	err = cli.Delete(context.TODO(), key)
+	if err != nil {
+		panic(err)
+	}
+	fmt.Printf("key: %s deleted\n", key)
+
+	// get key again from tikv
+	val, err = cli.Get(context.TODO(), key)
+	if err != nil {
+		panic(err)
+	}
+	fmt.Printf("found val: %s for key: %s\n", val, key)
+}
+```
+
+### Step 4: Run the code
+
+```bash
+❯ go mod tidy
+❯ go run test_api_v2.go
+[2022/11/02 21:23:10.507 +08:00] [INFO] [client.go:405] ["[pd] create pd client with endpoints"] [pd-address="[172.16.5.32:32379]"]
+[2022/11/02 21:23:10.513 +08:00] [INFO] [base_client.go:378] ["[pd] switch leader"] [new-leader=http://172.16.5.32:32379] [old-leader=]
+[2022/11/02 21:23:10.513 +08:00] [INFO] [base_client.go:105] ["[pd] init cluster id"] [cluster-id=7153087019074699621]
+[2022/11/02 21:23:10.514 +08:00] [INFO] [client.go:698] ["[pd] tso dispatcher created"] [dc-location=global]
+cluster ID: 7153087019074699621
+Successfully put Company:PingCAP to tikv
+found val: PingCAP for key: Company
+key: Company deleted
+found val:  for key: Company
+[2022/11/02 21:23:10.532 +08:00] [INFO] [client.go:779] ["[pd] stop fetching the pending tso requests due to context canceled"] [dc-location=global]
+[2022/11/02 21:23:10.533 +08:00] [INFO] [client.go:716] ["[pd] exit tso dispatcher"] [dc-location=global]
+```
+
+[MVCC]: https://en.wikipedia.org/wiki/Multiversion_concurrency_control
+[CDC]: https://en.wikipedia.org/wiki/Change_data_capture
+[TiKV-CDC]: https://github.com/tikv/migration/blob/main/cdc/README.md
+[TiKV-BR]: https://github.com/tikv/migration/blob/main/br/README.md
+[Go client]: https://github.com/tikv/client-go/wiki/RawKV-Basic
diff --git a/content/docs/7.1/concepts/explore-tikv-features/backup-restore-cn.md b/content/docs/7.1/concepts/explore-tikv-features/backup-restore-cn.md
@@ -0,0 +1,182 @@
+---
+title: RawKV BR 使用手册
+description: 如何使用 RawKV BR
+menu:
+    "7.1":
+        parent: RawKV BR-7.1
+        weight: 1
+        identifier: RawKV BR CN-7.1
+---
+
+本文是 RawKV BR 的使用手册。
+
+
+**[TiKV Backup & Restore (TiKV-BR)]** 是 TiKV 分布式备份恢复的命令行工具，用于对 TiKV 集群进行数据备份和恢复。 
+
+## 工作原理
+TiKV-BR 将备份或恢复操作命令下发到各个 TiKV 节点。TiKV 收到命令后执行相应的备份或恢复操作。 在一次备份或恢复中，各个 TiKV 节点都会有一个对应的备份路径，TiKV 备份时产生的备份文件将会保存在该路径下，恢复时也会从该路径读取相应的备份文件。  
+{{< figure
+    src="/img/docs/tikv-br.png"
+    caption="TiKV-BR 工作原理"
+    number="1" >}}
+
+### 安装
+
+#### 使用 TiUP 安装
+
+`tikv-br` 是 [TiUP] 的一个组件，你可以使用 [TiUP] 来部署 `tikv-br`:
+```bash
+tiup tikv-br:v1.1.0 <命令> <子命令> 
+```
+如果是第一次使用，TiUP 会自动下载和安装 `tikv-br` 组件。
+
+
+#### 手工安装
+你可以从 [GitHub] 下载 `tikv-br` 的最新发行版。 
+
+### 推荐部署配置
+- 生产环境中，推荐 TiKV-BR 运行在（4 核+/8 GB+）的节点上。操作系统版本要求可参考 [操作系统及平台的要求]。
+- 推荐使用 Amazon s3 存储 或者 SSD 网盘，挂载到 TiKV-BR 节点和所有 TiKV 节点上，网盘推荐万兆网卡，否则带宽有可能成为备份恢复时的性能瓶颈。
+- TiKV-BR 只支持版本大于 v5.0.0 的 TiKV 集群中 RawKV 模式数据的备份和恢复。
+- 建议为备份和恢复配置足够的资源：
+    - TiKV-BR、TiKV 节点和备份存储系统需要提供大于备份速度的的网络带宽。当集群特别大的时候，备份和恢复速度上限受限于备份网络的带宽。
+    - 备份存储系统还需要提供足够的写入/读取性能（IOPS），否则它有可能成为备份恢复时的性能瓶颈。
+    - TiKV 节点需要为备份准备至少额外的两个 CPU core 和高性能的磁盘，否则备份将对集群上运行的业务产生影响。
+
+### 最佳实践
+下面是使用 TiKV-BR 进行备份恢复的几种推荐操作：  
+- 推荐在业务低峰时执行备份操作，这样能最大程度地减少对业务的影响。
+- TiKV-BR 支持在不同拓扑的集群上执行恢复，但恢复期间对在线业务影响很大，建议低峰期或者限速 (rate-limit) 执行恢复。
+- TiKV-BR 备份最好串行执行。不同备份任务并行会导致备份性能降低，同时也会影响在线业务。
+- TiKV-BR 恢复最好串行执行。不同恢复任务并行会导致 Region 冲突增多，恢复的性能降低。
+- 可以通过指定 `--checksum=true`，在备份、恢复完成后进行一轮数据校验。数据校验将分别计算备份数据与 TiKV 集群中数据的 checksum，并对比二者是否相同。请注意，如果需要进行数据校验，请确保在备份或恢复的全过程，TiKV 集群没有数据变更和 TTL 过期。
+- TiKV-BR 可用于实现 [api-version] 从 V1 到 V2 的集群数据迁移。通过指定 `--dst-api-version V2` 将 `api-version=1` 的 TiKV 集群备份为 V2 格式，然后将备份文件恢复到新的 `api-version=2` TiKV 集群中。
+
+### TiKV-BR 命令行描述
+一条 `tikv-br` 命令是由子命令、选项和参数组成的。子命令即不带 `-` 或者 `--` 的字符。选项即以 `-` 或者 `--` 开头的字符。参数即子命令或选项字符后紧跟的、并传递给命令和选项的字符。
+#### 备份集群 Raw 模式数据
+要备份 TiKV 集群中 Raw 模式数据，可使用 `tikv-br backup raw` 命令。该命令的使用帮助可以通过 `tikv-br backup raw --help` 来获取。
+用例：将 TiKV 集群中 Raw 模式数据备份到 s3 `/backup-data/2022-09-16/` 目录中。
+```bash
+export AWS_ACCESS_KEY_ID=&{AWS_KEY_ID};
+export AWS_SECRET_ACCESS_KEY=&{AWS_KEY};
+tikv-br backup raw \
+    --pd="&{PDIP}:2379" \
+    --storage="s3://backup-data/2022-09-16/" \
+    --dst-api-version v2 \
+    --log-file="/tmp/backupraw.log \
+    --gcttl=5m \
+    --start="a" \
+    --end="z" \
+    --format="raw"
+```
+命令行各部分的解释如下：
+- `backup`：`tikv-br` 的子命令。
+- `raw`：`backup` 的子命令。
+- `-s` 或 `--storage`：备份保存的路径。
+- `"s3://backup-data/2022-09-16/"`：`--storage` 的参数，保存的路径为 S3 的 `/backup-data/2022-09-16/` 目录。
+- `--pd`：`PD` 服务地址。
+- `"${PDIP}:2379"`：`--pd` 的参数。
+- `--dst-api-version`: 指定备份文件的 `api-version`，请见 [TiKV API v2]。
+- `v2`: `--dst-api-version` 的参数，可选参数为 `v1`，`v1ttl`，`v2`(不区分大小写)，如果不指定 `dst-api-version` 参数，则备份文件的 `api-version` 与指定 `--pd` 所属的 TiKV 集群 `api-version` 相同。  
+- `gcttl`: GC 暂停时长。可用于确保从存量数据备份到 [创建 TiKV-CDC 同步任务] 的这段时间内，增量数据不会被 GC 清除。默认为 5 分钟。
+- `5m`: `gcttl` 的参数，数据格式为`数字 + 时间单位`, 例如 `24h` 表示 24 小时，`60m` 表示 60 分钟。
+- `start`, `end`: 用于指定需要备份的数据区间，为左闭右开区间 `[start, end)`。默认为`["", "")`， 即全部数据。
+- `format`：`start` 和 `end` 的格式，支持 `raw`、[hex] 和 [escaped] 三种格式。
+
+备份期间会有进度条在终端中显示，当进度条前进到 100% 时，说明备份已完成。
+
+备份完成后，会显示如下所示的信息:
+```bash
+[2022/09/20 18:01:10.125 +08:00] [INFO] [collector.go:67] ["Raw backup success summary"] [total-ranges=3] [ranges-succeed=3] [ranges-failed=0] [backup-total-regions=3] [total-take=5.050265883s] [backup-ts=436120585518448641] [total-kv=100000] [total-kv-size=108.7MB] [average-speed=21.11MB/s] [backup-data-size(after-compressed)=78.3MB]
+```
+以上信息的解释如下: 
+- `total-ranges`: 备份任务切分成的分片个数， 与 `ranges-succeed` + `ranges-failed` 相等.
+- `ranges-succeed`: 成功分片的个数。
+- `ranges-failed`: 失败分片的个数。
+- `backup-total-regions`: 执行备份任务的 TiKV region 个数。
+- `total-take`: 备份任务执行时长。
+- `backup-ts`: 备份时间点，只对 API V2 的 TiKV 集群生效。可以用于 [创建 TiKV-CDC 同步任务] 时的 `start-ts`.
+- `total-kv`: 备份文件中键值对的个数。
+- `total-kv-size`: 备份文件中键值对的大小。请注意，这是指压缩前的大小。
+- `average-speed`: 备份速率，约等于 `total-kv-size` / `total-take`。
+- `backup-data-size(after-compressed)`: 备份文件的大小。
+
+#### 恢复 Raw 模式备份数据
+
+要将 Raw 模式备份数据恢复到集群中来，可使用 `tikv-br restore raw` 命令。该命令的使用帮助可以通过 `tikv-br restore raw --help` 来获取。  
+用例：将 s3 `/backup-data/2022-09-16/` 路径中的 Raw 模式备份数据恢复到集群中。
+```bash
+export AWS_ACCESS_KEY_ID=&{AWS_KEY_ID};
+export AWS_SECRET_ACCESS_KEY=&{AWS_KEY};
+tikv-br restore raw \
+    --pd "${PDIP}:2379" \
+    --storage "s3://backup-data/2022-09-16/" \
+    --log-file restoreraw.log
+```
+以上命令中，`--log-file` 选项指定把 `TiKV-BR` 的 log 写到 `restoreraw.log` 文件中。
+恢复期间会有进度条在终端中显示，当进度条前进到 100% 时，说明恢复已完成。  
+
+恢复完成后，会显示如下所示的信息:
+```bash
+[2022/09/20 18:02:12.540 +08:00] [INFO] [collector.go:67] ["Raw restore success summary"] [total-ranges=3] [ranges-succeed=3] [ranges-failed=0] [restore-files=3] [total-take=950.460846ms] [restore-data-size(after-compressed)=78.3MB] [total-kv=100000] [total-kv-size=108.7MB] [average-speed=114.4MB/s]
+```
+以上信息的解释如下:  
+- `total-ranges`: 恢复任务切分成的分片个数， 与 `ranges-succeed` + `ranges-failed` 相等.
+- `ranges-succeed`: 成功分片的个数。
+- `ranges-failed`: 失败分片的个数。
+- `restore-files`: 执行恢复的文件个数。
+- `total-take`: 恢复时长。
+- `total-kv`: 恢复文件中键值对的个数。
+- `total-kv-size`: 恢复文件中键值对的大小。请注意，这是指压缩前的大小。
+- `average-speed`: 恢复速率，约等于 `total-kv-size` / `total-take`。
+- `restore-data-size(after-compressed)`: 恢复文件的大小。
+
+
+### 备份文件的数据校验
+
+TiKV-BR 可以在 TiKV 集群备份和恢复操作完成后执行 `checksum` 来确保备份文件的完整性和正确性。 checksum 可以通过 `--checksum` 来开启。
+
+Checksum 开启时，备份或恢复操作完成后，会使用 [client-go] 的 [checksum] 接口来计算 TiKV 集群中有效数据的 checksum 结果，并与备份文件保存的 checksum 结果进行对比。
+
+注意，当 TiKV 集群启用了 [TTL]，如果在备份或恢复过程中出现数据 TTL 过期，此时 TiKV 集群的 checksum 结果跟备份文件的 checksum 会不相同，因此无法在此场景中使用 `checksum`。
+
+### 备份恢复操作的安全性
+
+TiKV-BR 支持在开启了 [TLS 配置] 的 TiKV 集群中执行备份和恢复操作，你可以通过设置 `--ca`， `--cert` 和 `--key` 参数来指定客户端证书。
+
+### 性能
+
+TiKV-BR 的备份和恢复都是分布式的，在存储和网络没有达到瓶颈的时候，性能可以随着 TiKV 节点数量线性提升。以下是 TiKV-BR 的性能测试指标，以供参考。
+- TiKV 节点：4 核 CPU， 8G 内存，v6.4.0
+- PD 节点：4 核 CPU， 8G 内存，v6.4.0
+- TiKV-BR 节点：4 核 CPU， 8G 内存，v1.1.0
+- 存储容量： 50TB
+
+|指标|TiKV API v1|TiKV API v2|
+|:-:|:-:|:-:|
+|备份速度|每 TiKV 节点 40MB/s|每 TiKV 节点 40MB/s|
+|恢复速度|每 TiKV 节点 70MB/s|每 TiKV 节点 70MB/s|
+|性能影响|QPS 降低 20%，时延增加 20%|QPS 降低 20%，时延增加 20%|
+
+#### 性能调优
+
+如果你希望减少备份对集群的影响，你可以开启 [auto-tune] 功能。开启该功能后，备份功能会在不过度影响集群正常业务的前提下，以最快的速度进行数据备份。详见[自动调节]。  
+或者你也可以使用参数 `--ratelimit` 进行备份限速。
+
+
+[TiKV Backup & Restore (TiKV-BR)]: https://github.com/tikv/migration/tree/main/br
+[TiUP]: https://tiup.io
+[GitHub]: https://github.com/tikv/migration/releases
+[操作系统及平台的要求]: https://docs.pingcap.com/zh/tidb/dev/hardware-and-software-requirements
+[api-version]: ../api-v2
+[TiKV API v2]: ../api-v2
+[创建 TiKV-CDC 同步任务]: ../cdc/cdc-cn/#%E7%AE%A1%E7%90%86%E5%90%8C%E6%AD%A5%E4%BB%BB%E5%8A%A1-changefeed
+[hex]: https://zh.wikipedia.org/wiki/%E5%8D%81%E5%85%AD%E8%BF%9B%E5%88%B6
+[escaped]: https://zh.wikipedia.org/wiki/%E8%BD%AC%E4%B9%89%E5%AD%97%E7%AC%A6
+[checksum]: ../../../develop/rawkv/checksum
+[client-go]: https://github.com/tikv/client-go
+[TTL]: ../ttl
+[TLS 配置]: https://docs.pingcap.com/zh/tidb/dev/enable-tls-between-components
+[auto-tune]: https://docs.pingcap.com/zh/tidb/stable/tikv-configuration-file#enable-auto-tune-%E4%BB%8E-v54-%E7%89%88%E6%9C%AC%E5%BC%80%E5%A7%8B%E5%BC%95%E5%85%A5
+[自动调节]: https://docs.pingcap.com/zh/tidb/dev/br-auto-tune