升级 OceanBase 集群

本文将介绍如何使用升级脚本升级 OceanBase 集群。

前提条件

您已在所有的 OBServer 节点中安装 Python 2 的环境，并且安装适配 Python 2 的 mysql.connector 模块。

注意

如果 OceanBase 集群关联了仲裁服务，那么在进行 OceanBase 集群版本升级时，需要确保先升级仲裁服务版本，然后再升级 OceanBase 集群版本。仲裁服务版本升级的详细信息，请参见升级仲裁服务。
可以使用系统租户查询视图 oceanbase.DBA_OB_ARBITRATION_SERVICE 检查本 OceanBase 集群是否关联仲裁服务。更多升级注意信息，请参见升级概述。

操作步骤

注意

在下面步骤执行升级脚本时，指定的 -u 参数必须是 sys 租户有读写及 SUPER 权限的用户。

分析 oceanbase_upgrade_dep.yml 文件。
确认升级流程。
备份集群配置项。
上传并安装目标 RPM 包。
执行脚本 upgrade_checker.py。
执行脚本 upgrade_pre.py。
集群升级。
执行脚本 upgrade_post.py。
还原集群配置项。

步骤一：分析 oceanbase_upgrade_dep.yml 文件

解压目标版本的 OceanBase RPM 包后，可以获取 oceanbase_upgrade_dep.yml 文件，该文件记录了 OceanBase 集群的版本升级拓扑图。步骤如下：

获取目的版本 OceanBase RPM 安装包。

请在 OceanBase 官方网站左上角，单击资源 > 下载中心获取对应版本的 RPM 包。如果未找到对应版本的安装包，请联系技术支持获取目的版本的 RPM 包。
解压 OceanBase RPM 包。

您可以使用以下命令解压 OceanBase RPM 包至当前目录：
```
[xxx@xxx $rpm_dir]# sudo rpm2cpio $rpm_name | cpio -div
```
其中 $rpm_name 表示 RPM 包的名称。

说明

解压 RPM 包完成后，会在存放 RPM 包的目录下生成 home 和 use 两个目录。升级相关脚本和 oceanbase_upgrade_dep.yml 文件存放 home/admin/oceanbase/etc 目录下。
分析 oceanbase_upgrade_dep.yml 文件。

oceanbase_upgrade_dep.yml 文件中相关属性含义：
- version：当前 OceanBase 数据库版本号，以下简称：当前版本。
- can_be_upgraded_to：当前 OceanBase 数据库版本可以升级到的目标版本号，以下简称：目标版本。
- deprecated：当前版本是否可以作为升级的目标版本。若为 true，表示不能作为升级的目标版本。例如：示例中的 4.1.0.0-100000982023031415 版本就不能作为目标版本。
- require_from_binary：升级序列包含当前版本时是否需要先升级到当前版本，即当前版本是否是升级序列中的 barrier 版本。
  - value：当值为 true 时，和 when_come_from 属性联合使用。
  - when_come_from：是一个列表，当 when_come_from 未定义时，表示任何版本升级到目标版本时，都要先升级到当前 barrier 版本；当 when_come_from 已定义，表示列表中的版本号升级到目标版本时，需要先升级到当前 barrier 版本。例如：示例中的 4.0.0.0 和 4.1.0.0-100000982023031415 版本的 OceanBase 集群在升级到 V4.2.0.0 版本时，都要先升级到 V4.1.0.1(barrier) 版本。
示例如下：

假设 oceanbase_upgrade_dep.yml 文件中 OceanBase 集群各个版本升级依赖关系如下：
```
- version: 4.0.0.0
  can_be_upgraded_to:
      - 4.1.0.0

- version: 4.1.0.0-100000982023031415
  can_be_upgraded_to:
    - 4.1.0.0
  deprecated: True

- version: 4.1.0.0
  can_be_upgraded_to:
      - 4.1.0.1

- version: 4.1.0.1
  can_be_upgraded_to:
      - 4.2.0.0
  require_from_binary:
    value: True
    when_come_from: [4.0.0.0, 4.1.0.0-100000982023031415]
```
通过分析示例文件，可以得到以下升级序列：
- V4.0.0.0 > V4.1.0.0 > V4.1.0.1(barrier) > V4.2.0.0
- V4.1.0.0-100000982023031415 > V4.1.0.0 > V4.1.0.1(barrier) > V4.2.0.0
- V4.1.0.0 > V4.1.0.1 > V4.2.0.0
- V4.1.0.1 > V4.2.0.0
注意

