Upgrade OMS Community Edition in multi-node deployment mode

This topic describes how to upgrade OceanBase Migration Service (OMS) Community Edition in multi-node deployment mode to V4.2.3.

Background information

At present, only OMS Community Edition of the following two versions can be directly upgraded to V4.2.3. To upgrade OMS Community Edition in multi-node deployment mode, you need to upgrade all nodes.

• OMS Community Edition V4.2.2

• OMS Community Edition V4.1.0

Upgrade from V4.2.2 to V4.2.3

1. If high availability (HA) is enabled, disable it first.

   1. Log on to the console of OMS Community Edition.

   2. In the left-side navigation pane, choose System Management > System Parameters.

   3. On the System Parameters page, find ha.config.

   4. Click the edit icon in the Value column of the parameter.

   5. In the Modify Value dialog box, set enable to false to disable HA.

2. Back up the databases.

   1. Log on to the two hosts where the container of OMS Community Edition V4.2.2 is deployed by using their respective IP addresses, and suspend the container.

      sudo docker stop ${CONTAINER_NAME}
      

      Note

      CONTAINER_NAME specifies the name of the container.

   2. Log on to the cluster management (CM) heartbeat database specified in the configuration file and delete some useless records to reduce the backup time.

      # Log on to the CM heartbeat database specified in the configuration file.
      mysql -hxxx.xxx.xxx.1 -P<port> -u<username> -p<password> -Dcm_hb_422
      
      # Delete useless records.
      # The heatbeat_sequence table provides auto-increment IDs and reports heartbeats.
      delete from heatbeat_sequence where id < (select max(id) from heatbeat_sequence);
      

   3. Run the following commands to back up the rm, cm, and cm_hb databases as SQL files and make sure that the sizes of the files are not 0.

      If you have deployed databases in multiple regions, you must back up the cm_hb database in all regions. For example, if you have deployed databases in two regions, you must back up the following four databases: rm, cm, cm_hb1, and cm_hb2.

      mysqldump -hxxx.xxx.xxx.1 -P<port> -u<username> -p<password> --triggers=false rm_422 > /home/admin/rm_422.sql
      
      mysqldump -hxxx.xxx.xxx.1 -P<port> -u<username> -p<password> --triggers=false cm_422 > /home/admin/cm_422.sql
      
      mysqldump -hxxx.xxx.xxx.1 -P<port> -u<username> -p<password> --triggers=false cm_hb_422 > /home/admin/cm_hb_422.sql
      

      Parameter	Description
      -h	The IP address of the host from which the data is exported.
      -P	The port number used to connect to the database.
      -u	The username used to connect to the database.
      -p	The password used to connect to the database.
      --triggers	The data export trigger. The default value is false, which disables data export.
      rm_422, cm_422, cm_hb_422	Specifies to back up the rm, cm, and cm_hb databases as SQL files named in the format of database name > SQL file storage path.sql. You need to specify the values based on the actual environment.

3. Load the downloaded OMS Community Edition installation package to the local image repository of the Docker container.

   docker load -i <Installation package of OMS Community Edition>
   

