Deploy OMS on a single node

This topic describes how to use the OMS deployment tool to install OceanBase Migration Service (OMS) on a single node.

Prerequisites

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

• The RM database, CM database, and heartbeat database have been prepared as the metadata databases of OMS. If you have not prepared them in advance, OMS will automatically create them.

• You have obtained the OMS installation package, which is usually a tar.gz file that starts with oms.

• The downloaded OMS installation package has been loaded to the local image repository of the Docker container.

  docker load -i <installation package of OMS>

• OMS has 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) The time series database is prepared for OMS to store performance monitoring data and DDL/DML statistics.

Terms

In the following guides, some commands and prompt messages contain placeholders for values that you must replace. These placeholders are enclosed in <>.

• OMS container mount directory: For more information, see the section about OMS container mount directory in the prerequisites.

• Local IP address: The IP address of the host where the script is executed. In a single-node scenario, it is automatically resolved to the corresponding IP address in the CM configuration.

• OMS_IMAGE: After you load the OMS installation package using Docker, run the docker images command to obtain the [IMAGE ID] or [REPOSITORY:TAG] of the loaded image, which serves as the unique identifier of the image. The variable name is <OMS_IMAGE>. 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. In the following instructions, replace <OMS_IMAGE> in the related commands with one of the preceding values.

• Existing config.yaml configuration file path: If you want to deploy based on the existing config.yaml configuration file, this field provides the path of the existing configuration file.

Deployment process (without a configuration file)

If you do not have a configuration file for OMS, we recommend that you generate a new configuration file and deploy it by using the process without a configuration file. If you already have a configuration file, we recommend that you use the process with a configuration file.

Integrated deployment mode

1. Log in to the OMS deployment server.

2. (Optional) Deploy the time series database.

   If you want OMS to collect and display monitoring data, deploy the time series database. If not, 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. Run the deployment tool by using the deployment script.

   sh docker_remote_deploy.sh -o <OMS mount directory> -i <local IP address> -d <OMS_IMAGE>
   

5. Complete the deployment based on the tool tips. Press Enter after each input to proceed to the next step.

   1. Select the deployment mode:

      Select the Single Region Single Node option.

   2. Select the task you want to perform.

   Select No configuration file. Deploy OMS for the first time. Start from generating the configuration file.

   3. Configure the MetaDBs of RM and CM to store the metadata of OMS.

      1. Enter the IP address, port, username, and password of the RM MetaDB.

      2. Please set a prefix for the OMS MetaDB.

         For example, if the prefix is set to oms, the names of the created MetaDBs are oms_rm, oms_cm, and oms_cm_hb.

      3. Check the configuration information.

         Enter y to confirm the preceding configurations, or enter n to reconfigure the settings.

      4. If the Database name already exists in the MetaDB. Continue? prompt appears, it indicates that the database name you entered already exists in the MetaDB. This situation may be due to repeated deployment or OMS upgrade. Enter y to continue the deployment with the existing configuration, or enter n to re-enter the configuration.

   4. Enter the following CM configuration information:

   5. Please confirm whether the default IP address is correct.

      The displayed IP address corresponds to the Local IP Address entered when the deployment script was initiated. If the IP address is correct, enter y. If not, enter n.

   6. The interface displays the cluster configuration information of OMS. Please check whether the IP address in cm_url is the IP address of the current host. If it is, enter y. If not, enter n.

   7. Check whether to monitor the historical data of OMS.

      • If you chose to deploy the time series database in the (Optional) Deploy time series database step, enter y and proceed to the Configure time series database step to monitor the historical data of OMS.

      • If you chose not to deploy a time series database in the (Optional) Deploy Time Series Database step, enter n at this step. The system will then proceed to the Enable the Audit Log Feature and Configure Related SLS Parameters step. In this case, the deployed OMS cannot monitor historical data.

   8. Configure the time series database.

      Enter the configuration information of the time series database:

      1. Have you deployed a time series database service?

         Please enter y if the answer is yes, or n if the answer is no.

      2. Select the type of time series database: Choose "INFLUXDB".

         Notice

         Only the INFLUXDB time series database is supported.

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

      4. Please confirm all configuration details.

         If the information is correct, enter y. If you want to modify the information, enter n.

   9. Do you want to enable the OMS audit log feature and write the audit logs to the SLS service?

      If you enter y, the audit log feature is enabled. In this case, skip to the Enter SLS parameters step.

      If you enter n, the deployment is officially started. In this case, the deployed OMS does not support the audit log feature.

   10. Enter the SLS parameters.

       1. Enter the parameters of SLS based on the prompts.

       2. Please confirm all configuration details.

          If the information is correct, enter y. If you want to modify the information, enter n.

   11. If the configuration file check succeeds, all configuration information is displayed. Enter n to confirm the configurations. To modify the configurations, enter y.

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

   12. Enter the mount directory on the node with IP address for deploying the OMS container.

       Enter a directory with a large capacity as the mount directory for the OMS container.

   13. Please confirm whether the image name of OMS is correctly specified as <OMS_IMAGE>.

       If the information is correct, enter y. If you want to modify the information, enter n.

   14. Check whether to mount the HTTPS certificate to the OMS container.

       Enter y and follow the prompts to enter the https_key and https_crt directories if needed. Enter n if not needed.

   15. Start the deployment.

       If the deployment fails, you can log in to the running OMS container and view the .log files with the docker_init prefix in the /home/admin/logs directory to obtain log information. If the OMS container fails to start, no logs can be obtained.

