Create a cluster|V4.3.6| docs|Distributed Database

Create a cluster

Last Updated：2025-09-08 08:15:43 Updated

You can create a distributed primary cluster as needed.

Applicability

Only the OCP Community Edition allows you to create a primary cluster.

Background information

When the Deployment Mode of the cluster is set to "Multi-host in Single Zone", only the computing power of OceanBase Database is scaled out, and it does not support multi-replica high availability. This deployment mode applies only to development and test environments.
If the Deployment Mode of the cluster is set to an even number of zones, the high availability of data cannot be guaranteed, which poses a data security risk. We recommend that you adjust the configuration to ensure an odd number of zones or enable the arbitration service for the cluster or tenant.

Prerequisites

The current login user is the ADMIN role or ORG_ADMIN role.
(Optional) If you create a multi-replica OceanBase cluster, you need to have an available OBProxy cluster in the current OCP. To add an OBProxy cluster, see the following links.
- Create an OBProxy cluster
- Take over an OBProxy

Procedure

Step 1: Go to the Create Cluster page

Log in to the OCP console. In the left-side navigation pane, click Cluster to go to the Cluster page. Find the option to create a cluster based on your business scenario.
1. If you don't have any clusters that you can manage, the system will prompt you to create a cluster on the Clusters tab. Click Create Cluster in the prompt.
2. If you already have clusters that you can manage, click Create Cluster in the upper-right corner of the Clusters tab.
On the Create Cluster page, select Distributed Cluster.

Step 2: Configure basic cluster information

The following table describes the basic information required to create a distributed cluster.

Parameter	Description
Cluster Type	Select Primary Cluster.
Cluster Name	Specify the name of the managed cluster. The name must start with an English letter and end with an English letter or a number. It can contain English letters, numbers, and underscores, and must be 2 to 32 characters in length.
Root@sys Password	You can specify a custom password or generate a random one. The password must meet the following complexity requirements: 8 to 32 characters in length At least three of the following four types: numbers (0-9), uppercase letters (A-Z), lowercase letters (a-z), and special characters. Supported special characters: `~!@#%^&*_-+=\|(){}[]:;,.?/`.
OceanBase version	You can select an existing OceanBase cluster version from the list or click Add Version at the bottom of the list to upload an OceanBase version.
Associated OBProxy Cluster	If you are creating a multi-replica OceanBase cluster, we recommend that you enable the associated OBProxy cluster option to associate an OBProxy cluster with the OceanBase cluster. After association, your business SQL requests will be precisely forwarded to the corresponding replica, ensuring access performance comparable to a standalone database. 1. By default, the proxyro user is used for association, so you do not need to specify the username or password. 2. Select the OBProxy cluster to associate from the drop-down list. If there are no OBProxy clusters available in the drop-down list, add an OBProxy cluster based on the description in Prerequisites. For the OBProxy cluster to associate, the following conditions must be met: Only select an OBProxy cluster with the same network as the OceanBase cluster and that is not empty. When the OceanBase cluster version is V4.0 or later, only OBProxy clusters of V4.0.0 or later can be associated.
Load Type	You can select a load type for the cluster. The load type mainly affects the SQL query judgment time (parameter: large_query_threshold) and may significantly impact the response time (RT) for OLTP-type loads. Therefore, you must choose a load type carefully. OCP supports five cluster load types. The following table describes them. Express OLTP: This load type is suitable for workloads such as trade and payment core systems and high-throughput internet applications. It does not support foreign keys, stored procedures, long transactions, or large transactions. It does not support complex joins or complex subqueries. Version Limitation: This load type is suitable for OceanBase V4.2.5 and later. HTAP: This load type is suitable for workloads that combine hybrid OLAP and OLTP. It is typically used to obtain real-time insights from active operations data, fraud detection, and personalized recommendations. Version Limitation: This load type is suitable for OceanBase V4.2.5 and later. OLAP: This load type is suitable for real-time data warehouse analysis scenarios. Version Limitation: This load type is suitable for OceanBase V4.3.0 and later. Complex OLTP: This load type is suitable for workloads such as banking and insurance systems. These workloads typically involve complex joins, complex correlated subqueries, PL-written batch jobs, long transactions, and large transactions. Parallel execution is sometimes used for queries that run for a short time. Version Limitation: This load type is suitable for OceanBase V4.2.5 and later. OBKV: This load type is suitable for key-value workloads and wide-column workloads similar to HBase. These workloads typically have very high throughput and are sensitive to latency. Version Limitation: This load type is suitable for OceanBase V4.2.5 and later.

