Deploy OceanBase Database in a production environment by using the CLI

This topic describes how to deploy OceanBase Database in a production environment by running OceanBase Deployer (OBD) commands on the CLI.

Terms

• Central control server

  The server on which OBD is installed. It stores the installation package and configuration information about OceanBase clusters and is used for cluster management.

• Target server

  The server where you want to install OceanBase Database.

• OBD

  OBD is a tool used to install and deploy OceanBase clusters. For more information, see OBD Documentation.

• ODP

  OceanBase Database Proxy (ODP), also known as OBProxy, is a high-performance reverse proxy service designed for OceanBase Database. For more information, see ODP Documentation.

• OCP

  OceanBase Cloud Platform (OCP) is an O&M tool for OceanBase Database. For more information, see OCP Documentation.

• OCP Express

  OCP Express is a web-based management tool for OceanBase Database V4.x. Integrated with an OceanBase cluster, OCP Express allows you to view key performance metrics of the cluster and perform basic database management operations on the cluster.

Prerequisites

Before you deploy OceanBase Database, make sure that the following requirements are met:

• Your server meets the software and hardware requirements. For more information, see Software and hardware requirements.

• In the production environment, you must check the environment and configurations. For more information, see Configuration before deployment.

• You have installed OBD (latest version recommended) on the central control server. For more information, see Install and configure OBD.

• You have installed OceanBase Client (OBClient) on your server. For more information, see OBClient Documentation.

Deployment mode

This topic describes a three-replica deployment mode. You can choose an appropriate deployment mode as needed. We recommend that you use four servers for this deployment mode. The following table describes how the four servers are used.

Procedure

Step 1: (Optional) Download and install the all-in-one package

OceanBase provides an all-in-one installation package since V4.0.0. You can use this package to install OBD, OceanBase Database, ODP, OBAgent, and other components at a time.

You can download and install desired components of specified versions from OceanBase Download Center.

Online installation

If your server can connect to the Internet, run the following commands to install the components online:

[admin@test001 ~]$ bash -c "$(curl -s https://obbusiness-private.oss-cn-shanghai.aliyuncs.com/download-center/opensource/oceanbase-all-in-one/installer.sh)"
[admin@test001 ~]$ source ~/.oceanbase-all-in-one/bin/env.sh

Offline installation

If your server cannot connect to the Internet, perform the following steps to install the components offline:

1. Download the latest all-in-one package from OceanBase Download Center and copy it to any directory on the central control server.

2. In the directory where the package is located, run the following commands to decompress and install the package:

   [admin@test001 ~]$ tar -xzf oceanbase-all-in-one-*.tar.gz
   [admin@test001 ~]$ cd oceanbase-all-in-one/bin/
   [admin@test001 bin]$ ./install.sh
   [admin@test001 bin]$ source ~/.oceanbase-all-in-one/bin/env.sh
   

Step 2: Configure OBD

If you are deploying an OceanBase cluster offline, you can download the all-in-one installation package to the central control server and install the package as described in Step 1. The components provided in the all-in-one installation package have been adapted to each other and are officially recommended.

You can also download the installation package of the desired version for a component from OceanBase Download Center. Then, copy the package to any directory on the central control server and perform the following steps to configure OBD.

1. Disable remote repositories.

   [admin@test001 rpm]$ obd mirror disable remote
   

   Note

   After you install the all-in-one package, the remote repositories are automatically disabled. You can run the obd mirror list command for confirmation. If the values of the remote repositories in the Enabled column are changed to False, the remote image sources are disabled.

2. Add the installation package to the local image repository.

   [admin@test001 rpm]$ obd mirror clone *.rpm
   

3. View the list of installation packages in the local image repository.

   [admin@test001 rpm]$ obd mirror list local
   