Separate deployment mode

1. Log in to the OMS deployment server.

2. (Optional) Deploy the time series database.

   If you want OMS to collect and display monitoring data, deploy the time series database. If you don't need to display the monitoring data, 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_v2.sh from the loaded image.

   sudo docker run -d --net host --name oms-config-tool <management image or component image> bash && sudo docker cp oms-config-tool:/root/docker_remote_deploy_v2.sh . && sudo docker rm -f oms-config-tool
   

   Here is an example:

   sudo docker run -d --net host --name oms-config-tool 0719**** bash && sudo docker cp oms-config-tool:/root/docker_remote_deploy_v2.sh . && sudo docker rm -f oms-config-tool
   

4. Run the deployment tool by using the deployment script.

   You can deploy the management and component modules simultaneously or deploy the management or component module separately.

   • Deploying the management and component modules at the same time

     sh docker_remote_deploy_v2.sh -o <OMS container mount directory> -i <local IP address> -v <management image> -s <component image>
     

   • Deploy only the management module

     sh docker_remote_deploy_v2.sh -o <OMS container mount directory> -i <local IP address> -v <management image>
     

   • Deploy only the components.

     sh docker_remote_deploy_v2.sh -o <OMS container mount directory> -i <local IP address> -s <component image>
     

5. Complete the deployment based on the tool tips. Press Enter after each input to proceed to the next step.

   1. Select the deployment mode:

      Select the Single Region Single Node option here.

   2. Select the task you want to perform.

   Select No configuration file. Deploy OMS for the first time. Start from generating the configuration file.

   3. Configure the MetaDB for RM and CM to store metadata of OMS.

      1. Enter the IP address, port, username, and password of the MetaDB for RM and CM.

      2. Please set a prefix for the OMS MetaDB.

         For example, if the prefix is set to oms, the names of the created MetaDBs are oms_rm, oms_cm, and oms_cm_hb.

      3. Check the configuration information.

         Enter y to confirm the configuration information, or enter n to reconfigure the information.

      4. If the Database name already exists in the MetaDB. Continue? prompt appears, it indicates that the database name you entered already exists in the MetaDB. This situation may be due to repeated deployment or an OMS upgrade. Enter y to continue the deployment with the existing configuration, or enter n to reconfigure.

   4. Enter the following CM configuration information:

   5. Please confirm whether the default IP address is correct.

      The displayed IP address corresponds to the Local IP Address entered when the deployment script was initiated. If the IP address is correct, enter y. If not, enter n.

   6. The interface displays the cluster configuration of OMS. Please check whether the IP address in cm_url is the IP address of the current host. If it is, enter y. If not, enter n.

   7. Do you want to monitor the historical data of OMS?

      • If you chose to deploy the time series database in the (Optional) Deploy time series database step, enter y and proceed to the Configure time series database step to monitor the historical data of OMS.

      • If you chose not to deploy the time series database in the (Optional) Deploy time series database step, enter n at this step. The system will then proceed to the Enable the audit log feature and configure related SLS parameters step. In this case, the deployed OMS does not support historical data monitoring.

   8. Configure the time series database.

      Enter the following configuration information for the time series database:

      1. Have you deployed a time series database service?

         Please enter y if it exists, or n if it does not.

      2. Select the type of time series database: Choose "INFLUXDB".

         Notice

         At present, only the INFLUXDB time series database is supported.

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

      4. Please confirm all configuration details.

         If the information is correct, enter y. If you want to modify the information, enter n.

   9. Do you want to enable the OMS audit log feature and write the audit logs to the SLS service?

      If you enter y, the audit log feature is enabled. In this case, proceed to the Enter SLS parameters step.

      If you enter n, the deployment starts. After the OMS is deployed, the audit log feature is unavailable.

   10. Enter the SLS parameters.

       1. Enter the parameters of SLS according to the prompts.

       2. Please confirm all configuration details.

          If the information is correct, enter y. If you want to modify the information, enter n.

   11. If the configuration file check succeeds, all configuration information is displayed. Enter n to confirm the configurations. To modify the configurations, enter y.

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

   12. Complete the deployment of the management module based on the tool prompt.

       1. Enter the mount directory on the management node for deploying the OMS container.

       2. Please confirm whether the image name <OMS_IMAGE> for deploying OMS is correct.

          If the information is correct, enter y. If you want to modify the information, enter n.

       3. Check whether an HTTPS certificate needs to be mounted to the OMS container.

          If you want to enable HTTPS, enter y and follow the prompts to enter the https_key and https_crt directories. If not, enter n.

       4. Please confirm the write path of the configuration file config.yaml under the node.

          If the information is correct, enter y. If you want to modify the information, enter n.

       5. Start deploying the management module. Wait for the deployment to succeed.

          If the deployment fails, you can log in to the running OMS container and view the .log files with docker_init as the prefix in the /home/admin/logs directory to obtain log information. If the OMS container fails to start, no logs can be obtained.

   13. Complete the component deployment based on the tool tip.

       1. Enter the mount directory on the component node for deploying the OMS container.

       Please confirm whether the image name for deploying OMS, <OMS_IMAGE>, is correct.

        If the information is correct, enter y. If you want to modify the information, enter n.
       

       3. Check whether you need to mount the HTTPS certificate to the OMS container.

          If you need, enter y and follow the prompts to specify the https_key and https_crt directories. If not, enter n.

       4. Please confirm the write path of the configuration file config.yaml on the node.

          If the information is correct, enter y. If you want to modify the information, enter n.

       5. Start to deploy the component and wait for the deployment to succeed.