如果升级序列中存在 barrier 版本，那么您还需获取升级路径中所有 barrier 版本的 OceanBase RPM 包。

步骤二：确认升级流程

注意

如果 OceanBase 集群当前版本和目标版本之间存在 barrier 版本，那么 OceanBase 集群应该先升级到 barrier 版本，然后再从 barrier 版本升级到目标版本。

通过 步骤一 示例的升级序列，可以得到如下信息：

如果您当前使用的是 OceanBase 集群 V4.0.0.0 或者 V4.1.0.0-100000982023031415 版本，那么您在升级时 OceanBase 集群应该先升级到 V4.1.0.1（barrier）版本，然后再从 V4.1.0.1（barrier）版本升级到 V4.2.0.0 版本。
如果您当前使用的是 OceanBase 集群 V4.1.0.0 或者 V4.1.0.1 版本，那么您在升级时 OceanBase 集群可以直接升级到 V4.2.0.0 版本。

示例如下：

以下将以三副本的 OceanBase 集群为例介绍升级流程。

当前 OceanBase 集群版本是 V4.0.0.0 版本，升级流程如下：
1. 您需要先将 Zone1 从 V4.0.0.0 版本升级到 V4.1.0.1(barrier) 版本，再将 Zone2 从 V4.0.0.0 版本升级到 V4.1.0.1(barrier) 版本，然后将 Zone3 从 V4.0.0.0 版本升级到 V4.1.0.1(barrier) 版本；此时，整个集群已经从 V4.0.0.0 版本升级到了 V4.1.0.1（barrier）版本。
2. 您需再次按照 Zone 顺序依次将 Zone1、Zone2、Zone3 从 V4.1.0.1（barrier）版本升级到 V4.2.0.0，等到所有 Zone 均升级到 V4.2.0.0，集群升级就完成了。
当前 OceanBase 集群版本是 V4.1.0.0 版本，升级流程如下：

您只需要先将 Zone1 从 V4.1.0.0 版本升级到 V4.2.0.0 版本，再将 Zone2 从 V4.1.0.0 版本升级到 V4.2.0.0 版本，然后将 Zone3 从 V4.1.0.0 版本升级到 V4.2.0.0 版本，等到所有 Zone 均升级到 V4.2.0.0，集群升级就完成了。

步骤三：备份集群配置项

升级流程开始前需要备份下列配置项旧值，用于执行升级流程后还原：

在 sys 租户（系统租户）中执行以下 SQL 语句，获取需要备份的配置项的值：

SELECT SVR_IP,ZONE,NAME,VALUE FROM OCEANBASE.GV$OB_PARAMETERS WHERE NAME IN ("server_permanent_offline_time", "enable_rebalance", "enable_rereplication");

步骤四：上传并安装目标 RPM 包

使用 scp 命令将升级所用到的 OceanBase RPM 包上传到 OBServer 节点中。
```
scp $rpm_name admin@$observer_ip:/$rpm_dir
```
参数解释：
- $rpm_name：表示 RPM 包的名称。
- $observer_ip：表示 OBServer 节点的 IP。
- $rpm_dir：表示存放 RPM 包的目录。
示例如下：
```
scp oceanbase-4.2.0.0-100010022023081911.el7.x86_64.rpm admin@10.10.10.1:/home/admin/rpm
```
使用以下命令安装 OceanBase RPM 包。
注意
- 如果在您的升级路径中存在 barrier 版本，请先安装相应的 barrier 版本的 RPM 包。等待集群成功升级到 barrier 版本后，再安装目标版本的 RPM 包。
- 如果升级路径中有多个 barrier 版本，按照顺序依次进行安装和升级 barrier 版本，直到集群成功升级最后的 barrier 版本再安装目标版本的 RPM 包。
```
rpm -Uvh $rpm_name
```
其中 $rpm_name 表示 RPM 包的名称。