4. Select a configuration file.

   If OBD is directly downloaded and installed on your server, you can view the sample configuration file provided by OBD in the /usr/obd/example directory.

   If OBD is installed by using the all-in-one package, you can view the sample configuration file provided by OBD in the ~/.oceanbase-all-in-one/obd/usr/obd/example directory. Select the corresponding configuration file based on your resource conditions.

   Note

   Two types of configuration files are available: one for the small-scale development mode and one for the professional development mode. The configuration files for the two modes contain the same parameters but different parameter values. You can select a file based on your resource conditions.

   • The small-scale development mode applies to individual devices with at least 8 GB of memory. The configuration file name contains mini or min.

   • The professional development mode applies to advanced Elastic Compute Service (ECS) instances or physical servers with at least 16 CPU cores and 64 GB of memory.

   If you select standalone deployment, only one target server is required. In this case, you can use a configuration file for standalone deployment.

   • Sample configuration files for local standalone deployment: mini-local-example.yaml and local-example.yaml

   • Sample configuration files for standalone deployment: mini-single-example.yaml and single-example.yaml

   • Sample configuration files for standalone deployment with ODP: mini-single-with-obproxy-example.yaml and single-with-obproxy-example.yaml

   If you select distributed deployment, multiple target servers are required. In this case, you can use a configuration file for distributed deployment.

   • Sample configuration files for distributed deployment: mini-distributed-example.yaml and distributed-example.yaml

   • Sample configuration files for distributed deployment with ODP: mini-distributed-with-obproxy-example.yaml and distributed-with-obproxy-example.yaml

   • Sample configuration files for distributed deployment with ODP and OCP Express: default-components.yaml and default-components-min.yaml

   • Sample configuration files for distributed deployment with all components: all-components-min.yaml and all-components.yaml

   Note

   If you choose to deploy OCP Express or have deployed OCP, you do not need to deploy Prometheus or Grafana.