6. After the deployment is completed, you can run the sudo docker ps command to check if both the management and component containers are present.

Deployment process (with a configuration file)

If an OMS configuration file already exists, the deployment tool can verify the existing configuration file to deploy the system without the need to re-enter the configuration details.

After the deployment is completed, if you want to modify the configuration, perform the following operations:

1. Log in to the OMS container.

2. Modify the /home/admin/conf/config.yaml file as needed.

3. Initialize the metadata.

   sh /root/docker_init.sh
   

Integrated deployment mode

1. Log in to the OMS deployment server.

2. (Optional) Deploy the time series database.

   If you want OMS to collect and display monitoring data, deploy the time series database. If you don't need to display the monitoring data, 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. Run the deployment tool by using the deployment script.

   sh docker_remote_deploy.sh -o <OMS container mount directory> -c <path of the existing config.yaml file> -i <local IP address> -d <OMS_IMAGE>
   

5. Complete the deployment based on the tool tips. Press Enter after each input to proceed to the next step.

   1. Select the deployment mode.

      Select the Single Region Single Node option here.

   2. Select the task you want to perform.

      Select Reference configuration file has been passed in through the [-c] option of the script. Start to configure based on the file.

   3. If the Database name already exists in the MetaDB. Continue? prompt appears, it indicates that the database name you entered already exists in the RM and CM MetaDB of the original configuration file. This situation may be due to repeated deployment or OMS upgrade. Enter y to continue the deployment after confirming, or enter n to re-enter the configuration information.

   4. If the configuration file check succeeds, all configuration information is displayed. Enter n to confirm the configurations. To modify the configurations, enter y.

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

   5. Enter the mount directory on the node with the IP address for deploying the OMS container.

      Enter a directory with a large capacity as the mount directory for the OMS container.

   6. Please confirm whether the image name of OMS is correctly specified as <OMS_IMAGE>.

      If the information is correct, enter y. If you want to modify the information, enter n.

   7. Check whether to mount the HTTPS certificate to the OMS container.

      Enter y and follow the prompts to specify the https_key and https_crt directories, or enter n.

   8. Start the deployment.

      If the deployment fails, you can log in to the running OMS container and view the .log files that have the docker_init prefix in the /home/admin/logs directory to obtain log information. If the OMS container fails to start, no logs can be obtained.

Separate deployment mode

1. Log in to the OMS deployment server.

2. (Optional) Deploy the time series database.

   If you want OMS to collect and display monitoring data, deploy the time series database. If not, 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_v2.sh from the loaded image.

   sudo docker run -d --net host --name oms-config-tool <management image or component image> bash && sudo docker cp oms-config-tool:/root/docker_remote_deploy_v2.sh . && sudo docker rm -f oms-config-tool
   

4. Run the deployment tool by using the deployment script.

   You can deploy the management and component modules simultaneously or deploy the management or component module separately.

   • Deploying the management and component modules at the same time

     sh docker_remote_deploy_v2.sh -o <OMS container mount directory> -i <local IP address> -v <management image> -s <component image>
     

   • Deploy only the management module.

     sh docker_remote_deploy_v2.sh -o <OMS container mount directory> -i <local IP address> -v <management image>
     

   • Deploy only the components.

     sh docker_remote_deploy_v2.sh -o <OMS container mount directory> -i <local IP address> -s <component image>
     

