使用 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 版本

在中控机器上安装 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.6jmespath ≧ 0.9.0。为方便管理依赖,建议使用 pip 安装 TiDB Ansible 及其依赖,可参照在中控机器上安装 TiDB Ansible 及其依赖 进行安装。离线环境参照在中控机器上离线安装 TiDB Ansible 及其依赖

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

ansible --version
ansible 2.7.11
pip show jinja2
Name: Jinja2 Version: 2.10
pip show jmespath
Name: jmespath Version: 0.9.0

在中控机器上下载 TiDB Ansible

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

mv tidb-ansible tidb-ansible-bak

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

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

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

tidb 用户登录中控机并进入 /home/tidb/tidb-ansible 目录。

编辑 inventory.ini 文件

编辑 inventory.ini 文件,IP 信息参照备份文件 /home/tidb/tidb-ansible-bak/inventory.ini

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

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

    ## Connection # ssh via normal user ansible_user = tidb

    可参考如何配置 SSH 互信及 sudo 规则自动配置主机间互信。

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

    # process supervision, [systemd, supervise] process_supervision = systemd

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

编辑 TiDB 集群组件配置文件

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

注意以下参数变更:

  • TiKV 配置中 end-point-concurrency 变更为 high-concurrencynormal-concurrencylow-concurrency 三个参数:

    readpool: coprocessor: # Notice: if CPU_NUM > 8, default thread pool size for coprocessors # will be set to CPU_NUM * 0.8. # high-concurrency: 8 # normal-concurrency: 8 # low-concurrency: 8
  • TiKV 配置中不同 CF 中的 block-cache-size 参数变更为 block-cache

    storage: block-cache: capacity: "1GB"
  • TiKV 配置中单机多实例场景需要额外配置 tikv_status_port 端口:

    [tikv_servers] TiKV1-1 ansible_host=172.16.10.4 deploy_dir=/data1/deploy tikv_port=20171 tikv_status_port=20181 labels="host=tikv1" TiKV1-2 ansible_host=172.16.10.4 deploy_dir=/data2/deploy tikv_port=20172 tikv_status_port=20182 labels="host=tikv1" TiKV2-1 ansible_host=172.16.10.5 deploy_dir=/data1/deploy tikv_port=20171 tikv_status_port=20181 labels="host=tikv2" TiKV2-2 ansible_host=172.16.10.5 deploy_dir=/data2/deploy tikv_port=20172 tikv_status_port=20182 labels="host=tikv2" TiKV3-1 ansible_host=172.16.10.6 deploy_dir=/data1/deploy tikv_port=20171 tikv_status_port=20181 labels="host=tikv3" TiKV3-2 ansible_host=172.16.10.6 deploy_dir=/data2/deploy tikv_port=20172 tikv_status_port=20182 labels="host=tikv3"

下载 TiDB latest binary 到中控机

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

ansible-playbook local_prepare.yml

滚动升级 TiDB 集群组件

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

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

      ansible-playbook excessive_rolling_update.yml
    • 当前集群版本 ≥ 3.0.0,滚动升级及日常滚动重启 TiDB 集群,使用 rolling_update.yml

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

    ansible-playbook rolling_update.yml

滚动升级 TiDB 监控组件

ansible-playbook rolling_update_monitor.yml