From d51704c316339898a8c671fd3c63ac852ccd09a9 Mon Sep 17 00:00:00 2001 From: DanielZhangQD <36026334+DanielZhangQD@users.noreply.github.com> Date: Thu, 30 Apr 2020 19:07:32 +0800 Subject: [PATCH] update doc for tiflash (#236) --- zh/TOC.md | 1 + zh/configure-cluster-using-tidbcluster.md | 27 ++++++++-- zh/deploy-on-general-kubernetes.md | 38 ++++++++++++++ zh/deploy-tiflash.md | 62 +++++++++++++++++++++++ zh/scale-a-tidb-cluster.md | 27 +++++----- zh/use-auto-failover.md | 39 +++++++++++++- 6 files changed, 177 insertions(+), 17 deletions(-) create mode 100644 zh/deploy-tiflash.md diff --git a/zh/TOC.md b/zh/TOC.md index 6a55fa6c3..3a35cf8fe 100644 --- 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 index 3995fa4d2..e5c1b0565 100644 --- 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 +``` \ No newline at end of file diff --git a/zh/deploy-on-general-kubernetes.md b/zh/deploy-on-general-kubernetes.md index 0a9c663f0..3442dcb5d 100644 --- 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 new file mode 100644 index 000000000..46c101596 --- /dev/null +++ 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 index 7148a60fb..b1f76c8f0 100644 --- 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 index 54e901253..644e3bf76 100644 --- 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" +```