使用 TiDB Ansible 升级 TiDB

    本文档适用于从 TiDB 2.0、2.1、3.0、3.1 版本升级至 TiDB 4.0 版本以及 TiDB 4.0 的低版本升级至 TiDB 4.0 高版本。目前，TiDB 4.0 版本兼容 TiDB Binlog Cluster 版本。

    • 不支持在升级后回退至 3.1.x 或更旧版本
    • 从 2.0.6 之前的版本升级到 4.0 之前，需要确认集群中是否存在正在运行中的 DDL 操作，特别是耗时的 Add Index 操作，等 DDL 操作完成后再执行升级操作
    • 2.1 及之后版本启用了并行 DDL，早于 2.0.1 版本的集群，无法滚动升级到 4.0 版本，可以选择下面两种方案：
      • 停机升级，直接从早于 2.0.1 的 TiDB 版本升级到 4.0 版本
      • 先滚动升级到 2.0.1 或者之后的 2.0.x 版本，再滚动升级到 4.0 版本

    注意：

    在升级的过程中不要执行 DDL 请求，否则可能会出现行为未定义的问题。

    在中控机器上安装 TiDB Ansible 及其依赖

    TiDB Ansible 最新开发版依赖 2.5.0 及以上但不高于 2.7.11 的 Ansible 版本（2.5.0 ≦ ansible ≦ 2.7.11，建议 2.7.11 版本），另依赖 Python 模块：jinja2 ≧ 2.9.6 和 jmespath ≧ 0.9.0。为方便管理依赖，建议使用 pip 安装 TiDB Ansible 及其依赖，可参照在中控机器上安装 TiDB Ansible 及其依赖 进行安装。离线环境参照。

    安装完成后，可通过以下命令查看版本：

    1. ansible 2.7.11
    1. pip show jinja2
    1. Version: 2.10
    1. pip show jmespath
    1. Name: jmespath
    2. Version: 0.9.0

    注意：

    请务必按以上文档安装 TiDB Ansible 及其依赖。确认 Jinja2 版本是否正确，否则启动 Grafana 时会报错。确认 jmespath 版本是否正确，否则滚动升级 TiKV 时会报错。

    以 tidb 用户登录中控机并进入 /home/tidb 目录，备份 TiDB 2.0、2.1、3.0、3.1 或其他低版本的 tidb-ansible 文件夹：

    下载 TiDB 4.0 版本对应的 TiDB Ansible，默认的文件夹名称为 tidb-ansible。$tag 需替换为选定的 TAG 版本的值，例如 v4.0.0-rc。

    1. git clone -b $tag https://github.com/pingcap/tidb-ansible.git

    编辑 inventory.ini 文件和配置文件

    编辑 inventory.ini 文件，IP 信息参照备份文件 。

    以下变量配置，需要重点确认，变量含义可参考 inventory.ini 变量调整。

    1. 请确认 ansible_user 配置的是普通用户。为统一权限管理，不再支持使用 root 用户远程安装。默认配置中使用 tidb 用户作为 SSH 远程用户及程序运行用户。

      1.  ## Connection
      2.  # ssh via normal user
      3.  ansible_user = tidb

      可参考自动配置主机间互信。

    2. process_supervision 变量请与之前版本保持一致，默认推荐使用 systemd。

      1.  # process supervision, [systemd, supervise]
      2.  process_supervision = systemd

      如需变更，可参考如何调整进程监管方式从 supervise 到 systemd，先使用备份 /home/tidb/tidb-ansible-bak/ 分支变更进程监管方式再升级。

    编辑 TiDB 集群组件配置文件

    如之前自定义过 TiDB 集群组件配置文件，请参照备份文件修改 /home/tidb/tidb-ansible/conf 下对应配置文件。

    注意以下参数变更：

    • TiKV 配置中 end-point-concurrency 变更为 high-concurrency、normal-concurrency 和 low-concurrency 三个参数：

      1.   readpool:
      2.     coprocessor:
      3.       # Notice: if CPU_NUM > 8, default thread pool size for coprocessors
      4.       # high-concurrency: 8
      5.       # normal-concurrency: 8
      6.       # low-concurrency: 8
      1.   storage:
      2.     block-cache:
      3.       capacity: "1GB"

      注意：

      单机多 TiKV 实例（进程）情况下，需要修改 capacity 参数。如果当前版本已经是新的配置，则不需要再修改。

      推荐设置：capacity = (MEM_TOTAL * 0.5 / TiKV 实例数量)

    • TiKV 配置中单机多实例场景需要额外配置 tikv_status_port 端口：

    确认 tidb-ansible/inventory.ini 文件中 tidb_version = v4.0.x，然后执行以下命令下载 TiDB 4.0 binary 到中控机。

    1. ansible-playbook local_prepare.yml

    滚动升级 TiDB 集群组件

    • 如果 process_supervision 变量使用默认的 systemd 参数：

      • 当前集群版本 < 3.0，则通过 excessive_rolling_update.yml 滚动升级 TiDB 集群。

        1.   ansible-playbook excessive_rolling_update.yml

      • 当前集群版本 ≥ 3.0.0，滚动升级及日常滚动重启 TiDB 集群，使用 rolling_update.yml。

        1.   ansible-playbook rolling_update.yml

    • 如果 process_supervision 变量使用的是 supervise 参数，无论当前集群为哪个版本，均通过 rolling_update.yml 来滚动升级 TiDB 集群。

      1.   ansible-playbook rolling_update.yml

      TiDB（v4.0.2 起）默认会定期收集使用情况信息，并将这些信息分享给 PingCAP 用于改善产品。若要了解所收集的信息详情及如何禁用该行为，请参见。