Step 3: Configure the deployment mode of the cluster

By default, three zones are added. If you want to deploy the cluster across more than three zones, click Add to add more zones. If you want to deploy the cluster across fewer than three zones, click the delete icon next to a zone to remove it.

The following table describes the information required for each zone.

Parameter	Description
Zone Name	The name of the zone. You can keep the default name or customize it. The name must start with an English letter and can contain uppercase and lowercase letters, numbers, and underscores. It must be 2 to 48 characters long. If you deploy OceanBase clusters across multiple zones, one of the zones must be in the same region as the primary zone.
IDC	The IDC where the zone is located. A zone can only be located in one IDC.
Host Type	The type of the host. This parameter is optional. If you select a host type, the host list will be filtered based on the selected host type.
CPU Architecture	If multiple installation packages of different architectures are available for the selected OceanBase version, you must select the host hardware architecture that matches the software package. Caution The default architecture is the one of the first installation package, which can be changed. After you specify an architecture, the Host list displays the host of this architecture. If different architectures are specified for different zones, stability and performance may be affected. Proceed with caution.
Host	You can select multiple hosts or add hosts.
Root Service Location	You must select an IP address as the location of the root service. For a multi-replica OceanBase cluster, each zone must be assigned a root server.
Zone Priority Rankings (Not required for backup clusters)	Specifies whether to set priorities for the primary replicas of the sys tenant of the cluster. If you specify priorities, the zone with the highest priority is considered the primary zone, and only one primary zone is allowed. The procedure is as follows: 1. Select one or more zones in the left-side list. The left-side list displays all available zones in the current cluster. 2. Click the > button in the middle. The selected zones are then moved to the Zone Priority Rankings list. Multiple selected zones have the same priority. 3. Repeat steps 1 and 2 to add zones with a lower priority. 4. To adjust the priority, drag the zones in the Zone Priority Rankings list to the desired order. The priority decreases from top to bottom in the list. If you do not specify priorities, the first zone is considered to have the highest priority.
Add Arbitration Service	Specifies whether to add an arbitration service for the cluster. You can select an arbitration service from the service drop-down list or click Add Service to create a new arbitration service for the cluster. For more information, see Add an arbitration service. Description Arbitration services can be added only for the primary cluster of V4.1.0 and later versions.

Step 4: Enable Cgroup

Cgroup is used to isolate CPU resources between tenants within an OceanBase cluster and between tenants within the same cluster. You can choose whether to enable Cgroup based on your actual business requirements to achieve stronger CPU/IOPS isolation. When you create an OceanBase cluster of V4.0 or later, Cgroup is enabled by default.

Enabling Cgroup may result in a performance drop of about 7%. If your business scenario involves a single tenant, a small number of CPU cores (<14), and a need for higher database performance, we recommend that you disable Cgroup. Additionally, if the operating system kernel version on the host is below 4.1.9, tenants cannot be created on the host. In this case, Cgroup is disabled by default and the Cgroup switch is not displayed.

Step 5: Configure the CPU overselling quota

When different business scenarios have overlapping workloads, OceanBase clusters may experience overload conditions during operation, leading to thread competition for CPU resources among tenants, which can slow down actual business scenarios. To ensure that different tenant workloads can be controlled and interleaved, you can configure CPU resource overselling to improve resource utilization.

In the CPU Overallocation Settings section, you can configure the overselling quota using a slider or an input field. The default value is 120%, with a range of 101% to 200%.

Note

Only OceanBase Database 4.0 and later support CPU overselling. With proper configuration, you can fully utilize hardware resources.
CPU overselling depends on Cgroup. Before configuring the CPU overselling quota, make sure that Cgroup is enabled for the cluster.