4. Start a new container for OMS Community Edition V4.2.3.

   You can access the console of OMS Community Edition by using an HTTP or HTTPS URL. To securely access the console of OMS Community Edition, install a Secure Socket Layer (SSL) certificate and mount it to the specified directory in the container. The certificate is not required for HTTP access.

   Notice

   • Before you start the container for OMS Community Edition V4.2.3, make sure that the three disk mounting paths of OMS Community Edition are the same as those before the upgrade.
     You can run the sudo docker inspect ${CONTAINER_NAME} | grep -A5 'Binds' command to view the disk mounting paths before the upgrade, which are paths to the disks mounted to the old container of OMS Community Edition.

   • The -e IS_UPGRADE=true parameter is provided in OMS Community Edition V3.3.1 and later. This parameter is provided only to support OMS upgrades and must be specified when you upgrade OMS.

   • Replace work.oceanbase-dev.com/obartifact-store/oms:${IMAGE_TAG} with the name of the image that is imported by running the docker load -i command.

   OMS_HOST_IP=xxx
   CONTAINER_NAME=oms_xxx
   IMAGE_TAG=feature_x.x.x-ce
   
   docker run -dit --net host \
   -v /data/config.yaml:/home/admin/conf/config.yaml \
   -v /data/oms/oms_logs:/home/admin/logs \
   -v /data/oms/oms_store:/home/ds/store \
   -v /data/oms/oms_run:/home/ds/run \
   # If you mount the SSL certificate to the OMS container, you must set the following two parameters.
   -v /data/oms/https_crt:/etc/pki/nginx/oms_server.crt
   -v /data/oms/https_key:/etc/pki/nginx/oms_server.key
   -e OMS_HOST_IP=${OMS_HOST_IP} \
   -e IS_UPGRADE=true \
   --privileged=true \
   --pids-limit -1 \
   --ulimit nproc=65535:65535 \
   --name ${CONTAINER_NAME} \
   work.oceanbase-dev.com/obartifact-store/oms:${IMAGE_TAG}
   

   Parameter	Description
   OMS_HOST_IP	The IP address of the host. Notice The value of OMS_HOST_IP is different for each node.
   CONTAINER_NAME	The name of the container
   IMAGE_TAG	The unique identifier of the loaded image. After you load the OMS Community Edition installation package by using Docker, run the docker images command to obtain the [IMAGE ID] or [REPOSITORY:TAG] value of the loaded image. The obtained value is the unique identifier of the loaded image.
   /data/oms/oms_logs /data/oms/oms_store /data/oms/oms_run	/data/oms/oms_logs, /data/oms/oms_store, and /data/oms/oms_run can be replaced with the mount directories created on the server where OMS Community Edition is deployed to respectively store the runtime log files of OMS Community Edition, the files generated by the Store component, and the files generated by the Incr-Sync component, for local data persistence. Notice The mount directories must remain unchanged during subsequent redeployment or upgrades.
   /home/admin/logs /home/ds/store /home/ds/run	/home/admin/logs, /home/ds/store, and /home/ds/run are default directories in the container and cannot be modified.
   /data/oms/https_crt (optional) /data/oms/https_key (optional)	The mount directory of the SSL certificate in the container of OMS Community Edition. If you mount an SSL certificate, the NGINX service in the container of OMS Community Edition runs in HTTPS mode. In this case, you can access the console of OMS Community Edition by using only the HTTPS URL.
   IS_UPGRADE	To upgrade OMS Community Edition, you must set the IS_UPGRADE parameter to true. Note that IS_UPGRADE must be in uppercase.
   privileged	Specifies whether to grant extended privileges on the container.
   pids-limit	Specifies whether to limit the number of container processes. The value -1 indicates that the number is unlimited.
   ulimit nproc	The maximum number of user processes.

5. Go to the new container.

   docker exec -it ${CONTAINER_NAME} bash  
   

   Note

   CONTAINER_NAME specifies the name of the container.

6. Perform metadata initialization in the root directory.

   sleep 300
   bash /root/docker_init.sh
   

   Note

   • After you run the preceding commands, the script automatically implements schema changes of the three databases of OMS Community Edition.

   • If the same configuration file is used for multiple cm_nodes in the same region, you need to execute the docker_init.sh script only once in a region.
     If different configuration files are used for multiple cm_nodes in the same region, you need to execute the docker_init.sh script once on each node.

   If the execution of the preceding commands return the Version before 4.1.1 is not allowed to upgrade. error, perform the following operations:

   1. Verify that the version of OMS Community Edition to be upgraded is not earlier than V4.1.1.

   2. Execute the following SQL statements in the rm database:

      CREATE TABLE IF NOT EXISTS `oms_version` (    
         `version` varchar(64) NOT NULL COMMENT 'version',    
         `gmt_modified` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,    
         PRIMARY KEY (`version`)
         ) DEFAULT CHARSET = utf8mb4 COMMENT = 'version table';
      
      REPLACE INTO `oms_version`(`version`) VALUES('x.x.x-CE');  -- Specify the version number of OMS Community Edition before the upgrade.
      

   3. Run the initialization command again.

7. After the docker_init.sh script is executed, verify that the server list is normal and all servers are in the Online state.

   1. Log on to the console of OMS Community Edition.

   2. In the left-side navigation pane, choose OPS & Monitoring > Server.

   3. On the Servers page, check whether the server list is normal. Check whether all servers are in the Online state.

