update doc for tiflash (#236)

pingcap · Apr 30, 2020 · d51704c · d51704c
1 parent 320070c
commit d51704c
Show file tree

Hide file tree

Showing 6 changed files with 177 additions and 17 deletions.
diff --git a/zh/TOC.md b/zh/TOC.md
@@ -16,6 +16,7 @@
   - [集群环境要求](prerequisites.md)
   - [部署 TiDB Operator](deploy-tidb-operator.md)
   - [标准 Kubernetes 上的 TiDB 集群](deploy-on-general-kubernetes.md)
+  - [部署 TiFlash](deploy-tiflash.md)
   - [AWS EKS 上的 TiDB 集群](deploy-on-aws-eks.md)
   - [GCP 上的 TiDB 集群](deploy-on-gcp-gke.md)
   - [阿里云上的 TiDB 集群](deploy-on-alibaba-cloud.md)

diff --git a/zh/configure-cluster-using-tidbcluster.md b/zh/configure-cluster-using-tidbcluster.md
@@ -6,11 +6,11 @@ category: how-to
 
 # 通过 TidbCluster 配置 TiDB 集群
 
-TidbCluster 文件支持在其上面直接配置 TiDB/TiKV/PD 的配置选项，本篇文章将介绍如何在 TidbCluster 上配置参数。目前 Operator 1.1 版本支持了 TiDB 集群 v3.1 版本参数。针对各组件配置参数，请参考 PingCAP 官方文档。
+TidbCluster 文件支持在其上面直接配置 TiDB/TiKV/PD/TiFlash 的配置选项，本篇文章将介绍如何在 TidbCluster 上配置参数。目前 Operator 1.1 版本支持了 TiDB 集群 v3.1 版本参数。针对各组件配置参数，请参考 PingCAP 官方文档。
 
 ## 配置 TiDB 配置参数
 
-你可以通过 `TidbCluster.Spec.Tidb.Config` 来配置 TiDB 配置参数，以下是一个例子。获取所有可以配置的 TiDB 配置参数，请参考 [TiDB 配置文档](https://pingcap.com/docs-cn/v3.1/reference/configuration/tidb-server/configuration-file/)。
+你可以通过 TidbCluster Custom Resource 的 `spec.tidb.config` 来配置 TiDB 配置参数，以下是一个例子。获取所有可以配置的 TiDB 配置参数，请参考 [TiDB 配置文档](https://pingcap.com/docs-cn/v3.1/reference/configuration/tidb-server/configuration-file/)。
 
 > **注意：**
 >
@@ -38,7 +38,7 @@ spec:
 
 ## 配置 TiKV 配置参数
 
-你可以通过 `TidbCluster.Spec.Tikv.Config` 来配置 TiKV 配置参数，以下是一个例子。获取所有可以配置的 TiKV 配置参数，请参考 [TiKV 配置文档](https://pingcap.com/docs-cn/v3.1/reference/configuration/tikv-server/configuration-file/)
+你可以通过 TidbCluster Custom Resource 的 `spec.tikv.config` 来配置 TiKV 配置参数，以下是一个例子。获取所有可以配置的 TiKV 配置参数，请参考 [TiKV 配置文档](https://pingcap.com/docs-cn/v3.1/reference/configuration/tikv-server/configuration-file/)
 
 > **注意：**
 >
@@ -63,7 +63,7 @@ spec:
 
 ## 配置 PD 配置参数
 
-你可以通过 `TidbCluster.Spec.Pd.Config` 来配置 PD 配置参数，以下是一个例子。获取所有可以配置的 PD 配置参数，请参考 [PD 配置文档](https://pingcap.com/docs-cn/v3.1/reference/configuration/pd-server/configuration-file/)
+你可以通过 TidbCluster Custom Resource 的 `spec.pd.config` 来配置 PD 配置参数，以下是一个例子。获取所有可以配置的 PD 配置参数，请参考 [PD 配置文档](https://pingcap.com/docs-cn/v3.1/reference/configuration/pd-server/configuration-file/)
 
 > **注意：**
 >
@@ -82,3 +82,22 @@ spec:
       format: "format"
       disable-timestamp: false
 ```
+
+## 配置 TiFlash 配置参数
+
+你可以通过 TidbCluster Custom Resource 的 `spec.tiflash.config` 来配置 TiFlash 配置参数，以下是一个例子。
+
+```yaml
+apiVersion: pingcap.com/v1alpha1
+kind: TidbCluster
+metadata:
+  name: basic
+spec:
+  ...
+  tiflash:
+    config:
+      config:
+        logger:
+          count: 5
+          level: information
+```
diff --git a/zh/deploy-on-general-kubernetes.md b/zh/deploy-on-general-kubernetes.md
@@ -31,6 +31,44 @@ category: how-to
 
 默认条件下，修改配置不会自动应用到 TiDB 集群中，只有在 Pod 重启时，才会重新加载新的配置文件，建议设置 `spec.configUpdateStrategy` 为 `RollingUpdate` 开启配置自动更新特性，在每次配置更新时，自动对组件执行滚动更新，将修改后的配置应用到集群中。
 
+如果要在集群中开启 TiFlash，需要在 `${cluster_name}/tidb-cluster.yaml` 文件中配置 `spec.pd.config.replication.enable-placement-rules: "true"`，并配置 `spec.tiflash`：
+
+```yaml
+  pd:
+    config:
+      ...
+      replication:
+        enable-placement-rules: "true"
+        ...
+  tiflash:
+    baseImage: pingcap/tiflash
+    maxFailoverCount: 3
+    replicas: 1
+    storageClaims:
+    - resources:
+        requests:
+          storage: 100Gi
+      storageClassName: local-storage
+```
+
+TiFlash 支持挂载多个 PV，如果要为 TiFlash 配置多个 PV，可以在 `tiflash.storageClaims` 下面配置多项，每一项可以分别配置 `storage reqeust` 和 `storageClassName`，例如：
+
+```yaml
+  tiflash:
+    baseImage: pingcap/tiflash
+    maxFailoverCount: 3
+    replicas: 1
+    storageClaims:
+    - resources:
+        requests:
+          storage: 100Gi
+      storageClassName: local-storage
+    - resources:
+        requests:
+          storage: 100Gi
+      storageClassName: local-storage
+```
+
 如果要部署 TiDB 集群监控，请参考 TidbMonitor [示例](https://github.com/pingcap/tidb-operator/blob/master/manifests/monitor/tidb-monitor.yaml)和 [API 文档](api-references.md)（示例和 API 文档请切换到当前使用的 TiDB Operator 版本）完成 TidbMonitor CR，并保存到文件 `${cluster_name}/tidb-monitor.yaml`。
 
 ### 存储类型

diff --git a/zh/deploy-tiflash.md b/zh/deploy-tiflash.md
@@ -0,0 +1,62 @@
+---
+title: 在 Kubernetes 上部署 TiFlash
+summary: 了解如何在 Kubernetes 上部署 TiFlash。
+category: how-to
+---
+
+# 在 Kubernetes 上部署 TiFlash
+
+本文介绍如何在 Kubernetes 上部署 TiFlash。
+
+## 前置条件
+
+* TiDB Operator [部署](deploy-tidb-operator.md)完成。
+
+## 全新部署 TiDB 集群同时部署 TiFlash
+
+参考 [在标准 Kubernetes 上部署 TiDB 集群](deploy-on-general-kubernetes.md)进行部署。
+
+## 在现有 TiDB 集群上新增 TiFlash 组件
+
+编辑 TidbCluster Custom Resource：
+
+{{< copyable "shell-regular" >}}
+
+``` shell
+kubectl eidt tc ${cluster_name} -n ${namespace}
+```
+
+按照如下示例增加 TiFlash 配置：
+
+```yaml
+spec:
+  tiflash:
+    baseImage: pingcap/tiflash
+    maxFailoverCount: 3
+    replicas: 1
+    storageClaims:
+    - resources:
+        requests:
+          storage: 100Gi
+      storageClassName: local-storage
+```
+
+TiFlash 支持挂载多个 PV，如果要为 TiFlash 配置多个 PV，可以在 `tiflash.storageClaims` 下面配置多项，每一项可以分别配置 `storage reqeust` 和 `storageClassName`，例如：
+
+```yaml
+  tiflash:
+    baseImage: pingcap/tiflash
+    maxFailoverCount: 3
+    replicas: 1
+    storageClaims:
+    - resources:
+        requests:
+          storage: 100Gi
+      storageClassName: local-storage
+    - resources:
+        requests:
+          storage: 100Gi
+      storageClassName: local-storage
+```
+
+[新增部署 TiFlash](https://pingcap.com/docs-cn/stable/reference/tiflash/deploy/#%E5%9C%A8%E5%8E%9F%E6%9C%89-tidb-%E9%9B%86%E7%BE%A4%E4%B8%8A%E6%96%B0%E5%A2%9E-tiflash-%E7%BB%84%E4%BB%B6) 需要 PD 配置 `replication.enable-placement-rules: "true"`，通过上述步骤在 TidbCluster 中增加 TiFlash 配置后，TiDB Operator 会自动为 PD 配置 `replication.enable-placement-rules: "true"`。
diff --git a/zh/scale-a-tidb-cluster.md b/zh/scale-a-tidb-cluster.md
@@ -12,6 +12,11 @@ category: how-to
 
 TiDB 水平扩缩容操作指的是通过增加或减少节点的数量，来达到集群扩缩容的目的。扩缩容 TiDB 集群时，会按照填入的 replicas 值，对 PD、TiKV、TiDB 进行顺序扩缩容操作。扩容操作按照节点编号由小到大增加节点，缩容操作按照节点编号由大到小删除节点。目前 TiDB 集群有通过 Helm 与使用 TidbCluster Custom Resource (CR) 两种管理方式，你可以根据 TiDB 集群的管理方式选择对应的方式进行伸缩。
 
+### 水平扩缩容操作 (CR)
+
+使用 kubectl 修改集群所对应的 `TidbCluster` 对象中的 `spec.pd.replicas`、`spec.tidb.replicas`、`spec.tikv.replicas` 至期望值。
+如果集群中部署了 TiFlash，可以通过修改 `spec.tiflash.replicas` 对 TiFlash 进行扩缩容。
+
 ### 水平扩缩容操作 (Helm)
 
 1. 修改集群的 `value.yaml` 文件中的 `pd.replicas`、`tidb.replicas`、`tikv.replicas` 至期望值。
@@ -24,10 +29,6 @@ TiDB 水平扩缩容操作指的是通过增加或减少节点的数量，来达
     helm upgrade ${release_name} pingcap/tidb-cluster -f values.yaml --version=${chart_version}
     ```
 
-### 水平扩缩容操作 (CR)
-
-使用 kubectl 修改集群所对应的 `TidbCluster` 对象中的 `spec.pd.replicas`、`spec.tidb.replicas`、`spec.tikv.replicas` 至期望值。
-
 ### 查看集群水平扩缩容状态
 
 {{< copyable "shell-regular" >}}
@@ -40,15 +41,21 @@ watch kubectl -n ${namespace} get pod -o wide
 
 > **注意：**
 >
-> - PD、TiKV 组件在滚动升级的过程中不会触发扩缩容操作。
-> - TiKV 组件在缩容过程中会调用 PD 接口将对应 TiKV 标记为下线，然后将其上数据迁移到其它 TiKV 节点，在数据迁移期间 TiKV Pod 依然是 `Running` 状态，数据迁移完成后对应 Pod 才会被删除，缩容时间与待缩容的 TiKV 上的数据量有关，可以通过 `kubectl get tidbcluster -n ${namespace} ${release_name} -o json | jq '.status.tikv.stores'` 查看 TiKV 是否处于下线 `Offline` 状态。
-> - PD、TiKV 组件在缩容过程中被删除的节点的 PVC 会保留，并且由于 PV 的 `Reclaim Policy` 设置为 `Retain`，即使 PVC 被删除，数据依然可以找回。
+> - PD、TiKV、TiFlash 组件在滚动升级的过程中不会触发扩缩容操作。
+> - TiKV 组件在缩容过程中，TiDB Operator 会调用 PD 接口将对应 TiKV 标记为下线，然后将其上数据迁移到其它 TiKV 节点，在数据迁移期间 TiKV Pod 依然是 `Running` 状态，数据迁移完成后对应 Pod 才会被删除，缩容时间与待缩容的 TiKV 上的数据量有关，可以通过 `kubectl get tidbcluster -n ${namespace} ${release_name} -o json | jq '.status.tikv.stores'` 查看 TiKV 是否处于下线 `Offline` 状态。
 > - TiKV 组件不支持在缩容过程中进行扩容操作，强制执行此操作可能导致集群状态异常。假如异常已经发生，可以参考 [TiKV Store 异常进入 Tombstone 状态](troubleshoot.md#tikv-store-异常进入-tombstone-状态) 进行解决。
+> - TiFlash 组件缩容处理逻辑和 TiKV 组件相同。
+> - PD、TiKV、TiFlash 组件在缩容过程中被删除的节点的 PVC 会保留，并且由于 PV 的 `Reclaim Policy` 设置为 `Retain`，即使 PVC 被删除，数据依然可以找回。
 
 ## 垂直扩缩容
 
 垂直扩缩容操作指的是通过增加或减少节点的资源限制，来达到集群扩缩容的目的。垂直扩缩容本质上是节点滚动升级的过程。目前 TiDB 集群有通过 Helm 与使用 TidbCluster Custom Resource (CR) 两种管理方式，你可以根据 TiDB 集群的管理方式选择对应的方式进行伸缩。
 
+### 垂直扩缩容操作 (CR)
+
+通过 kubectl 修改集群所对应的 `TidbCluster` 对象的 `spec.pd.resources`、`spec.tikv.resources`、`spec.tidb.resources` 至期望值。
+如果集群中部署了 TiFlash，可以通过修改 `spec.tiflash.resources` 对 TiFlash 进行垂直扩缩容。
+
 ### 垂直扩缩容操作 (Helm)
 
 1. 修改 `values.yaml` 文件中的 `tidb.resources`、`tikv.resources`、`pd.resources` 至期望值。
@@ -61,10 +68,6 @@ watch kubectl -n ${namespace} get pod -o wide
     helm upgrade ${release_name} pingcap/tidb-cluster -f values.yaml --version=${chart_version}
     ```
 
-### 垂直扩缩容操作 (CR)
-
-通过 kubectl 修改集群所对应的 `TidbCluster` 对象的 `spec.pd.resources`、`spec.tikv.resources`、`spec.tidb.resources` 至期望值。
-
 ### 查看升级进度
 
 {{< copyable "shell-regular" >}}
@@ -77,5 +80,5 @@ watch kubectl -n ${namespace} get pod -o wide
 
 > **注意：**
 >
-> - 如果在垂直扩容时修改了资源的 `requests` 字段，由于 PD、TiKV 使用了 `Local PV`，升级后还需要调度回原节点，如果原节点资源不够，则会导致 Pod 一直处于 `Pending` 状态而影响服务。
+> - 如果在垂直扩容时修改了资源的 `requests` 字段，并且 PD、TiKV、TiFlash 使用了 `Local PV`，那升级后 Pod 还会调度回原节点，如果原节点资源不够，则会导致 Pod 一直处于 `Pending` 状态而影响服务。
 > - TiDB 作为一个可水平扩展的数据库，推荐通过增加节点个数发挥 TiDB 集群可水平扩展的优势，而不是类似传统数据库升级节点硬件配置来实现垂直扩容。
diff --git a/zh/use-auto-failover.md b/zh/use-auto-failover.md
@@ -32,9 +32,11 @@ controllerManager:
  tikvFailoverPeriod: 5m
  # tidb failover period default(5m)
  tidbFailoverPeriod: 5m
+ # tiflash failover period default(5m)
+ tiflashFailoverPeriod: 5m
 ```
 
-`pdFailoverPeriod`、`tikvFailoverPeriod` 和 `tidbFailoverPeriod` 默认均为 5 分钟，它们的含义是在确认实例故障后的等待超时时间，超过这个时间后，TiDB Operator 就开始做自动的故障转移。
+`pdFailoverPeriod`、`tikvFailoverPeriod`、`tiflashFailoverPeriod` 和 `tidbFailoverPeriod` 默认均为 5 分钟，它们的含义是在确认实例故障后的等待超时时间，超过这个时间后，TiDB Operator 就开始做自动的故障转移。
 
 ## 实现原理
 
@@ -84,3 +86,38 @@ status
 ### TiDB 故障转移策略
 
 假设 TiDB 集群有 3 个节点，TiDB 的故障转移策略跟 Kubernetes 中的 `Deployment` 的是一致的。如果一个 TiDB 节点挂掉超过 5 分钟（`tidbFailoverPeriod` 可配置），TiDB Operator 会添加一个新的 TiDB 节点。此时会有 4 个 Pod 同时存在，待挂掉的 TiDB 节点恢复后，TiDB Operator 会将新启动的节点删除掉，恢复成原来的 3 个节点。
+
+### TiFlash 故障转移策略
+
+当一个 TiFlash 节点无法正常工作后，该节点的状态会变为 `Disconnected`，30 分钟（通过 `pd.config` 文件中 `[schedule]` 部分的 `max-store-down-time = "30m"` 来配置）后会变成 `Down` 状态，TiDB Operator 会在此基础上再等待 5 分钟（`tiflashFailoverPeriod` 可配置），如果该 TiFlash 节点仍不能恢复，就会新起一个 TiFlash 节点。待挂掉的 TiFlash 节点恢复后，TiDB Operator 不会自动删除新起的节点，用户需要手动减少 TiFlash 节点，恢复成原来的节点数。操作方法是将该 TiFlash 节点从 `TidbCluster` 对象的 `status.tiflash.failureStores` 字段中删除。
+
+示例如下，假如有两个 TiFlash Pod 异常：
+
+{{< copyable "shell-regular" >}}
+
+```shell
+kubectl edit tc -n ${namespace} ${cluster_name}
+```
+
+```
+status
+  tiflash:
+    failureStores:
+      "1":
+        podName: cluster1-tiflash-0
+        storeID: "1"
+      "2":
+        podName: cluster1-tiflash-1
+        storeID: "2"
+```
+
+`cluster1-tiflash-0` Pod 恢复后，将其删除后变为：
+
+```
+status
+  tiflash:
+    failureStores:
+      "2":
+        podName: cluster1-tiflash-1
+        storeID: "2"
+```