Step 6: Configure cluster parameters

Go to the Parameter Settings module to customize the cluster parameters.

If you set the load type in the Basic Settings section, the system will use the corresponding parameter template by default.
You can add and configure individual startup parameters.

Alternatively, you can click Select Parameter Template, select a parameter template, and the system will automatically populate the template parameters and configurations to this section. If no cluster parameter template has been created, you can click Create Cluster Template to create one. For more information, see Manage cluster parameter templates.

The system provides six built-in templates, each containing common parameter settings that you can apply for cluster initialization. The following table describes the built-in templates.

Template	Description
COMPLEX_OLTP Default Parameter Template	Corresponds to the Complex OLTP workload type. This template is only applicable to OceanBase Database V4.2.5 and later.
HTAP Default Parameter Template	Corresponds to the HTAP workload type. This template is only applicable to OceanBase Database V4.2.5 and later.
KV Default Parameter Template	Corresponds to the OBKV workload type. This template is only applicable to OceanBase Database V4.2.5 and later.
EXPRESS_OLAP Default Parameter Template	Corresponds to the Express OLAP workload type. This template is only applicable to OceanBase Database V4.2.5 and later.
OLAP Default Parameter Template	Corresponds to the OLAP workload type. This template is only applicable to OceanBase Database V4.3.0 and later.
Default Parameter Template for OceanBase Database V2.2.77	The recommended parameter settings for OceanBase Database V2.2.77, suitable for production environments.

Note

If you have specific customization requirements for CPU, memory, data disk, and log disk usage at the cluster level, set the parameters: cpu_count, memory_limit_percentage, system_memory, data_disk_usage_limit_percentage, datafile_size, clog_disk_usage_limit_percentage, and log_disk_size. For more information, see the Overview of Cluster Parameters on the OceanBase Database website.

Step 7: Configure users, paths, and ports

In the Custom Settings section, you can configure cluster-level settings such as the operating system user, paths, and ports. These settings include the operating system user for installing and running OBServer, the software installation path, data disk path, log disk path, SQL port, and RPC port.

Configure the operating system user:

This user is used for installing and running OBServer. It cannot be edited. You can modify this user by adjusting the default value of the ocp.operation.default.os.user parameter. Note that changes to this parameter only affect the creation of distributed clusters, standalone centralized clusters, OBProxy clusters, and arbitration services. It does not affect the configurations of existing clusters.

Configure the paths:

Configuration	Description
Software Installation Path	When Operating System User is admin, Software Installation Path defaults to `/home/admin/oceanbase`, which can be customized. When Operating System User is not admin, Software Installation Path defaults to `/opt/oceanbase/oceanbase`, which can be customized.
Data Disk Path	Defaults to `/data/1`, which can be customized.
Log Disk Path	Defaults to `/data/log1`, which can be customized. In a production environment, OceanBase Database recommends that the log disk space be at least three times the host memory space. To avoid performance issues, we recommend that you do not mount the data directory and log directory on the same disk. Note Starting from OCP 4.3.0 BP1, when you create an OceanBase cluster of the following versions, the slog directory is placed on the log disk and is no longer bound to the data disk. If you set `log_disk_size=0`, it will be considered as exclusive use for clogs, with the default value of `log_disk_percentage` being 90%. If the size of the disk where slog and clog are stored is less than 40 GiB, the reserved space for slog will be less than 4 GiB, which may affect the writing of slog. V4.2.4.0 ≤ OceanBase ＜ V4.3.0.0 OceanBase ≥ V4.3.1.0 For more information about slog, see Installation directory structure of OBServer nodes.

Configure the ports:

Configuration	Description
SQL Port	Defaults to 2881, which can be customized.
RPC Port	Defaults to 2882, which can be customized.

After you configure the parameters, click Test to verify whether the paths and ports are available.
- If the test succeeds, click Submit.
- If the test fails, perform troubleshooting based on the error message.

Step 8: Verify the configuration information

In the right-side panel, verify that the configuration information is correct and click OK. After the configuration is submitted, you can view the task progress in Task Center.