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 Database. For more information, see obd documentation.

• OceanBase Database Proxy (ODP)

  ODP is a dedicated proxy service designed for OceanBase Database. For more information, see ODP documentation.

• OceanBase Cloud Platform (OCP)

  OCP is an OceanBase Database management platform. 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. For more information, see OCP Express.

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 a production environment, you have checked the environment and configurations. For more information, see 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 Database V4.0.0 and later provide an all-in-one installation package. 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. Query the list of installation packages in the local image repository.

   [admin@test001 rpm]$ obd mirror list local
   

4. Select a configuration file.

   If you have installed obd by downloading the RPM package for obd, you can view the sample configuration files in the /usr/obd/example directory.

   If you have installed obd by using the all-in-one installation package, you can view the sample configuration files 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 the other 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 type based on your resource conditions.

   • The small-scale development mode applies to individual devices with at least 8 GB of memory. The configuration file names contain 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 choose 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 must 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 in 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 parameter if your key does not require a password. Otherwise, the value of the password parameter will be taken as the password of the key and used for login, leading to a login 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:
          # Please don't use hostname, only IP can be 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.
          max_syslog_file_count: 4 # The maximum number of reserved log files before enabling auto recycling. The default value is 0.
          # observer cluster name, consistent with obproxy's cluster_name
          appname: obdemo
          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.
          obshell_port: 2886 # Operation and maintenance port for OceanBase Database.
          # 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. 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 password, 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. Configurations 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	None	Specify each server in the format of - name: server identifier (line feed) ip: server IP address. You can specify multiple servers. The server identifiers must be unique. You can specify unique server IP addresses in the format of - <ip> (line feed) - <ip>, where - <ip> is equivalent to - name: server IP address (line feed) ip: server IP address.
      devname	No	None	The network interface cards (NICs) corresponding to the IP addresses specified in servers. You can view the mappings 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 specified, the memory_limit_percentage parameter takes effect.
      system_memory	No	0M	The reserved system memory, which is a 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.
      datafile_next	No	0	The auto scaling step of disk space for data files. For information about how to enable auto scaling when this parameter is not specified, see Configure automatic scale-out of disk space for data files.
      datafile_maxsize	No	0	The maximum size that the disk space for storing data files can be scaled out to. For information about how to enable auto scaling when this parameter is not specified, see Configure automatic scale-out of disk space for data files.
      log_disk_size	No	0	The size of the disk space for storing redo logs. If this parameter is not specified, 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.
      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.
      appname	No	obcluster	The name of the OceanBase cluster.
      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 port number for the SQL service protocol.
      rpc_port	Yes	2882	The port number for remote access, which is the remote procedure call (RPC) communication port between the observer process and other node processes.
      obshell_port	Yes	2886	The O&M port of OceanBase Database.
      home_path	Yes	None	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. We recommend that you use a separate disk.
      root_password	No	Empty in versions earlier than obd V2.1.0 Random string in 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 in versions earlier than obd V2.1.0 Random string in obd V2.1.0 and later	The password of the account (proxyro@sys) used by ODP to connect to the OceanBase cluster. 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 setting.

      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 password, 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	None	Specify each server in the format of - name: server identifier (line feed) ip: server IP address. You can specify multiple servers. The server identifiers must be unique. You can specify unique server IP addresses in the format of - <ip> (line feed) - <ip>, where - <ip> is equivalent to - name: server IP address (line feed) ip: server IP address.
      listen_port	Yes	2883	The listening port of ODP.
      prometheus_listen_port	Yes	2884	The Prometheus listening port of ODP.
      home_path	Yes	None	The installation path of ODP. We recommend that you choose a path under the admin user.
      obproxy_sys_password	No	Empty in versions earlier than obd V2.1.0 Random string in 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 in versions earlier than obd V2.1.0 Random string same as proxyro_password in obd V2.1.0 and later	The password of the account (proxyro@sys) used by ODP to connect to the OceanBase cluster. This password must be the same as the value of proxyro_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 settings 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
            # Please don't use hostname, only IP can be 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	None	Specify each server in the format of - name: server identifier (line feed) ip: server IP address. You can specify multiple servers. The server identifiers must be unique. You can specify unique server IP addresses in the format of - <ip> (line feed) - <ip>, where - <ip> is equivalent to - name: server IP address (line feed) ip: server IP address.
      home_path	Yes	None	The installation path of the component. We recommend that you choose a path under the admin user.
      memory_size	Yes	None	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 counted in the expected number of tenants.
      logging_file_total_size_cap	Yes	1GB	The total size of log files. 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	No	The password of the admin account for logging in 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 the 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 repository.

2. Start the OceanBase cluster.

   [admin@test001 ~]$ obd cluster start obtest
   

   If OCP Express is installed, the access address of OCP Express is returned. In 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 public IP address.

3. Query 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 obd cluster edit-config command to enter the edit mode before you can edit the cluster configurations.

   [admin@test001 ~]$ obd cluster edit-config obtest
   

   After you modify and save the configurations and exit, obd will prompt you on how to validate the modifications. The output returned after you save the configurations is as follows:

   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.
   

   Copy and run the command provided by obd.

   [admin@test001 ~]$ obd cluster reload obtest
   

Step 4: Connect to the OceanBase cluster

Here, we use OBClient as an example to describe how to connect to the OceanBase cluster:

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

where:

• -h specifies the IP address for connecting to OceanBase Database. The value is the IP address of an OBServer node in the case of direct connection, and is the IP address of ODP in the case of connection through ODP.

• -u specifies the account for connecting to OceanBase Database. Supported account formats are username@tenant name#cluster name, cluster name:tenant name:username, cluster name-tenant name-username, and cluster name.tenant name.username. The default username of the administrator of a MySQL tenant is root.

  Notice

  The cluster name used for connection is the one specified by appname in the configuration file, instead of the one specified by deploy name during deployment.

• -P specifies the port for connecting to OceanBase Database. It is the value of the mysql_port parameter in the case of direct connection, and the value of the listen_port parameter in the case of connection through ODP.

• -p specifies the password for connecting to OceanBase Database.

• -c specifies not to ignore comments in the runtime environment of OBClient.

  Note

  Hints are special comments that are not affected by the -c option.

• -A specifies not to automatically retrieve the statistical information when connecting to OceanBase Database by using OBClient.

For more information about how to connect to an OceanBase cluster, see Connect to OceanBase Database.

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 amounts of resources to the tenant. For more information about this command, see obd cluster tenant create in Cluster commands in obd documentation.

• 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 the `obtest` cluster.
obd cluster display obtest

# Stop a running cluster named `obtest`.
obd cluster stop obtest

# Destroy a deployed cluster named `obtest`.
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 in to the CLI again or run the source command to make the modification take effect. Here is an example::

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