Deploy OMS on a single node

This topic describes how to deploy OceanBase Migration Service (OMS) on a single node by using the deployment tool.

Prerequisites

• The installation environment meets the system and network requirements. For more information, see System and network requirements.

• You have created a MetaDB cluster for OMS.

• You have obtained the installation package of OMS, which is generally a tar.gz file whose name starts with oms.

• You have loaded the installation package of OMS to the local image repository of the Docker container.

  docker load -i <OMS installation package>

• You have prepared a directory for mounting the OMS container. In the mount directory, OMS will create the /home/admin/logs, /home/ds/store, and /home/ds/run directories for storing the component information and logs generated during the running of OMS.

• (Optional) You have prepared a time-series database for storing performance monitoring data and DDL/DML statistics of OMS.

Terms

You need to replace variable names in some commands and prompts. A variable name is enclosed with angle brackets (<>).

• Mount directory of the OMS container: See the description of the mount directory in the "Prerequisites" section of this topic.

• IP address of the server: the IP address of the host that executes the script. In a single-node deployment scenario, by default, it is the IP address in the cluster manager (CM) configuration information.

• OMS_IMAGE: the unique identifier of the loaded image. After you load the OMS installation package by using Docker, run the docker images command to obtain the [IMAGE ID] or [REPOSITORY:TAG] of the loaded image. The obtained value is the unique identifier of the loaded image. Here is an example:

  $sudo docker images
  REPOSITORY                                          TAG                 IMAGE ID        
  work.oceanbase-dev.com/obartifact-store/oms     feature_3.4.0       2a6a77257d35      
  

  In this example, <OMS_IMAGE> can be work.oceanbase-dev.com/obartifact-store/oms:feature_3.4.0 or 2a6a77257d35. Replace the value of <OMS_IMAGE> in related commands with the preceding value.

• Directory of the config.yaml file: If you want to deploy OMS based on an existing config.yaml configuration file, this directory is the one where the configuration file is located.

Deployment procedure without a configuration file

If no OMS configuration file exists, we recommend that you generate a configuration file for deployment. If the OMS configuration file exists, we recommend that you use the existing configuration file for deployment.

1. Log in to the server where OMS is to be deployed.

2. (Optional) Deploy a time-series database.

   If you need to collect and display OMS monitoring data, deploy a time-series database. Otherwise, you can skip this step. For more information, see Deploy a time-series database.

3. Run the following command to obtain the deployment script docker_remote_deploy.sh from the loaded image:

   sudo docker run -d --net host --name oms-config-tool <OMS_IMAGE> bash && sudo docker cp oms-config-tool:/root/docker_remote_deploy.sh . && sudo docker rm -f oms-config-tool
   

   Here is an example:

   sudo docker run -d --net host --name oms-config-tool work.oceanbase-dev.com/obartifact-store/oms:feature_3.4.0 bash && sudo docker cp oms-config-tool:/root/docker_remote_deploy.sh . && sudo docker rm -f oms-config-tool
   

4. Use the deployment script to start the deployment tool.

   sh docker_remote_deploy.sh -o <Mount directory of the OMS container> -i <IP address of the server> -d <OMS_IMAGE>
   

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

   1. Select a deployment mode.

      Select Single Node in Single Region.

   2. Select a task.

      Select No Configuration File. Deploy OMS Starting from Configuration File Generation.

   3. Enter the configuration information of the MetaDB as follows:

      1. Enter the URL, port, username, and password of the MetaDB.

      2. Set a prefix for names of databases in the MetaDB.

         For example, when the prefix is set to oms, the databases in the MetaDB are named oms_rm, oms_cm, and oms_cm_hb.

      3. Confirm your settings.

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

      4. If the system displays The specified database names already exist in the MetaDB. Are you sure that you want to continue?, it indicates that the database names you specified already exist in the MetaDB. This may be caused by repeated deployment or upgrade of OMS. You can enter y and press Enter to proceed, or enter n and press Enter to modify the settings.

   4. Perform the following operations to configure the CM service of OMS:

      1. Check whether the obtained default IP address is correct.

         The displayed IP address must be the same as the value of the IP address of the server field that you specified when you started the deployment tool. If yes, enter y and press Enter to proceed. Otherwise, enter n and press Enter to modify the settings.

      2. The page displays the OMS settings. Check whether the value of the cm_url field is the IP address of the server. If yes, enter y and press Enter to proceed. Otherwise, enter n and press Enter to modify the settings.

   5. Determine whether to monitor historical data of OMS.

      • If you have deployed a time-series database in Step 2, enter y and press Enter to go to the step of configuring the time-series database and enable monitoring for OMS historical data.

      • If you chose not to deploy a time-series database in Step 2, enter n and press Enter to go to the step of determining whether to enable the audit log feature and configure Simple Log Service (SLS) parameters. In this case, OMS does not monitor the historical data after deployment.

   6. Configure the time-series database.

      Perform the following operations:

      1. Confirm whether you have deployed a time-series database.

         Enter the value based on the actual situation. If yes, enter y and press Enter. If no, enter n and press Enter to go to the step of determining whether to enable the audit log feature and set SLS parameters.

      2. Set the type of the time-series database to INFLUXDB.

         Notice

         At present, only INFLUXDB is supported.

      3. Enter the URL, username, and password of the time-series database. For more information, see Deploy a time-series database.

      4. Confirm whether the displayed settings are correct.

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

   7. Determine whether to enable the audit log feature and write the audit logs to SLS.

      To enable the audit log feature, enter y and press Enter to go to the next step to specify the SLS parameters.

      Otherwise, enter n and press Enter to start the deployment. In this case, OMS does not audit the logs after deployment.

   8. Specify the SLS parameters.

      1. Set the SLS parameters as prompted.

      2. Confirm whether the displayed settings are correct.

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

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

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

   10. Specify the directory to which the OMS container is mounted on the node.

       Specify a directory with a large capacity.

   11. Confirm whether the OMS image file can be named <OMS_IMAGE>.

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

   12. Determine whether to mount an SSL certificate to the OMS container.

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

   13. Start the deployment.

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

