OceanBase Shell (OBShell) allows you to deploy an OceanBase cluster by using the following methods:
Deploy an OceanBase cluster by calling API operations
Deploy an OceanBase cluster by using the CLI
Prerequisites
Before you deploy an OceanBase cluster, make sure that the following requirements are met:
Your machine meets the software and hardware requirements. For more information, see Software and hardware requirements.
In the production environment, you have checked the environment and configurations. For more information, see Before deployment.
Terms
Single Agent: the initial role of OBShell Agent. You can call
jointo switch the role from Single Agent to Master Agent or Follower Agent.Master Agent: a role of OBShell Agent. You can call
initto switch the role from Master Agent to Cluster Agent and callremoveto switch the role from Master Agent to Single Agent.Follower Agent: a role of OBShell Agent. You can call
initto switch the role from Follower Agent to Cluster Agent and callremoveto switch the role from Follower Agent to Single Agent.Cluster Agent: a role of OBShell Agent.
OceanBase cluster initialization (init): a centralized task. In this phase, OBShell Agent has two roles: Master Agent and Follower Agent. The init task is led by the Master Agent role and carried out by all OBShell processes. After the init task is completed, the cluster is decentralized. Then, all OBShell processes have only one role, that is, Cluster Agent.
The following figure shows the role switching state machine:
Deployment mode
This topic provides an example in which the three-replica deployment mode is adopted and three machines are used. You can choose an appropriate deployment solution based on your needs. The following table describes the three machines.
| Role | Machine | Remarks |
|---|---|---|
| OBServer node | 10.10.10.1 | In OceanBase Database Zone 1, with the role of Master Agent before the init task is completed. |
| OBServer node | 10.10.10.2 | In OceanBase Database Zone 2, with the role of Follower Agent before the init task is completed. |
| OBServer node | 10.10.10.3 | In OceanBase Database Zone 3, with the role of Follower Agent before the init task is completed. |
Deploy an OceanBase cluster by calling API operations
Note
Each of the following API operations creates an asynchronous task. You must wait until the current task is completed before you can proceed to the next step. For more information, see GetDagDetails.
OBShell verifies the security of requested API operations. Therefore, you must encrypt the request before you call an API operation. For more information, see Hybrid encryption for API operations. You must also specify
${request_headers}and${request_body}in thecurlcommand.
Step 1: Start OBShell
OBShell is installed in the
/home/admin/oceanbase/bin/obshelldirectory.Start OBShell on each OBServer node. For more information, see obshell agent start.
Run the following command on the OBServer node with the IP address of
10.10.10.1:[admin@test001 ~]$ /home/admin/oceanbase/bin/obshell agent start --ip 10.10.10.1 -P 2886Run the following command on the OBServer node with the IP address of
10.10.10.2:[admin@test002 ~]$ /home/admin/oceanbase/bin/obshell agent start --ip 10.10.10.2 -P 2886Run the following command on the OBServer node with the IP address of
10.10.10.3:[admin@test003 ~]$ /home/admin/oceanbase/bin/obshell agent start --ip 10.10.10.3 -P 2886
Step 2: Switch the role from Single Agent to Master Agent
Call the /api/v1/agent/join API operation on the OBServer node whose role is Single Agent (10.10.10.1) with the IP address and port number of OBShell specified as 10.10.10.1:2886 to switch the role from Single Agent to Master Agent. For more information, see AddNodeBeforeClusterInitialization.
[admin@test001 ~]$ curl -H "Content-Type: application/json" -H 'X-OCS-Header:${request_headers}' -X POST -d '${request_body}' http://10.10.10.1:2886/api/v1/agent/join
Step 3: Switch the role from Single Agent to Follower Agent
Call the /api/v1/agent/join API operation on the OBServer nodes whose role is Single Agent (10.10.10.2 and 10.10.10.3) with the IP address and port number of OBShell specified as those of Master Agent (10.10.10.1:2886) to switch the role from Single Agent to Follower Agent. For more information, see AddNodeBeforeClusterInitialization.
Run the following command on the OBServer node with the IP address of 10.10.10.2:
[admin@test002 ~]$ curl -H "Content-Type: application/json" -H 'X-OCS-Header:${request_headers}' -X POST -d '${request_body}' http://10.10.10.2:2886/api/v1/agent/join
Run the following command on the OBServer node with the IP address of 10.10.10.3:
[admin@test003 ~]$ curl -H "Content-Type: application/json" -H 'X-OCS-Header:${request_headers}' -X POST -d '${request_body}' http://10.10.10.3:2886/api/v1/agent/join
Step 4: Set the cluster configurations
Call the /api/v1/obcluster/config API operation on the OBServer node whose role is Master Agent to set the cluster configurations. For more information, see SetClusterConfig.
[admin@test001 ~]$ curl -H "Content-Type: application/json" -H 'X-OCS-Header:${request_headers}' -X PUT -d '${request_body}' http://10.10.10.1:2886/api/v1/obcluster/config
Step 5: Set the server configurations
Call the /api/v1/observer/config API operation with an effective scope specified on the OBServer node whose role is Master Agent to set the server configurations for the specified OBShell process. For more information, see SetServerConfig.
[admin@test001 ~]$ curl -H "Content-Type: application/json" -H 'X-OCS-Header:${request_headers}' -X PUT -d '${request_body}' http://10.10.10.1:2886/api/v1/observer/config
Step 6: Initialize the cluster
Call the /api/v1/ob/init API operation on the OBServer node whose role is Master Agent to initialize the cluster. For more information, see InitializeCluster.
[admin@test001 ~]$ curl -H 'X-OCS-Header:${request_headers}' -X POST http://10.10.10.1:2886/api/v1/ob/init
Step 7: Connect to the OceanBase cluster
In this example, OBClient is used to connect to OceanBase Database. The command is as follows:
[admin@test001 ~]$ obclient -h10.10.10.1 -uroot@sys -P2881 -p -A
-h: the IP address for connecting to OceanBase Database, that is, the IP address specified when you start OBShell, for example,10.10.10.1.-u: the tenant account name in the Username@Tenant name format. The default username of the administrator of a MySQL tenant isroot.-P: the port for connecting to OceanBase Database. If you do not specify the port in Step 5, the default port2881is used.-p: the tenant account password.-A: specifies not to automatically retrieve the statistical information when connecting to the cluster.
For more information about how to connect to an OceanBase cluster, see Connect to OceanBase Database.
Deploy an OceanBase cluster by using the CLI
Step 1: Start OBShell
OBShell is installed in the
/home/admin/oceanbase/bin/obshelldirectory.Start OBShell on each OBServer node. For more information, see Start OBShell.
Run the following command on the OBServer node with the IP address of
10.10.10.1:[admin@test001 ~]$ /home/admin/oceanbase/bin/obshell agent start --ip 10.10.10.1 -P 2886Run the following command on the OBServer node with the IP address of
10.10.10.2:[admin@test002 ~]$ /home/admin/oceanbase/bin/obshell agent start --ip 10.10.10.2 -P 2886Run the following command on the OBServer node with the IP address of
10.10.10.3:[admin@test003 ~]$ /home/admin/oceanbase/bin/obshell agent start --ip 10.10.10.3 -P 2886
Step 2: Switch the role from Single Agent to Master Agent and set the server configurations
On the current OBServer node, run the obshell cluster join command with the IP address and port number of OBShell specified for -s to switch the role from Single Agent to Master Agent. For more information, see obshell cluster join.
Run the following command on the OBServer node with the IP address of 10.10.10.1:
[admin@test001 ~]$ /home/admin/oceanbase/bin/obshell cluster join -s "10.10.10.1:2886" -z zone1 -p 2881 -P 2882 -o 'memory_limit=16G,system_memory=8G,log_disk_size=24G,datafile_size=24G'
Step 3: Switch the role from Single Agent to Follower Agent and set the server configurations
On the current OBServer node, run the obshell cluster join command with the IP address and port number of Master Agent (10.10.10.1:2886) specified for -s to switch the role from Single Agent to Follower Agent. For more information, see obshell cluster join.
Run the following command on the OBServer node with the IP address of 10.10.10.2:
[admin@test002 ~]$ /home/admin/oceanbase/bin/obshell cluster join -s "10.10.10.1:2886" -z zone2 -p 2881 -P 2882 -o 'memory_limit=16G,system_memory=8G,log_disk_size=24G,datafile_size=24G'
Run the following command on the OBServer node with the IP address of 10.10.10.3:
[admin@test003 ~]$ /home/admin/oceanbase/bin/obshell cluster join -s "10.10.10.1:2886" -z zone3 -p 2881 -P 2882 -o 'memory_limit=16G,system_memory=8G,log_disk_size=24G,datafile_size=24G'
Step 4: Set the cluster configurations and initialize the cluster
Run the obshell cluster init command on any OBServer node to set the cluster configurations and initialize the cluster. For more information, see obshell cluster init.
[admin@test001 ~]$ /home/admin/oceanbase/bin/obshell cluster init -n ob-test --rp ********
Step 5: Connect to the OceanBase cluster
In this example, OBClient is used to connect to OceanBase Database. The command is as follows:
[admin@test001 ~]$ obclient -h10.10.10.1 -uroot@sys -P2881 -p -A
-h: the IP address for connecting to OceanBase Database, that is, the IP address specified when you start OBShell, for example,10.10.10.1.-u: the tenant account name in the Username@Tenant name format. The default username of the administrator of a MySQL tenant isroot.-P: the port for connecting to OceanBase Database. If you do not specify the port in Step 4, the default port2881is used.-p: the tenant account password.-A: specifies not to automatically retrieve the statistical information when connecting to the cluster.
For more information about how to connect to an OceanBase cluster, see Connect to OceanBase Database.