8. After you upgrade OMS on two nodes, enable HA on the System Parameters page, and configure the parameters.

   1. Log on to the console of OMS Community Edition.

   2. In the left-side navigation pane, choose System Management > System Parameters.

   3. On the System Parameters page, find ha.config.

   4. Click the edit icon in the Value column of the parameter.

   5. In the Modify Value dialog box, set enable to true to enable HA, and record the time as T2.

      You can also set the perceiveStoreClientCheckpoint parameter to true. After that, you do not need to record T1 and T2.

   6. If you set the perceiveStoreClientCheckpoint parameter to false, you need to modify the value of the refetchStoreIntervalMin parameter based on your business needs. refetchStoreIntervalMin specifies the time interval, in minutes, for pulling data from the Store component. The value must be greater than T2 minus T1.

      If you set the perceiveStoreClientCheckpoint parameter to true, you can use the default value of the refetchStoreIntervalMin parameter. HA is enabled, so the system starts the Store component based on the earliest request time of downstream components minus the value of the refetchStoreIntervalMin parameter. For example, if the earliest request time of the downstream Connector or JDBC-Connector component is 12:00:00 and the refetchStoreIntervalMin parameter is set to 30 minutes, the system starts the Store component at 11:30:00.

      The following table shows status changes of components and projects when HA is enabled or disabled.

9. (Optional) To roll back OMS Community Edition, perform the following steps:

   1. Disable the HA feature based on Step 1.

   2. Suspend the new container and record the time as T3.

      sudo docker stop ${CONTAINER_NAME}
      

   3. Connect to the MetaDB and run the following commands:

      drop database rm_422;
      drop database cm_422;
      drop database cm_hb_422;
      
      create database rm_422;
      create database cm_422;
      create database cm_hb_422;
      

   4. Restore the original databases based on the SQL files created in Step 2.

      mysql -hxxx.xxx.xxx.1 -P<port> -u<username> -p<password> -e "source /home/admin/rm_422.sql" -Drm_422
      
      mysql -hxxx.xxx.xxx.1 -P<port> -u<username> -p<password> -e "source /home/admin/cm_422.sql" -Dcm_422
      
      mysql -hxxx.xxx.xxx.1 -P<port> -u<username> -p<password> -e "source /home/admin/cm_hb_422.sql" -Dcm_hb_422
      

   5. Restart the old container of OMS Community Edition V4.2.2.

      sudo docker restart ${CONTAINER_NAME}
      

   6. On the System Parameters page, enable HA and set the refetchStoreIntervalMin parameter.

      When you perform a rollback, the HA feature supports automatic disaster recovery. However, you may need to manually recover the Incr-Sync or Full-Import component.

10. After the upgrade is complete, clear the browser cache before you log on to OMS Community Edition.

Upgrade from V4.1.0 to V4.2.3

Limitations

• You can directly upgrade OMS Community Edition from V4.1.0 to V4.2.3. To upgrade OMS Community Edition of a version earlier than V4.1.0, you must upgrade it first to V4.1.0 and then to V4.2.3 based on the operations described in this section. For more information about how to upgrade OMS Community Edition to V4.1.0, see Upgrade Guide for V4.1.0.

• Before and during the upgrade, make sure that no users are creating data migration or synchronization projects by using OMS Community Edition.

• Before you start the upgrade, make sure that no full migration or full verification tasks are in Running state in OMS Community Edition V4.1.0.

Procedure

1. Copy the configuration file of OMS Community Edition V4.1.0.

   sudo docker cp ${CONTAINER_NAME}:/home/admin/conf/config.yaml ${host directory}
   

   Note

   CONTAINER_NAME specifies the name of the container.

2. Suspend the container of OMS Community Edition V4.1.0.

   sudo docker stop ${CONTAINER_NAME}
   

3. Pull the upgrade script docker_remote_deploy_410_up_423_version.sh from the image of OMS Community Edition V4.2.3 to the current directory.

   sudo docker run -d --net host --name oms-config-tool ${OMS_IMAGE} bash && sudo docker cp oms-config-tool:/root/docker_remote_deploy_410_up_423_version.sh . && sudo docker rm -f oms-config-tool
   

   Notice

   You need to replace ${IMAGE_TAG} with the image name specified in the docker load -i command.

4. Execute the upgrade script to deploy OMS Community Edition V4.2.3.

   sh docker_remote_deploy_410_up_423_version.sh -o ${mount directory} -c ${configuration file path} -i ${local IP address} -d ${IMAGE_TAG}
   

   Parameter	Description
   mount directory	The mount directory, which must be the same as that of the container of OMS Community Edition V4.1.0.
   config.yaml	The configuration file used for the container of OMS Community Edition V4.1.0, which is copied in Step 1.
   IMAGE_TAG	The image name. You need to replace IMAGE_TAG with the image name specified in the docker load -i command.

   The upgrade script automatically generates a backup of config.yaml named config_copy.yaml. The deployment tool of OMS Community Edition automatically verifies the CPU, memory, and disk resources. If any type of resource does not meet the requirement, the deployment tool displays a message prompting that insufficient resources will affect the data migration speed.