说明

升级相关脚本和 oceanbase_upgrade_dep.yml 文件存放 /home/admin/oceanbase/etc 目录下。目录 /home/admin/oceanbase/etc 为 OceanBase 数据库的默认安装目录。
重复步骤 1~2，直至所有 OBServer 节点中安装目标版本 RPM 包。

步骤五：执行脚本 upgrade_checker.py

在任意一个 OBServer 节点中指定 sys 租户直连 OBServer 节点的登录信息，执行 upgrade_checker.py 脚本进行升级前置检查，脚本执行成功表示可以继续升级。命令如下：

python upgrade_checker.py -h 127.0.0.1 -P 2881 -u $user_name@sys -p$password

参数解释：

$user_name：表示 sys 租户有读写及修改全局系统参数的权限的用户。
$password：表示是用户密码。

示例如下：

使用以下命令切换到 /home/admin/oceanbase/etc 目录。
```
cd /home/admin/oceanbase/etc
```

使用以下命令执行 upgrade_checker.py 脚本进行升级前置检查。

[root@xxx /home/admin/oceanbase/etc]# python upgrade_checker.py -h 127.0.0.1 -P 2881 -u root@sys -p******

步骤六：执行脚本 upgrade_pre.py

在任意一个 OBServer 节点中指定 sys 租户直连 OBServer 节点的登录信息，执行 upgrade_pre.py 脚本，脚本执行成功表示可以继续升级。命令如下：

python upgrade_pre.py -h 127.0.0.1 -P 2881 -u $user_name@sys -p$password

参数解释：

$user_name：表示 sys 租户有读写及修改全局系统参数的权限的用户。
$password：表示是用户密码。

upgrade_pre.py 脚本会执行以下命令及动作：

alter system begin upgrade。
alter system begin rolling upgrade。
special pre action：关闭及调整配置项。
health check: 集群级别健康检查。

完整的 upgrade_pre.py 脚本能力如下所示：

./upgrade_pre.py [OPTIONS]

-I, --help          Display this help and exit.
-V, --version       Output version information and exit.
-h, --host=name     Connect to host.
-P, --port=name     Port number to use for connection.
-u, --user=name     User for login.
-p, --password=name Password to use when connecting to server. If password is
                    not given it's empty string "".
-t, --timeout=name  Cmd/Query execute timeout(s).
-m, --module=name   Modules to run. Modules should be a string combined by some of
                    the following strings:
                    1. begin_upgrade
                    2. begin_rolling_upgrade
                    3. special_action
                    4. health_check
                    5. all: "all" represents that all modules should be run.
                    They are splitted by ",".
                    For example: -m all, or --module=begin_upgrade,begin_rolling_upgrade,special_action
-l, --log-file=name Log file path. If log file path is not given it's ./upgrade_pre.log


Maybe you want to run cmd like that:
./upgrade_pre.py -h 127.0.0.1 -P 2881 -u ******  -p ******

示例如下：

使用以下命令切换到 /home/admin/oceanbase/etc 目录。
```
cd /home/admin/oceanbase/etc
```

使用以下命令执行 upgrade_pre.py 脚本进行升级前检查。

[root@xxx /home/admin/oceanbase/etc]# python upgrade_pre.py -h 127.0.0.1 -P 2881 -u root@sys -p******

步骤七：集群升级

按 Zone 升级, 每个 Zone 都要按照下面的步骤执行一遍，以 zone1 为例。

