tiup cluster upgrade
命令 tiup cluster upgrade 用于将指定集群升级到特定版本。
语法
tiup cluster upgrade <cluster-name> <version> [flags]<cluster-name>为要操作的集群名字，如果忘记集群名字可通过集群列表查看。<version>为要升级到的目标版本，例如v7.1.8-5.2。目前仅允许升级到比当前集群更高的版本，不允许升级到比当前集群更低的版本，即不允许降级。同时也不允许升级成 nightly 版本。
例如，仅升级 TiDB 和 TiKV，并在每个实例开始升级前确认：
tiup cluster upgrade tidb-test v7.1.8-5.2 --role tidb,tikv --confirm-each-instance选项
--force
- 升级集群需要保证集群目前是启动的，在某些情况下，可能希望在集群未启动的状态下升级，这时候可以使用
--force忽略升级过程的错误，强制替换二进制文件并启动集群。 - 数据类型：
BOOLEAN - 该选项默认关闭，默认值为
false。在命令中添加该选项，并传入true值或不传值，均可开启此功能。
注意
对正在提供服务的集群强制升级可能导致集群服务不可用。对于未启动的集群，升级成功后会自动启动集群。
--transfer-timeout（uint，默认 600）
在升级 PD 或 TiKV 时，会先将被升级节点的 leader 迁移到其他节点，迁移过程会需要一定时间，可以通过设置 --transfer-timeout 设置最长等待时间（单位为秒），超时之后会跳过等待直接升级服务。
注意
若出现跳过等待直接升级的情况，服务性能可能会出现抖动。
--region-load-timeout（uint，默认 120）
PD 重启后，如果目标 PD 版本支持 ready API，TiUP 会等待 PD 完成 Region 加载。该选项用于设置等待 pd/api/v2/ready 就绪的超时时间（单位为秒）。
该选项仅影响 PD 重启后的 ready API/Region 加载等待，不会修改服务重启超时、Leader 迁移超时或其他操作的通用等待超时。PD ready API 支持上游 v8.5.2 及更高版本，以及 Pingkai v7.1.8-5.2 和后续 v7.1.8-5.x 版本。
例如，将 PD Region 加载等待时间设置为 300 秒：
tiup cluster upgrade tidb-test v7.1.8-5.2 -R pd --region-load-timeout 300--ignore-config-check
- 在二进制文件更新之后，TiUP 会对 TiDB，TiKV 和 PD 组件执行配置检查，检查方式为
<binary> --config-check <config-file>，其中<binary>为新部署的二进制文件的路径，<config-file>为根据用户配置生成的配置文件。如果想要跳过该项检查，可以使用该选项。 - 数据类型：
BOOLEAN - 该选项默认关闭，默认值为
false。在命令中添加该选项，并传入true值或不传值，均可开启此功能。
--ignore-version-check
- 在升级前，TiUP 会检查目标版本是否大于等于当前版本。如果想要跳过该项检查，可以使用该选项。
- 数据类型：
BOOLEAN - 该选项默认关闭，默认值为
false。在命令中添加该选项，并传入true值或不传值，均可开启此功能。
--offline
- 声明当前集群处于停止状态。指定该选项时，TiUP Cluster 仅原地替换集群组件的二进制文件，不执行迁移 Leader 以及重启服务等操作。
--offline不能与--confirm-each-instance（或其--interactive别名）同时使用。- 数据类型：
BOOLEAN - 该选项默认关闭，默认值为
false。在命令中添加该选项，并传入true值或不传值，均可开启此功能。
-R, --role
- 仅升级指定的组件或角色。参数为以逗号分隔的列表，也可以重复指定此选项；参数中的空格会被忽略，重复项会自动去重。
- 例如，
--role tidb,tikv和-R tidb -R tikv等价。支持的名称包括tidb、tikv、pd、tiflash、cdc（TiCDC）、tiproxy、prometheus、grafana、alertmanager等当前拓扑中的组件角色。 - 未指定此选项时，升级所有需要升级的组件。指定的组件不存在或没有可升级实例时，命令会在执行升级前返回错误。
- 数据类型：
STRINGS - 默认值：
[]
--components
--components是--role的兼容别名，用法相同。- 该选项已弃用，新的脚本和命令请使用
-R或--role。
--confirm-each-instance
- 在每个选定实例开始升级前显示组件、实例、端口、当前版本和目标版本，并等待输入。直接回车或输入
y/yes/continue继续，输入n/no/skip跳过当前实例，输入q/quit停止剩余升级。 - 跳过只影响当前实例；停止不会回滚已经完成的实例，尚未执行的实例会保留为未执行状态，整个集群不会被标记为已完成升级。
- 交互模式会将并发数强制设置为
1，并在每个实例成功升级及健康检查后再执行--restart-timeout等待。部分组件升级可能产生临时的混合版本，请在确认前检查组件兼容性。 - 此选项需要交互式终端。非 TTY（例如 CI）环境会输出告警并自动回退为非交互式升级，不会阻塞输入。
- 数据类型：
BOOLEAN - 默认值：
false
--interactive
--interactive是--confirm-each-instance的兼容别名，用于逐实例确认升级。- 该选项已弃用，新的脚本和命令请使用
--confirm-each-instance。
--pd-version
- 指定 PD 的版本。指定后，PD 的版本将不再与集群版本保持一致。
- 数据类型：
STRINGS - 不指定该选项时，PD 的版本与集群版本保持一致。
--tikv-version
- 指定 TiKV 的版本。指定后，TiKV 的版本将不再与集群版本保持一致。
- 数据类型：
STRINGS - 不指定该选项时，TiKV 的版本与集群版本保持一致。
--tikv-cdc-version
- 指定 TiKV CDC 的版本。指定后，TiKV CDC 的版本将不再与集群版本保持一致。
- 数据类型：
STRINGS - 不指定该选项时，TiKV CDC 的版本与集群版本保持一致。
--tiflash-version
- 指定 TiFlash 的版本。指定后，TiFlash 的版本将不再与集群版本保持一致。
- 数据类型：
STRINGS - 不指定该选项时，TiFlash 的版本与集群版本保持一致。
--cdc-version
- 指定 TiCDC 的版本。指定后，TiCDC 的版本将不再与集群版本保持一致。
- 数据类型：
STRINGS - 不指定该选项时，TiCDC 的版本与集群版本保持一致。
--tiproxy-version
- 指定 TiProxy 的版本。指定后，TiProxy 的版本将不再与集群版本保持一致。
- 数据类型：
STRINGS - 不指定该选项时，TiProxy 的版本与集群版本保持一致。
--tidb-dashboard-version
- 指定 TiDB Dashboard 的版本。指定后，TiDB Dashboard 的版本将不再与集群版本保持一致。
- 数据类型：
STRINGS - 不指定该选项时，TiDB Dashboard 的版本与集群版本保持一致。
--alertmanager-version
- 指定 alert manager 的版本。指定后，alert manager 的版本将不再与集群版本保持一致。
- 数据类型：
STRINGS - 不指定该选项时，alert manager 的版本与集群版本保持一致。
--restart-timeout
- 指定滚动升级之间的间隔，即在升级组件后等待一段时间。
- 数据类型:
STRINGS。支持所有golang time.ParseDuration能够解析的数据类型。 - 默认值：
0 - 不指定该选项时，升级组件后不会等待。
-h, --help
- 输出帮助信息。
- 数据类型：
BOOLEAN - 该选项默认关闭，默认值为
false。在命令中添加该选项，并传入true值或不传值，均可开启此功能。
--pre-upgrade-script
警告：
该选项目前为实验特性，不建议在生产环境中使用。
- 在升级前运行该脚本。
- 数据类型：
STRINGS - 该选项指定节点在升级前要运行的脚本的路径。
--post-upgrade-script
警告：
该选项目前为实验特性，不建议在生产环境中使用。
- 在升级后运行该脚本。
- 数据类型：
STRINGS - 该选项指定节点在升级后要运行的脚本的路径。该脚本只会在已完成升级的节点上运行。
--local-pre-upgrade-script
警告：
该选项目前为实验特性，不建议在生产环境中使用。
- 在每个实例升级前，在运行 TiUP 的本地机器上运行脚本。
- 数据类型：
STRINGS - 该选项指定本地脚本的路径。
--local-post-upgrade-script
警告：
该选项目前为实验特性，不建议在生产环境中使用。
- 在每个实例升级后，在运行 TiUP 的本地机器上运行脚本。
- 数据类型：
STRINGS - 该选项指定本地脚本的路径；脚本只会在已完成升级的实例上运行。
--skip-leader-balance-wait
- TiKV 实例恢复后，不等待 Region Leader 重新均衡就继续升级后续实例。
- 数据类型：
BOOLEAN - 该选项默认关闭，默认值为
false。
输出
升级服务的日志。交互式升级结束时还会输出已成功、跳过、失败和未执行实例的汇总。