5. Complete the deployment based on the tool tips. Press Enter after each input to proceed to the next step.

   1. Select the deployment mode.

      Select the Single Region Single Node option here.

   2. Select the task you want to perform.

      Select Reference configuration file has been passed in through the [-c] option of the script. Start to configure based on the file.

   3. If the Database name already exists in the MetaDB. Continue? prompt appears, the specified database name already exists in the RM and CM MetaDB. This situation may be caused by repeated deployment or OMS upgrade. Enter y to continue the deployment with the existing configuration, or enter n to re-enter the configuration.

   4. If the configuration file check succeeds, all configuration information is displayed. Enter n if the information is correct. Enter y to modify the information.

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

   5. Complete the deployment of the management module based on the tool prompt.

      1. Enter the mount directory on the node with IP address for deploying the OMS container.

         Enter a directory with a large capacity as the mount directory for the OMS container.

      2. Please confirm whether the image name of OMS is correctly specified as <OMS_IMAGE>.

         If the information is correct, enter y. If you want to modify the information, enter n.

      3. Check whether to mount the HTTPS certificate to the OMS container.

         Enter y and follow the prompts to specify the https_key and https_crt directories if you need to. Enter n if you do not need to.

      4. Start deploying the management module and wait for the deployment to succeed.

         If the deployment fails, you can log in to the running OMS container and view the .log files with docker_init as the prefix in the /home/admin/logs directory to obtain log information. If the OMS container fails to start, no logs can be obtained.

   6. Complete the component deployment based on the tool tip.

      1. Enter the mount directory on the component node for deploying the OMS container.

      2. Please confirm whether the image name of OMS is correctly specified as <OMS_IMAGE>.

         If the information is correct, enter y. If you want to modify the information, enter n.

      3. Check whether you need to mount the HTTPS certificate to the OMS container.

         Enter y and follow the prompts to specify the https_key and https_crt directories if needed. Enter n if not needed.

      4. Start the component deployment and wait for it to complete.

Template and sample of the configuration file

Configuration file template

The configuration file template in this topic is for the general password login method. If you log in to OMS using single sign-on (SSO), you need to integrate with the OIDC protocol and add parameters to the config.yaml file template. For more information, see Integrate OMS with the OIDC protocol for SSO.

# RM and CM MetaDB information
oms_cm_meta_host: ${oms_cm_meta_host}
oms_cm_meta_password: ${oms_cm_meta_password}
oms_cm_meta_port: ${oms_cm_meta_port}
oms_cm_meta_user: ${oms_cm_meta_user}
oms_rm_meta_host: ${oms_rm_meta_host}
oms_rm_meta_password: ${oms_rm_meta_password}
oms_rm_meta_port: ${oms_rm_meta_port}
oms_rm_meta_user: ${oms_rm_meta_user}

# Users can customize the names of the following three databases. When OMS is deployed, the three databases will be created in the metadata database.
drc_rm_db: ${drc_rm_db}
drc_cm_db: ${drc_cm_db}
drc_cm_heartbeat_db: ${drc_cm_heartbeat_db}

# Configure OMS
# In single-node deployment, the IP address is usually set to the IP address of the current OMS server (we recommend that you use an intranet IP address).
cm_url: ${cm_url}
cm_location: ${cm_location}
# If you deploy the CM single-node edition, you do not need to set cm_region.
# cm_region: ${cm_region}
# If you deploy a single node, do not set cm_region_cn.
# cm_region_cn: ${cm_region_cn}
cm_nodes:
 - ${cm_nodes}

console_nodes:
 - ${cm_nodes}

# Configure time series databases
# The default value is false. To enable the metrics reporting feature, set the value to true.
# tsdb_enabled: false 
# If tsdb_enabled is set to true, remove the comments from the following parameters and specify appropriate values.
# tsdb_service: 'INFLUXDB'
# tsdb_url: '${tsdb_url}'
# tsdb_username: ${tsdb_user}
# tsdb_password: ${tsdb_password}

Configuration file sample

Please replace the actual values of the parameters based on your target deployment environment.

oms_cm_meta_host: xxx.xxx.xxx.xxx
oms_cm_meta_password: **********
oms_cm_meta_port: 2883
oms_cm_meta_user: oms_cm_meta_user
oms_rm_meta_host: xxx.xxx.xxx.xxx
oms_rm_meta_password: **********
oms_rm_meta_port: 2883
oms_rm_meta_user: oms_rm_meta_user
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: Anhui
cm_nodes:
  - xxx.xxx.xxx.xxx
tsdb_service: 'INFLUXDB'
tsdb_enabled: true
tsdb_url: 'xxx.xxx.xxx.xxx:8086'
tsdb_username: username
tsdb_password: *************