执行以下命令进行集群级别健康检查。
```
python upgrade_health_checker.py -h 127.0.0.1 -P 2881 -u $user_name@sys -p$password
```
参数解释：
- $user_name：表示 sys 租户有读写及修改全局系统参数的权限的用户。
- $password：表示是用户密码。
示例如下：
1. 使用以下命令切换到 /home/admin/oceanbase/etc 目录。
```
cd /home/admin/oceanbase/etc
```
2. 使用以下命令执行 upgrade_health_checker.py 脚本进行集群级别健康检查。
```
[root@xxx /home/admin/oceanbase/etc]# python upgrade_health_checker.py -h 127.0.0.1 -P 2881 -u root@sys -p******
```

停止 Zone（STOP ZONE）。

使用 root 用户登录到集群的 sys 租户，使用以下命令停止 Zone，其中 $zone_name 为 Zone 的名称。命令如下：

ALTER SYSTEM STOP ZONE '$zone_name';

STOP ZONE 命令会等主副本（Leader）都切走才返回成功。

示例如下：

obclient [(none)]> ALTER SYSTEM STOP ZONE 'zone1';

可以使用下面 SQL 命令查看 Zone 状态。

obclient [(none)]> SELECT ZONE,STATUS FROM oceanbase.DBA_OB_ZONES;

返回结果如下：

+-------+----------+
| ZONE  | STATUS   |
+-------+----------+
| zone1 | INACTIVE |
| zone2 | ACTIVE   |
| zone3 | ACTIVE   |
+-------+----------+
3 rows in set

Zone 内机器停进程，替换新版本 binary 重启。

停止 observer 进程，然后重新启动 observer 进程。
1. 切换至 admin 用户。
```
[root@xxx /home/admin/oceanbase/etc]# su - admin
```
2. 停止 observer 进程。
```
-bash-4.2$ kill -9 `pidof observer`
```
3. 重新启动 observer 进程。
```
-bash-4.2$ cd /home/admin/oceanbase && /home/admin/oceanbase/bin/observer
```
  说明
  
  再次启动 observer 进程时不需要指定启动参数，因为之前的启动参数已经写到参数文件里了。
执行 Zone 级别健康检查。

Zone 级别健康检查基本上复用了集群级别健康检查逻辑，主要是校验指定 Zone 的所有机器相关状态。命令如下：
```
python upgrade_health_checker.py -h 127.0.0.1 -P 2881 -u $user_name@sys -p$password -z '$zone_name'
```
参数解释：
- $user_name：表示 sys 租户有读写及修改全局系统参数的权限的用户。
- $password：表示是用户密码。
- $zone_name：表示 Zone 的名称。
示例如下：
1. 使用以下命令切换到 /home/admin/oceanbase/etc 目录。
```
cd /home/admin/oceanbase/etc
```
2. 使用以下命令执行 upgrade_health_checker.py 脚本进行 Zone 级别健康检查。
```
[root@xxx /home/admin/oceanbase/etc]# python upgrade_health_checker.py -h 127.0.0.1 -P 2881 -u root@sys -p****** -z 'zone1'
```
启动 Zone（start zone）。

使用 root 用户登录到集群的 sys 租户，使用以下命令启动 Zone，其中 $zone_name 为 Zone 的名称。命令如下：
```
ALTER SYSTEM START ZONE '$zone_name';
```
示例如下：
```
obclient [(none)]> ALTER SYSTEM START ZONE 'zone1';
```
重复步骤 1~5，直至所有 Zone 升级完成。

步骤八：执行脚本 upgrade_post.py

在任意一个 OBServer 节点中指定 sys 租户直连 OBServer 节点的登录信息，执行 upgrade_post.py 脚本完成主要的升级操作及相关检查。命令如下：

python upgrade_post.py -h 127.0.0.1 -P 2881 -u $user_name@sys -p$password

注意

在执行升级脚本 upgrade_post.py 时，若出现错误，其原因很可能是 RS 切主过。建议通过以下步骤进行排查与修复：