5. Modify the configuration file.

   The following uses default-components.yaml, a configuration file for distributed deployment, as an example to describe how to modify the configuration file.

   Note

   You need to modify related parameters based on the actual environment.

   1. Change the username and password.

      ## Only need to configure when remote login is required
      user:
        username: admin
      #   password: your password if need
        key_file: /home/admin/.ssh/id_rsa
      #   port: your ssh port, default 22
      #   timeout: ssh connection timeout (second), default 30
      

      Here, username specifies the username of the account used to log on to the target server. Make sure that this account has the write privilege on home_path. password and key_file are used for user verification. Generally, you only need to specify either of them.

      Notice

      After you specify the path of the key, comment out or delete the password field if your key does not require a password. Otherwise, the value of the password parameter will be deemed as the password of the key and used for logon, leading to a logon verification failure.

   2. Modify the IP address, port, and related directories of each server, and specify memory-related parameters and the password.

      oceanbase-ce:
        servers:
          # Do not use the hostname. Only IP address is supported.
          - name: server1
            ip: 10.10.10.1
          - name: server2
            ip: 10.10.10.2
          - name: server3
            ip: 10.10.10.3
        global:
          devname: eth0
          cluster_id: 1
          # please set memory limit to a suitable value which is matching resource.
          memory_limit: 64G # The maximum running memory for an observer
          system_memory: 30G # The reserved system memory. system_memory is reserved for general tenants.
          datafile_size: 192G # Size of the data file.
          datafile_next: 200G
          datafile_maxsize: 1T
          log_disk_size: 192G # The size of disk space used by the clog files.
          enable_syslog_wf: false # Print system logs whose levels are higher than WARNING to a separate log file. The default value is true.
          enable_syslog_recycle: true # Enable auto system log recycling or not. The default value is false.
          max_syslog_file_count: 4 # The maximum number of reserved log files before enabling auto recycling. The default value is 0.
          ocp_meta_tenant: # The config for ocp express meta tenant
            tenant_name: ocp
            max_cpu: 1
            memory_size: 2G
            log_disk_size: 7680M
          mysql_port: 2881 # External port for OceanBase Database. The default value is 2881. DO NOT change this value after the cluster is started.
          rpc_port: 2882 # Internal port for OceanBase Database. The default value is 2882. DO NOT change this value after the cluster is started.
          # The working directory for OceanBase Database. OceanBase Database is started under this directory. This is a required field.
          home_path: /home/admin/observer
          # The directory for data storage. The default value is $home_path/store.
          data_dir: /data
          # The directory for clog, ilog, and slog. The default value is the same as the data_dir value.
          redo_dir: /redo
          root_password: ****** # root user password, can be empty
          proxyro_password: ******** # proxyro user pasword, consistent with obproxy's observer_sys_password, can be empty
        server1:
          zone: zone1
        server2:
          zone: zone2
        server3:
          zone: zone3
      

      If the servers have inconsistent parameters, move the relevant parameters to the sections of target servers and separately set the parameters for the servers. Parameters in server sections have higher priority than those in the global section. For example, you can modify the configuration file as follows to configure different ports for two servers:

      server2:
        mysql_port: 3881
        rpc_port: 3882
        zone: zone2
      server3:
        mysql_port: 2881
        rpc_port: 2882
        zone: zone3
      

      Parameter	Required?	Default value	Description
      servers	Yes	N/A	Each server is specified in the format of - name: server identifier (line break) ip: server IP address. You can specify multiple servers. The server identifiers must be unique. If the server IP addresses are unique, you can also specify the servers in the - <ip> (line break)- <ip> format. In this case, - <ip> is equivalent to - name: server IP address (line break) ip: server IP address.
      devname	No	N/A	The network interface card (NIC) corresponding to the IP address specified in servers. You can view the mapping between IP addresses and NICs by using the ip addr command.
      memory_limit	No	0	The maximum memory that the observer process can obtain from the environment. If this parameter is not configured, the memory_limit_percentage parameter takes effect. For more information about the two parameters, see memory_limit and memory_limit_percentage.
      system_memory	No	0M	The reserved system memory, which is part of memory_limit. If this parameter is not specified, OceanBase Database reserves memory for the system in adaptive mode.
      datafile_size	No	0	The size of the data file block_file on the corresponding OBServer node. If this parameter is not specified, the datafile_disk_percentage parameter takes effect. For more information, see datafile_size and datafile_disk_percentage.
      datafile_next	No	0	The auto scaling step of disk space. If this parameter is not configured, to enable auto scaling, see Configure auto scaling of disk data files.
      datafile_maxsize	No	0	The maximum disk space allowed for auto scaling. If this parameter is not configured, to enable auto scaling, see Configure auto scaling of disk data files.
      log_disk_size	No	0	The size of the redo log disk. If this parameter is not configured, the log_disk_percentage parameter takes effect. For more information, see log_disk_size and log_disk_percentage.
      enable_syslog_wf	No	true	Specifies whether to print system logs above the WARN level to a separate log file.
      enable_syslog_recycle	No	false	Specifies whether to automatically recycle system logs. This parameter is used together with the max_syslog_file_count parameter. This parameter takes effect only when max_syslog_file_count is set to a nonzero value.
      max_syslog_file_count	No	0	The maximum number of system log files that can be retained. The value 0 indicates to disable automatic recycling.
      ocp_meta_tenant	No	tenant_name: ocp max_cpu: 1 memory_size: 2147483648	The meta tenant specifications for OCP Express. The configurations under ocp_meta_tenant are passed in as parameters when you create a tenant. The example only shows a few important parameters. For more information about the parameters that can be configured, see the description of the obd cluster tenant create command in Cluster commands in OBD Documentation.
      mysql_port	Yes	2881	The SQL port number. Default value: 2881.
      rpc_port	Yes	2882	The Remote Procedure Call (RPC) port number, which is used for communication between the observer process and other node processes. Default value: 2882.
      home_path	Yes	N/A	The installation path of OceanBase Database. We recommend that you choose a path under the admin user.
      data_dir	No	$home_path/store	The directory for storing SSTables and other data. We recommend that you use a separate disk.
      redo_dir	No	Same as data_dir by default	The directory for storing clogs, ilogs and slogs. The value is the same as that of data_dir by default. We recommend that you use an independent directory.
      root_password	No	Empty by default for OBD V2.0.0 and earlier A random string by default for OBD V2.1.0 and later	The password of the super administrator (root@sys) of the OceanBase cluster. We recommend that you set a complex password. If you do not specify this parameter in OBD V2.1.0 or later, a random string is automatically generated.
      proxyro_password	No	Empty by default for OBD V2.0.0 and earlier A random string by default for OBD V2.1.0 and later	The password of the account for connecting the OceanBase cluster (proxyro@sys) through ODP. If you do not specify this parameter in OBD V2.1.0 or later, a random string is automatically generated.

   3. Configure the obproxy-ce component and modify the IP address and home_path.

      obproxy-ce:
        depends:
          - oceanbase-ce
        servers:
          - 10.10.10.4
        global:
          listen_port: 2883 # External port. The default value is 2883.
          prometheus_listen_port: 2884 # The Prometheus port. The default value is 2884.
          home_path: /home/admin/obproxy
          enable_cluster_checkout: false
          skip_proxy_sys_private_check: true
          enable_strict_kernel_release: false
          obproxy_sys_password: ****** # obproxy sys user password, can be empty. When a depends exists, OBD gets this value from the oceanbase-ce of the depends.
          observer_sys_password: ***** # proxyro user pasword, consistent with oceanbase-ce's proxyro_password, can be empty. When a depends exists, OBD gets this value from the oceanbase-ce of the depends.
      

      Parameter	Required?	Default value	Description
      servers	Yes	N/A	Each server is specified in the format of - name: server identifier (line break) ip: server IP address. You can specify multiple servers. The server identifiers must be unique. If the server IP addresses are unique, you can also specify the servers in the - <ip> (line break)- <ip> format. In this case, - <ip> is equivalent to - name: server IP address (line break) ip: server IP address.
      listen_port	Yes	2883	The ODP listening port. Default value: 2883.
      prometheus_listen_port	Yes	2884	The listening port of ODP Prometheus. Default value: 2884.
      home_path	Yes	N/A	The ODP installation path. We recommend that you use a path under the admin user.
      obproxy_sys_password	No	Empty by default for OBD V2.0.0 and earlier A random string by default for OBD V2.1.0 and later	The password of the ODP administrator account (root@proxysys). If you do not specify this parameter in OBD V2.1.0 or later, a random string is automatically generated.
      observer_sys_password	No	Empty by default for OBD V2.0.0 and earlier A random string same as proxyro_password by default for OBD V2.1.0 and later	The password of the account for connecting the OceanBase cluster (proxyro@sys) through ODP. Set the password same as observer_sys_password. If you do not specify this parameter in OBD V2.1.0 or later, a random string same as proxyro_password is automatically generated.

   4. Modify the IP addresses and home_path for the obagent and ocp-express components.

      Notice

      OBD V2.0.0 and later support the deployment of OCP Express. OBD V2.0.0 supports the deployment of OCP Express V1.0.0 only. To deploy OCP Express V1.0.1 or later, you must use OBD V2.1.0 or later.

      obagent:
        depends:
          - oceanbase-ce
        servers:
          - name: server1
            # Do not use the hostname. Only IP address is supported.
            ip: 10.10.10.1
          - name: server2
            ip: 10.10.10.2
          - name: server3
            ip: 10.10.10.3
        global:
          home_path: /home/admin/obagent
      ocp-express:
        depends:
          - oceanbase-ce
          - obproxy-ce
          - obagent
        servers:
          - name: server1
            ip: 10.10.10.4
        global:
          # The working directory for prometheus. prometheus is started under this directory. This is a required field.
          home_path: /home/oceanbase/ocp-server
          memory_size: 1G # The memory size of ocp-express server. The recommend value is 512MB + (expect node num + expect tenant num) * 60MB.
          admin_passwd: ********
          logging_file_total_size_cap: 10GB # The total log file size of ocp-express server.
          # logging_file_max_history: 1 # The maximum of retention days the log archive log files to keep. The default value is unlimited
      

      Parameter	Required?	Default value	Description
      servers	Yes	N/A	Each server is specified in the format of - name: server identifier (line break) ip: server IP address. You can specify multiple servers. The server identifiers must be unique. If the server IP addresses are unique, you can also specify the servers in the - <ip> (line break)- <ip> format. In this case, - <ip> is equivalent to - name: server IP address (line break) ip: server IP address.
      home_path	Yes	N/A	The installation path of the component. We recommend that you use a path under the admin user.
      memory_size	Yes	N/A	The memory capacity of the OCP Express server. The recommended value is calculated as follows: memory_size = 512 MB + (Expected number of nodes × Expected number of tenants) × 60 MB. The sys tenant and OCP meta tenant must be included in this formula.
      logging_file_total_size_cap	Yes	1 GB	The total size of log files. The default value is 1 GB. Notice The unit of this parameter must be GB or MB. If you use the unit G or M, an error is reported and OCP Express cannot be deployed.
      admin_passwd	Yes	N/A	The password of the admin account for logging on to OCP Express. The password must be 8 to 32 characters in length and contain at least two digits, two uppercase letters, two lowercase letters, and two special characters. The supported special characters are ~!@#%^&*_-+=\|(){}[]:;,.?/. If you do not specify this parameter in OBD V2.1.0 or later, a random string is automatically generated.