5. Complete the deployment as prompted. After you set a parameter, press Enter to move on to the next parameter.

   1. Select a deployment mode.

      Select Multiple Nodes in Single Region or Multiple Regions.

   2. Select a task.

      Select Use Configuration File Uploaded with Script Option [-c].

   3. If the system displays The specified database names already exist in the MetaDB. Are you sure that you want to continue?, enter y and press Enter.

   4. If the message The specified database names already exist in the MetaDB. Do you want to reinitialize the MetaDB? is displayed, enter y and press Enter.

   5. If the configuration file passes the check, all the settings are displayed. If the settings are correct, enter y and press Enter to proceed. Otherwise, enter n and press Enter to modify the settings.

      If the configuration file fails the check, modify the configuration information as prompted.

   6. Complete deployment settings on each node as follows:

      1. Specify the directory to which the container of OMS Community Edition is mounted in the host.

         The mount directory must be the same as that of the container of OMS Community Edition V4.1.0. For a remote node, the username and password for logging on to the remote node are required. The corresponding user account must have the sudo privilege on the remote node.

      2. Confirm whether the image file of OMS Community Edition can be named as OMS_IMAGE.

         If yes, enter y and press Enter to proceed. Otherwise, enter n and press Enter to modify the settings.

      3. Determine whether to mount an SSL certificate to the container of OMS Community Edition.

         If yes, enter y, press Enter, and specify the https_key and https_crt directories as prompted. Otherwise, enter n and press Enter.

      4. If the current node is a remote node, the system finds that the IP address of the deployment mode is inconsistent with the IP address of the server where the deployment tool resides, and asks you whether to remotely execute the script. This requires that the remote node support SSH connection and you have the sudo privilege on the remote node.

         If you enter y, check whether the port of the node can be connected through Secure Shell (SSH). If SSH connection is supported, enter the username and password for logging on to the remote node as prompted.

         If you leave the password empty, the system will prompt that the password is an empty string and ask you whether to use trusted logon. If you enter y, enter the password of the sudo user again. If no password is required, directly press Enter.

      5. Confirm whether the path to which the config.yaml configuration file will be written is correct.

         If yes, enter y and press Enter to proceed. Otherwise, enter n and press Enter to modify the settings.

   7. If you select Multiple Regions for Deployment Mode, you also need to specify whether to deploy OMS Community Edition in a new region.

      If yes, enter y and press Enter to proceed as prompted. If not, enter n and press Enter to end the deployment process.

      If the deployment fails, you can log on to the container of OMS Community Edition and view logs in the .log file prefixed with docker_init in the /home/admin/logs directory. If the container of OMS Community Edition fails to be started, you cannot obtain logs.

6. Begin the upgrade process.

   1. Enter the container of OMS Community Edition V4.2.3.

      sudo docker exec -it ${CONTAINER_NAME} bash
      

   2. Enter the root directory and check the upgrade script named docker_oms_ce_version_upgrade.sh.

      cd /root
      ls
      

   3. Execute the upgrade script.

      sh docker_oms_ce_version_upgrade.sh
      

7. When the execution is completed, the following message is displayed: [Completed] All initialization steps are executed. Then, you can use OMS Community Edition V4.2.3.

8. Check whether the data migration and synchronization projects are successful and whether the components are running properly.

   For information about common issues that may occur after the upgrade and solutions, see Common issues in the upgrade from V4.1.0 to V4.2.3.

Perform a rollback

You can roll back OMS Community Edition from V4.2.3 to V4.1.0 by performing the following operations.

1. Execute the rollback script.

   1. Enter the container of OMS Community Edition V4.2.3.

      sudo docker exec -it ${CONTAINER_NAME} bash
      

   2. Enter the root directory and view the rollback script named docker_oms_ce_version_roll_back.sh.

      cd /root
      ls
      

   3. Execute the rollback script.

      docker_oms_ce_version_roll_back.sh
      

   4. When the execution is completed, the following message is displayed: [Completed] All initialization steps are executed.

2. Suspend and delete the container of OMS Community Edition V4.2.3.

   1. Exit the new container.

   2. Suspend the new container.

      sudo docker stop ${CONTAINER_NAME}
      

   3. Delete the new container.

      sudo docker rm ${CONTAINER_NAME}
      

3. Check the config.yaml file of OMS Community Edition V4.1.0.

   config.yaml must be consistent with config_copy.yaml. If not, modify parameters in the config.yaml file.

4. Start the container of OMS Community Edition V4.1.0.

   sudo docker start ${CONTAINER_NAME}