可以执行 SELECT * FROM oceanbase.DBA_OB_TENANT_JOBS WHERE job_type = 'upgrade_all' ORDER BY job_id DESC LIMIT 1; 验证升级任务状态。若 JOB_STATUS 显示为 inprogress，且 MODIFY_TIME 为最近时间（与当前时间间隔较短），则可以手动执行一下 ALTER SYSTEM RUN UPGRADE JOB 'UPGRADE_ALL'; 命令解决这个问题。
重新执行升级脚本。

参数解释：

$user_name：表示 sys 租户有读写及修改全局系统参数的权限的用户。
$password：表示是用户密码。

upgrade_post.py 脚本会完成以下升级动作：

集群级别健康检查。
alter system end rolling upgrade。
按租户执行 begin upgrade。
按租户执行系统变量修正。
按租户执行系统表修正。
按租户执行虚拟表/视图修正。
按租户执行版本相关升级动作。
按租户执行内部表自检操作。
按租户结束 end upgrade。
alter system end upgrade：结束集群升级状态。
upgrade post check：重新打开升级过程中禁用的部分配置项，并执行检查。

上述第 3～5、7、9 步在下列升级场景下不执行：

同版本升级。
跨版本升级，原版本和目标版本的数据版本一致。

完整的 upgrade_post.py 脚本能力如下所示：

./upgrade_post.py [OPTIONS]

-I, --help          Display this help and exit.
-V, --version       Output version information and exit.
-h, --host=name     Connect to host.
-P, --port=name     Port number to use for connection.
-u, --user=name     User for login.
-p, --password=name Password to use when connecting to server. If password is
                    not given it's empty string "".
-t, --timeout=name  Cmd/Query execute timeout(s).
-m, --module=name   Modules to run. Modules should be a string combined by some of
                    the following strings:
                    1. health_check
                    2. end_rolling_upgrade
                    3. tenant_upgrade
                    4. end_upgrade
                    5. post_check
                    6. all: "all" represents that all modules should be run.
                    They are splitted by ",".
                    For example: -m all, or --module=health_check,begin_rolling_upgrade
-l, --log-file=name Log file path. If log file path is not given it's ./upgrade_pre.log


Maybe you want to run cmd like that:
./upgrade_post.py -h 127.0.0.1 -P 2881 -u *** -p ******

示例如下：

使用以下命令切换到 /home/admin/oceanbase/etc 目录。
```
cd /home/admin/oceanbase/etc
```

使用以下命令执行 upgrade_post.py 脚本完成主要的升级操作及相关检查。

[root@xxx /home/admin/oceanbase/etc]# python upgrade_post.py -h 127.0.0.1 -P 2881 -u root@sys -p******

步骤九：还原集群配置项

基于 步骤三 备份的配置项旧值，使用 root 用户登录到集群的 sys 租户，使用以下命令还原相关配置项。

ALTER SYSTEM SET $parameter value= $parameter_value

参数解释：

$parameter：表示配置项的名称
$parameter_value：表示配置项的值。

示例如下：

还原 server_permanent_offline_time 的值。

obclient [(none)]> ALTER SYSTEM SET server_permanent_offline_time = '3600s';

还原 enable_rebalance 的值。

obclient [(none)]> ALTER SYSTEM SET enable_rebalance = 'True';

还原 enable_rereplication 的值。

obclient [(none)]> ALTER SYSTEM SET enable_rereplication = 'True';

后续操作

升级后检查

验证是否升级完成，请参见升级后检查。

重新配置 cgroup

如果在升级前 OceanBase 集群配置了 cgroup，那么在 OceanBase 集群升级后，需要重新配置 cgroup。详细信息，参见配置 cgroup。

前提条件

注意

操作步骤

注意

步骤一：分析 oceanbase_upgrade_dep.yml 文件

说明

注意

步骤二：确认升级流程

注意

步骤三：备份集群配置项

步骤四：上传并安装目标 RPM 包

注意

说明

步骤五：执行脚本 upgrade_checker.py

步骤六：执行脚本 upgrade_pre.py

步骤七：集群升级

说明

步骤八：执行脚本 upgrade_post.py

注意

步骤九：还原集群配置项

后续操作

升级后检查

重新配置 cgroup

相关文档