Deploy OceanBase Database in a production environment by using a CLI

This topic describes how to deploy OceanBase Database in a production environment by using OceanBase Deployer (OBD).

Concepts

• Central control server

  The server where OBD is installed. The central control server manages the OceanBase cluster and stores the installation package and configurations of the cluster.

• Target server

  The server on which you want to install OceanBase Database.

• OBD

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

• ODP

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

• OCP

  OceanBase Cloud Platform (OCP) is an operation and maintenance tool of OceanBase Database. For more information, see the OCP documentation.

• OCP Express

  OCP Express is a web-based management tool for OceanBase Database V4.x. It is integrated into OceanBase clusters to provide key performance management and basic database management. For more information, see OCP Express.

Prerequisites

Before you connect to OceanBase Database, make sure that:

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

• You have checked the production environment and configurations. For more information, see Configuration before deployment.

• You have installed OBD of the latest version 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 the 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 the purposes of the four servers.

Procedure

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

OceanBase Database is available in an all-in-one installation package since V4.0.0. You can use this package to install OBD, OceanBase Database, ODP, OceanBase Agent (OBAgent), Grafana, Prometheus, and OCP Express 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 OBD 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 OBD 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 deploy the OceanBase cluster in offline mode, download the all-in-one package and install it on the central control server by referring to Step 1. The components in the all-in-one package have passed mutual adaptation tests and therefore are recommended.

You can 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 of OBD to the local image repository.

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

3. View the installation packages list 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 resources.

   Note

   OBD has two configuration files for two modes: minimum specification and professional. The two configuration files have the same resource items with different values. You can select a configuration file based on your actual resource conditions.

   • Minimum-specification mode: applies to individual servers with at least 8 GB of memory. The name of the configuration file of this mode contains the mini or min keyword.

   • Professional mode: applies to an advanced Elastic Compute Service (ECS) instance or physical server with at least 16 CPU cores and 64 GB of memory.

   If you deploy OceanBase Database in standalone mode (with only one OBServer node), you can use the 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 deploy OceanBase Database in distributed mode (with multiple OBServer nodes), 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 want to deploy OCP Express or you have deployed OCP, you do not need to deploy Prometheus and Grafana.