Step 3: Deploy the OceanBase cluster

1. Deploy an OceanBase cluster.

   [admin@test001 ~]$ obd cluster deploy obtest -c default-components.yaml
   

   After you run the obd cluster deploy command, if your server is connected to the Internet, OBD checks whether the desired installation package exists on the target server. If no, OBD automatically obtains the installation package from the YUM source.

2. Start the OceanBase cluster.

   [admin@test001 ~]$ obd cluster start obtest
   

   If OCP Express is installed, the access address of OCP Express is returned. On Alibaba Cloud or other cloud environments, the installation program may fail to obtain a public IP address and thereby return an intranet network address. Make sure that you use the correct address.

3. View the status of the OceanBase cluster.

   # View the list of clusters managed by OBD.
   [admin@test001 ~]$ obd cluster list
   
   # View the status of the obtest cluster.
   [admin@test001 ~]$ obd cluster display obtest
   

4. (Optional) Modify the cluster configurations.

   OceanBase Database has hundreds of parameters and some are coupled. We recommend that you do not modify parameters in the sample configuration file before you become familiar with OceanBase Database. The following example shows you how to modify a parameter and make it take effect:

   # Run the edit-config command to enter the edit mode before you can edit the cluster configurations.
   # After you modify and save the configurations and exit, OBD will prompt how to validate the modifications. Copy the command provided by OBD.
   [admin@test001 ~]$ obd cluster edit-config obtest
   Search param plugin and load ok
   Search param plugin and load ok
   Parameter check ok
   Save deploy "obtest" configuration
   Use `obd cluster reload obtest` to make changes take effect.
   [admin@test001 ~]$ obd cluster reload obtest
   

