Merge pull request #766 from LinuxGit/Louis/refine-deployment-docs

*: refine ansible deployment docs
pingcap · Jun 19, 2018 · 9dc8eac · 9dc8eac
2 parents d3e96b7 + c547012
commit 9dc8eac
Show file tree

Hide file tree

Showing 13 changed files with 863 additions and 1,175 deletions.
diff --git a/QUICKSTART.md b/QUICKSTART.md
diff --git a/README.md b/README.md
@@ -78,31 +78,32 @@
   + 部署集群
     - [Ansible 部署方案（强烈推荐）](op-guide/ansible-deployment.md)
     - [离线 Ansible 部署方案](op-guide/offline-ansible-deployment.md)
-    - [TiDB 2.0 升级操作指南](op-guide/tidb-v2-upgrade-guide.md)
     - [Docker 部署方案](op-guide/docker-deployment.md)
     - [Docker Compose 部署方案](op-guide/docker-compose.md)
     - [跨机房部署方案](op-guide/location-awareness.md)
   + 配置集群
     - [参数解释](op-guide/configuration.md)
     - [TiDB 配置项解释](op-guide/tidb-config-file.md)
+    - [使用 Ansible 变更组件配置](op-guide/ansible-deployment-rolling-update.md#变更组件配置)
     - [开启 TLS 验证](op-guide/security.md)
     - [生成自签名证书](op-guide/generate-self-signed-certificates.md)
   + 监控集群
     - [整体监控框架概述](op-guide/monitor-overview.md)
     - [重要监控指标详解](op-guide/dashboard-overview-info.md)
     - [组件状态 API & 监控](op-guide/monitor.md)
   + 扩容缩容
-     - [使用 Ansible 扩容缩容](QUICKSTART.md#tidb-集群扩容缩容方案)
-     - [集群扩容缩容方案](op-guide/horizontal-scale.md)
-  - [升级](op-guide/ansible-deployment.md#滚动升级)
+    - [集群扩容缩容方案](op-guide/horizontal-scale.md)
+    - [使用 Ansible 扩容缩容](op-guide/ansible-deployment-scale.md)
+  + 升级
+    - [升级组件版本](op-guide/ansible-deployment-rolling-update.md#升级组件版本)
+    - [TiDB 2.0 升级操作指南](op-guide/tidb-v2-upgrade-guide.md)
   - [性能调优](op-guide/tune-tikv.md)
   + 备份与迁移
     - [备份与恢复](op-guide/backup-restore.md)
     + 数据迁移
       - [数据迁移概述](op-guide/migration-overview.md)
       - [全量导入](op-guide/migration.md#使用-mydumperloader-全量导入数据)
       - [增量导入](op-guide/migration.md#使用-syncer-增量导入数据)
-  - [Binary 部署方案](op-guide/binary-deployment.md)
   - [故障诊断](trouble-shooting.md)
 + TiDB 周边工具
   - [Syncer](tools/syncer.md)
@@ -150,7 +151,7 @@
   - [一面数据](http://t.cn/RT9r5di)
   - [凤凰网](http://t.cn/RHRQfNT)
   - [猿辅导](http://t.cn/RTKnKSX)
-  - [Mobikok](http://t.cn/Rm1F6lg)
+  - [Mobikok](http://t.cn/Rm1F6lg)
   - [二维火](http://t.cn/R8bXM2f)
   - [客如云](http://t.cn/R1wSEJH)
   - [Ping++](http://t.cn/RE5xYKn)

diff --git a/op-guide/ansible-deployment-rolling-update.md b/op-guide/ansible-deployment-rolling-update.md
@@ -0,0 +1,116 @@
+---
+title: 使用 TiDB Ansible 升级 TiDB 集群
+category: deployment
+---
+
+# 使用 TiDB Ansible 升级 TiDB 集群
+
+滚动升级 TiDB 集群时，会串行关闭服务，更新服务 binary 和配置文件，再启动服务。在前端配置负载均衡的情况下，滚动升级期间不影响业务运行（最小环境 ：pd * 3 、tidb * 2、tikv * 3）。
+
+> **注**：
+> 如果 TiDB 集群开启了 binlog，部署了 pump 和 drainer 服务，升级 TiDB 服务时会升级 pump，请先停止 drainer 服务再执行滚动升级操作。
+
+## 升级组件版本
+
+> **注**：
+> 跨大版本升级，需要更新 `tidb-ansible`，从 TiDB 1.0 升级到 TiDB 2.0，请参考 [TiDB 2.0 升级操作指南](tidb-v2-upgrade-guide.md)。
+
+### 自动下载 binary
+
+1.  修改 `/home/tidb/tidb-ansible/inventory.ini` 中的 `tidb_version` 参数值，指定需要升级的版本号，如从 `v2.0.2` 升级到 `v2.0.3`
+
+    ```
+    tidb_version = v2.0.3
+    ```
+
+2.  删除原有的 downloads 目录 `/home/tidb/tidb-ansible/downloads/`
+
+    ```
+    $ cd /home/tidb/tidb-ansible
+    $ rm -rf downloads
+    ```
+
+3.  使用 playbook 下载 TiDB `v2.0.3` 版本 binary，自动替换 binary 到 `/home/tidb/tidb-ansible/resource/bin/`
+
+    ```
+    $ ansible-playbook local_prepare.yml
+    ```
+
+### 手动下载 binary
+
+1.  除 “下载 binary” 中描述的方法之外，也可以手动下载 binary，解压后手动替换 binary 到 `/home/tidb/tidb-ansible/resource/bin/`，请注意替换链接中的版本号。
+
+    ```
+    wget http://download.pingcap.org/tidb-v2.0.3-linux-amd64-unportable.tar.gz
+    ```
+
+### 使用 Ansible 滚动升级
+
+- 滚动升级 PD 节点（只升级单独 PD 服务）
+
+    ```
+    $ ansible-playbook rolling_update.yml --tags=pd
+    ```
+   
+  如果 PD 实例数大于等于 3，滚动升级 PD leader 实例时，Ansible 会先迁移 PD leader 到其他节点再关闭该实例。
+
+- 滚动升级 TiKV 节点（只升级 TiKV 服务）
+
+    ```
+    $ ansible-playbook rolling_update.yml --tags=tikv
+    ```
+
+   滚动升级 TiKV 实例时，Ansible 会迁移 region leader 到其他节点。具体逻辑为：调用 PD API 添加 evict leader scheduler，每 10 秒探测一次该 TiKV 实例 leader_count， 等待 leader_count 降到 10 以下（或 为空）或探测超 12 次后，即两分钟超时后，开始关闭 TiKV 升级，启动成功后再去除 evict leader scheduler，串行操作。
+
+   如中途升级失败，请登录 pd-ctl 执行 scheduler show，查看是否有 evict-leader-scheduler, 如有需手工清除。`{PD_IP}` 和 `{STORE_ID}` 请替换为你的 PD IP 及 TiKV 实例的 store_id 。
+
+    ```
+    $ /home/tidb/tidb-ansible/resources/bin/pd-ctl -u "http://{PD_IP}:2379" -d scheduler show
+    $ curl -X DELETE "http://{PD_IP}:2379/pd/api/v1/schedulers/evict-leader-scheduler-{STORE_ID}"
+    ```
+
+- 滚动升级 TiDB 节点（只升级单独 TiDB 服务，如果 TiDB 集群开启了 binlog，升级 TiDB 服务时会升级 pump）
+
+    ```
+    $ ansible-playbook rolling_update.yml --tags=tidb
+    ```
+
+- 滚动升级所有服务（依次升级 PD，TiKV，TiDB 服务，如果 TiDB 集群开启了 binlog，升级 TiDB 服务时会升级 pump）
+
+    ```
+    $ ansible-playbook rolling_update.yml
+    ```
+
+- 滚动升级监控组件
+
+    ```
+    $ ansible-playbook rolling_update_monitor.yml
+    ```
+
+## 变更组件配置
+
+1. 更新组件配置模板
+
+TiDB 集群组件配置模板存储在 `/home/tidb/tidb-ansible/conf` 文件夹下。
+
+| 组件       | 配置文件模板名     |
+| :-------- | :----------: |
+| TiDB | tidb.yml  |
+| TiKV | tikv.yml  |
+| PD | pd.yml  |
+
+默认配置项是注释状态，使用默认值。如果需要修改，需取消注释，即去除 `#`，修改对应参数值。配置模板使用 yaml 格式，注意参数名及参数值之间使用 `:` 分隔，缩进为两个空格。
+
+如修改 TiKV 配置中  `high-concurrency`、`normal-concurrency` 和 `low-concurrency` 三个参数为 16：
+
+```
+readpool:
+  coprocessor:
+    # Notice: if CPU_NUM > 8, default thread pool size for coprocessors
+    # will be set to CPU_NUM * 0.8.
+    high-concurrency: 16
+    normal-concurrency: 16
+    low-concurrency: 16
+```
+
+2. 修改服务配置后，需使用 Ansible 滚动升级，参考[使用 Ansible 滚动升级](#使用-Ansible-滚动升级)。