5. Modify the configuration file.

   The following procedure describes how to use the configuration file default-components.yaml to deploy a distributed OceanBase cluster.

   Note

   You must modify the 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. Change the IP address, port, and directories of the server, and configure the memory 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
          # Set the memory limit to a suitable value that matches the memory 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.
          log_disk_size: 192G # The size of disk space used by the clog files.
          enable_syslog_wf: false # Specifies whether to print system logs whose levels are higher than WARNING to a separate log file. Default value: true.
          enable_syslog_recycle: true # Specifies whether to enable auto system log recycling. Default value: 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. Default value: $home_path/store.
          data_dir: /data
          # The directory for clog, ilog, and slog files. Default value: the same as the value of the data_dir parameter.
          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 a parameter has different values on different servers, you can specify this parameter for these servers in the configuration file. The server-specific parameters in the configuration file have a higher priority than global parameters. The following example shows that different ports are configured 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 - name: Server name (line break) ip: Server IP address format. You can specify multiple servers in this format. The server names must be unique. If the server IP addresses are unique, you can also specify servers in the - <ip> (line break)- <ip> format, in which - <ip> is equivalent to - name: Server name (line break) ip: Server IP address.
      devname	No	N/A	The NIC corresponding to the IP address specified for the servers parameter. You can run the ip addr command to view the mappings between IP addresses and NICs.
      memory_limit	No	0	The maximum memory in the system available for the observer process. If this parameter is not specified, the value of memory_limit_percentage takes effect.
      system_memory	No	0M	The reserved system memory. The system memory is part of the memory specified for the memory_limit parameter. If system_memory is not specified, OceanBase Database automatically adapts the size of the reserved system memory.
      datafile_size	No	0	The size of the data file (block_file) of the corresponding OBServer node. If this parameter is not specified, the value of the datafile_disk_percentage parameter takes effect.
      log_disk_size	No	0	The size of the REDO log disk. If this parameter is not specified, the value of the log_disk_percentage parameter takes effect.
      enable_syslog_wf	No	true	Specifies whether to print system logs of a level higher than WARN 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 number of log files supported before log file recycling. The value 0 indicates that log files are not automatically cleared.
      ocp_meta_tenant	No	tenant_name: ocp max_cpu: 1 memory_size: 2147483648	The specifications of the meta tenant for OCP Express. The parameters for ocp_meta_tenant are passed in when the meta tenant is created. The example shows only several 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 of the OBD documentation.
      mysql_port	Yes	2881	The port for the SQL service. Default value: 2881. OBClient directly connects to this port to access the OBServer node.
      rpc_port	Yes	2882	The port used by the observer process for RPC communication with processes on other nodes, which is 2882 by default.
      home_path	Yes	N/A	The installation path of OceanBase Database. We recommend that you specify a directory under the admin user.
      data_dir	No	$home_path/store	The directory for storing data such as SSTable files. We recommend that you specify an independent disk partition.
      redo_dir	No	Same as the value of data_dir	The directory for storing clogs, ilogs, and slogs. The default value is the same as the value of data_dir. We recommend that you specify an independent disk partition.
      root_password	No	Empty for OBD V2.0.0 and earlier A random string for OBD V2.1.0 and later	The password for the super administrator (root@sys) of the OceanBase cluster. We recommend that you specify a complex password. If this parameter is not specified in OBD V2.1.0 or later, a random string is automatically generated.
      proxyro_password	No	Empty for OBD V2.0.0 and earlier A random string for OBD V2.1.0 and later	The password for the account (proxyro@sys) used by ODP to connect to the OceanBase cluster. If this parameter is not specified in OBD V2.1.0 or later, a random string is automatically generated.

   3. Configure ODP Community Edition and change its IP address and the value of home_path.

      obproxy-ce:
        depends:
          - oceanbase-ce
        servers:
          - 10.10.10.4
        global:
          listen_port: 2883 # The external port. Default value: 2883.
          prometheus_listen_port: 2884 # The Prometheus port. Default value: 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 - name: Server name (line break) ip: Server IP address format. You can specify multiple servers in this format. The server names must be unique. If the server IP addresses are unique, you can also specify servers in the - <ip> (line break)- <ip> format, in which - <ip> is equivalent to - name: Server name (line break) ip: Server IP address.
      listen_port	Yes	2883	The listening port of ODP. Default value: 2883.
      prometheus_listen_port	Yes	2884	The listening port of Prometheus. Default value: 2884.
      home_path	Yes	N/A	The installation path of ODP. We recommend that you specify a directory under the admin user.
      obproxy_sys_password	No	Empty for OBD V2.0.0 and earlier A random string for OBD V2.1.0 and later	The password for the administrator account (root@proxysys) of ODP. If this parameter is not specified in OBD V2.1.0 or later, a random string is automatically generated.
      observer_sys_password	No	Empty for OBD V2.0.0 and earlier A random string the same as the value of proxyro_password for OBD V2.1.0 and later	The password for the account (proxyro@sys) used by ODP to connect to the OceanBase cluster. The value must be the same as that of observer_sys_password. For OBD V2.1.0 and later, if this parameter is not specified, a random string the same as the value of proxyro_password is automatically generated.

   4. Change the IP addresses and the value of home_path for OBAgent and OCP Express.

      Notice

      You can use OBD to deploy OCP Express since V2.0.0. OBD V2.0.0 can be used to deploy only OCP Express V1.0.0. OCP Express V1.0.1 and later must be deployed by using 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 - name: Server name (line break) ip: Server IP address format. You can specify multiple servers in this format. The server names must be unique. If the server IP addresses are unique, you can also specify servers in the - <ip> (line break)- <ip> format, in which - <ip> is equivalent to - name: Server name (line break) ip: Server IP address.
      home_path	Yes	N/A	The installation path of OCP Express. We recommend that you specify a directory under the admin user.
      memory_size	Yes	N/A	The memory capacity for OCP Express. The recommended value is calculated by using the following formula: memory_size = 512 MB +(Expected number of nodes × Expected number of tenants) × 60 MB. The sys and OCP meta tenant must be counted.
      logging_file_total_size_cap	Yes	1 GB	The total size of log files. Default value: 1 GB. Notice The unit for this parameter must be GB or MB. The unit G or M will cause failure in deploying OCP Express.
      admin_passwd	Yes	N/A	The password for the admin user on the logon page of OCP Express. The password is 8 ~ 32 characters in length, and it must contain at least two digits, two uppercase letters, two lowercase letters, and two special characters. Supported special characters are ~ ! @ # % ^ & * _ - + = \	( ) { } [ ] : ; , . ? / If this parameter is not specified 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 source.

2. Start the OceanBase cluster.

   [admin@test001 ~]$ obd cluster start obtest
   

   If OCP Express is installed, the access URL of OCP Express is generated. In Alibaba Cloud or other cloud environments, the installation program may not be able to obtain a public IP address and therefore will generate an internal IP address. You must replace it with a correct public IP 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 connect to the OceanBase cluster by using OBClient:

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

In this command, IP is the IP address for connecting to OceanBase Database. PORT is the port for connecting to OceanBase Database, which is the value of mysql_port if you connect to the database directly or the value of listen_port if you connect to the database by using ODP.

Step 5: Create user tenants

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

You can create a user tenant by using the following methods:

• 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
  

  This command automatically creates a tenant based on all remaining resources of the cluster. You can configure the related parameters to control the resources available for the tenant. For more information, see the description of the obd cluster tenant create command in Cluster commands of the OBD documentation.

• Method 2: Create a user tenant by using a CLI.

Related operations

Manage clusters

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

# View the cluster list.
obd cluster list

# View the status of the obtest cluster.
obd cluster display obtest

# Stop the running obtest cluster.
obd cluster stop obtest

# Destroy the obtest cluster.
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 the environment variable.

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

3. Make the modification take effect. For example, after you delete the environment variable, you must log on to the client again or run the following source command for the modification to take effect:

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