Step 4: Connect to the OceanBase cluster

Run the following command to use OBClient to connect to the OceanBase cluster:

obclient -h<IP> -P<PORT> -uroot@sys -p -c -A
# example
obclient -h10.10.10.4 -P2883 -uroot@sys -p -c -A

In the command, IP specifies the IP address for connecting to OceanBase Database, and PORT specifies the port for connecting to OceanBase Database, which takes the value of the mysql_port parameter in the case of a direct connection, or the value of the listen_port parameter in the case of a connection through ODP.

For more information about how to use OBClient to connect to an OceanBase cluster, see Connect to an OceanBase Database tenant by using OBClient.

Step 5: Create a user tenant

After the OceanBase cluster is deployed, we recommend that you create a user tenant to perform business operations. The sys tenant is intended only for cluster management and is unsuitable for business scenarios.

You can use one of the following methods to create a user tenant:

• Method 1: Create a user tenant by using OBD.

  obd cluster tenant create <deploy name> [-n <tenant name>] [flags]
  # example
  obd cluster tenant create test -n obmysql --max-cpu=2 --memory-size=2G --log-disk-size=3G --max-iops=10000 --iops-weight=2 --unit-num=1 --charset=utf8
  

  By default, this command creates a tenant based on all remaining available resources of the cluster. You can configure the parameters to allocate specific amount of resources to the tenant. For more information about this command, see obd cluster tenant create in Cluster commands.

• Method 2: Create a user tenant by using the CLI. For more information, see Create a tenant.

Related operations

Manage clusters

You can run the following commands to manage OceanBase clusters deployed by using OBD. For more information, see Cluster commands in OBD Documentation.

# View the cluster list.
obd cluster list

# View the status of a cluster. The following takes the obtest cluster as an example.
obd cluster display obtest

# Stop a running cluster. The following takes the obtest cluster as an example.
obd cluster stop obtest

# Destroy a deployed cluster. The following takes the obtest cluster as an example.
obd cluster destroy obtest

Uninstall the all-in-one package

To uninstall the all-in-one package, perform the following steps:

1. Uninstall the package.

   [admin@test001 ~]$ cd oceanbase-all-in-one/bin/
   [admin@test001 bin]$ ./uninstall.sh
   

2. Delete environment variables.

   [admin@test001 bin]$ vim ~/.bash_profile
   # Delete the source /home/admin/.oceanbase-all-in-one/bin/env.sh from the file.
   

3. Make the modification take effect.

   After you delete the environment variables, you must log on to the terminal again or run the source command to make the modification take effect. For example:

   [admin@test001 ~]$ source ~/.bash_profile