Deployment procedure with a configuration file

If an OMS configuration file exists, you can use the deployment tool to verify the OMS configuration file and directly use the file.

1. Log in to the server where OMS is to be deployed.

2. (Optional) Deploy a time-series database.

   If you need to collect and display OMS monitoring data, deploy a time-series database. Otherwise, you can skip this step. For more information, see Deploy a time-series database.

3. Run the following command to obtain the deployment script docker_remote_deploy.sh from the loaded image:

   sudo docker run --name oms-config-tool <OMS_IMAGE> bash && sudo docker cp oms-config-tool:/root/docker_remote_deploy.sh . && sudo docker rm -f oms-config-tool
   

4. Use the deployment script to start the deployment tool.

   sh docker_remote_deploy.sh -o <Mount directory of the OMS container> -c <Directory of the existing config.yaml file> -i <IP address of the server> -d <OMS_IMAGE>
   

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

   1. Select a deployment mode.

      Select Single Node in Single Region.

   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?, it indicates that the database names you specified already exist in the MetaDB in the original configuration file. This may be caused by repeated deployment or upgrade of OMS. You can enter y and press Enter to proceed, or enter n and press Enter to modify the settings.

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

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

   5. Specify the directory to which the OMS container is mounted on the node.

      Specify a directory with a large capacity.

   6. Confirm whether the OMS image file can be named <OMS_IMAGE>.

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

   7. Determine whether to mount an SSL certificate to the OMS container.

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

   8. Start the deployment.

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

To modify the configuration after deployment, perform the following steps:

1. Log in to the OMS container.

2. Modify the config.yaml file in the /home/admin/conf/ directory based on business needs.

3. Run the python -m omsflow.scripts.units.oms_init_manager --init-config-file command.

4. Run the supervisorctl restart oms_console oms_drc_supervisor command.

Template and example of a configuration file

Configuration file template

The configuration file template in this topic is used for the regular password-based login method. If you log in to the OMS console by using single sign-on (SSO), you must integrate the OpenID Connect (OIDC) protocol and add parameters in the config.yaml file template. For more information, see Integrate the OIDC protocol to OMS to implement SSO.

# Information about the OMS MetaDB
oms_meta_host: ${oms_meta_host}
oms_meta_port: ${oms_meta_port}
oms_meta_user: ${oms_meta_user}
oms_meta_password: ${oms_meta_password}
     
# You can customize the names of the following three databases, which are created in the MetaDB when you deploy OMS.
drc_rm_db: ${drc_rm_db}
drc_cm_db: ${drc_cm_db}
drc_cm_heartbeat_db: ${drc_cm_heartbeat_db}
     
# OMS settings
# In single-node deployment mode, the IP address of the server where OMS is to be deployed is used. We recommend that you use an internal IP address.
cm_url: ${cm_url}
cm_location: ${cm_location}
# The cm_region parameter is not required in single-node deployment mode.
# cm_region: ${cm_region}
# The cm_region_cn parameter is not required in single-node deployment mode.
# cm_region_cn: ${cm_region_cn}
cm_is_default: true
cm_nodes:
 - ${cm_nodes}
     
# Configurations of the time-series database
# The default value of `tsdb_enabled`, which specifies whether to configure a time-series database, is `false`. To enable metric reporting, set the parameter to `true`.
# tsdb_enabled: false 
# If the `tsdb_enabled` parameter is set to `true`, delete comments for the following parameters and specify the values based on your actual configurations.
# tsdb_service: 'INFLUXDB'
# tsdb_url: '${tsdb_url}'
# tsdb_username: ${tsdb_user}
# tsdb_password: ${tsdb_password}

Sample configuration file

Replace related parameters with the actual values in the target deployment environment.

oms_meta_host: xxx.xxx.xxx.xxx
oms_meta_port: 2883
oms_meta_user: oms_meta_user
oms_meta_password: **********
drc_rm_db: oms_rm
drc_cm_db: oms_cm
drc_cm_heartbeat_db: oms_cm_heartbeat
cm_url: http://xxx.xxx.xxx.xxx:8088
cm_location: 100
cm_region: cn-anhui
cm_region_cn: cn-anhui
cm_is_default: true
cm_nodes:
  - xxx.xxx.xxx.xxx
tsdb_service: 'INFLUXDB'
tsdb_enabled: true
tsdb_url: 'xxx.xxx.xxx.xxx:8086'
tsdb_username: username
tsdb_password: *************