# 操作指导
#### 前提条件
- 环境要求：
  - 所有服务器操作系统运行状态正常。
  
  - 网络环境稳定无异常。
   
- 依赖项：已成功执行前置脚本gs_preinstall完成环境预配置。
- 权限要求：需要使用执行gs_preinstall时指定的集群用户进行安装操作。
 
#### 语法
- 显示帮助信息。
  ```
  gs_upgradectl -? | --help
  ```
  
- 显示版本号信息。
  ```
  gs_upgradectl -V | --version
  ```
  
- 选择升级策略。
  ```
  gs_upgradectl -t chose-strategy [-l LOGFILE]
  ```
  
- 升级集群。
  ```
  gs_upgradectl -t auto-upgrade -X XMLFILE {-g NODENUMBER | -h HOSTNAME | --continue} [-l LOGFILE] [--rolling] 
  [--grey] [--begin=ShardStartNumber] [--end=ShardEndNumber] [--force] [--ignoreVMFaults=HOSTNAME][--auto_script]
  ```
  
- 回滚升级。
  ```
  gs_upgradectl -t auto-rollback -X XMLFILE [-l LOGFILE] [--force] [--hadr_force] [--ignoreVMFaults=HOSTNAME][--auto_script]
  ```
  
- 升级提交。
  ```
  gs_upgradectl -t commit-upgrade -X XMLFILE [-l LOGFILE] [--force_commit] [--skip_rebalance_set]
  ```
  ![](https://support.huaweicloud.com/distributed-devg-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
  - 一旦提交操作完成，则不能再执行回滚操作。
    
 
#### 核心约束
1. 业务要求
   - 集群需满足：
     - 主备DN数据完全同步。
     
     - 运行状态正常。
      
   
   - 业务压力大的情况下建议开启流控。
    
2. 操作限制
   - 禁止与节点替换/扩容/缩容操作并行执行。
   
   - 不支持虚拟IP配置。
   
   - 升级期间禁用kerberos开关。
   
   - 禁止修改安装包内version.cfg文件。
   
   - 选择灰度升级方式进行升级时，升级过程中不支持节点替换/修改IP/扩容/缩容/hotpatch，部分节点升级成功后不建议执行节点修复；不支持增加CN。
    
3. 资源要求
   - DN节点磁盘使用率必须低于85%。
   
   - 升级后原归档日志失效。
   
   - 升级后原二进制目录将被清除，请不要存放个人数据。
    
4. 参数管控
   - 升级期间禁止修改以下GUC参数：wal_level、max_connections、max_prepared_transactions、max_locks_per_transaction。
   
   
   
   - 如果灰度升级过程中出现异常导致升级失败，需用户手动回滚，且回滚成功后才能进行下一次升级。回滚成功后升级过程中设置的GUC参数将失效。
    
5. Roach备份与升级的交互：
   - 灰度升级观察期间支持Roach备份。
   
   - 灰度升级部分节点时，参与备份的节点大版本要求一致，否则会导致备份失败。DISK备份会校验所有节点。OBS、NAS、XBSA备份会校验参与备份的节点，关于备份节点的选取规则为：
     - 备份下发节点。
     
     - GTM：主GTM。
     
     - CMS：主CMS。
     
     - DN：主机备份为每个分片的主机，备机备份为每个分片上正常的回放速度最快的备DN。
     
     - CN：不开归档时为第一个正常的CN，开归档时为所有正常的CN。
      
    
 
#### 进程故障升级约束
- 少数派VM故障或少数派进程故障升级约束：
  - 前置条件：
    1. 下发升级命令之前，集群状态至少为Degraded。
    
    2. 需要下发增加--ignoreVMFaults参数的升级命令。
     
  
  - 异常处理：
    - 升级过程中，若主流程VM节点故障，升级报错为正常报错，重新将升级命令下发至正常节点即可。
    
    - 通过增加--ignoreVMFaults参数，被隔离的节点不会被升级。升级后需通过节点替换完成集群修复。
    
    - 被隔离的进程会忽略掉无法启动的错误。
     
   
 
- 多数派VM故障或多数派进程故障升级约束：
  - 适用范围：
    - 只支持小版本升级，不支持大版本升级。
    
    - 由于"安装目录\\bin"下的gaussdb二进制文件损坏导致的多数派进程故障支持小版本强制升级，由于VM级故障导致的故障不支持升级。（内核版本号不变的升级方式为小版本升级，否则就是大版本升级。内核版本号在升级文件压缩包中的version.cfg的第二行查看）。
     
  
  - 强制升级限制：
    - 升级不带有修复功能，升级后不保证集群一定可用。
    
    - 强制升级未提交或回滚前，即使集群恢复正常，也无法进行正常的升级操作。
    
    - 支持回滚操作。回滚成功后，不保证集群可用。
     
   
#### 滚动升级操作步骤
1. 以root身份登录节点。
2. 进入安装包解压出的script目录下。 
   ```
   cd /opt/software/gaussdb_upgrade/script
   ```
   
   
3. 执行前置脚本gs_preinstall。
   
   ```
   ./gs_preinstall -U omm -G dbgrp -X /opt/software/GaussDB_Kernel/clusterconfig.xml --alarm-type=1 --non-interactive
   ```
   上述命令中的"clusterconfig.xml"为安装配置文件。
   
   
4. 切换至omm（集群用户）用户。 
   ```
   su - omm
   ```
   
   
5. 独立部署模式下，滚动升级采用分片升级的方式，对集群进行升级。用户可以一次指定任意多个分片进行升级，升级命令如下。 
   ```
   gs_upgradectl -t auto-upgrade -X /opt/software/GaussDB_Kernel/clusterconfig.xml --begin=ShardStartNumber --end=ShardEndNumber
   ```
   如果指定升级第1个分片，命令如下：
   ```
   gs_upgradectl -t auto-upgrade -X /opt/software/GaussDB_Kernel/clusterconfig.xml --begin=1 --end=1
   ```
   混合部署模式下，滚动升级采用AZ级的升级方式，对集群进行升级。用户可以指定任意AZ的所有节点进行升级，升级命令如下：
   ```
   gs_upgradectl -t auto-upgrade -X /opt/software/GaussDB_Kernel/clusterconfig.xml -h nodename1,nodename2... --rolling
   ```
   注意：命令中的nodename必须要是一个AZ或者多个AZ的所有节点。若一次性升级集群中所有节点，假设节点总数为n，则可使用如下组合命令：
   ```
   gs_upgradectl -t auto-upgrade -X /opt/software/GaussDB_Kernel/clusterconfig.xml -g n --rolling
   ```
   ![](https://support.huaweicloud.com/distributed-devg-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
   - 如果准备升级的节点或节点上的少数派进程故障，则使用如下命令进行升级。
     ```
     gs_upgradectl -t auto-upgrade -X /opt/software/GaussDB_Kernel/clusterconfig.xml --begin=1 --end=1 --ignoreVMFaults=nodeName1,nodeName2,...
     ```
     *=nodeName1,nodeName2*,...代表集群中需要忽略的故障的节点名列表或有进程故障的节点名列表。
     需要在第一次滚动升级时指定需要忽略的故障的节点名列表或有进程故障的节点名列表。后续滚动升级时不需要再次指定，除非有新增的故障节点和进程故障节点。
     
    
   如果指定升级第3、4、5分片，命令如下：
   ```
   gs_upgradectl -t auto-upgrade -X /opt/software/GaussDB_Kernel/clusterconfig.xml --begin=3 --end=5
   ```
   本次指定的分片升级成功后，用户可以继续使用本命令，指定未升级的分片进行升级操作，直到完成所有分片的升级。
   
   
6. 使用--auto_script参数通过自动生成升级脚本的方式滚动升级全部3个节点。 
   ```
   gs_upgradectl -t auto-upgrade -X /opt/software/GaussDB_Kernel/clusterconfig.xml -g n --rolling --auto_script
   ```
   
   
7. 升级版本查询。 
   ```
   gs_ssh -c "gsql -V"
   ```
   
   
8. 检查升级集群状态。 
   ```
   cm_ctl query -Cdvi
   ```
   查询结果的Cluster State为normal代表集群正常。
   
   
9. 升级提交。 
   ```
   gs_upgradectl -t commit-upgrade -X /opt/software/GaussDB_Kernel/clusterconfig.xml
   ```
   ![](https://support.huaweicloud.com/distributed-devg-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
   一旦提交操作完成，则不能再执行回滚操作。
   
   
 
#### 滚动升级回滚步骤
1. 执行如下命令完成版本回滚（回滚内核代码）。回滚完成，如果需要保持内核代码和om代码的一致，可以执行旧包的前置命令，依次执行[1]\~[3]。若要重新升级，则需按照步骤[1]\~[3]，重新执行新版本包的前置。
   
   ```
   gs_upgradectl -t auto-rollback -X /opt/software/GaussDB_Kernel/clusterconfig.xml
   ```
   ![](https://support.huaweicloud.com/distributed-devg-v10-gaussdb/public_sys-resources/note_3.0-zh-cn.png)
   - 如果准备回滚的节点或节点上的少数派进程故障，则使用如下命令进行回滚。
     ```
     gs_upgradectl -t auto-rollback -X /opt/software/GaussDB_Kernel/clusterconfig.xml --ignoreVMFaults=nodeName1,nodeName2,...
     ```
     *=nodeName1,nodeName2*,...代表集群中需要忽略的故障的节点名列表或有进程故障的节点名列表。
     需要在回滚时指定需要忽略的故障的节点名列表或有进程故障的节点名列表。
     
    
   
   
2. 查看回滚之后的版本号。 
   ```
   gsql -V
   ```